Script Array Upgrade
by Daniel Neilsen · 10/17/2003 (11:29 am) · 80 comments
Download Code File
This is a powerful array class which adds php style arrays to TGE script.
This means you can do the following:
- array pointers
This allows you to move forwards or backwards through the array
as if it was a list including jumping to the start or end
- sorting
You can sort in either alpha or numeric mode on the key or the
value in ascending or descending order
- adding and removing of elements from any array position
You can pop and push elements from the start and end of the
array and also insert or erase elements in the middle of the
array.
- removal of duplicates
You can remove duplicate keys or duplicate values.
- searching
You can search the array and return the index of a particular
key or value value
- Advanced Features
Several other advanced features like array appends, array
cropping and array duplication.
- Counting
Count the number of instaces of a particular value or key in
the array, as well as the number of elements
This array class will also support both string and number values.
INSTALLATION:
1) Backup your stuff
2) BACK IT UP!
3) Copy the arrayObject.cc file into the /engine/console dir
4) Compile
I have tested it with the latest head (release 1.2) but I am pretty sure it would work for all versions of TGE.
USAGE:
In script you can do the following
%myarray = new array();
%myarray.add(%key, %value);
%myarray.add("bla", 5.34);
%myarray.add("bla", "test");
COMMANDS:
add() - (string key, string value)Adds a new element to the end of an array
append() - (Array target)Appends the target array to the array object
count() - Get the number of elements in the array
countKey() - (string key)Get the number of times a particular key is found in the array
countValue() - (string value)Get the number of times a particular value is found in the array
crop() - (Array target)Removes elements with matching keys from array
duplicate() - (Array target)Alters array into an exact duplicate of the target array
echo() - Echos the array in the console
empty() - Emptys all elements from an array
erase() - (int index)Removes an element at a specific position from the array
getCurrent() - Gets the current pointer index
getIndexFromKey() - (string key)Search array from current position for the first matching key
getIndexFromValue() - (string value)Search array from current position for the first matching value
getKey() - (int index)Get the key of the array element at the submitted index
getValue() - (int index)Get the value of the array element at the submitted index
insert() - (string key, string value, int index)Adds a new element to a specified position in the array
moveFirst() - Moves array pointer to start of array
moveLast() - Moves array pointer to end of array
moveNext() - Moves array pointer to next position (returns -1 if cannot move)
movePrev() - Moves array pointer to prev position (returns -1 if cannot move)
pop_back() - Removes the last element from the array
pop_front() - Removes the first element from the array
push_back() - (string key, string value)Adds a new element to the end of an array
push_front() - (string key, string value)Adds a new element to the front of an array
sort() - (bool desc)Sorts the array by value (default ascending sort)
sorta() - Alpha sorts the array by value in ascending order
sortd() - Alpha sorts the array by value in descending order
sortkd() - Alpha sorts the array by key in descending order
sortka() - (bool desc)Sorts the array by key (default ascending sort)
sortn() - (bool desc)Sorts the array numerically by value (default ascending sort)
sortna() - Numerical sorts the array by value in ascending order
sortnd() - Numerical sorts the array by value in descending order
sortnka() - Numerical sorts the array by key in ascending order
sortnkd() - Numerical sorts the array by key in descending order
uniqueKey() - Removes any elements that have duplicated keys (leaving the first instance)
uniqueValue() - Removes any elements that have duplicated values (leaving the first instance)
Thats about it.
Any questions about usage or whatever, just post em here
Edit (28/10/03):
Added setValue and setKey methods - was a bit of an oversight to have missed them ;)
This is a powerful array class which adds php style arrays to TGE script.
This means you can do the following:
- array pointers
This allows you to move forwards or backwards through the array
as if it was a list including jumping to the start or end
- sorting
You can sort in either alpha or numeric mode on the key or the
value in ascending or descending order
- adding and removing of elements from any array position
You can pop and push elements from the start and end of the
array and also insert or erase elements in the middle of the
array.
- removal of duplicates
You can remove duplicate keys or duplicate values.
- searching
You can search the array and return the index of a particular
key or value value
- Advanced Features
Several other advanced features like array appends, array
cropping and array duplication.
- Counting
Count the number of instaces of a particular value or key in
the array, as well as the number of elements
This array class will also support both string and number values.
INSTALLATION:
1) Backup your stuff
2) BACK IT UP!
3) Copy the arrayObject.cc file into the /engine/console dir
4) Compile
I have tested it with the latest head (release 1.2) but I am pretty sure it would work for all versions of TGE.
USAGE:
In script you can do the following
%myarray = new array();
%myarray.add(%key, %value);
%myarray.add("bla", 5.34);
%myarray.add("bla", "test");
COMMANDS:
add() - (string key, string value)Adds a new element to the end of an array
append() - (Array target)Appends the target array to the array object
count() - Get the number of elements in the array
countKey() - (string key)Get the number of times a particular key is found in the array
countValue() - (string value)Get the number of times a particular value is found in the array
crop() - (Array target)Removes elements with matching keys from array
duplicate() - (Array target)Alters array into an exact duplicate of the target array
echo() - Echos the array in the console
empty() - Emptys all elements from an array
erase() - (int index)Removes an element at a specific position from the array
getCurrent() - Gets the current pointer index
getIndexFromKey() - (string key)Search array from current position for the first matching key
getIndexFromValue() - (string value)Search array from current position for the first matching value
getKey() - (int index)Get the key of the array element at the submitted index
getValue() - (int index)Get the value of the array element at the submitted index
insert() - (string key, string value, int index)Adds a new element to a specified position in the array
moveFirst() - Moves array pointer to start of array
moveLast() - Moves array pointer to end of array
moveNext() - Moves array pointer to next position (returns -1 if cannot move)
movePrev() - Moves array pointer to prev position (returns -1 if cannot move)
pop_back() - Removes the last element from the array
pop_front() - Removes the first element from the array
push_back() - (string key, string value)Adds a new element to the end of an array
push_front() - (string key, string value)Adds a new element to the front of an array
sort() - (bool desc)Sorts the array by value (default ascending sort)
sorta() - Alpha sorts the array by value in ascending order
sortd() - Alpha sorts the array by value in descending order
sortkd() - Alpha sorts the array by key in descending order
sortka() - (bool desc)Sorts the array by key (default ascending sort)
sortn() - (bool desc)Sorts the array numerically by value (default ascending sort)
sortna() - Numerical sorts the array by value in ascending order
sortnd() - Numerical sorts the array by value in descending order
sortnka() - Numerical sorts the array by key in ascending order
sortnkd() - Numerical sorts the array by key in descending order
uniqueKey() - Removes any elements that have duplicated keys (leaving the first instance)
uniqueValue() - Removes any elements that have duplicated values (leaving the first instance)
Thats about it.
Any questions about usage or whatever, just post em here
Edit (28/10/03):
Added setValue and setKey methods - was a bit of an oversight to have missed them ;)
About the author
#62
Ok, thanks for following up. Looking into this now, will probably create a variant of the Array class that only allows floating point values to come around the whole string management issue.
However I've found a previously unmentioned bug in insert(). When trying to insert an element while there are no elements in the array you will get a crash. The code assumes that the U32 in the function can't go below 0 but in fact it is not handled correctly. I just changed the type to S32 to fix it.
09/01/2008 (8:37 am)
@ThomasOk, thanks for following up. Looking into this now, will probably create a variant of the Array class that only allows floating point values to come around the whole string management issue.
However I've found a previously unmentioned bug in insert(). When trying to insert an element while there are no elements in the array you will get a crash. The code assumes that the U32 in the function can't go below 0 but in fact it is not handled correctly. I just changed the type to S32 to fix it.
// Adds a new array item to a particular index of the array
void Array::insert(StringTableEntry key, StringTableEntry value, U32 index)
{
index = mClampF(index, 0, mArray.size()-1);
S32 size = mArray.size() - 1;
for(S32 i=size; i>=(S32)index; i--)
{
moveIndex(i, i+1);
}
Element temp;
temp.value = value;
temp.key = key;
mArray[index] = temp;
} 
#63
We have happened upon a flaw however: getKey() and getValue() truncate the return values to 99 characters.
the fix is simple:
arrayObject.cc
replace this:
11/03/2008 (10:39 am)
This is a great resource.We have happened upon a flaw however: getKey() and getValue() truncate the return values to 99 characters.
the fix is simple:
arrayObject.cc
replace this:
ConsoleMethod( Array, getValue, const char*, 3, 3, "(int index)"
"Get the value of the array element at the submitted index")
{
StringTableEntry key = object->getValueFromIndex(dAtoi(argv[2]));
char* buff = Con::getReturnBuffer(100);
dSprintf(buff,100,"%s",key);
return buff;
}
ConsoleMethod( Array, getKey, const char*, 3, 3, "(int index)"
"Get the key of the array element at the submitted index")
{
StringTableEntry key = object->getKeyFromIndex(dAtoi(argv[2]));
char* buff = Con::getReturnBuffer(100);
dSprintf(buff,100,"%s",key);
return buff;
}with this:ConsoleMethod( Array, getValue, const char*, 3, 3, "(int index)"
"Get the value of the array element at the submitted index")
{
StringTableEntry ret = object->getValueFromIndex(dAtoi(argv[2]));
return ret; // oxe 20081103 - no need to use the return buffer mechanism because StringTableEntries are write-once read-many.
}
ConsoleMethod( Array, getKey, const char*, 3, 3, "(int index)"
"Get the key of the array element at the submitted index")
{
StringTableEntry ret = object->getKeyFromIndex(dAtoi(argv[2]));
return ret; // oxe 20081103 - no need to use the return buffer mechanism because StringTableEntries are write-once read-many.
} 
#64
02/15/2009 (3:51 pm)
No words can aptly describe how useful this resource is...Thanks so much! 
#65
arrayobject.zip - 2009-04-15
04/15/2009 (2:46 am)
Great resource, and fantastic fixes! As my thanks, I decided to host a recent version of the resource that has all the changes up until now:arrayobject.zip - 2009-04-15
#66
04/15/2009 (10:38 pm)
Thank Konrad, I used your zip and it works fine in TGEA 1.8.1. 
#67
And thanks Kornard for hosting the latest version, it is exactly what I need!
05/14/2009 (1:09 am)
It is really a great resource @Daniel, very very useful. Thanks!And thanks Kornard for hosting the latest version, it is exactly what I need!
#68
05/20/2009 (10:54 am)
Glad to see it made it into the T3D trunk as ArrayObject, though I'm still using the older Array code for TGEA 1.8.1.
#69
repro: at the console, enter the following:
new Array().getValue(0);
fix:
in arrayObject.cc, change this segment:
to this:
comparing for equality to zero is obvious,
and i also removed the useless test against less-than-zero, since it's an unsigned value.
06/11/2009 (2:01 pm)
not sure if this has been caught previously or not, but there is a bug in getValueFromIndex() and getKeyFromIndex().repro: at the console, enter the following:
new Array().getValue(0);
fix:
in arrayObject.cc, change this segment:
// Returns the key for a given index.
// Will return a null value for an invalid index
StringTableEntry Array::getKeyFromIndex(U32 index)
{
if(index > m_Array.size() || index < 0)
return NULL;
return m_Array[index].first;
}
// Returns the value for a given index.
// Will return a null value for an invalid index
StringTableEntry Array::getValueFromIndex(U32 index)
{
if(index > m_Array.size() || index < 0)
return NULL;
return m_Array[index].second;
}to this:
// Returns the key for a given index.
// Will return a null value for an invalid index
StringTableEntry Array::getKeyFromIndex(U32 index)
{
if(index >= m_Array.size())
return NULL;
return m_Array[index].first;
}
// Returns the value for a given index.
// Will return a null value for an invalid index
StringTableEntry Array::getValueFromIndex(U32 index)
{
if(index >= m_Array.size())
return NULL;
return m_Array[index].second;
}comparing for equality to zero is obvious,
and i also removed the useless test against less-than-zero, since it's an unsigned value.
#70
06/11/2009 (2:07 pm)
@Orion: I think the index < 0 was there because the getIndexFrom* functions can return -1. Of course with the U32 index that won't work, so for that less than zero check to work, the U32 index declaration needs to be changed to S32 index.
#71
06/11/2009 (3:18 pm)
so what will happen, i imagine is that if you do getKeyFromIndex(-1) it will be interpreted as getKeyFromIndex(0xffffffff), and unless you actually have 2^32 elements in your array, it will fail in index >= m_Array.size(). so the behaviour should happen to be correct, but it seems the resource could use a U32-vs-S32 consistency pass.
#72
Actually, the download I have above has this change already.
06/11/2009 (10:22 pm)
I agree, everything that deals with indexes should be signed.Actually, the download I have above has this change already.
#74
08/04/2009 (11:29 pm)
There is a bug in 2 functions, here is the fix.ConsoleMethod( ArrayObject, setKey, void, 4, 4, "(string key, int index)"
"Set the key at the given index" )
{
StringTableEntry key = StringTable->insert( argv[2], object->isCaseSensitive() );
U32 index = dAtoi( argv[3] ); //changed
object->setKey( key, index );
}
ConsoleMethod( ArrayObject, setValue, void, 4, 4, "(string value, int index)"
"Set the value at the given index" )
{
StringTableEntry value = StringTable->insert( argv[2], object->isCaseSensitive() );
U32 index = dAtoi( argv[3] ); //changed
object->setValue( value, index );
}
#75
If you don't have unique key, this will not work. This is the way it have been designed.
I hope this help.
08/04/2009 (11:49 pm)
I suggest you add also this function which allows to get a value from its key. I use the same method as the current getIndexfromKey... which means it will take the value from the first key matching the input.If you don't have unique key, this will not work. This is the way it have been designed.
I hope this help.
ConsoleMethod( ArrayObject, getValueFromKey, const char*, 3, 3, "(string key)"
"Get the value of the array element at the first submitted key" )
{
StringTableEntry value = StringTable->insert( argv[2], object->isCaseSensitive() );
U32 index = object->getIndexFromKey( value );
StringTableEntry key = object->getValueFromIndex(index);
char *buff = Con::getReturnBuffer( 512 );
dSprintf( buff, 512, "%s", key );
return buff;
} 
#76
If anyone does have improvements to, or found bugs with, the version of ArrayObject that now exists in T3D please post those on the T3D forums rather than here.
08/30/2009 (2:13 pm)
I think everyone here is talking about this actual resource, but, just for clarification... If anyone does have improvements to, or found bugs with, the version of ArrayObject that now exists in T3D please post those on the T3D forums rather than here.
#77
how about if it updates this resource and T3D, So be it kept here as long as it updates our array and works for our updates, why would you want ONLY community updates to be only for t3d. Thats sort of WRONG ! Considering the T3D arrayclass is basically the same thing. So please, I ask you, very nicely. Leave this resource alone, im sure the people are smart enough to figure out. Or else you can go to EVERY RESOURCE saying the ame thing... nono dont update this code here... not in tge... only post it for tgea owners. Im sorry bu I dont think your comment was really needed. Its such as if I have a problem with my tge gui..... im not going to take it to the tgea forums.... Get my point? Just let us as a community do what we have been doing.
Obviously people can read a date on the forums. and Obviously people didnt come out with t3d in 2003. So Honestly, dont take away support from this topic just because GG stole the array script. Thanks, bye bye.
09/24/2009 (6:38 am)
@James, how about if it updates this resource and T3D, So be it kept here as long as it updates our array and works for our updates, why would you want ONLY community updates to be only for t3d. Thats sort of WRONG ! Considering the T3D arrayclass is basically the same thing. So please, I ask you, very nicely. Leave this resource alone, im sure the people are smart enough to figure out. Or else you can go to EVERY RESOURCE saying the ame thing... nono dont update this code here... not in tge... only post it for tgea owners. Im sorry bu I dont think your comment was really needed. Its such as if I have a problem with my tge gui..... im not going to take it to the tgea forums.... Get my point? Just let us as a community do what we have been doing.
Obviously people can read a date on the forums. and Obviously people didnt come out with t3d in 2003. So Honestly, dont take away support from this topic just because GG stole the array script. Thanks, bye bye.
#78
T3D has an arrayObject that started with this resource, but has been drawn into T3D and has been improved upon. By posting a resource here, you (well, not you, since you haven't posted any resources in the past four years, I'm speaking about anyone here..) let others use your resource in a free and royalty-free manner. You should perhaps choose your words better.
If a resource is worth it, it gets pulled into the engine. It has been like that for a long time.
Posting T3D Beta bugs however must happen in the T3D Private forums for obvious reasons. The code some people posted here was likely from T3D and not this resource. Technically, it's almost the same, but there are licensing and other issues with that, which James was trying to shed light on.
On the other hand, this resource is not being followed by T3D devs, and to have bugs fixed, they need to be reported through the appropriate channels.
I'm sure nobody came with the intent you described.
09/24/2009 (6:58 am)
Robert, I believe you misunderstood James' comment. T3D has an arrayObject that started with this resource, but has been drawn into T3D and has been improved upon. By posting a resource here, you (well, not you, since you haven't posted any resources in the past four years, I'm speaking about anyone here..) let others use your resource in a free and royalty-free manner. You should perhaps choose your words better.
If a resource is worth it, it gets pulled into the engine. It has been like that for a long time.
Posting T3D Beta bugs however must happen in the T3D Private forums for obvious reasons. The code some people posted here was likely from T3D and not this resource. Technically, it's almost the same, but there are licensing and other issues with that, which James was trying to shed light on.
On the other hand, this resource is not being followed by T3D devs, and to have bugs fixed, they need to be reported through the appropriate channels.
I'm sure nobody came with the intent you described.
#79
After some research though I verified that the T3D ArrayObject is significantly different from this one and the posters here were indeed referring to "this" ArrayObject.
The intention of my post is to prevent other people from having this same confusion. Thats all, continue updating this resource all you would like.
In summary... this resource is not the same ArrayObject as exists in T3D, therefore discussion here which refers to ArrayObject is "this" one. If you have questions or bugs to report about the T3D ArrayObject please post those in the T3D forums to prevent confusion.
Cheers.
09/24/2009 (10:58 pm)
I was reading the posts on this resource and saw several posts showing fixes for bugs in ArrayObject. At first I was not sure if these were bugs/fixes intended for the T3D ArrayObject or this one, because if there is something broken in the T3D ArrayObject I would like to fix it.After some research though I verified that the T3D ArrayObject is significantly different from this one and the posters here were indeed referring to "this" ArrayObject.
The intention of my post is to prevent other people from having this same confusion. Thats all, continue updating this resource all you would like.
In summary... this resource is not the same ArrayObject as exists in T3D, therefore discussion here which refers to ArrayObject is "this" one. If you have questions or bugs to report about the T3D ArrayObject please post those in the T3D forums to prevent confusion.
Cheers.
#80
Im a beginner at coding so I have no idea how this could have happened, and likewise no idea of a solution.
Its been a while so im not exactly sure how i managed the relative movement so i cant post my code yet. Im going to look for it now.
In the meantime..
Is there anything in the arrayobject.cpp that could conflict with movement?
10/18/2009 (5:07 am)
Hello, Ive used this resource and installed the array, but upon compiling and verifying that everything worked, ive discovered that it broke a control that changed the way my movement worked, somehow. I had it set up so that movement was relative to the canvas, with W always going to the top of the screen. I have no idea what could be conflicting with it in this, because it has reverted to the original controls of w being forward of whatever way the player is facing.Im a beginner at coding so I have no idea how this could have happened, and likewise no idea of a solution.
Its been a while so im not exactly sure how i managed the relative movement so i cant post my code yet. Im going to look for it now.
In the meantime..
Is there anything in the arrayobject.cpp that could conflict with movement?
Torque 3D Owner Thomas Huehn
Yes over long time - at mmo for example - is allocate a lot of memory. I noticed that after about running a server over an year and switched from array object to simobject last days. I used it to keep track of score for example. The scores in my game internally are floating point values so it raised up a lot saving each value to the stringtable. I got never in real trouble since i make an update about each month but using it the way i did is maybe not the best idea ;)