C++ STL-Style Array That's Compatible with AngelScript

I've been working on a new class that I think will be useful to programmers working with AngelScript. AngelScript is nice because its data types are so similar to C++ that it's easy to bind it and share data. There's one thing that doesn't have an easy one-to-one AngelScript counterpart and that's static arrays. I can understand the reasoning behind this as the script has no mechanism that it can use to garuntee the life time of the array. AngelScript does have a nice add-on for arrays that's generic and can add arrays for any type, but I wanted something easier. I decided to make a template class that would wrap the CScriptArray add-on and give it an interface like std::vector including stl-style iterators.

Using the class.
The CScriptArraySTL class was designed so that the array can be created in C++ and then shared with AngelScript as a registered property, or as the return value of a registered functon. It is a template class that takes two template parameters.

template <class T, class TArrayClass = CScriptArray>
class CScriptArraySTL

The first parameter is the type, and the second parameter is the internal array class that has been registered with AngelScript. The default array class is the CScriptArray add-on that is included in the AngelScript SDK. To use this it, you must also include the CScriptArray add-on in your project and register it with AngelScript using the RegisterScriptArray() function. The internal array class is given as a template argument to allow the programmer to be able to use there own array implementation.

Declaring a variable:

// uses CScriptArray addon internally
// for this to work, std::string should be registered with AngelScript.
// This can be done using the ScriptStdString add-on.
CScriptArraySTL <std::string> string_array;

// uses a user-defined array type called CScriptArrayInt
// this type should be a specialized version of CScriptArray that only handles integers
CScriptArraySTL <int, CScriptArrayInt> int_array;

InitArray()
You can create variables using CScriptArraySTL anytime, but you can't use it until after the CScriptArraySTL object has been initialized using the InitArray() method. Here's the declaration for that function:

// Initializes the array so it can be directly accessed using AngelScript
// This must be called before the array can be used
int InitArray(asIScriptEngine *engine, char *declaration, size_type init_length = 0);

asIScriptEngine *engine
The first parameter is a pointer to the script engine. To maximize compatibility with AngelScript, this class uses creates it's internal data using the types that have been registered with AngelScript.

char *declaration
The second parameter is how you would write the type for this array in AngelScript. This allows the class to match its type with AngelScript. For example, if the class holds integers, it should be written "array<int>".

size_t init_length
This is the initial size of the array.

GetRef()
This function returns a pointer to the internal array class and can be registered with AngelScript as a property or returned from a function that has been registered with AngelScript.

Release()
This will release a reference to the array. After this method has been called, the CScriptArraySTL class will no longer be able to access the array data; however, as arrays are reference types in AngelScript, the data may still exist inside AngelScript until the reference count is zero. This method should be called before the script engine is released.

Sample Code

// Create the script engine
asIScriptEngine *engine = asCreateScriptEngine(ANGELSCRIPT_VERSION);

// Register needed add-ons
RegisterStdString(engine);
RegisterScriptArray(engine, true);

// setup our string array
CScriptArraySTL <std::string> string_array;
string_array.InitArray(engine, "array<string>");

// register our array as a global variable in the script
r = engine->RegisterGlobalProperty("array<string> string_array", string_array.GetRef()); assert( r >= 0 );

// do other things and load and run scripts
...

// Release the array
string_array.Release();

// Release the script engine
engine->Release();

Get the Source.
The source code and a example project can be found on GitHub. If you copy the "scriptarraystl" folder to the AngelScript SDK add_on folder, the project directory paths should work. Only a Visual Studio 2010 solution is being provided, but you should be able to run it using other compilers. To use this class in your project, all you need to do is include "ScriptArraySTL.h" The class has been implemented entirely in one header file.

GitHub link: https://github.com/squaredprogramming/scriptarraystl

____________________________________________________________________

Here's the complete list of the methods that I've implemented for the class.

// Constructors, Destructors and AngelScript initialization -------------------------------
CScriptArraySTL(void);
~CScriptArraySTL(void);

// Initializes the array so it can be directly accessed using AngelScript
// This must be called before the array can be used
int InitArray(asIScriptEngine *engine, char *declaration, size_type init_length = 0);

// returns a pointer to an array class that can be used in an AS script
TArrayClass *GetRef();

// Releases a reference to the array. After this is called, this class can
// no longer access the array data, but the data may still exist inside
// AngelScript until the refernce count is 0.
void Release();

// Capacity ----------------------------------------------------------------------------------

// returns the number of elements in the array
size_type size() const;
 
// resizes the array, adding unitialized data if the new size is bigger than the old size or
// deleting data if the new size is smaller
void resize(size_type n);

// returns true if the array is empty
bool empty() const;

// grows the buffer capacity
void reserve(size_type n);


// iterators ----------------------------------------------------------------------------
// returns an iterator to the begining of the array
iterator begin();

// returns an iterator to the end of the array
iterator end();

// returns a constant iterator to the begining of the array
const_iterator cbegin() const;

// returns a constant iterator to the end of the array
const_iterator cend() const;

// returns a constant iterator to the begining of the array
iterator begin() const;

// returns a constant iterator to the end of the array
iterator end() const;

// returns a reverse iterator to the begining of the array
reverse_iterator rbegin();

// returns a reverse iterator to the end of the array
reverse_iterator rend();

// returns a constant reverse iterator to the begining of the array
const_reverse_iterator crbegin() const;

// returns a constant reverse iterator to the end of the array
const_reverse_iterator crend() const;

// returns a constant reverse iterator to the begining of the array
const_reverse_iterator rbegin() const;

// returns a constant reverse iterator to the end of the array
const_reverse_iterator rend() const;

// Element Access -----------------------------------------------------------------------

// returns a reference to an element in the array. This will not throw an out-of-range exception.
// undefined behavior if out of range.
reference operator[](size_type index);

// returns a const reference to an element in the array. This will not throw an out-of-range exception.
// undefined behavior if out of range.
const_reference operator[](size_type index) const;

// returns a reference to an element in the array. This will throw an out-of-range exception.
reference at(size_type index);

// returns a constant reference to an element in the array. This will throw an out-of-range exception.
const_reference at(size_type) const;

// returns a reference to the first element
// undefined if empty
reference front();

// returns a constant reference to the first element
// undefined if empty
const_reference front() const;

// returns a reference to the last element
// undefined if empty
reference back();

// returns a constant reference to the last element
// undefined if empty
const_reference back() const;

// Modifiers ------------------------------------------------------------------------------------

// adds a value to the end of the array
void push_back (const value_type& val);

// removes the last element
void pop_back();

// assigns new data to the array using iterators.
template <class inputiterator=""&rt;
void assign (InputIterator first, InputIterator last);

// fills the array 
void assign (size_type n, const value_type& val);

// clears the contents of the array
void clear()