Routines (alphabetical) > Routines: D > DICTIONARY

# DICTIONARY

The DICTIONARY function creates a new dictionary. An IDL dictionary is a compound data type that contains key-value pairs of different data types including any mixture of scalars, arrays, structures, pointers, object references, lists, hashes, and other dictionaries. Unlike HASH, the keys in a dictionary are case insensitive and must be valid IDL variable names. An IDL dictionary is very similar to an IDL structure except that it is easy to add or remove keys, or change the data type of a value.

IDL dictionaries have the following properties:

- Elements in a dictionary are unordered and are indexed by a scalar key.
- The key is a case-insensitive scalar string and must be a valid IDL variable name (i.e., no spaces or special characters).
- You can retrieve elements by using either the bracket array notation or using the "dot" syntax like an IDL structure.
- Dictionaries can change their size, growing and shrinking as elements are added or deleted.
- Unlike structures, with a dictionary you can change the data type of a value without a performance penalty.

### Methods and Additional Information

- Dictionary::Count
- Dictionary::Filter

- Dictionary::HasKey

- Dictionary::IsEmpty

- Dictionary::Keys

- Dictionary::Map
- Dictionary::Reduce

- Dictionary::Remove

- Dictionary::ToStruct

- Dictionary::Values

- Dictionary::Where

- Dictionary Access Using Dot Notation

Note: Since the DICTIONARY 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 a dictionary containing three key-value pairs, with strings for keys.

dict = DICTIONARY("one", 1.0, "blue", [255,0,0], "Pi", !DPI)

PRINT, N_ELEMENTS(dict)

IDL prints:

3

#### Access and modify dictionary values using both the bracket and "dot" notation.

dict = DICTIONARY("one", 1.0, "blue", [255,0,0], "Pi", !DPI)

PRINT, dict["one"]

PRINT, dict.one

PRINT, dict.ONE

In all three cases IDL prints:

1.00000

Now try changing the data type:

dict.one = 'my value'

PRINT, dict.One ; case insensitive

IDL prints:

my value

Now dynamically add a new key:

dict.newkey = [0,1,2]

PRINT, dict.newkey

IDL prints:

0 1 2

#### Create a dictionary 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))

dict = DICTIONARY(keys, values)

PRINT, N_ELEMENTS(dict)

IDL prints:

7

#### Create a dictionary from a structure, and also convert any substructures into dictionaries

struct = {FIELD1: 4.0, FIELD2: {SUBFIELD1: "hello", SUBFIELD2: 3.14}}

dict = DICTIONARY(struct, /EXTRACT)

PRINT, dict

PRINT, dict.field2

PRINT, 'subfield1 = ', dict.field2.subfield1

IDL prints:

FIELD2: DICTIONARY <ID=4 NELEMENTS=2>

FIELD1: 4.00000

SUBFIELD1: hello

SUBFIELD2: 3.14000

subfield1 = hello

## Syntax

For details on the input arguments and keywords see HASH.

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

or

Result = DICTIONARY( Keys, Values, /EXTRACT )

or

Result = DICTIONARY( Keys )

or

Result = DICTIONARY( Structure, /EXTRACT )

## Arguments

### Keyn

### Valuen

### Structure

## Keywords

### EXTRACT

### NO_COPY

# Dictionary::Count

See Hash::Count for detailed documentation.

## Syntax

Result = dictionary.Count( [Value] )

## Arguments

### Value

# Dictionary::Filter

See Hash::Filter for detailed documentation.

## Syntax

Result = dictionary.Filter(Function, Args)

## Arguments

### Function

### Args

# Dictionary::HasKey

See Hash::HasKey for detailed documentation.

## Syntax

Result = dictionary.HasKey( Keys )

## Arguments

### Keys

# Dictionary::IsEmpty

See Hash::IsEmpty for detailed documentation.

## Syntax

Result = dictionary.IsEmpty( )

# Dictionary::Keys

See Hash::Keys for detailed documentation.

## Syntax

Result = dictionary.Keys( )

# Dictionary::Map

See Hash::Map for detailed documentation.

## Syntax

Result = dictionary.Map(Function, Args)

## Arguments

### Function

### Args

# Dictionary::Reduce

See Hash::Reduce for detailed documentation.

## Syntax

Result = dictionary.Reduce(Function, Args, VALUE=value)

## Arguments

### Function

### Args

## Keywords

### VALUE

# Dictionary::Remove

See Hash::Remove for detailed documentation.

## Syntax

dictionary.Remove [, Keys] [, /ALL]

or

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

## Arguments

### Keys

## Keywords

### ALL

# Dictionary::ToStruct

See Hash::ToStruct for detailed documentation.

## Syntax

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

## Keywords

### MISSING

### NO_COPY

### RECURSIVE

### SKIPPED

# Dictionary::Values

See Hash::Values for detailed documentation.

## Syntax

Result = dictionary.Values( )

# Dictionary::Where

See Hash::Where for detailed documentation.

## Syntax

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

## Arguments

### Value

## Keywords

### COMPLEMENT

### COUNT

### NCOMPLEMENT

# Additional Information on Dictionaries

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

- Concatenating Hashes

- Comparing Hashes

- Hash Access

- Information about Hashes

## Dictionary Access

In many cases, you can access elements of a dictionary variable using standard IDL array syntax, as if the dictionary were a one-dimensional array. You can also access elements using standard IDL structure syntax using dot notation.

### Retrieve a Single Element

To copy the value of a single dictionary element into a new variable, leaving the dictionary unchanged, use array syntax:

value = dictionary[Key]

where Key is an IDL variable containing a scalar string.

Or you can use dot notation:

value = dictionary.Key

where `Key` is the name of the desired element within the dictionary.

For example:

d = DICTIONARY("planet", "Saturn")

mykey = "dwarf"

; Three ways to access the same key.

PRINT, d[mykey], d["dwarf"], d.dwarf

Note: Using array notation, you are supplying a variable containing a string key. Using dot notation, you are hard-coding the key name into your program. The array notation method is more flexible because the variable can be created at runtime, while the dot notation may produce more human-readable code and is slightly faster to execute.

Note: IDL structures have a "special" parentheses syntax where you can retrieve structure fields by the tag number enclosed in parentheses. You cannot use this parentheses notation with dictionaries.

### Insert a Single Element

To insert a single value into a dictionary, use array syntax or dot notation:

dictionary[Key] = Value

or

dictionary.Key = Value

where Value is the value to be stored in the new dictionary element.

Note: Using array notation, you supply a variable containing a string key. Using dot notation, you hard-code the key name into your program. The array notation method is more flexible because the variable can be created at runtime, while the dot notation may produce more human-readable code and is slightly faster to execute.

### Change the Value of a Single Element

To change the value of a single dictionary element, use array syntax or dot notation:

dictionary[Key] = Value

or

dictionary.Key = Value

where Value is the new value.

Note: Using array notation, you supply a variable containing a string key. Using dot notation, you hard-code the key name into your program. The array notation method is more flexible because the variable can be created at runtime, while the dot notation may produce more human-readable code and is slightly faster to execute.

#### Difference between Dictionary and IDL Structures

If your dictionary contains an array, you can combine the dot notation with brackets to access a subset of the array. For example:

IDL> dict = DICTIONARY('data', FINDGEN(10))

IDL> PRINT, dict.data[2:5]

2.00000 3.00000 4.00000 5.00000

However, unlike structures, you cannot change the array elements using the dot notation:

IDL> dict = DICTIONARY('data', FINDGEN(10))

IDL> dict.data[2:5] = 0

% Attempt to store into an expression: Structure reference.

% Execution halted at: $MAIN$

Instead, you should use the bracket notation with multiple indexing to change just a subset. For example:

IDL> dict['data', 2:5] = 0

This is because the DICTIONARY is implemented as a container of data pointers instead of a structure that is laid out directly into memory.

### Iterating over a Dictionary

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

Note: While iterating through a dictionary you should avoid adding or removing elements. If the dictionary is changed during the FOREACH, the behavior is undefined.

## Version History

8.3 | Introduced
8.4 | Added Filter, Map, Reduce methods

## See Also

!NULL, Creating and Defining Structures, HASH, LIST, ORDEREDHASH, Logical Operators, Modifying Object Properties, Relational Operators, Structure References, LAMBDA