v1.2

Author: monkey0506

CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## Version 1.2
+
+Version:     1.2  
+Author:      monkey0506  
+Date:        28 March 2009  
+Description: Added `Stack.GetItemsArray`, `File.WriteStack`, `File.ReadStackBack`, and
+`Stack.LoadFromFile` functions. The module now exports `StackDataFormat` so it can be used by other
+scripts for extending the module. It is not imported, it must be locally imported to the script
+requiring it. Modified the way `Stack.Copy` formats the data to better prevent collisions. Fixed a
+bug with `Stack.Push` where if you were adding an item at a specific index `ItemCount` was still
+getting increased. Added data type `eStackDataInvalid` to indicate that the object is not valid
+`StackData`. Included module information in the Properties pane for the script.
+
 ## Version 1.0
 
 Version:     1.0  

README.md

@@ -29,6 +29,10 @@ AGS v3.1.2+
 
 Defines the current version of the module, formatted as a `float`.
 
+#### Stack_VERSION_120
+
+Defines version 1.2 of the module.
+
 #### Stack_VERSION_100
 
 Defines version 1.0 of the module.
@@ -45,6 +49,7 @@ Defines version 1.0 of the module.
 - `eStackDataGUI`: The stored data is a GUI
 - `eStackDataGUIControl`: The stored data is a GUIControl
 - `eStackDataStack`: The stored data is a Stack object
+- `eStackDataInvalid`: The object does not contain any valid StackData
 
 #### StackPopType
 
@@ -146,6 +151,18 @@ object can **only** be used with/by the following functions:
 
 Returns a StackData object containing `theFloat`.
 
+#### Stack.GetItemsArray
+
+`StackData[] Stack.GetItemsArray()`
+
+Returns an array containing each of the items in the stack. The size of the array will be the same
+as the [ItemCount](#stackitemcount). If `ItemCount` is 0, returns `null`.
+
+*NOTE:* Since the stacks are all vectorized, it's not practical for this to be implemented as a
+property. Doing so would require a static size specified for the size of the property. This method
+allows you to get the items in a dynamic array without having to limit the number of items that can
+be returned this way.
+
 #### Stack.GUIControlToData
 
 `static StackData Stack.GUIControlToData(GUIControl *theControl)`
@@ -182,6 +199,14 @@ Returns whether the stack has **no** items in it.
 
 Returns the number of items stored in the stack.
 
+#### Stack.LoadFromFile
+
+`void Stack.LoadFromFile(File *theFile)`
+
+Attempts to read back a `Stack` object from `theFile`, and load it into this stack. If `theFile`
+was not written by [File.WriteStack](#filewritestack) this will crash the game, just as the normal
+`File` functions do.
+
 #### Stack.LoadFromStack
 
 `bool Stack.LoadFromStack(StackData otherStack)`
@@ -222,6 +247,25 @@ by [Stack.Copy](#stackcopy).
 
 Returns a StackData object containing `theString`.
 
+---------
+
+### File
+
+#### File.WriteStack
+
+`bool File.WriteStack(StackData stackCopy)`
+
+Writes the stack data from `stackCopy` to the file. If `stackCopy` does not contain a valid stack,
+or there is an error writing to the file, returns `false`.
+
+#### File.ReadStackBack
+
+`StackData File.ReadStackBack()`
+
+Attempts to read back a `Stack` object from the file. If the file was not written by
+[File.WriteStack](#filewritestack) this will crash the game, just as the normal `File` functions
+do.
+
 ## Examples
 
 This module is admittedly a bit intimidating, so here's a couple examples of how the scripts can be used.

Stack.asc

@@ -1,12 +1,17 @@
 
 String StackDataDelimiter;
 String StackDataFormat;
+export StackDataFormat; // allow extensions from other scripts
 String StackDataCopyFormat;
-int StackDataCopyID = 0;
 
 StackDataType GetType(this StackData*) {
+  if (this.Length < (StackDataFormat.Length - 1)) return eStackDataInvalid;
   StackData type = this.Substring(0, StackDataFormat.Length - 1);
-  return type.Chars[type.IndexOf(":") + 1];
+  int i = type.IndexOf(":");
+  if (i == -1) return eStackDataInvalid;
+  char c = type.Chars[i + 1];
+  if (type != String.Format(StackDataFormat, c)) return eStackDataInvalid;
+  return c;
 }
 
 int GetAsInt(this StackData*) {
@@ -103,39 +108,32 @@ static StackData Stack::GUIControlToData(GUIControl *theControl) {
   return StackData.Format("%s%d", type, ((theControl.OwningGUI.ID * AGS_MAX_CONTROLS_PER_GUI) + theControl.ID));
 }
 
-StackData StackDataMergeArray(StackData array[]) {
-  if ((array == null) || (StackData.IsNullOrEmpty(array[0])) || (array[0].AsInt <= 0)) return null;
+StackData MergeArray(this Stack*, StackData array[]) {
+  if (array == null) return null;
   StackData glue = StackDataDelimiter;
   StackData buffer = "";
-  int i = 1;
-  int size = array[0].AsInt;
-  while (i <= size) {
+  int i = 0;
+  int size = this.ItemCount;
+  while (i < size) {
     buffer = buffer.Append(array[i]);
-    if (i < size) buffer = buffer.Append(glue);
+    if (i < (size - 1)) buffer = buffer.Append(glue);
     i++;
   }
   return buffer;
 }
 
-StackData[] SplitDataByItems(this Stack*) {
+StackData[] GetItemsArray(this Stack*) {
   if (this.Data == null) return null;
-  StackData items[] = new StackData[this.ItemCount + 1];
-  items[0] = StackData.Format("%d", this.ItemCount);
+  StackData items[] = new StackData[this.ItemCount];
   StackData buffer = this.Data;
   String format = StackDataFormat.Substring(0, StackDataFormat.IndexOf(":") + 1);
   int i = buffer.IndexOf(format);
-  int j = 1;
-  while ((i != -1) && (j <= this.ItemCount)) {
+  int j = 0;
+  while ((i != -1) && (j < this.ItemCount)) {
     StackDataType type = buffer.Chars[format.Length];
     if (type == eStackDataStack) {
       StackData temp = buffer.Substring(StackDataFormat.Length - 1, buffer.Length);
-      StackData stamp = temp.Substring(0, StackDataCopyFormat.IndexOf(":") + 1);
-      i = stamp.Length;
-      while ((temp.Chars[i] >= '0') && (temp.Chars[i] <= '9')) {
-        stamp = stamp.AppendChar(temp.Chars[i]);
-        i++;
-      }
-      stamp = stamp.Append(StackDataCopyFormat.Substring(StackDataCopyFormat.IndexOf(":%d") + 3, StackDataCopyFormat.Length));
+      StackData stamp = temp.Substring(0, StackDataCopyFormat.Length + 14); // format + 16 byte key - %s
       temp = temp.Substring(stamp.Length, temp.Length);
       i = temp.IndexOf(stamp);
       if (i != -1) items[j] = buffer.Truncate(i + (StackDataFormat.Length - 1) + (stamp.Length * 2));
@@ -170,12 +168,14 @@ bool Stack::Push(StackData data, int index) {
     this.ItemCount++;
     return true;
   }
-  StackData items[] = this.SplitDataByItems();
-  int size = items[0].AsInt;
-  if (index < size) items[index + 1] = data;
-  this.Data = StackDataMergeArray(items);
-  if (index >= size) this.Data = this.Data.Append(StackDataDelimiter.Append(data));
-  this.ItemCount++;
+  StackData items[] = this.GetItemsArray();
+  int size = this.ItemCount;
+  if (index < size) items[index] = data;
+  this.Data = this.MergeArray(items);
+  if (index >= size) {
+    this.Data = this.Data.Append(StackDataDelimiter.Append(data));
+    this.ItemCount++;
+  }
   return true;
 }
 
@@ -187,28 +187,26 @@ StackData Stack::Pop(bool remove, int index) {
   }
   if ((index < 0) || (index >= this.ItemCount) || (!this.ItemCount) ||
   (StackData.IsNullOrEmpty(this.Data))) return null;
-  StackData items[] = this.SplitDataByItems();
-  int size = items[0].AsInt;
-  if (index >= size) return null;
-  StackData data = items[index + 1];
+  StackData items[] = this.GetItemsArray();
+  int size = this.ItemCount;
+  StackData data = items[index];
   if (remove) {
     this.ItemCount--;
     if ((!this.ItemCount) || (size == 1)) {
       this.Data = null;
       items = null; // prevent AGS 3.1.2 bug - Object not in managed pool.
       return data;
     }
-    StackData buffer[] = new StackData[size];
-    int i = 1;
-    while (i < size) {
-      if (i <= index) buffer[i] = items[i];
+    StackData buffer[] = new StackData[this.ItemCount];
+    int i = 0;
+    while (i < this.ItemCount) {
+      if (i < index) buffer[i] = items[i];
       else buffer[i] = items[i + 1];
       i++;
     }
-    buffer[0] = StackData.Format("%d", size - 1);
     items = buffer;
   }
-  this.Data = StackDataMergeArray(items);
+  this.Data = this.MergeArray(items);
   items = null; // prevent AGS 3.1.2 bug - Object not in managed pool.
   return data;
 }
@@ -222,10 +220,30 @@ bool Stack::IsEmpty() {
   return (!this.ItemCount);
 }
 
+StackData BuildKey(this Stack*) { // returns a 128-bit (16-byte) key for Stack::Copy
+  StackData key = "";
+  int i = 0;
+  while (i < 16) {
+    char c = 0;
+    int j = 7;
+    while (j >= 0) { // build-a-byte
+      DateTime *now = DateTime.Now;
+      bool bit = (Random(now.RawTime) % 2); // returns either 1 or 0
+      c += (bit << j); // then we shift that bit into place
+      j--;
+    }
+    if (c) {
+      key = key.AppendChar(c);
+      i++;
+    }
+  }
+  return key;
+}
+
 StackData Stack::Copy() {
   StackData type = StackData.Format(StackDataFormat, eStackDataStack);
-  StackData stamp = StackData.Format(StackDataCopyFormat, StackDataCopyID);
-  StackDataCopyID++;
+  StackData key = this.BuildKey();
+  StackData stamp = StackData.Format(StackDataCopyFormat, key);
   StackData data = this.Data;
   if (data == null) data = "";
   return StackData.Format("%s%s%d,%d,%s%s", type, stamp, this.ItemCount, this.PopType, data, stamp);
@@ -234,13 +252,7 @@ StackData Stack::Copy() {
 bool Stack::LoadFromStack(StackData otherStack) {
   if ((otherStack == null) || (otherStack.GetType() != eStackDataStack)) return false;
   StackData data = otherStack.Substring(StackDataFormat.Length - 1, otherStack.Length);
-  StackData stamp = data.Substring(0, StackDataCopyFormat.IndexOf(":") + 1);
-  int i = stamp.Length;
-  while ((data.Chars[i] >= '0') && (data.Chars[i] <= '9')) {
-    stamp = stamp.AppendChar(data.Chars[i]);
-    i++;
-  }
-  stamp = stamp.Append(StackDataCopyFormat.Substring(StackDataCopyFormat.IndexOf(":%d") + 3, StackDataCopyFormat.Length));
+  StackData stamp = data.Substring(0, StackDataCopyFormat.Length + 14); // format + 16 byte key - %s
   data = data.Substring(stamp.Length, data.Length);
   data = data.Truncate(data.IndexOf(stamp));
   StackData buffer = data.Substring(0, data.IndexOf(","));
@@ -252,8 +264,26 @@ bool Stack::LoadFromStack(StackData otherStack) {
   return true;
 }
 
+bool WriteStack(this File*, StackData stackCopy) {
+  if ((this.Error) || (stackCopy == null) || (stackCopy.GetType() != eStackDataStack)) return false;
+  this.WriteString(stackCopy);
+  return (!this.Error);
+}
+
+StackData ReadStackBack(this File*) {
+  if ((this.Error) || (this.EOF)) AbortGame("File::ReadStackBack: File was not written by File::WriteStack.");
+  StackData data = this.ReadStringBack();
+  if ((data == null) || (data.GetType() != eStackDataStack) || (this.Error)) AbortGame("File::ReadStackBack: File was not written by File::WriteStack.");
+  return data;
+}
+
+void Stack::LoadFromFile(File *theFile) {
+  if ((theFile == null) || (theFile.Error) || (theFile.EOF)) AbortGame("Stack::LoadFromFile: File was not written by File::WriteStack.");
+  this.LoadFromStack(theFile.ReadStackBack());
+}
+
 function game_start() {
   StackDataDelimiter = "**STACKDATA**";
   StackDataFormat = "**STACKDATA:%c**";
-  StackDataCopyFormat = "**STACKDATA STACK:%d**";
+  StackDataCopyFormat = "**STACKDATA STACK:%s**";
 }