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.

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

      // 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;

      // 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;
        void resize(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
        asIObjectType* t = engine->GetObjectTypeById(engine->GetTypeIdByDecl("array<string@>"));

        CScriptArray* arr = new CScriptArray(3, t);
        for( asUINT i = 0; i < arr->GetSize(); i++ )
        {
          // Get the pointer to the element so it can be set
          CScriptString** p = static_cast<CScriptString**>(arr->At(i));
          *p = new CScriptString("test");
        }

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