The built-in functions in the Assoc package allow you to manipulate the Assoc (Associative) data type. An Assoc is a map for associating arbitrary key/value pairs. An Assoc differs from a Record in that the keys are less expensive to add and remove, the keys can be data types other than Strings, and the keys are sorted by key comparison rather than by some fixed order.

Each Assoc has an "undefined value" that is returned when a nonexistent key is referenced. This "undefined value" is usually Undefined by default, but Assoc.NotSetValue() or any other value may be used.

An Assoc is formally created with Assoc.CreateAssoc(), however OScript has a convenience feature in that this is automatically invoked when an Assoc is declared so that it can be used right away. This does not happen with a Record since, while Assoc is meant to be a tool for relating data in an OScript program, Record is meant to be a tool for accessing database table data.

Class Attributes Index

o AssocType
The constant type identifier for the Assoc data type.

Class Methods Index

o Copy( Assoc src )
Returns a duplicate Assoc.
o CreateAssoc( [Dynamic value] )
Returns a new Assoc.
o Delete( Assoc a, Dynamic key )
Removes a key/value pair from an Assoc.
o FromRecord( Record rec )
Converts a Record to an Assoc.
o IsKey( Assoc a, Dynamic key )
Returns true if the Assoc contains key.
o Items( Assoc a )
Returns a List of all the values in an Assoc.
o Keys( Assoc a )
Returns a List of all the keys in an Assoc
o Merge( Assoc assoc1, Assoc assoc2 )
Merges assoc2 into assoc1.
o NotSetValue()
Returns a unique data type constant which can be used as the "undefined value".
o ToRecord( Assoc a )
Converts an Assoc into a Record.
o UndefinedValue( Assoc a, [Dynamic value] )
Returns and optionally sets the "undefined value" of an Assoc.

Class Attributes

o AssocType 
 Integer AssocType

The type number for the Assoc data type.

Class Methods

o Copy 
 Assoc Copy(
          Assoc src )

Creates and returns a shallow copy of the specified source Assoc. This is necessary since Assocs are passed by reference, meaning that simple assignment does not copy an Assoc as it does with an Integer. The copying process follows the same conventions used in function parameter passing. Thus the contents of the copy will contain copies of those values in the source which are passed by value, and and references to those values in the source which are passed by reference. The following example illustrates this:

Assoc	a, b, b2, c
Dynamic	key
c.ok = TRUE
a.( 2006 ) = c
a.count = 1
b = Assoc.copy( a )	// copy
b2 = b			// assignment does not copy
b2.a = "a"		// modify the reference
b.alert = "Stop!"	// modify the copy itself
b.count += 1		// modify copy value
b.( 2006 ).ok = FALSE	// modify copy reference.
for key in Assoc.keys( b )
	Echo( "a.", key, " = ", a.( key ) )
	Echo( "b.", key, " = ", b.( key ) )
end

a.a = ?
b.a = a				// b2 mod referenced b
a.alert = ?
b.alert = Stop!			// copy mod local
a.count = 1
b.count = 2			// value mod local
a.2006 = A<1,?,'ok'=false>
b.2006 = A<1,?,'ok'=false>	// reference mod not local
Parameters:
src  -  The Assoc to copy.
Returns:
The new Assoc copy.
o CreateAssoc 
 Assoc CreateAssoc(
            [Dynamic value] )

Returns a new, empty Assoc whose "undefined value" will be Undefined or value if value is specified. The "undefined value" is the value returned by an Assoc when referenced by a key it does not contain.

Parameters:
value  -  The "undefined value" of the returned Assoc, which will be Undefined if this argument is not specified.
Returns:
A new, empty Assoc.
o Delete 
 Dynamic Delete(
             Assoc a,
             Dynamic key )

Removes the specified key from the Assoc if that Assoc contains the key.

Parameters:
a  -  The Assoc to remove a key/value pair from.
key  -  The key for the key/value pair to remove.
Returns:
The value removed, or the "undefined value" if the key was not found.
o FromRecord 
 Assoc FromRecord(
             Record rec )

Creates and returns a new Assoc containing the field names and corresponding columns of the specified Record as its String keys and associated values. As with Assoc.Copy(), the new Assoc returned will be a shallow copy of the Record.

Parameters:
rec  -  The Record from which an Assoc will be created.
Returns:
A new Assoc, copied from the Record.
o IsKey 
 Boolean IsKey(
            Assoc a,
            Dynamic key )

Returns true if the specified Assoc contains the specified key.

Parameters:
a  -  The Assoc whose key set is tested.
key  -  The key to test.
Returns:
True if the Assoc contains the key.
o Items 
 List Items(
         Assoc a )

Returns a List of the keyed values in a.

Parameters:
a  -  The Assoc whose values are returned in a List.
Returns:
A List of the keyed values in the Assoc.
o Keys 
 List Keys(
         Assoc a )

Returns a List of the keys in a.

Parameters:
a  -  The Assoc whose keys are returned in a List.
Returns:
A List of keys in the Assoc.
o Merge 
 Assoc Merge(
          Assoc assoc1,
          Assoc assoc2 )

The two Assocs are merged by copying the contents of assoc2 into assoc1. The copy process is the same as used for Assoc.Copy(). If a key is common to both Assocs, then the associated value in assoc1 will be replaced by that in assoc2, as shown by the following example:

Assoc		a, b, c
Dynamic		key
a.value = "a"
a.count = 1
b.value = "b"
b.ok = FALSE
c = Assoc.Merge( a, b )
for key in Assoc.Keys( a )
	Echo( "a.", key, " = ", a.( key ) )
end

a.count = 1	// only in a before merge
a.ok = false	// only in b before merge
a.value = b	// in both before merge, b superceded.
Parameters:
assoc1  -  Destination Assoc for merge.
assoc2  -  Assoc whose contents are copied into assoc1.
Returns:
A reference to the first assoc passed in.
o NotSetValue 
 NotSet NotSetValue()

Returns a unique data type constant useful as the "undefined value" for an Assoc when Undefined or other values will not work since they might be keys within the Assoc. Use with Assoc.CreateAssoc() or Assoc.UndefinedValue().

Returns:
A unique data type constant useful as the "undefined value" for an Assoc.
o ToRecord 
 Record ToRecord(
             Assoc a )

Creates a new Record and returns it after copying the values of the given Assoc into it, translating String keys and values into field names and column entries. The Assoc should only contain String keys. As with Assoc.Copy(), the new Assoc returned will be a shallow copy of the Record.

Parameters:
a  -  The Assoc to convert into a new Record.
Returns:
A new Record copied from the Assoc.
o UndefinedValue 
 Dynamic UndefinedValue(
                 Assoc a,
                [Dynamic value] )

Returns the "undefined value" for the specified Assoc. If value is specified than the "undefined value" for the Assoc will be changed to value (meaning value will be returned).

Parameters:
a  -  The Assoc whose "undefined value" is queried and optionally set.
value  -  If specified, then the "undefined value" of a will be set to this.
Returns:
The "undefined value" for the Assoc.