ORDEREDHASH
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
- ORDEREDHASH( )
- OrderedHash::Count
- OrderedHash::Filter
- OrderedHash::HasKey
- OrderedHash::IsEmpty
- OrderedHash::IsFoldCase
- OrderedHash::Keys
- OrderedHash::Map
- OrderedHash::Reduce
- OrderedHash::Remove
- OrderedHash::ToStruct
- OrderedHash::Values
- OrderedHash::Where
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