Welcome to the Harris Geospatial product documentation center. Here you will find reference guides, help documents, and product libraries.


ORDEREDHASH

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

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.

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

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 you should avoid adding or removing elements. If the ordered hash is changed during the FOREACH, the behavior is undefined.

Version History


8.3

Introduced

8.4

Added Filter, Map, Reduce methods

Added FOLD_CASE keyword

8.5.1

Added IsFoldCase method

See Also


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



© 2017 Exelis Visual Information Solutions, Inc. |  Legal
My Account    |    Buy    |    Contact Us