Routines (alphabetical) > Routines: O > 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

- ORDEREDHASH( )
- OrderedHash::Count
- OrderedHash::Filter
- OrderedHash::HasKey
- OrderedHash::IsEmpty
- 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.

## 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::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:

- Concatenating Hashes
- Comparing Hashes
- Hash Access
- Information about 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

## See Also

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