array template object

Path: /sdk/add_on/scriptarray/

The array type is a template object that allow the scripts to declare arrays of any type. Since it is a generic class it is not the most performatic due to the need to determine characteristics at runtime. For that reason it is recommended that the application registers a template specialization for the array types that are most commonly used.

The type is registered with RegisterScriptArray(asIScriptEngine *engine, bool defaultArrayType). The second parameter should be set to true if you wish to allow the syntax form type[] to declare arrays.

Compile the add-on with the pre-processor define AS_USE_STLNAMES=1 to register the methods with the same names as used by C++ STL where the methods have the same significance. Not all methods from STL is implemented in the add-on, but many of the most frequent once are so a port from script to C++ and vice versa might be easier if STL names are used.

Public C++ interface

class CScriptArray
{
public:
  // Constructor
  CScriptArray(asUINT length, asIObjectType *ot);
  CscriptArray(asUINT length, void *defaultValue, asIObjectType *ot);
  virtual ~CScriptArray();

  // Memory management
  void AddRef() const;
  void Release() const;

  // Type information
  asIObjectType *GetArrayObjectType() const;
  int            GetArrayTypeId() const;
  int            GetElementTypeId() const;

  // Get the current size
  asUINT GetSize() const;
  
  // Returns true if the array is empty
  bool IsEmpty() const;

  // Pre-allocates memory for elements
  void Reserve(asUINT numElements);
  
  // Resize the array
  void Resize(asUINT numElements);
  
  // Get a pointer to an element. Returns 0 if out of bounds
  void       *At(asUINT index);
  const void *At(asUINT index) const;

  // Set value of an element. The value arg should be a pointer
  // to the value that will be copied to the element
  void  SetValue(asUINT index, void *value);

  // Copy the contents of one array to another (only if the types are the same)
  CScriptArray &operator=(const CScriptArray&);

  // Compare two arrays
  bool operator==(const CScriptArray &) const;

  // Array manipulation
  void InsertAt(asUINT index, void *value);
  void RemoveAt(asUINT index);
  void InsertLast(void *value);
  void RemoveLast();
  void SortAsc();
  void SortAsc(asUINT index, asUINT count);
  void SortDesc();
  void SortDesc(asUINT index, asUINT count);
  void Reverse();
  int  Find(void *value) const;
  int  Find(asUINT index, void *value) const;
};

Public script interface

  class array<class T>
  {
    array();
    array(uint length);
    array(uint length, const T &in defaultValue);

    T       &opIndex(uint);
    const T &opIndex(uint) const;

    array<T> opAssign(const array<T> &in);
    bool     opEquals(const array<T> &in) const;

    uint length { get const; set; }

    void insertAt(uint index, const T &in);
    void removeAt(uint index);
    void insertLast(const T& in);
    void removeLast();
    uint length() const;
    uint isEmpty() const;
    void resize(uint);
    void reserve(uint);
    void sortAsc();
    void sortAsc(uint index, uint count);
    void sortDesc();
    void sortDesc(uint index, uint count);
    void reverse();
    int  find(const T& in) const;
    int  find(uint index, const T& in) const;
  }

Script example

  int main()
  {
    array<int> arr = {1,2,3};

    int sum = 0;
    for( uint n = 0; n < arr.length; n++ )
      sum += arr[n];

    return sum;
  }

C++ example

This function shows how a script array can be instanciated from the application and then passed to the script.

CScriptArray *CreateArrayOfStrings()
{
  // If called from the script, there will always be an active 
  // context, which can be used to obtain a pointer to the engine.
  asIScriptContext *ctx = asGetActiveContext();
  if( ctx )
  {
    asIScriptEngine* engine = ctx->GetEngine();

    // The script array needs to know its type to properly handle the elements.
    // Note that the object type should be cached to avoid performance issues
    // if the function is called frequently.
    asIObjectType* t = engine->GetObjectTypeById(engine->GetTypeIdByDecl("array<string>"));

    // Create an array with the initial size of 3 elements
    CScriptArray* arr = new CScriptArray(3, t);
    for( asUINT i = 0; i < arr->GetSize(); i++ )
    {
      // Set the value of each element
      string val("test");
      arr->SetValue(i, &val);
    }

    // The ref count for the returned handle was already set in the array's constructor
    return arr;
  }
  return 0;
}