The Associative
Array Object
By Matt Galanto
Index
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 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.
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.
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.
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.
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.