C++ STL-Style Array That's Compatible with AngelScript
I guess this will be like part 1.5 of my 2 part article on 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.
[color=#ff8c00]
Using the class.
[/color]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.
[code=:0]template 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:
[code=:0]// 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 string_array; // uses a user-defined array type called CScriptArrayInt// this type should be a specialized version of CScriptArray that only handles integersCScriptArraySTL 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:
[code=:0]// Initializes the array so it can be directly accessed using AngelScript// This must be called before the array can be usedint 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".
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
[code=:0]// Create the script engineasIScriptEngine *engine = asCreateScriptEngine(ANGELSCRIPT_VERSION); // Register needed add-onsRegisterStdString(engine);RegisterScriptArray(engine, true); // setup our string arrayCScriptArraySTL string_array;string_array.InitArray(engine, "array"); // register our array as a global variable in the scriptr = engine->RegisterGlobalProperty("array string_array", string_array.GetRef()); assert( r >= 0 ); // do other things and load and run scripts... // Release the arraystring_array.Release(); // Release the script engineengine->Release();[color=#ff0000]Get the Source.[/color]
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.
[code=:0]// 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 usedint InitArray(asIScriptEngine *engine, char *declaration, size_type init_length = 0); // returns a pointer to an array class that can be used in an AS scriptTArrayClass *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 arraysize_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 smallervoid resize(size_type n); // returns true if the array is emptybool empty() const; // grows the buffer capacityvoid reserve(size_type n); // iterators ----------------------------------------------------------------------------// returns an iterator to the begining of the arrayiterator begin(); // returns an iterator to the end of the arrayiterator end(); // returns a constant iterator to the begining of the arrayconst_iterator cbegin() const; // returns a constant iterator to the end of the arrayconst_iterator cend() const; // returns a constant iterator to the begining of the arrayiterator begin() const; // returns a constant iterator to the end of the arrayiterator end() const; // returns a reverse iterator to the begining of the arrayreverse_iterator rbegin(); // returns a reverse iterator to the end of the arrayreverse_iterator rend(); // returns a constant reverse iterator to the begining of the arrayconst_reverse_iterator crbegin() const; // returns a constant reverse iterator to the end of the arrayconst_reverse_iterator crend() const; // returns a constant reverse iterator to the begining of the arrayconst_reverse_iterator rbegin() const; // returns a constant reverse iterator to the end of the arrayconst_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 emptyreference front(); // returns a constant reference to the first element// undefined if emptyconst_reference front() const; // returns a reference to the last element// undefined if emptyreference back(); // returns a constant reference to the last element// undefined if emptyconst_reference back() const; // Modifiers ------------------------------------------------------------------------------------ // adds a value to the end of the arrayvoid push_back (const value_type& val); // removes the last elementvoid pop_back(); // assigns new data to the array using iterators.template void assign (InputIterator first, InputIterator last); // fills the array void assign (size_type n, const value_type& val); // clears the contents of the arrayvoid clear()
