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


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

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


See Hash::IsFoldCase for detailed documentation.

Note: This function will always return True (1) for a dictionary.

Syntax


Result = dictionary.IsFoldCase( )


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

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

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

8.5.1

Added IsFoldCase method

See Also


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



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