AngelScript

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(const CScriptArray &other);
      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

See also:
  Arrays in the script language

## 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;
    }