Work with Associative Arrays

To determine the number of keys that an associative array contains, use the N Items() function.

cary = Associative Array();

cary["state"] = "NC";

cary["population"] = 116234;

cary["weather"] = "cloudy";

cary["population"] += 10;

cary["weather"] = "sunny";

cary["high schools"] = {"Cary", "Green Hope", "Panther Creek"};

N Items( cary );

Add and Delete Keys and Values

To add or delete key-value pairs from an associative array, use the following functions:

•

•

•

•

•

Insert() and Remove() return a named copy of the given associative array with the key-value pair added or removed.

•

Insert Into() and Remove From() add or remove the key-value pairs directly from the given associative array.

•

Insert() and Insert Into() take three arguments: the associative array, a key, and a value.

•

Remove() and Remove From() take two arguments: the associative array and a key.

•

If you insert a key with no value provided, the key is assigned a value of 1.

Examples

The following examples illustrate Insert() and Insert Into():

newcary = Insert( cary, "time zone", "Eastern" );

Show( cary, newcary );

cary = Associative Array({{"high schools", {"Cary", "Green Hope", "Panther Creek"}}, {"population", 116244}, {"state", "NC"}, {"weather", "sunny"}});

newcary = Associative Array({{"high schools", {"Cary", "Green Hope", "Panther Creek"}}, {"population", 116244}, {"state", "NC"}, {"time zone", "Eastern"}, {"weather", "sunny"}});

Insert Into(cary, "county", "Wake");

Show( cary );

Note that aa <<Insert is a message sent to an associative array that does the same thing as the function Insert Into(). For example, these two statements are equivalent:

cary << Insert( "county", "Wake" );

Insert Into( cary, "county", "Wake" );

The following examples illustrate Remove() and Remove From():

newcary = Remove( cary, "high schools" );

Show( cary, newcary );

cary = Associative Array({{"county", "Wake"}, {"high schools", {"Cary", "Green Hope", "Panther Creek"}}, {"population", 116244}, {"state", "NC"}, {"weather", "sunny"}});

Remove From( cary, "weather" );

Show( cary );

cary = Associative Array({{"high schools", {"Cary", "Green Hope", "Panther Creek"}}, {"population", 116244}, {"state", "NC"}});

Note that aa << Remove is a message sent to an associative array that does the same thing as the function Remove From(). For example, these two statements are equivalent:

cary << Remove( "weather" );

Remove From( cary, "weather" );

Find Keys or Values in an Associative Array

To determine whether a certain key is contained within an associative array, use the Contains() function.

cary = Associative Array();

cary["state"] = "NC";

cary["population"] = 116234;

cary["weather"] = "cloudy";

cary["population"] += 10;

cary["weather"] = "sunny";

cary["high schools"] = {"Cary", "Green Hope", "Panther Creek"};

Contains(cary, "high schools");

Contains(cary, "lakes");

To obtain a list of all keys contained in an associative array, use the << Get Keys message.

cary << Get Keys;

{"high schools", "population", "state", "weather"}

To obtain a list of all values contained in an associative array, use the <<Get Values message.

cary << Get Values;

{{"Cary", "Green Hope", "Panther Creek"}, 116244, "NC", "sunny"}

If you want to see only the values for certain keys, you can specify them as arguments. The keys must be given as a list.

cary << Get Values({"state", "population"});

{"NC", 116244}

To see a value for a single key, use the <<Get Value message. Specify only one key and do not place it in a list.

cary << Get Value("weather");

"sunny"

To obtain a list of all key-value pairs in an associative array, use the <<Get Contents message.

cary << Get Contents;

{{"high schools", {"Cary", "Green Hope", "Panther Creek"}},

{"population", 116244},

{"state", "NC"},

{"weather", "sunny"}}

Note: Using the <<Get Contents message, the returned list does not include the default value. Keys are listed alphabetically.

Iterate through an Associative Array

To iterate through as associative array, use the <<First and <<Next messages. <<First returns the first key in the associative array. <<Next(key) returns the key that follows the key that is given as the argument.

The following example removes all key-value pairs from the associative array cary, leaving an empty associative array:

currentkey = cary << First;

total = N Items( cary );

For( i = 1, i <= total, i++,

	nextkey = cary << Next( currentkey );

	Remove From( cary, currentkey );

	currentkey = nextkey;

);

Show( cary );

cary = [=>];