XDict Reference

XDict is a module of AppleScript to provides associative list type data collection. The associateve list is a collection of pairs of keys and values.

AppleScript's record class is similar to the associative list.But record object can do followings :

XDict allows to avoid these limitations.

The method to search keys in XDict is linear search. This means large number of keys cause to make performance slowdown. A few hundred of keys may not be serious problems.A few thousand of keys will cause low performance.

On the other hand, any kind of objects (not only text) can be accept as keys,for example object spefifiers and script objects and records.

Example

use XDict : script "XDict"

(* Make Instances *)
set empty_dict to make XDict
set a_dict to XDict's make_with_lists({"key1", "key2"}, {"value1", "value2"})
set a_dict to XDict's make_with_pairs({{"key1", "value1"}, {"key2", "value2"}})

(* obtain value *)
log a_dict's value_for_key("key1")
--result : "value1"
try
a_dict's value_for_key("key3")
on error number 900
log "No value associated with key3"
end try

(* Reverse Search *)
log a_dict's key_for_value("value2") -- result : "key2"

(* Non string values can be used as keys *)
script scriptA
end script

script scriptB
end script

a_dict's set_value(scriptA, "value3")
log a_dict's value_for_key(scriptA) --result : "value3"
try
a_dict's value_for_key(scriptB)
on error number 900
log "No value associated with scriptB"
end try

(* Iterator *)
set dict_iterator to a_dict's iterator()
repeat while dict_iterator's has_next()
set {a_key, a_value} to dict_iterator's next()
end repeat

(* Loop with a Script Object *)
script DictScanner
on do({a_key, a_value})
log a_key
log a_value
return true
end do
end script

a_dict's each(DictScanner)

script ValueExtractor
on do({a_key, a_value})
return a_value
end do
end script

set a_xlist to a_dict's map(ValueExtractor)

(* Dump the Contents for Debugging *)
log a_dict's remove_for_key(scriptA) -- result : true
a_dict's dump()
(* result :
"key1 -> value1
key2 -> value2
"
*)

Constructer Methods

make

Make an empty XDict instance

make_with_pairs

Make a new XDict instance with a list of pair lists of a key and a value.

make_with_lists

Make a XDict instance with a list of keys and a list of values.

make_with_xlists

Make a XDict instance with a XList of keys and a XList of values.

Instance Methods

value_for_key

Obtain a value associated with a specified key. If a key is not in a XDict, error number 900 will be rasied.

key_for_value

Obtain a key associating a value. If a same value using "is" operator is not found, missing value is returened.

set_value

Set a value associated with a key. If the key is not in the XDict, the key is added.

has_key

Chack whether a passed value is icluded as a key value or not.

remove_for_key

Remove a specified key and a associated value.

all_keys

Obtain all keys as a list

all_values

Obtain all values as a list

count_keys

Obtain all keys as a list

forget

Remove all keys and values

Setting and Getting Comparators

set_key_comparator

Set a key comparator script to the instance.

set_value_comparator

Set a value comparator script to the instance.

key_comparator

Obrain the key comprator of the XDict instance.

value_comparator

Obrain the value comprator of the XDict instance.

Obtain Iterator Object

iterator

Make an iterator object of XDict. The iterator object return a pair list of key and a value i.e. {a_key, a_value} with next() handler.

Methods of Iterator Object

has_next

Check whether next object can be obtained or not.

next

Obtain a next pair of a key and its value.

reset

Make a pair of a key and a value retuned by next() revert to first one.

Loop with Script Object

each

Perform do handler of given script object with passing pair lists of each key and value as a argument.

map

Perform do handler of given script object with passing pair lists of each key and value as a argument.　A XList consisting of the results of do handler is returned.

map_as_list

Almost same to map, but a result of this method is AppleScript's list.

Debugging

dump

Dump keys and values in XDict as text. Use this method for debugging.