Docu-stringlists

From Graal Kingdoms Wiki
Jump to: navigation, search

String lists

Instead of just simple text, string variables can also contain string lists. They are stored the same way like string variables, a string list is just a string in the flag list with the format 'name=entry1,entry2,entry3,...'. Also the name conventions of string variables (this.,client.,server. etc.) apply to string lists.

String list entries can contain spaces and commas, the scripting engine will eventually add special characters to know where the entries start and end (when the string contains spaces it will add a " at the beginning and end of the string).

1. Adding and removing of strings

For changing the content of a string list you have following script commands: addstring listname,string insertstring listname,position,string replacestring listname,position,string removestring listname,string deletestring listname,position

Adding of strings:

With 'addstring' you simply add a string to the end of the list. With 'insertstring' you can insert the new string at a special position, the specified index must be between 0 and listsize-1. If the index is not in that range then the string is simply added at the end if the list, like when you do 'addstring'. With 'replacestring' you can replace the string at the specified index with the new string you provide. If the index is not in the range 0..listsize-1 then the string is added at the end of the list, because there was no previous string to replace.

Removing of strings:

With 'removestring' you remove all occurances of the string in the string list. With 'deletestring' you can delete a string at a special position, the specified index must be in the range of 0 to listsize-1.

2. Setting and copying of complete string lists

If you have complex string lists and want to copy them to other strings, then copying each entry would be too slow and take a lot of scripting code. But you can copy string lists with the 'setstring' command. Since string lists are stored like normal string variables, you can use that command to initialize and copying string lists.

Here an example for initializing a string list with 3 entries 'one','two' and 'three', and an example for initializing it with more complex entries: --- setstring mylist,one,two,three; setstring mylist2,Godzilla,"Hulk Hogan","Batman, the movie" --- Copying a list to another list: --- setstring mylist,one,two,three; setstring mylist2,#s(mylist); --- Attaching the complete content of one list to another: --- setstring mylist,one,two,three; setstring mylist2,four,five,six; setstring mylist,#s(mylist),#s(mylist2); ---

3. Accessing entries of string lists

For retrieving the entries of a string list you must use the message code #I(listname,position). It is giving you the list entry from the specified position. The position must be in the range from 0 to listsize-1.

An example for showing the second entry (index 1) of a list, it will display 'two': --- if (playerenters) {

 setstring mylist,one,two,three;
 message #I(mylist,1);

} ---

To know the size of a string list there is the function sarraylen(listname). To find the position of a string in the string list you can use the function lindexof(string,listname) (the parameters are in reverse order to keep the order like in the indexof(partstring,string) function). The function will return a value between 0 and listsize-1 if it finds the string, otherwise -1.

This example will try to display the position of a special string in a list (if the petnames list is 'petnames=cat,dog,mouse' it will display position 1): --- if (playerenters) {

 pos = lindexof(dog,petnames);
 if (pos>=0)
   message Position: #v(pos);
 else
   message String not found in the list!;

} ---

4. Use of string lists

String lists can be used to store data in a more organized way. You can emulate objects by saving the attributes of the object in a string list and then access the attributes by the object name and attribute index. You can also use string lists to save the account names of players that are allowed to enter a house, member of a kingdom, or you could save names of items bought by the player in a shop.

There are things you must keep care of: - the string list needs to have the right leading (client., server., etc., described in the chapter about string variables) to be stored and transferred like you intend to - string lists are not meant to be too long; they can theoretically have a size of more than 20k characters, but then they are displayed incorrectly in the remotecontrol.exe (only the first 220 characters are displayed) and can slow down the login of a player when the string list is stored in the account of the player and is sent to the player at login - accessing entries of a string list is much slower than accessing members of numerical arrays, so don't use them if not needed