ATDD Scripting: StringList (Doc)

//Begin String List
/* String List Implementation V1.0 */
/* Written by: Apjjm               */

//+ Constants
//Change the delimiter to suit, it is currently the null character.
const string _STRLPFX = "_!strli!_"; //Prefixed to all stringList var names
const string _STRLDLM = "\0";    //SINGLE CHARACTER Delimiter for items
//-

//Begin List Management
//+ bool stringListCreate(string &in asName)
////////////////////////////////////////////////////////////////
//stringListCreate:                                           //
//      initiates a list with the given name                  //
//asName:                                                     //
//      name for the list                                     //
//returns:                                                    //
//      if the creation was sucessful (fails if list exists)  //
////////////////////////////////////////////////////////////////
bool stringListCreate(string &in asName) {
  string name = _STRLPFX + asName;
  //If Exists alread, don't overwrite
  if(GetLocalVarInt(name + "_exist")==1) return false;
  //Else continue as normal
  SetLocalVarInt(name + "_exist",1); //State list exists
  SetLocalVarInt(name + "_count",0);  //Put a count on the list
  SetLocalVarString(name,"");         //Define list w/ empty string
  return true;
}
//-
//+ bool stringListDestroy(string &in asName)
////////////////////////////////////////////////////////////////
//stringListDestroy:                                          //
//      Clears & destroys a list with the given name          //
//asName:                                                     //
//      name of the list                                      //
//returns:                                                    //
//      destruction was sucessful? (false if invalid list)    //
////////////////////////////////////////////////////////////////
bool stringListDestroy(string &in asName) {
  string name = _STRLPFX + asName;
  //If it doesn't exist - we can't destroy it
  if(GetLocalVarInt(name + "_exist")!=1) return false;
  //Else reduce all vars to min size - mark as not existing
  SetLocalVarInt(name + "_exist",0);  //State list doesn't exist
  SetLocalVarInt(name + "_count",0);  //Change the list count
  SetLocalVarString(name,"");         //Define list w/ empty string
  return true;
}
//-
//+ bool stringListExists(string &in asName)
////////////////////////////////////////////////////////////////
//stringListExists:                                           //
//      Determines if list with a given name exists           //
//asName:                                                     //
//      name of the list                                      //
//returns:                                                    //
//      if the list exists                                    //
////////////////////////////////////////////////////////////////
bool stringListExists(string &in asName) {
  return (GetLocalVarInt(_STRLPFX + asName + "_exist") == 1);
}
//-
//+ int stringListSize(string &in asName)
////////////////////////////////////////////////////////////////
//stringListSize:                                             //
//      returns the size of a list                            //
//asName:                                                     //
//      name of the list                                      //
//returns:                                                    //
//      list size (0 if empty or non-existant)                //
////////////////////////////////////////////////////////////////
int stringListSize(string &in asName) {
  return (GetLocalVarInt(_STRLPFX + asName + "_count"));
}
//-
//+ void stringListClear(string &in asName)
////////////////////////////////////////////////////////////////
//stringListClear:                                            //
//      initiates a list with the given name                  //
//asName:                                                     //
//      name of the list                                      //
////////////////////////////////////////////////////////////////
void stringListClear(string &in asName) {
  string name = _STRLPFX + asName;
  //Don't do anything if list doesn't exist
  if(GetLocalVarInt(name + "_exist")!=1) return;
  //Else reset list to defaults
  SetLocalVarInt(name + "_count",0);  //Put a count on the list to 0
  SetLocalVarString(name,"");         //Define list w/ empty string
}
//-
//End List Management

//Begin Item Management
//+ string[] stringListItems(string &in asName)
////////////////////////////////////////////////////////////////
//stringListItems                                             //
//                                                            //
//asName:                                                     //
//      name of the list                                      //
//returns:                                                    //
//      Array of all the items in the list                    //
////////////////////////////////////////////////////////////////
string[] stringListItems(string &in asName) {
  string str = GetLocalVarString(_STRLPFX + asName);
  //Output array vars
  string[] output = {};
  int outputIndex = 0;
  //Early-out if string is faulty
  if(!StringContains(str,_STRLDLM)) return output;
  //String matching vars
  uint8 dlm = _STRLDLM[0];
  int last = 0;
  //Loop and add each substring
  for(int i =0; i<str.length(); i++) //For each char
   {
    if(str[i] == dlm) //If char matches delimiter
     {
      int len = i - last; //Determine length of token to read
      if(len>= 0)
       {
        output.resize(outputIndex+1); //Increase array size
        output[outputIndex] = StringSub(str,last,len); //Get token into array
        outputIndex++; //Location of next token
       }
      last = i+1; //Say token begins at the next char
     }
   }
  //Return array of substrings
  return output;
}
//-
//+ int stringListAddItem(string &in asName, string &in asItem)
////////////////////////////////////////////////////////////////
//stringListAddItem                                           //
//      Adds specified item to the list                       //
//asName:                                                     //
//      name of the list                                      //
//asItem:                                                     //
//      Item to be added                                      //
//returns:                                                    //
//      Index of the item added (-1 if adding failed)         //
////////////////////////////////////////////////////////////////
int stringListAddItem(string &in asName, string &in asItem) {
  string name = _STRLPFX + asName;
  //Return error value if list doesn't exist
  if(GetLocalVarInt(name + "_exist")!=1) return -1;
  //Add the item with the delimiter, increment count
  int index = GetLocalVarInt(name + "_count");
  AddLocalVarInt(name + "_count",1);
  AddLocalVarString(name,asItem + _STRLDLM);
  return index;
}
//-
//+ void stringListAddItems(string &in asName, string[] asItem)
////////////////////////////////////////////////////////////////
//stringListAddItems                                          //
//      Adds an array of items to the list                    //
//asName:                                                     //
//      name of the list                                      //
//asItem:                                                     //
//      Array of Items to be added                            //
////////////////////////////////////////////////////////////////
void stringListAddItems(string &in asName, string[] asItem) {
  //Doesnt exist / Bad parameter? return.
  string name = _STRLPFX + asName;
  if(GetLocalVarInt(name + "_exist")!=1  || asItem.length()==0) return;
  //Append all items together w/ the delimiter
  string item = "";
  for(int i =0; i<asItem.length(); i++) item += asItem[i] + _STRLDLM;
  //Add this new item string, Increment count
  AddLocalVarString(name,item);
  AddLocalVarInt(name + "_count",asItem.length());
}
//-
//+ string stringListGetItem(string &in asName, int alIndex)
////////////////////////////////////////////////////////////////
//stringListGetItem                                           //
//      Gets item from the list at the specified index        //
//asName:                                                     //
//      name of the list                                      //
//alIndex:                                                    //
//      Index of  the item to retrieve                        //
//returns:                                                    //
//      Item at specified index                               //
////////////////////////////////////////////////////////////////
string stringListGetItem(string &in asName, int alIndex) {
  //This is just an array fetch + grab at index
  string name = _STRLPFX + asName;
  string output = "";
  if(alIndex>= 0 && GetLocalVarInt(name + "_exist") == 1) //Parameters valid enough to progress?
   {
    string[] names = stringListItems(asName); //Get list of items
    if(alIndex <names.length())
     {
      output = names[alIndex]; //Index in bounds: set ouput to item
     }
   }
  return output;
}
//-
//+ int stringListGetLastIndexof(string &in asName, string &in asItem)
////////////////////////////////////////////////////////////////
//stringListLastIndexof                                       //
//      Finds the last index of the specified item in the list//
//asName:                                                     //
//      name of the list                                      //
//asItem:                                                     //
//      Item to be found                                      //
//returns:                                                    //
//      Index of last occurance of asItem in list (-1 if none)//
////////////////////////////////////////////////////////////////
int stringListGetLastIndexof(string &in asName, string &in asItem) {
  //This is a linear search of the list of items
  string name = _STRLPFX + asName;
  int index = -1;
  if(GetLocalVarInt(name + "_exist") == 1)
   {
    string[] items = stringListItems(asName); //Get list of items
    for(int i=0; i<items.length(); i++)
     { if(asItem == items[i]) index = i; } //Search for match. If match set index to index of match.
   }
  return index;
}
//-
//+ int stringListGetFirstIndexof(string &in asName, string &in asItem)
////////////////////////////////////////////////////////////////
//stringListGetFirstIndexof                                   //
//      gets the first index of asItem in the target list     //
//asName:                                                     //
//      name of the list                                      //
//asItem:                                                     //
//      Item to be located                                    //
//returns:                                                    //
//      Index of first occurance of asItem in list(-1 if none)//
////////////////////////////////////////////////////////////////
int stringListGetFirstIndexof(string &in asName, string &in asItem) {
  //This is a linear search of the list of items
  string name = _STRLPFX + asName;
  int index = -1;
  if(GetLocalVarInt(name + "_exist") == 1)
   {
    string[] items = stringListItems(asName); //Get list of items
    for(int i=0; i<items.length(); i++)
     {
      if(asItem == items[i])
        {
         index = i;
         i = items.length();
        }
     }
   }
  return index;
}
//-
//+ bool stringListContains(string &in asName, string &in asItem)
////////////////////////////////////////////////////////////////
//stringListContains                                          //
//      Gets if the list contains asItem                      //
//asName:                                                     //
//      name of the list                                      //
//asItem:                                                     //
//      Item to be found                                      //
//returns:                                                    //
//      If asItem is in the list                              //
////////////////////////////////////////////////////////////////
bool stringListContains(string &in asName, string &in asItem) {
  return stringListGetLastIndexof(asName, asItem)>=0;
}
//-
//+ bool stringListRemoveItemAt(string &in asName, int alIndex)
////////////////////////////////////////////////////////////////
//stringListRemoveItemAt                                      //
//      Removes item at specified index                       //
//asName:                                                     //
//      name of the list                                      //
//alIndex:                                                    //
//      Index to be removed                                   //
//returns:                                                    //
//      True if the item was found and removed                //
////////////////////////////////////////////////////////////////
bool stringListRemoveItemAt(string &in asName, int alIndex) {
    string name = _STRLPFX + asName;
    //List exists?
    if(GetLocalVarInt(name + "_exist")!=1) return false;
    //Get list
    string[] list = stringListItems(asName);
    //Re-add all but deleted item
    string item = "";
    int count = 0;
    bool op = false;
    for(int i =0; i<list.length(); i++)
    {
     if(i != alIndex)
      {
       item += list[i] + _STRLDLM;
       count++;
      }
     else op=true;
    }
    //Set back to the array
    SetLocalVarInt(name + "_count",count);  //Change count
    SetLocalVarString(name,item);           //Redefine list
    //Return if anything was deleted
    return op;
}
//-
//+ int stringListRemoveItems(string &in asName, string asItem)
////////////////////////////////////////////////////////////////
//stringListRemoveItems                                       //
//      Removes any items matching asItem                     //
//asName:                                                     //
//      name of the list                                      //
//asItem:                                                     //
//      Item to be removed (duplicate items are removed too)  //
//returns:                                                    //
//      Number of occurances of the item removed              //
////////////////////////////////////////////////////////////////
int stringListRemoveItems(string &in asName, string asItem) {
    string name = _STRLPFX + asName;
    //List exists?
    if(GetLocalVarInt(name + "_exist")!=1) return 0;
    //Get list
    string[] list = stringListItems(asName);
    //Re-add all but deleted items
    string item = "";
    int count = 0;
    int delamt = 0;
    for(int i =0; i<list.length(); i++)
    {
     if(asItem != list[i])
      {
       item += list[i] + _STRLDLM;
       count++;
      }
     else delamt++;
    }
    //Set back to the array
    SetLocalVarInt(name + "_count",count);  //Change count
    SetLocalVarString(name,item);           //Redefine list
    //Return if anything was deleted
    return delamt;
}
//-
//End Item Management

//Begin List Debug
//Draws each item in list specified by asName
void stringListDraw(string &in asName) {
    string[] sli = stringListItems(asName); string o = "";
    for(int i =0; i<sli.length(); i++) o += " | " + i + ": " + sli[i] + " |";
    AddDebugMessage(o,false);
}
//Draws the string of the specified list straight to the screen
//Warning: Will not display correctly - if delimiter isn't defined in the font file!
void stringListDrawRaw(string & in asName) {
  AddDebugMessage(GetLocalVarString(_STRLPFX + asName),false);
}
//End
//End String List