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