The Pack-X Object for Multimedia Fusion
This object preforms the (apparently useful) task of "packing" a string into a number, and unpacking it again. This allows you to store strings into Alterable values, or into numeric array items.
However, the strings converted to numbers cannot be very long, so they will fit in an integer. Hopefully, this will not be too much of a problem for you.
Keys
When you pack or unpack a string, it is useful to tell the object which characters you may potentially use. This is called the 'key'. For example, if you know your just going to use the letters between A and Z, there is no point wasting memory on numbers or lower case letters.
Every expression and condition in this object uses this key, so how the key works and how you express it is discussed first, and how the expressions, conditions and actions work is explored later.
The key is simply a list of letters you are using. For example, if the string you wanted to pack was representing DNA, you know it would only include the letters ATCG. So they key would be "ATCG". However, if you were storing an abbreviated name for a name of an object to be stored in an array, for example, you know you'd be using "ABCDEFGHIJKLMNOPQRSTUVWXYZ". Although that would be a valid key, it is hardly concise. To quickly write ranges in a key, you may use a range. A range is contained within a pair of square brackets, like this:
[A-Z]
You can also mix ranges with other values. For example:
[A-Z]!
That allowed A through to Z, and an exclamation mark. You may also mix multiple ranges and individual values. For example:
[A-Z][a-z][0-9]()_
The above key allows A through to Z in both upper and lower case, and the digits. It also allowed left and right parenthesis and underscores.
[Z-A] is recognized as the same as [A-Z]
Although, for example, [!-^] is valid, it probably does not make sense. If you must use a range like this, it is worth checking which characters you will be including on an ANSI character map.
You may also do [A-z], but note this is not the same as [A-Z][a-z], since there are other characters in between A and z, so it is not recommended. Also, note [a-Z]is different, and will only include a, z and some symbols like _and ^
Ranges add a problem though. What happens if you want to use [ or ] as an individual item? You'd run the risk of confusing PackX into thinking your defining a range. The solution is to escape the [ and ] characters using the \ character. For example:
\[\][A-Z]
...allows A to Z, and both square brackets. You can use these escape sequences.
The disadvantage of using more characters in a key is that you will be able to store less in it. For example, you can only fit 6 characters in "[A-Z]", however you can fit many more in "ATGC".
When you Unpack a number back into a string, you must use exactly the same key as you used to pack it, otherwise you will get strange results.
How to set the key
You set the key with the Set Key action. A prompt box pops up for you to put in your key.
Now you know how to write keys, lets look at the basic expressions
Pack String into Number
This turns a string into a number, using a key. When you select it from the dialog invoked by the "Retrieve data from an object" button, the following appears in the Expression Evaluator:
PackX( "PackX Object", > Enter string here < )
The > Enter string here <should be replaced with the string you want to pack. For example, you might set an objects alterable value to:
PackX( "PackX Object", "SPRITE" )
Unpack number into String
Once you have packed a string into a number, at some point you'll probably want to get the original string back. To do this, use the Unpack expression. When you select it from the dialog invoked by the "Retrieve data from an object" button, the following appears in the Expression Evaluator:
UnPackX$( "PackX Object", > Enter value here < )
The > Enter value here < should be replaced with the number you wish to unpack. Remember to set the key to the same as you used to pack it.
These two expressions are all that is needed to work most of Pack-Xes magic. However, there are 2 additional expressions that you might need:
Find Max Length for Key
As I have mentioned many times before, the size of the string you can store is very limited, and also dependent on the key. This expression is used to find the maximum safe length of a string you can store with it.
The expression is:
MaxLen( "PackX Object" )
It uses the current key.
Note that if you attempt to pack a string too long into a number, it will cut the size of the string automatically.
Count the amount of chars in a key
I'm not quite sure why you'd want to, but at some point you might wish to count the amount of characters are contained within a key. (You cannot just use the len expression to find this out, because of ranges.)
The expression is:
MaxLen( "PackX Object" )
It, of course, uses the current key.
Conditions
There is a condition to make it easy to check if a string is short enough for to be packed using a key. This condition should be self explanatory.
Notes
Note that when you pack a string, if it contains characters that are not in the key, the characters will just be ignored. There will be no errors. So this means if you packed "Jax" into "[a-z]", and then unpacked it again using the same key, you'd get "ax".
The End
This object, and its examples and documentation, is written by Jack Webster. It was developed using CICK (Made life so much easier!), by Dan Burke, used Firemonekys SDK, and I did it because Fodo told me to ages ago. It is free to use for any purpose, and it is included with source code. You may improve this object and re-release it (With or without source-code) without limitation (So long as you state it uses my code).
This document was written in OpenOffice.org.