The Associative Array Object
By Matt Galanto

Index

Disclaimer

This object uses the Blowfish encryption algorithm. Please check with your local laws concerning encryption and exportation before offering, or selling, any encryption tools for public or for private use. The laws concerning the strength and type of encryption used vary, and you may be subject to restrictions and even criminal penatlies for failure to comply.

The author of this extension makes no claims concerning the fitness of this extension for any purpose whatsoever, and makes no gurantees, written or implied, of its level of security and safety to authors or to end users in any respect. You agree to use this extension at your own risk and to hold the author harmless in any event.

The Basics

The Associative Array Object works very much like a normal array. The main difference is that an associative array uses string indices (called keys) wheras a normal array uses numeric indices. In a normal array, you might say, "Get the value at index 5." In an associative array, you might say, "Get the value at key 'Matt'." Another difference between normal arrays and this Associative Array Object is that the Associative Array Object stores both a value (that is, a number) and a string at eack key. It does not create separate keys for strings and values.
Addresses: The Associative Array Object allows you to have indirect access to locations in memory (that is, addresses of data). You can use these addresses to access the elements in the associative array without having to know the keys for the elements. It also allows you to access and modify strings and values without constantly having to search for keys. For big associative arrays, using addresses is much more efficient. WARNING: If you enter a bad address (some number you made up, the address of key that you deleted, etc.), you run the risk of crashing your application or otherwise mess things up, so be careful. The only bad address that is safe to use is 0, which is returned by the Associative Array Object in many situations.

Upgrading from Version 1.13 or Earlier

In earlier versions of this object, global objects and sub-applications did not work together. You may have taken alternative measures. The problems have been fixed in this version. The changes are such that you may need to rework any applications that use global Associative Arrays in sub-applications. For information, check out the Global Data and Sub-Applications section.

Global Data

The Associative Array object's set-up dialog allows you to set the object's data to be global. If you select this option, that object will keep its data over frames. Exactly what data it will keep:
- All keys and their strings and values
- Key found in the last 'Key Exists' condition
- Last error code
- File loading and saving intervals
If you're loading or saving a file, have data set to be global, and change frames, the object will immediately stop loading or saving. The loading and saving will not be continued on the next frame.

In order for an Associative Array object to keep data over frames, the objects in both frames must:
- Have the same name
- Both be set as global
There is a "bug" in MMF where names get truncated at run-time if they're longer than 24 characters, so if you have say "Associative Array Object" and "Associative Array Object 2", at run-time, both names will be the same because the second one gets truncated to "Associative Array Object". This will cause problems with the global data.

Global Data and Sub-Applications

An interesting question arises when one thinks about using global data and sub-applications. What you tend to have are two global objects (with the same name) existing simultaneously. How should these two global objects interact? Well, in the Associative Array object, two global objects existing simultaneously share the same exact data. Changing a key in one, modifies a key in the other. Loading a file in one, loads it in the other. There are some quirks to be aware of when using two simultaneous global Associative Array objects:
- If an error occurs in an action or in a condition, the error is only generated in the object in which the error occured. It is not generated in the other global objects.

Conditions

Does a Certain Key Exist?
This condition returns true if the specified key is found in the array.

Do So Many Keys Starting With a Substring Exist?
This condition returns true if the specified number of keys exist that start with the specified substring. The last key found is the nth key starting wth the specified substring, where n is the specified number of keys. For example, if you check for 3 keys, the third key found would be the last key found regardless of how many keys there are that start with the substring.

Do So Many Keys Ending With a Substring Exist?
This condition returns true if the specified number of keys exist that end with the specified substring. The last key found is the nth key ending wth the specified substring, where n is the specified number of keys. For example, if you check for 3 keys, the third key found would be the last key found regardless of how many keys there are that end with the substring.

Do So Many Keys Containing a Substring Exist?
This condition returns true if the specified number of keys exist that contain the specified substring. The last key found is the nth key containing the specified substring, where n is the specified number of keys. For example, if you check for 3 keys, the third key found would be the last key found regardless of how many keys there are that contain the substring.

Result of Last 'Key Exists' Condition
This condition will return the result of the last 'Key Exists' condition. In other words, if the last search found a key, this will return true. If not, it will return false.

File is Loading
This condition returns true if a file is currently being loaded.

File is Saving
This condition returns true if a file is currently being saved.

File is Done Loading
This condition is a true event condition. That means that events having this condition will be executed as soon as a file is finished successfully being loaded.

File is Done Saving?
This condition is a true event condition. That means that events having this condition will be executed as soon as a file is finished successfully being saved.

Has the Array Been Modified?
This condition returns true if the array has been modified since the last time the a file was saved or loaded or since the last time the array was cleared.

Is the Array Empty?
This returns true if the array is empty.

Has an Error Occured?
This condition is a true event condition. That means that events having this condition will be executed as soon as an error is encountered in an ACTION or CONDITION by the Associative Array Object (and only when an error is encountered). It will return true when the Error Number is greater than 0, which will always be the case when an error is encountered. To check for errors in expressions, use the Get the Current Expression Error Number expression.

Actions

Modify/Add a Value
This action will change the value at the specified key to the specified value. If the key does not exist, it will be created. If the key is created, its string will be set to "".

Add to a Value
This action adds a number to the value at the specified key. If the key does not exist, an error (code 6) is generated.

Subtract from a Value
This action subtracts a number from the value at the specified key. If the key does not exist, an error (code 6) is generated.

Multiply a Value
This action multiplies the value at the specified key by a number. If the key does not exist, an error (code 6) is generated.

Divide a Value
This action divides the value at the specified key by a number. If the key does not exist, an error (code 6) is generated.

Modulus a Value
This action modulus the value at the specified key by a number. If the key does not exist, an error (code 6) is generated.

Operate on a Value
This action performs the specified operation on value at the specified key using the specified number as the second operand. If the key does not exist, an error (code 6) is generated. Acceptable operations are + (addition), - (subtraction), * (multiplication), / (division), and % (modulus). Any other operation will reuslt in an error (code 12) being generated. Note: Only the first character of the operation string is looked at.

Modify/Add a String
This action will change the string at the specified key to the specified string. If the key does not exist, it will be created. If the key is created, its value will be set to 0.

Modify/Add a Value at an Address
This action will change the value at the specified address to the specified value. If the address is bad (that is, 0), it will generate an error (code 5).

Modify/Add a String at an Address
This action will change the string at the specified address to the specified string. If the address is bad (that is, 0), it will generate an error (code 5).

Delete a Key
This action deletes the specified key. If the key is not found, this action returns an error (code 6).

Clear the Array
This actions deletes all of the keys from the array.

Crop with Respect to the Start of Keys
This action removes keys from the array. If Include is 0, keys starting with the given substring are removed from the array. If Include is 1, keys starting with the given substring are included (or left) in the array while every other key is removed.

Crop with Respect to the End of Keys
This action removes keys from the array. If Include is 0, keys ending with the given substring are removed from the array. If Include is 1, keys ending with the given substring are included (or left) in the array while every other key is removed.

Crop with Respect to the Contents of Keys
This action removes keys from the array. If Include is 0, keys containing the given substring are removed from the array. If Include is 1, keys containing the given substring are included (or left) in the array while every other key is removed.

Copy All Keys
This action copies all of the keys of the array with the specified array address to the array.

Copy with Respect to the Start of Keys
This action copies keys of the array with the specified array address to the array. If Include is 1, keys starting with the given substring are copied from the array. If Include is 0, keys starting with the given substring are not copied from the array.

Copy with Respect to the End of Keys
This action copies keys of the array with the specified array address to the array. If Include is 1, keys ending with the given substring are copied from the array. If Include is 0, keys ending with the given substring are not copied from the array.

Copy with Respect to the Contents of Keys
This action copies keys of the array with the specified array address to the array. If Include is 1, keys containing the given substring are copied from the array. If Include is 0, keys containing the given substring are not copied from the array.

Set File Loading Interval
This action sets the interval (in millisecond) at which the object will temporarily stop loading a file and allow MMF to execute one program loop. If the interval is 0, the entire file will be loaded all at once. If the interval is not 0, the file will not start being loaded until the end of the current MMF loop.

Set to Load Entire File All at Once
This action sets the loading interval to 0 so that the entire file will be loaded all at once.

Set File Saving Progress Update Interval
This action sets the interval (in millisecond) at which the object will temporarily stop saving a file and allow MMF to execute one program loop. If the interval is 0, the entire file will be saved all at once. If the interval is not 0, the file will not start being saved until the end of the current MMF loop.

Set to Save Entire File All at Once
This action sets the saving interval to 0 so that the entire file will be saved all at once.

Set Encryption Key
This action sets the encryption key to be used with the Load/Save Encrypted Array File actions. You must set the key before using those functions. The key may be a maximum of 56 characters. Anything longer will be truncated to 56 characters.

Load an Encrypted Associative Array File
This actions loads an Encrypted Array File using the current encryption key and using the specified Method number. If you attempt to load an array using the wrong key, an error will be generated. Using a wrong method will simply load gibberish.

Save an Encrypted Associative Array File
This actions saves an Encrypted Array File using the current encryption key and using the specified Method number. If you attempt to save an array before setting the key, an error will be generated. The Method number provides slightly more encryption just as it does for normal array files.

Load an Associative Array File
This actions loads in a file saved with the 'Save an Associatve Array File' action. In order to successfully load an Associatve Array File, you must use the Method number used when saving the file. Otherwise, you will just load in useless gibberish.

Save an Associative Array File
This action saves an encrypted file containing all of the data (both strings and values) stored in the array. The Method number determines how the file will be encrypted (using 0 will leave the file unencrypted). You will need to use the same Method number you use here in order to load the Associatve Array File later, so don't forget it!

Load an INI into Strings
This action clears the array and loads the data from the specified INI file. Each item in loaded as a key, and the item's string is stored as a string at the key. Groups are ignored in this action.

Load an INI into Strings and Keep Group Info
This action clears the array and loads the data from the specified INI file. Each item is loaded as key in this format: groupnamedelimiteritemname. The item's string is stored as a string at the key.

Load an INI into Values
This action clears the array and loads the data from the specified INI file. Each item in loaded as a key, and the item's string is converted stored as a value at the key. Groups are ignored in this action.

Load an INI into Values and Keep Group Info
This action clears the array and loads the data from the specified INI file. Each item is loaded as key in this format: groupnamedelimiteritemname. The item's string is converted and stored as a value at the key.

Load an INI into Strings and into Values
This action clears the array and loads the data from the specified INI file. Each item in loaded as a key, and the item's string is stored as a string and as a value at the key. Groups are ignored in this action.

Load an INI into Strings and into Values and Keep Group Info
This action clears the array and loads the data from the specified INI file. Each item is loaded as key in this format: groupnamedelimiteritemname. The item's string is stored as a string and as a value at the key.

Save an INI from Strings
This action saves the data in the array to the specified file. It stores data in this format: key=string. This action will not save the values stored at keys.

Save an INI from Strings and Keep Group Info
This action saves the data in the array to the specified file. It uses the delimiter to separate group names and item names for the INI. For example, if the delimiter is set to "|++|" and if the current key is "gargle|++|cramped", this action will put cramped=string under group gargle in the INI file. This action will not save the values stored at keys.

Save an INI from Values
This action saves the data in the array to the specified file. It stores data in this format: key=value. This action will not save the strings stored at keys.

Save an INI from Values and Keep Group Info
This action saves the data in the array to the specified file. It uses the delimiter to separate group names and item names for the INI. For example, if the delimiter is set to "|++|" and if the current key is "gargle|++|cramped", this action will put cramped=value under group gargle in the INI file. This action will not save the strings stored at keys.

Save an INI from Strings with Exclusion
This action saves the data in the array to the specified file. It stores data in this format: key=string or value. This action will save the string stored at a key so long as the string is not equal to the exclusion string. If it is equal to the exclusion string, the action will save the value stored at the key instead.

Save an INI from Strings with Exclusion and Keep Group Info
This action saves the data in the array to the specified file. It uses the delimiter to separate group names and item names for the INI. For example, if the delimiter is set to "|++|" and if the current key is "gargle|++|cramped", this action will put cramped=string or value under group gargle in the INI file. This action will save the string stored at a key so long as the string is not equal to the exclusion string. If it is equal to the exclusion string, the action will save the value stored at the key instead.

Save an INI from Values with Exclusion
This action saves the data in the array to the specified file. It stores data in this format: key=string or value. This action will save the value stored at a key so long as the value is not equal to the exclusion value. If it is equal to the exclusion value, the action will save the string stored at the key instead.

Save an INI from Values with Exclusion and Keep Group Info
This action saves the data in the array to the specified file. It uses the delimiter to separate group names and item names for the INI. For example, if the delimiter is set to "|++|" and if the current key is "gargle|++|cramped", this action will put cramped=string or value under group gargle in the INI file. This action will save the value stored at a key so long as the value is not equal to the exclusion value. If it is equal to the exclusion value, the action will save the string stored at the key instead.

Load a List File
This action clears the array and loads the specified list file, which is file containing a list of elements separated by line breaks. Each element in the list is loaded as key with a string of "" and a value of 0.

Save a List File
This action saves the data in the array to the specified file. The keys are saved as a list with elements separated by line breaks. Strings and values are not saved.

Clear Expression Error Code
This action clears the expression error code, setting it to 0.

Expressions

Get a Value from a Key
GetValue(Object Name, Key)
Returns the value stored at the specified key. If the key is not found, returns 0 and generates an error (code 6).

Get a String from a Key
GetString$(Object Name, Key)
Returns the string stored at the specified key. If the key is not found, returns "" and generates an error (code 6).

Get the Value from the Key Found in the Last 'Key Exists' Condition
GetValueAtFoundKey(Object Name)
Returns the value of the key found in the lasy 'Key Exists' search. If no key was found in the last search, returns 0 and generates an error (code 7).

Get the String from the Key Found in the Last 'Key Exists' Condition
GetStringAtFoundKey$(Object Name)
Returns the string of the key found in the lasy 'Key Exists' search. If no key was found in the last search, returns "" and generates an error (code 7).

Get Address of First Element in Array
GetFirstAddress(Object Name)
Returns the address of the first element in the array. If the array is empty, returns 0 and generates an error (code 8).

Get Address of Last Element in Array
GetLastAddress(Object Name)
Returns the address of the last element in the array. If the array is empty, returns 0 and generates an error (code 8).

Get Address of a Key
GetAddress(Object Name, Key)
Returns the address of the specified key. If the key is not found, returns 0 and generates an error (code 6).

Get the Address of the Key Found in the Last 'Key Exists' Condition
GetAddressOfFoundKey(Object Name)
Returns the address of the key found in the lasy 'Key Exists' search. If no key was found in the last search, returns 0 and generates an error (code 7).

Get the Address of the nth Key Starting With a Substring
GetAddyKeysStart(Object Name, Substring, n, Address)
Returns the address of the nth key that starts with the specified substring. The search begins at the element at the specified address. Returns 0 if there are not n keys starting with the substring.

Get the Address of the nth Key Ending With a Substring
GetAddyKeysEnd(Object Name, Substring, n, Address)
Returns the address of the nth key that ends with the specified substring. The search begins at the element at the specified address. Returns 0 if there are not n keys ending with the substring.

Get the Address of the nth Key Containing a Substring
GetAddyKeysContain(Object Name, Substring, n, Address)
Returns the address of the nth key that contains the specified substring. The search begins at the element at the specified address. Returns 0 if there are not n keys containing the substring.

Get a Value from an Address
GetValueAtAddress(Object Name, Address)
Returns the value stored at the specified address. If the address is bad (that is, 0), returns 0 and generates an error (code 5).

Get a String from an Address
GetStringAtAddress$(Object Name, Address)
Returns the string stored at the specified address. If the address is bad (that is, 0), returns "" and generates an error (code 5).

Get a Key from an Address
GetKeyAtAddress$(Object Name, Address)
Returns the key at the specified address. If the address is bad (that is, 0), returns "" and generates an error (code 5).

Get Address of Previous Element in Array
GetNextAddress(Object Name, Address)
Returns the address of the element before the element at the specified address in the array. If the address is bad (that is, if it's 0 or if the it's the address of the first element in the array), returns 0 and generates an error (code 5).

Get Address of Next Element in Array
GetPreviousAddress(Object Name, Address)
Returns the address of the element after the element at the specified address in the array. If the address is bad (that is, if it's 0 or if the it's the address of the last element in the array), returns 0 and generates an error (code 5).

Get File Progress (percentage)
GetFileProgress(Object Name)
Returns the current percentage of the file that has been loaded or saved.

Get File Loading Interval
GetLoadInterval(Object Name)
Returns the loading interval.

Get File Saving Interval
GetSaveInterval(Object Name)
Returns the saving interval.

Get the Number of Keys Starting with a Substring
GetNumKeysStart(Object Name, Substring)
Returns the number of keys in the array that start with the specified substring.

Get the Number of Keys Ending with a Substring
GetNumKeysEnd(Object Name, Substring)
Returns the number of keys in the array that end with the specified substring.

Get the Number of Keys Containing a Substring
GetNumKeysContain(Object Name, Substring)
Returns the number of keys in the array that contain the specified substring.

Get the Number of Elements in the Array
GetSize(Object Name)
Returns the number of elements (or keys) in the array. That is, returns the size of the array.

Get the Current Error Number
GetError(Object Name)
Returns the current error number. That is, returns the number of the last error encountered in an ACTION or CONDITION. Here's what each error number means:
0: No errors
1: Error opening file
2: Error writing to file
3: Error reading from file
4: Delimiter cannot be "" when saving to INI
5: Bad address (that is, you used 0 for an address somewhere)
6: Key not found
7: Cannot access data because last 'Key Exists' Search failed
8: Array is empty and does not have a First or Last element
9: Cannot work with files while load or save is in progress
10: Cannot modify array while load or save is in progress
11: Cannot divide by 0
12: Invalid operator
13: Cannot save files in Vitalize mode
14: Invalid array address
15: Cannot save/load encrypted files without setting key
16: Cannot create key ""

Get the Current Expression Error Number
GetExpressionError(Object Name)
Returns the current expression error number. That is, returns the number of the last error encountered in an expression.

Get the Array's Address
GetArrayAddress(Object Name)
Returns the address of the array. This value is needed in the array copying actions.

Go Back to Matt's MMF Objects

Go to Clickteam's Web Site

Go to Bumderland