[MODULE] StructStream v.1.0

[Crimson Wizard]

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 v. 1.0 or better to enable two functions supporting StackData type.

Download
Download mirror


Example of usage
  Consider following custom structures:
 

Code: ags

    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:
 

Code: ags

    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:
 

Code: ags

    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...
    }