The ORDEREDHASH function creates a new ordered hash. An ordered hash is a compound data type that contains key-value pairs of different data types, including any mixture of scalars, arrays, structures, pointers, object references, dictionaries, lists, hashes, and other ordered hashes. Unlike HASH, the keys in an ordered hash are kept in the same order in which they are inserted.

Ordered hashes have the following properties:

  • Elements in an ordered hash are kept in their insert order and are indexed by a scalar key.
  • The key can be a scalar string or number. String keys are case sensitive unless the FOLD_CASE keyword is set.
  • You can retrieve elements using the bracket array notation.
  • Ordered hashes can change their size, growing and shrinking as elements are added or deleted.
  • Unlike structures, with an ordered hash you can change the data type of a value without a performance penalty.

Methods and Additional Information

Note: Since the ORDEREDHASH is so similar to HASH, most of the documentation can be found under HASH. Here we provide some examples of the differences between the two data types.

The ORDEREDHASH function and class was ported from PRO code to C/C++ code in 8.8.1. You can run the SAVEFILE_CLEANUP procedure to inspect an older save file and remove any routines that might cause problems in IDL 8.8.1 and newer. See SAVEFILE_CLEANUP for more information.

Examples

Create an ordered hash containing all of the elements of a list.

keys = ['A', 'B', 'C', 'D', 'E', 'F', 'G']
values = LIST('one', 2.0, 3, 4l, PTR_NEW(5), {n:6}, COMPLEX(7,0))
hash = ORDEREDHASH(keys, values)
PRINT, hash

IDL prints:

A: one
B:       2.00000
C:        3
D:            4
E: <PtrHeapVar79>
F: {       6}
G: (      7.00000,     0.000000)

Create a regular hash containing the same elements.

keys = ['A', 'B', 'C', 'D', 'E', 'F', 'G']
values = LIST('one', 2.0, 3, 4l, PTR_NEW(5), {n:6}, COMPLEX(7,0))
hash = HASH(keys, values)
PRINT, hash

IDL prints:

A: one
F: {       6}
C:        3
D:            4
G: (      7.00000,     0.000000)
B:       2.00000
E: <PtrHeapVar31>

Notice that the regular hash returns the elements in an arbitrary order while the ordered hash preserves the original element order.

Create an ordered hash from a structure, and also convert any substructures into ordered hashes.

struct = {FIELD1: 4.0, FIELD2: {SUBFIELD1: "hello", SUBFIELD2: 3.14}}
hash = ORDEREDHASH(struct, /EXTRACT)
PRINT, hash
 
; Use array syntax to retrieve the "substructure" hash.
PRINT, hash['FIELD2']
 
; Use special array syntax to access a key within the "substructure".
PRINT, 'SUBFIELD1 = ', hash['FIELD2', 'SUBFIELD1']

IDL prints:

FIELD1:       4.00000
FIELD2: ORDEREDHASH  <ID=4  NELEMENTS=2>
 
SUBFIELD1: hello
SUBFIELD2:       3.14000
 
SUBFIELD1 = hello

Syntax

For details on the input arguments and keywords see HASH.

Result = ORDEREDHASH( Key1, Value1, Key2, Value2, ... Keyn, Valuen , /EXTRACT, /FOLD_CASE, /NO_COPY )

or

Result = ORDEREDHASH( Keys, Values, /EXTRACT, /FOLD_CASE )

or

Result = ORDEREDHASH( Keys, /FOLD_CASE)

or

Result = ORDEREDHASH( Structure, /EXTRACT, /FOLD_CASE, /LOWERCASE)

Arguments

Keyn

Valuen

Structure

Keywords

EXTRACT

FOLD_CASE

LOWERCASE

NO_COPY

OrderedHash::Count

See Hash::Count for detailed documentation.

Syntax

Result = orderedhash.Count( [Value] )

Arguments

Value

OrderedHash::Filter

See Hash::Filter for detailed documentation.

Syntax

Result = orderedhash.Filter(Function, Args)

Arguments

Function

Args

OrderedHash::HasKey

See Hash::HasKey for detailed documentation.

Syntax

Result = orderedhash.HasKey( Keys )

Arguments

Keys

OrderedHash::IsEmpty

See Hash::IsEmpty for detailed documentation.

Syntax

Result = orderedhash.IsEmpty( )

OrderedHash::IsFoldCase

See Hash::IsFoldCase for detailed documentation.

Syntax

Result = orderedhash.IsFoldCase( )

OrderedHash::Keys

See Hash::Keys for detailed documentation.

Syntax

Result = orderedhash.Keys( )

OrderedHash::Map

See Hash::Map for detailed documentation.

Syntax

Result = orderedhash.Map(Function, Args)

Arguments

Function

Args

OrderedHash::Reduce

See Hash::Reduce for detailed documentation.

Syntax

Result = orderedhash.Reduce(Function, Args, /CUMULATIVE, VALUE=value)

Arguments

Function

Args

Keywords

CUMULATIVE

If this keyword is set, then the Result will be a hash containing all of the intermediate cumulative results instead of just the final result.

VALUE

OrderedHash::Remove

See Hash::Remove for detailed documentation.

Syntax

ordered hash.Remove [, Keys] [, /ALL]

or

Result = orderedhash.Remove( [, Keys] [, /ALL] )

Arguments

Keys

Keywords

ALL

OrderedHash::ToStruct

See Hash::ToStruct for detailed documentation.

Syntax

Result = orderedhash.ToStruct( [, MISSING=value] [, /NO_COPY] [, /RECURSIVE] [, SKIPPED=variable] )

Keywords

MISSING

NO_COPY

RECURSIVE

SKIPPED

OrderedHash::Values

See Hash::Values for detailed documentation.

Syntax

Result = orderedhash.Values( )

OrderedHash::Where

See Hash::Where for detailed documentation.

Syntax

Result = orderedhash.Where( Value [, COMPLEMENT=variable] [, COUNT=variable] [, NCOMPLEMENT=variable] )\

Arguments

Value

Keywords

COMPLEMENT

COUNT

NCOMPLEMENT

Additional Information on Ordered Hashes

See the following sections in HASH for additional information on using ordered hashes:

Iterating over an OrderedHash

Just like HASH, you can use the FOREACH operator to iterate over the ordered hash.

Note: While iterating through an ordered hash, avoid adding or removing elements. If the ordered hash is changed during the FOREACH, the behavior is undefined.

Output

You can output an orderedhash in JSON format using implied print or JSON_SERIALIZE. You can also output in YAML notation using YAML_SERIALIZE.

Version History

8.3

Introduced

8.4

Added Filter, Map, Reduce methods

Added FOLD_CASE keyword
8.5.1 Added IsFoldCase method
8.8.1

Ported from PRO code to C++ for performance.

See Also

!NULL, DICTIONARY, HASH, LIST, Logical Operators, Relational Operators, LAMBDA