Description
The Struct Stream module defines and implements two types meant for
user-friendly ways of writing custom structs or data chains to String
and reading them back.
Type Struct2String is used for writing, while type String2Struct is
used for reading.
Purpose
At the time this module is written AGS does not support nested custom
types (structs), i.e. objects of custom type put inside another custom
type. One of the most effective workaround known is storing nested
structs as Strings. This simple module provides an easy and generalized
way to write and read such structs to/from Strings.
In terms of containers Struct Stream implements FIFO method and may be
considered as a FIXED-SIZED QUEUE.
Requires AGS 3.0+
Optionally requires monkey_05_06's Stack module (http://www.adventuregamestudio.co.uk/yabb/index.php?topic=37232.0) v. 1.0 or better to enable two functions supporting StackData type.
Download (http://www.mediafire.com/file/5nn5zttnjy2/StructStream_1.0.scm)
Download mirror (http://www.box.net/shared/7mhjj4x8pv)
Example of usage
Consider following custom structures:
struct TypeHumanBody
{
int Weight;
int Height;
String Hands[2];
};
struct TypeHand
{
bool IsLeft;
int Length;
int Strength;
String Fingers[5];
};
struct TypeFinger
{
int Length;
int Agility;
};
Type HumanBody should contain two instances of type Hand, while each of the
Hand objects should contain five instances of type Finger. Since we cannot
make variables of custom types be members of another custom types, we use
Strings to store nested structures.
Example of initializing Human Body variable:
TypeHumanBody Body;
...
#define HAND_TYPE 1
#define FINGER_TYPE 2
function SomeFunc()
{
Struct2String writer;
String fingers[10];
Body.Weight = 10;
Body.Height = 20;
// Writing all 10 fingers to the temporary array
int i;
while (i < 10)
{
writer.Open(FINGER_TYPE, S2S_DEFAULT_DELIMETER);
writer.WriteInt((i + 1) % 5 + 1); // finger length
writer.WriteInt(2); // finger agility
fingers[i] = writer.Finalize();
i++;
}
// Writing right hand data
writer.Open(HAND_TYPE, S2S_DEFAULT_DELIMETER);
writer.WriteBool(false);
writer.WriteInt(10); // hand length
writer.WriteInt(12); // hand strength
i = 0;
while (i < 5)
{
writer.Write(fingers[i]);
i++;
}
Body.Hands[0] = writer.Finalize();
writer.Open(HAND_TYPE, S2S_DEFAULT_DELIMETER);
writer.WriteBool(true);
writer.WriteInt(10); // hand length
writer.WriteInt(6); // hand strength
while (i < 10)
{
writer.Write(fingers[i]);
i++;
}
Body.Hands[1] = writer.Finalize();
}
Now, assuming we need to get information about 3rd finger on the second hand:
function ProcessFingerData()
{
TypeFinger finger;
String2Struct reader;
reader.Open(Body.Hands[1], HAND_TYPE, S2S_DEFAULT_DELIMETER);
// Skip basic hand data and first two fingers
// Notice, that we shouldn't really bother what types of values are stored there
reader.Read(); // IsLeft
reader.Read(); // Length
reader.Read(); // Strength
reader.Read(); // First finger struct
reader.Read(); // Second finger struct
// Read third finger data
reader.Open(reader.Read(), FINGER_TYPE, S2S_DEFAULT_DELIMETER);
finger.Length = reader.ReadInt();
finger.Agility = reader.ReadInt();
// do something with acquired data...
}