BlueScript: Hash Procedures
Contents
Description
Allows for the creation and manipulation of hash tables that
map strings to arbitrary values or objects.
Documentation
Note that hash objects need not be explicitly destroyed.
They are automatically destroyed when the last reference to
them is destroyed.
Objects
hash
Hash tables are represented as opaque objects. This
means that they are passed by reference and not by value.
hash clear
Usage
hash clear
Description
Empties the contents of the hash table. After calling
this procedure, the hash table will be empty.
Examples
1. Emptying a hash table
set h [hash]
$h set foo 0
$h set bar 1
$h set joe 2
$h clear
$h export
Result: none
hash copy
Usage
hash copy
Returns
A new hash object which contains the same key/value
mappings as the original.
Note that there is an important difference between this
operation and simple assignment. For example:
set h2 $h
will create a duplicate reference to the original
hash table. That is, modifying the hash table referred
to by $h2 will also modify the table referred to by
$h. However, if a copy of the table is mad:
set h2 [$h copy]
then modifying the table referred to by $h2 will
not modify the table referred to by $h.
Examples
1. Making a copy of a hash table
set h [hash]
$h set foo 0
$h set bar 1
$h set joe 2
set h2 [$h copy]
$h2 export
Result: {bar 1} {joe 2} {foo 0}
hash export
Usage
hash export
Returns
The contents of the hash table as a list.
Description
Provides a method for extracting the entire contents of
the hash table. The contents are represented as a list. Each
element of the list is itself a list of two elements - a
key and a value. This format can be used to
reconstruct the hash table at a later time using the
import procedure.
Examples
1. Retrieving the values of a hash table
set h [hash]
$h set foo 0
$h set bar 1
$h set joe 2
$h export
Result: {bar 1} {joe 2} {foo 0}
hash get
Usage
hash get key
Returns
The value of a key in the table, if it exists, or a
blank string otherwise.
Examples
1. Retrieve a value from the hash table
set h [hash]
$h set foo 0
$h get foo
Result: 0
2. Retrieve a non-existent value from the same hash
table
$h get bar
Result: none
hash has
Usage
hash has key
Returns
True (1) if the hash table contains an entry for the
given key, or false (0) if the hash table does not contain
an entry for the given key.
Examples
1. Checking for the existence of keys
set h [hash]
$h set foo 0
$h has foo
Result: 1
2. Checking for non-existent keys
set h [hash]
$h set foo 0
$h has bar
Result: 0
hash import
Usage
hash import list
Description
Adds the given elements in the list to the hash table.
Each element of the list must itself be a list of two
elements - a key and a value. That is, the
format of list must be the same as the output of
the export procedure. These key-value pairs are
merged into the existing contents of the hash table,
overriding any existing cases which share the same key.
Note that the hash table is not cleared before importing.
Examples
1. Importing a list of key-value pairs
set h [hash]
$h import {{foo 0} {bar 1} {joe 2}}
$h export
Result: {bar 1} {joe 2} {foo 0}
hash keys
Usage
hash keys
Returns
A list of the keys in the hash table.
Description
Retrieves a list of the keys in the hash table. The
order in which the keys are returned is arbitrary.
Examples
1. Retrieving the keys of a hash table
set h [hash]
$h set foo 0
$h set bar 1
$h set joe 2
$h keys
Result: bar joe foo
hash set
Usage
hash set key [value]
Returns
The value corresponding to key in the hash
table. If key is not in the hash table, then an
error is generated.
Description
Creates entries in the hash table if value is
specified. Returns values for keys that exist in the
table.
Examples
1. Create an entry in the hash table
set h [hash]
$h set foo 0
Result: 0
2. Retrieve a value from the same hash table
$h set foo
Result: 0
hash unset
Usage
hash unset key
Description
Removes an entry from the table. If the given key does
not exist in the table, then this procedure has no
effect.
Examples
1. Remove an entry from the hash table
set h [hash]
$h set foo 0
$h set bar 1
$h set joe 2
$h unset foo
$h export
Result: {bar 1} {joe 2}
hash values
Usage
hash values
Returns
A list of the values in the hash table.
Description
Retrieves a list of the values in the hash table. The
order in which the values are returned is arbitrary.
Examples
1. Retrieving the values of a hash table
set h [hash]
$h set foo 0
$h set bar 1
$h set joe 2
$h values
Result: 1 2 0
Procedures
hash
Usage
hash
Returns
A new hash object.