code:
/**

\page doc_script_func_decl Function declaration

Global functions provide the mean to implement routines that should operate on some input and produce a result.
The functions themselves do not keep any memory, though they can update global variables, or memory passed by
reference.

The function is always declared together with the function body. There is no need to declare function prototypes,
as the function is globally visible regardless where it has been declared.

  // A simple function declaration
  int AFunction(int a, int b)
  {
    // Implement the function logic here
    return a + b;
  }

The type of the return value should be specified before the name of the function. If the function doesn't return anything
the type should be defined as 'void'. After the function name, the list of parameters is specified between parenthesis.
Each parameter is defined by its type and name.

\todo describe using namespace within statement block

\page doc_script_func_ref Parameter references

The parameters and return value can be of any type that can also be used for variable declarations. In addition, it is also
possible to make a function take a value by reference, i.e. rather than a copy of the original value, the parameter will refer
to the value.

Parameter references are used mainly for two purposes; a means of providing additional output from the function, or as a more performatic
way of passing values.

In AngelScript it is necessary to specify the intention of the parameter reference, i.e. if it is meant as input, output, or both.
This is necessary in order for the compiler to prepare the reference in a way that it cannot be invalidated due to some action during
the processing of the function.

Input references are written as &in. As the reference is meant as input only, the actual value it refers to normally is a copy of the
original so the function doesn't accidentally modify the original value. These are not commonly used, as they provide little benefit
over passing arguments by value. Only in some circumstances can the performance be improved, especially if the parameter is declared as
const too.

Output references are written as &out. These references are meant to allow the function to return additional values. When going in to
the function, the reference will point to an uninitialized value. After the function returns, the value assigned by the function will be
copied to the destination determined by the caller.

When the reference is meant as both input and output, it is declared as &inout, or just &. In this case the reference will point to the
actual value. Only \ref doc_datatypes_obj "reference types", i.e. that can have handles to them, are allowed to be passed as inout references. This is because
in order to guarantee that the reference will stay valid during the entire execution of the function, the value must be located in the
memory heap.

  void Function(const int &in a, int &out b, Object &c)
  {
    // Assigning an output value to the output reference
    b = a;

    // The object is an inout reference and refers to the real object
    c.DoSomething();
  }

\page doc_script_func_retref Return references

A function can also return references, which will allow the caller to modify the value pointed to
by the reference. To declare a function that return a reference include the & symbol between the
return type and name of the function. Add const before the type if the reference should be read only,
i.e. it shouldn't be possible to modify the value it points to.

  int property;
  int &Function()
  {
    // Return a reference to the property
    return property;
  }

  void main()
  {
    // Modify the value pointed to by the returned reference
    Function() = 1;
  }

Due to the need to guarantee that the reference is valid even after the function returns to the
caller there exist certain restrictions. You don't need to try to remember these restrictions as
the compiler will give an error if you they are violated, but if you do encounter a compile
error when returning a reference it will be good to understand why it is happening so that
you can determine how to avoid it.

\section doc_script_retref_global References to global variables are allowed

As a global variable is in the global scope, the lifetime of the variable is longer than the
scope of the function. A function can thus return a reference to a global variable, or even member
of an object reached through a global variable.

\section doc_script_refref_member References to class members are allowed

A class method can return a reference to a class property of the same object, because the caller
is required to hold a reference to the object it is known that the member will exist even after the
method returns.

The class method is also allowed to return reference to global variables, just like any other function.

\section doc_script_retref_local Can't return reference to local variables

Because local variables must be freed when the function exits, it is not allowed to return
a reference to them. The same is also true for any parameters that the function received. The
parameters are also cleaned up when the function exits, so they too cannot be returned by
reference.

\section doc_script_retref_deferred Can't use expressions with deferred parameters

For some function calls with arguments, there may be a necessary processing of the arguments
after the function call returned, e.g. to clean up the input object, or to assign the output
parameters. If the function that was called is returning a reference, then that reference cannot
in turn be returned again, as it may be invalidated by the deferred evaluation of the arguments.

\section doc_script_refref_cleanup Can't use expressions that rely on local objects

All local objects must be cleaned up before a function exits. For functions that return references
this clean-up happens before the return expression is evaluated, otherwise the cleanup of the
local objects may accidentally invalidate the reference. For this reason it is not possible
to use expressions that rely on local objects to evaluate the reference that should be returned.

Primitive values can be used though, as these do not require cleanup upon exit.

\page doc_script_func_overload Function overloading

Function overloading happens when more than one function with the same name is declared with
different parameters. This is a useful feature when an operation needs to be able to work with
different types of input, yet produce similar result.

The compiler is able to resolve which function to call by matching the type of each argument
expression to the function parameter, and eliminating the functions where there is no possible
conversion available. The compiler will do this for each argument from first to last. When all
arguments have been evaluated only one function should be the best match, otherwise the compiler
will give an error about the impossibility to determine the correct function to call.

The type of conversion that needs to be performed on the argument to get to the type of the
parameter determines how well a function matches. The following list gives the order of how one
type of conversion compares to another.

 - no conversion needed
 - conversion to const
 - conversion of enum to integer of same size
 - conversion of enum to integer of different size
 - size of primitive type increases
 - size of primitive type decreases
 - signed integer to unsigned integer conversion
 - unsigned integer to signed integer conversion
 - integer type to float type
 - float type to integer type
 - reference cast
 - object to primitive conversion
 - conversion to object
 - variable argument type

Observe that it is not possible to create overloads where the only difference is the return
type. This is because the return type is not part of the selection criteria that the compiler
uses to determine which function to call, the return type is just the result of the called
function.

  void Function(int a, float b, string c) {}
  void Function(string a, int b, float c) {}
  void Function(float a, string b, int c) {}

  void main()
  {
    Function(1, 2.5f, 'a');  // Will call the first overload
    Function('a', 1, 2.5f);  // Will call the second overload
    Function(2.5f, 'a', 1);  // Will call the third overload
  }

\page doc_script_func_defarg Default arguments

Sometimes implementing different functions for each overload is unnecessary when the difference can
be provided with a default value to a parameter. This is where default arguments come in handy.

By defining default arguments in the declaration of the function, the script doesn't have to provide
these values specifically when calling the function as the compiler will automatically fill in the
default arguments.

  void Function(int a, int b = 1, string c = "")
  {
    // Inside the function the arguments work normally
  }

  void main()
  {
    // Default arguments doesn't have to be informed
    // The following three calls produce the exact same result
    Function(0);
    Function(0,1);
    Function(0,1,"");
  }

When defining a default argument to one of the parameters, all subsequent parameters must have a
default argument too.

The default argument expression can include references to variables or call functions, but only if
the variables or functions are visible in the global scope.

  int myvar = 42;
  void Function(int a, int b = myvar) {}
  void main()
  {
    int myvar = 1;
    Function(1);    // This will use the global myvar and not the local myvar
  }

The special 'void' expression can be used as default argument to make an optional output parameter.

  void func(int &out output = void) { output = 42; }

\page doc_script_anonfunc Anonymous functions

Anonymous functions, or lambdas as they are sometimes called, are functions that are
declared locally for use with \ref doc_datatypes_funcptr "function handles".

The following is a quick demonstration on how to use anonymous functions.

  funcdef bool CMP(int first, int second);

  void main()
  {
    int valueA = 1, valueB = 2;

    bool result1 = func(valueA, valueB, function(a,b){ return a == b; });
    bool result2 = func(valueA, valueB, function(a,b){ return a != b; });
  }

  bool func(int a, int b, CMP \@f)
  {
    return f(a,b);
  }

The anonymous function takes on the signature of the function handle it is assigned to,
so the type of the arguments and the return type doesn't have to be explicitly declared.

It is not yet possible for anonymous functions to access variables declared in the same
scope as the function, i.e. they cannot be used as closures.

If there are multiple matching uses for the anonymous function it will be necessary to
explicitly inform the parameter types, so the ambiguity can be resolved.

  funcdef void A(int);
  funcdef void B(float);
  void func(A@) {}
  void func(B@) {}

  void main()
  {
    // Explicitly specify the type to tell the compiler that A is wanted
    func(function(int a) {});
  }

*/


code:
/**

\page doc_global_variable Variables

Global variables may be declared in the scripts, which will then be shared between
all contexts accessing the script module.

Variables declared globally like this are accessible from all functions. The
value of the variables are initialized at compile time and any changes are
maintained between calls. If a global variable holds a memory resource, e.g.
a string, its memory is released when the module is discarded or the script engine is reset.

  int MyValue = 0;
  const uint Flag1 = 0x01;

Variables of primitive types are initialized before variables of non-primitive types.
This allows class constructors to access other global variables already with their
correct initial value. The exception is if the other global variable also is of a
non-primitive type, in which case there is no guarantee which variable is initialized
first, which may lead to null-pointer exceptions being thrown during initialization.

Be careful with calling functions that may access global variables from within the
initialization expression of global variables. While the compiler tries to initialize the
global variables in the order they are needed, there is no guarantee that it will always
succeed. Should a function access a global variable that has not yet been initialized you
will get unpredictable behaviour or a null-pointer exception.

\page doc_global_virtprop Virtual properties

Virtual properties is a property with special behaviour for reading and writing to it.
These can be declared globally, but are most usually found as members of classes.

  int prop
  {
    get { return SomeValue(); }
    set { UpdateValue(value); }
  }

\see \ref doc_script_class_prop

\page doc_global_interface Interfaces

An interface works like a contract, the classes that implements an interface
are guaranteed to implement the methods declared in the interface. This allows
for the use of polymorphism in that a function can specify that it wants an
object handle to an object that implements a certain interface. The function
can then call the methods on this interface without having to know the
exact type of the object that it is working with.

  // The interface declaration
  interface MyInterface
  {
    void DoSomething();
  }

  // A class that implements the interface MyInterface
  class MyClass : MyInterface
  {
    void DoSomething()
    {
      // Do something
    }
  }

A class can implement multiple interfaces; Simply list all the interfaces
separated by a comma.

\page doc_global_import Imports

Sometimes it may be useful to load script modules dynamically without having to recompile
the main script, but still let the modules interact with each other. In that case the script
may import functions from another module. This declaration is written using the import
keyword, followed by the function signature, and then specifying which module to import from.

This allows the script to be compiled using these imported functions, without them actually
being available at compile time. The application can then bind the functions at a later time,
and even unbind them again.

If a script is calling an imported function that has not yet been bound the script will be
aborted with a script exception.

  import void MyFunction(int a, int b) from "Another module";

\page doc_global_enums Enums

Enums are a convenient way of registering a family of integer constants that may be used throughout the script
as named literals instead of numeric constants. Using enums often help improve the readability of the code, as
the named literal normally explains what the intention is without the reader having to look up what a numeric value
means in the manual.

Even though enums list the valid values, you cannot rely on a variable of the enum type to only contain values
from the declared list. Always have a default action in case the variable holds an unexpected value.

The enum values are declared by listing them in an enum statement. Unless a specific value is given for an enum
constant it will take the value of the previous constant + 1. The first constant will receive the value 0,
unless otherwise specified.

  enum MyEnum
  {
    eValue0,
    eValue2 = 2,
    eValue3,
    eValue200 = eValue2 * 100
  }

\page doc_global_typedef Typedefs

Typedefs are used to define aliases for other types.

Currently a typedef can only be used to define an alias for primitive types, but a future version will have
more complete support for all kinds of types.

  typedef float  real32;
  typedef double real64;

\page doc_global_funcdef Funcdefs

Funcdefs are used to define a function signature that will be used to store pointers to
functions with matching signatures. With this a function pointer can be created, which is
able to store dynamic pointers that can be invoked at a later time as a normal function call.

  // Define a function signature for the function pointer
  funcdef bool CALLBACK(int, int);

\see \ref doc_datatypes_funcptr for more information on how to use this

\page doc_global_namespace Namespaces

Namespaces can be used to organize large projects in logical units that may be easier
to remember. When using namespaces it is also not necessary to worry about using names
for entities that may exist in a different part of the project under a different namespace.

  namespace A
  {
    // Entities in a namespace see each other normally.
    void function() { variable++; }
    int variable;
  }

  namespace B
  {
    // Entities in different namespaces don't immediately see each other and
    // can reuse the same name without causing name conflicts. By using the
    // scoping operator the entity from the desired namespace can be explicitly
    // informed.
    void function() { A::function(); }
  }

Observe that in order to refer to an entity from a different namespace the scoping operator
must be used, unless it is a parent namespace in which case it is only necessary if the child
namespace declare the same entity.

  int var;
  namespace Parent
  {
    int var;
    namespace Child
    {
      int var;
      void func()
      {
        // Accessing variable in parent namespace requires
        // specifying the scope if an entity in a child namespace
        // uses the same name
        var = Parent::var;

        // To access variables in global scope the scoping
        // operator without any name should be used
        Parent::var = \::var;
      }
    }
  }

  void func()
  {
    // Access variable in a nested namespace requires
    // fully qualified scope specifier
    int var = Parent::Child::var;
  }

\todo Describe using namespace. Can be global and can be within namespace

*/

repo_name: Antidote/openrpgeditor

license: mit


code:
/**

\page doc_script_handle Object handles

An object handle is a type that can hold a reference to an object. With
object handles it is possible to declare more than one variables that refer
to the same physical object.

Not all types allow object handles to be used. None of the primitive
data types, bool, int, float, etc, can have object handles. Object types
registered by the application may or may not allow object handles, depending
on how they have been registered.

\see \ref doc_obj_handle

\section doc_script_handle_1 General usage

An object handle is declared by appending the @ symbol to the data type.

  object\@ obj_h;

This code declares the object handle obj and initializes it to null, i.e.
it doesn't hold a reference to any object.

In expressions variables declared as object handles are used the exact
same way as normal objects. But you should be aware that object handles are
not guaranteed to actually reference an object, and if you try to access the
contents of an object in a handle that is null an exception will be raised.

  object obj;
  object\@ obj_h;
  obj.Method();
  obj_h.Method();

Operators like = or any other operator registered for the object type work
on the actual object that the handle references. These will also throw an
exception if the handle is empty.

  object obj;
  object\@ obj_h;
  obj_h = obj;

When you need to make an operation on the actual handle, you should prepend
the expression with the \@ symbol. Setting the object handle to point to an
object is for example done like this:

  object obj;
  object\@ obj_h;
  \@obj_h = \@obj;

Note that the compiler can often implicitly determine that it is the handle of the
object that is needed rather than the actual object itself. In these cases it is not
necessary to explicitly prepend the expression with \@.

An object handle can be compared against another object handle
(of the same type) to verify if they are pointing to the same object or not.
It can also be compared against null, which is a special keyword that
represents an empty handle. This is done using the identity operator, <tt>is</tt>.

  object\@ obj_a, obj_b;
  if( obj_a is obj_b ) {}
  if( obj_a !is null ) {}

Observe, the == and != operators will do a value comparison on the objects referred to
by the handles using the \ref doc_script_class_cmp_ops "opEquals" or \ref doc_script_class_cmp_ops "opCmp"
operator overloads. Though, if the expressions are prepended with @ the operators will have the
same function as <tt>is</tt> and <tt>!is</tt>.

\section doc_script_handle_2 Object life times

An object's life time is normally for the duration of the scope the
variable was declared in. But if a handle outside the scope is set to
reference the object, the object will live on until all object handles are
released.

  object\@ obj_h;
  {
    object obj;
    \@obj_h = \@obj;

    // The object would normally die when the block ends,
    // but the handle is still holding a reference to it
  }

  // The object still lives on in obj_h ...
  obj_h.Method();

  // ... until the reference is explicitly released
  // or the object handle goes out of scope
  \@obj_h = null;

\section doc_script_handle_3 Object relations and polymorphing

Object handles can be used to write common code for related types, by means of
inheritance or interfaces. This allows a handle to an interface to store references
to all object types that implement that interface, similarly a handle to a base
class can store references to all object types that derive from that class.

  interface I {}
  class A : I {}
  class B : I {}

  // Store reference in handle to interface
  I \@i1 = A();
  I \@i2 = B();

  void function(I \@i)
  {
    // Functions implemented by the interface can be
    // called directly on the interface handle. But if
    // special treatment is need for a specific type, a
    // cast can be used to get a handle to the true type.
    A \@a = cast(i);
    if( a !is null )
    {
      // Access A's members directly
      ...
    }
    else
    {
      // The object referenced by i is not of type A
      ...
    }
  }

\section doc_script_handle_4 Const handles

Sometimes it is necessary to hold handles to objects that shouldn't be allowed to be modified.
This is done by prefixing the type with 'const', e.g.

  obj \@a;                      // handle to modifiable object
  const obj \@b;                // handle to non-modifiable object

A handle to a non-modifiable object can refer to both modifiable objects and non-modifiable objects, but
the script will not allow the object to be modified through that handle, nor allow the handle to be passed
to another handle that would allow modifications.

This syntax is not to be confused with handles that are themselves read-only, i.e. the handle cannot be
re-assigned to refer to a different object. Read-only handles like this are declared by adding the 'const' keyword
as a suffix after the '@' symbol.

  obj \@ const c = obj();       // read-only handle to a modifiable object
  const obj \@ const d = obj(); // read-only handle to a non-modifiable object

A read-only handle can only be initialized when declared.

*/


code:
/**

\page doc_script_mixin Mixin class

As \ref doc_script_class_inheritance "multiple inheritance" is not available,
it may sometimes be necessary to implement identical code in multiple classes.
When this is necessary it is recommended to use mixin classes to avoid writing
the identical code in multiple places.

Mixin classes allows a script to declare a partial class structure that will be
included into multiple different class declarations. The mixin classes themselves
are not real types and cannot be instanciated.

When a mixin class is included into a class declaration, the properties and methods
that were declared in the mixin class will be automatically replicated into the class.

  // Declare a mixin class
  mixin class MyMixin
  {
    void SomeMethod() { property++; }
    int property;
  }

  // Include the mixin class into the class to receive the methods and properties
  class MyClass : MyMixin
  {
    int OtherMethod()
    {
      SomeMethod();
      return property;
    }
  }

Properties and methods that have already been explicitly declared in the class will
not be included again. This way the mixin class can provide a default implementation
that can be overridden by the class that includes the mixin.

The class methods included from a mixin class will be compiled in the context of the class
that included it, so it is possible for a mixin class method to refer to properties and other
methods that are not declared in the mixin class if the class that includes the mixin class
provides those.

  mixin class MyMixin
  {
    void MethodA() { print("Default behaviour"); }
    void MethodB() { property++; }
  }

  class MyClass : MyMixin
  {
    // Override the default behaviour in MethodA
    void MethodA() { print("Overridden behaviour"); }

    // Declare the property that will be used by MethodB
    int property;
  }

Mixin class methods override inherited methods from base classes, just as if the included method
had been implemented in the derived class directly. Mixin class properties on the other hand
are not included if the property is already inherited from a base class.

  class MyBase
  {
    void MethodA() { print("Base behaviour"); }
    int property;
  }

  mixin class MyMixin
  {
    void MethodA() { print("Mixin behaviour"); }
    float property;
  }

  // Inheriting from base class and including mixin.
  // MyClass ends up with the property from the base
  // class and the method from the mixin class.
  class MyClass : MyBase, MyMixin
  {
  }

A mixin class can inform a list of interfaces that has to be implemented by the script
class that includes the mixin class. In this case the methods for the interfaces can optionally
be provided by the mixin class itself, or left out to be implemented by the script class directly.

A mixin class cannot inherit from other classes.

  interface I
  {
    void a();
    void b();
  }

  mixin class M : I
  {
    // provide default implementation of a()
    void a() { print("hello from a"); }

    // leave the implementation of b() to the script class
  }

  class C : M
  {
    // a() is implemented by mixin class

    // b() has to be explicitly implemented by script class
    void b() { print("hello from b"); }
  }

*/


code:
/**

\page doc_operator_precedence Operator precedence

In expressions, the operator with the highest precedence is always computed first.

\section unary Unary operators

Unary operators have the higher precedence than other operators, and between unary operators the operator closest to the actual value has the highest precedence. Post-operators have higher precedence than pre-operators.

This list shows the available unary operators.

::

scope resolution operator

[]

indexing operator

++ \--

post increment and decrement

.

member access

++ \--

pre increment and decrement

not !

logical not

+ -

unary positive and negative

~

bitwise complement

@

handle of

\section binary Binary and ternary operators

This list shows the dual and ternary operator precedence in decreasing order.

**

exponent

* / %

multiply, divide, and modulo

+ -

add and subtract

<< >> >>>

left shift, right shift, and arithmetic right shift

&

bitwise and

^

bitwise xor

|

bitwise or

<= < >= >

comparison

== != is !is xor ^^

equality, identity, and logical exclusive or

and &&

logical and

or ||

logical or

?:

condition

= += -= *= /= %= **= &=

|= ^= <<= >>= >>>=

assignment and compound assignments

*/


code:
/**

\page doc_reserved_keywords Reserved keywords and tokens

These are the keywords that are reserved by the language, i.e. they can't
be used by any script defined identifiers. Remember that the host application
may reserve additional keywords that are specific to that application.

and

abstract*

auto

bool

break

case

cast

catch

class

const

continue

default

delete*

do

double

else

enum

explicit*

external*

false

final*

float

for

from*

funcdef

function*

get*

if

import

in

inout

int

interface

int8

int16

int32

int64

is

mixin

namespace

not

null

or

out

override*

private

property*

protected

return

set*

shared*

super*

switch

this*

true

try

typedef

uint

uint8

uint16

uint32

uint64

void

while

xor

\todo Add foreach and using

\todo Separate reserved keywords and context sensitive keywords

* Not really a reserved keyword, but is recognized by the compiler as a built-in keyword.

These are the non-alphabetical tokens that are also used in the language syntax.

\*

\**

/

%

+

-

<=

<

>=

>

(

)

==

!=

?

:

=

+=

-=

\*=

/=

%=

\**=

++

\--

&

,

{

}

;

|

^

~

<<

>>

>>>

&=

|=

^=

<<=

>>=

>>>=

.

&&

||

!

[

]

^^

@

!is

::

\todo Add ...

Other than the above tokens there are also numerical, string, identifier, and comment tokens.

123456789
123.123e123
123.123e123f
0x1234FEDC
0d123987
0o1276
0b1010
'abc'
"abc"
"""heredoc"""
_Abc123
//
/*
*/

The characters space (32), tab (9), carriage return (13), line feed (10), and the
UTF8 byte-order-mark (U+FEFF) are all recognized as whitespace.

*/


code:
/**

\page doc_script_shared Shared script entities

If the application uses multiple script modules to control different parts
of the application it may sometimes be beneficial to allow parts of
the scripts to be shared between the script modules. The main benefits of
shared entities is the reduced memory consumption, and the fact that the
type of the shared entity is the same for the modules thus simplifying the
information exchange between modules where this is used.

Shared entities have a restriction in that they cannot access non-shared
entities because the non-shared entities are exclusive to the script module
in which they were compiled.

\section doc_script_shared_1 How to declare shared entities

To declare a shared entity simply put the keyword 'shared' before the ordinary
declaration, e.g.

  shared class Foo
  {
    void MethodInFoo(int b) { bar = b; }
    int bar;
  }

  shared void GlobalFunc() {}

If the script tries to access any non-shared entity from within the shared
entity then the compiler will give an error message.

Obviously, in order to work the scripts in all modules that share the entity
must implement the entity the same way. If this is not done, the compiler will
give an error in the scripts that are compiled after the first script that
implemented the shared entity.

The easiest way to guarantee that the implementation is the same is by using the
same source file, but this is not a requirement.

\section doc_script_shared_external External shared entities

An alternative to declaring the full shared entity in each module is to declared
the shared entity that is known to have been compiled before as external. This
can shorten the script, both reducing the size of the source code and the time to
compile it.

To declare a shared entity as external, simply add the keyword 'external' before
the declaration and end the statement with ';' after the signature that uniquely identifies
the entity.

  external shared class Foo;
  external shared void GlobalFunc();

When compiling a shared entity declared as external and the shared entity hasn't been compiled
in any other module before it, the compiler will give an error message.

\section doc_script_shared_2 What can be shared

Currently only the \ref doc_script_class "class", \ref doc_global_interface "interface",
\ref doc_script_func "function", \ref doc_global_enums "enum", and
\ref doc_datatypes_funcptr "funcdefs" entities can be shared.

Future versions may allow \ref doc_global_variable "global variables" to be shared too.

*/


code:
/**

\page doc_script_statements Statements

 - \ref variable
 - \ref expression
 - \ref if
 - \ref while
 - \ref break
 - \ref return
 - \ref block
 - \ref try

\todo describe using namespace within statement block. Should it be a statement?

\section variable Variable declarations

  int var = 0, var2 = 10;
  object\@ handle, handle2;
  const float pi = 3.141592f;

Variables must be declared before they are used within the statement block,
or any sub blocks. When the code exits the statement block where the variable
was declared the variable is no longer valid.

A variable can be declared with or without an initial expression. If it
is declared with an initial expression it, the expression must have the evaluate
to a type compatible with the variable type.

Any number of variables can be declared on the same line separated with commas, where
all variables then get the same type.

Variables can be declared as const. In these cases the value of the
variable cannot be changed after initialization.

Variables of primitive types that are declared without an initial value, will have
a random value. Variables of complex types, such as handles and object are initialized
with a default value. For handles this is null, for objects this is
what is defined by the object's default constructor.

\todo Describe variables with direct object initialization, i.e. object obj(expr);

\todo Describe how to declare variables of template types, i.e. array<int> arr;

\section expression Expression statement

  a = b;  // a variable assignment
  func(); // a function call

Any \ref doc_expressions "expression" may be placed alone on a line as a statement. This will
normally be used for variable assignments or function calls that don't return any value of importance.

All expression statements must end with a ;.

\section if Conditions: if / if-else / switch-case

  if( condition )
  {
    // Do something if condition is true
  }

  if( value < 10 )
  {
    // Do something if value is less than 10
  }
  else
  {
    // Do something else if value is greater than or equal to 10
  }

If statements are used to decide whether to execute a part of the logic
or not depending on a certain condition. The conditional expression must
always evaluate to true or false.

It's possible to chain several if-else statements, in which case
each condition will be evaluated sequencially until one is found to be true.

  switch( value )
  {
  case 0:
    // Do something if value equals 0, then leave
    break;

  case 2:
  case constant_value:
    // This will be executed if value equals 2 or the constant_value
    break;

  default:
    // This will be executed if value doesn't equal any of the cases
  }

If you have an integer (signed or unsigned) expression that have many
different outcomes that should lead to different code, a switch case is often
the best choice for implementing the condition. It is much faster than a
series of ifs, especially if all of the case values are close in numbers.

Each case should be terminated with a break statement unless you want the
code to continue with the next case.

The case value can be a constant variable that was initialized with a constant
expression. If the constant variable was initialized with an expression that
cannot be determined at compile time it cannot be used in the case values.

\section while Loops: while / do-while / for / foreach

  // Loop, where the condition is checked before the logic is executed
  int i = 0;
  while( i < 10 )
  {
    // Do something
    i++;
  }

  // Loop, where the logic is executed before the condition is checked
  int j = 0;
  do
  {
    // Do something
    j++;
  } while( j < 10 );

For both while and do-while the expression that determines
if the loop should continue must evaluate to either true or false. If it evaluates
to true, the loop continues, otherwise it stops and the code will continue with the next
statement immediately following the loop.

  // More compact loop, where condition is checked before the logic is executed
  for( int n = 0; n < 10; n++ )
  {
    // Do something
  }

The for loop is a more compact form of a while loop. The
first part of the statement (until the first ;) is executed only once,
before the loop starts. Here it is possible to declare a variable that will be visible
only within the loop statement. The second part is the condition that must be satisfied
for the loop to be executed. A blank expression here will always evaluate to true. The last
part is executed after the logic within the loop, e.g. used to increment an iteration variable.

Multiple variables can be declared in the for loop, separated by ,.
Likewise, multiple increment expressions can be used in the last part by separating them with ,.

\todo Document foreach loops. Reference \ref doc_script_class_foreach_ops

\section break Loop control: break / continue

  for(;;) // endless loop
  {
    // Do something

    // End the loop when condition is true
    if( condition )
      break;
  }

break terminates the smallest enclosing loop statement or switch statement.

  for(int n = 0; n < 10; n++ )
  {
    if( n == 5 )
      continue;

    // Do something for all values from 0 to 9, except for the value 5
  }

continue jumps to the next iteration of the smallest enclosing loop statement.

\section return Return statement

  float valueOfPI()
  {
    return 3.141592f; // return a value
  }

Any function with a return type other than void must be finished with a
return statement where expression evaluates to the same
data type as the function return type. Functions declared as void can have
return statements without any expression to terminate early.

\section block Statement blocks

  {
    int a;
    float b;

    {
      float a; // Override the declaration of the outer variable
               // but only within the scope of this block.

      // variables from outer blocks are still visible
      b = a;
    }

    // a now refers to the integer variable again
  }

A statement block is a collection of statements. Each statement block has its own scope of
visibility, so variables declared within a statement block are not visible outside the block.

\section try Try-catch blocks

 {
   try
   {
     DoSomethingThatMightThrowException();

     // This is not executed if an exception was thrown
   }
   catch
   {
     // This is executed if an exception was thrown
   }
  }

A try-catch block can be used if you're executing some code that might throw an exception
and you want to catch that exception and continue with the exception rather than just abort
the script.

Exceptions can occur for various reasons, some examples include, accessing null pointers in
uninitialized handles, division by zero, or exceptions raised from application registered functions.
In some cases exceptions are intentionally raised by the script to interrupt some execution.

\see \ref doc_script_stdlib_exception

*/


code:
/**

\page doc_script_stdlib Standard library

This pages describes the standard library provided by the AngelScript SDK. The applications that
use AngelScript may or may not expose the standard library to the scripts. Always consult the application's
manual for information on the API it exposes.

 - \subpage doc_script_stdlib_exception
 - \subpage doc_script_stdlib_string
 - \subpage doc_datatypes_arrays
 - \subpage doc_datatypes_dictionary
 - \subpage doc_datatypes_ref
 - \subpage doc_datatypes_weakref
 - \subpage doc_script_stdlib_datetime
 - \subpage doc_script_stdlib_coroutine
 - \subpage doc_script_stdlib_file
 - \subpage doc_script_stdlib_filesystem
 - \subpage doc_script_stdlib_system

\todo Add socket

\page doc_script_stdlib_exception Exception handling

\note The standard <tt>throw</tt> and <tt>getExceptionInfo</tt> are only
provided if the application \ref doc_addon_helpers_try "registers them".

\section try_func Functions

void throw(const string &in exception)

Explicitly throw an exception. The string should identify the type of exception, for logging or treating.

string getExceptionInfo()

Get the exception string for the last exception thrown.

\page doc_datatypes_arrays array

\note Arrays are only available in the scripts if the application \ref doc_addon_array "registers the support for them".
The syntax for using arrays may differ for the application you're working with so consult the application's manual
for more details.

\todo Explain the foreach support

It is possible to declare array variables with the array identifier followed by the type of the
elements within angle brackets.

Example:

  array<int> a, b, c;
  array<Foo\@> d;

a, b, and c are now arrays of integers, and d
is an array of handles to objects of the Foo type.

When declaring arrays it is possible to define the initial size of the array by passing the length as
a parameter to the constructor. The elements can also be individually initialized by specifying an
initialization list. Example:

  array<int> a;           // A zero-length array of integers
  array<int> b(3);        // An array of integers with 3 elements
  array<int> c(3, 1);     // An array of integers with 3 elements, all set to 1 by default
  array<int> d = {5,6,7}; // An array of integers with 3 elements with specific values

Multidimensional arrays are supported as arrays of arrays, for example:

  array<array<int>> a;                     // An empty array of arrays of integers
  array<array<int>> b = {{1,2},{3,4}}      // A 2 by 2 array with initialized values
  array<array<int>> c(10, array<int>(10)); // A 10 by 10 array of integers with uninitialized values

Each element in the array is accessed with the indexing operator. The indices are zero based, i.e. the
range of valid indices are from 0 to length - 1.

  a[0] = some_value;

When the array stores \ref doc_script_handle "handles" the elements are assigned using the \ref handle "handle assignment".

  // Declare an array with initial length 1
  array<Foo\@> arr(1);

  // Set the first element to point to a new instance of Foo
  \@arr[0] = Foo();

Arrays can also be created and initialized within expressions as \ref anonobj "anonymous objects".

  // Call a function that expects an array of integers as input
  foo({1,2,3,4});

  // If the function has multiple overloads supporting different types with
  // initialization lists it is necessary to explicitly inform the array type
  foo2(array<int> = {1,2,3,4});

\section doc_datatypes_arrays_addon Supporting array object

The array object supports a number of operators and has several class methods to facilitate the manipulation of strings.

The array object is a \ref doc_datatypes_obj "reference type" even if the elements are not, so it's possible
to use handles to the array object when passing it around to avoid costly copies.

\subsection doc_datatypes_array_addon_ops Operators

=       assignment

The assignment operator performs a shallow copy of the content.

[]      index operator

The index operator returns the reference of an element allowing it to be
inspected or modified. If the index is out of range, then an exception will be raised.

==, !=  equality

Performs a value comparison on each of the elements in the two arrays
and returns true if all match the used operator.

\subsection doc_datatypes_array_addon_mthd Methods

uint length() const

Returns the length of the array.

void resize(uint)

Sets the new length of the array.

void reverse()

Reverses the order of the elements in the array.

void insertAt(uint index, const T& in value)

void insertAt(uint index, const array<T>& arr)

Inserts a new element, or another array of elements, into the array at the specified index.

void insertLast(const T& in)

Appends an element at the end of the array.

void removeAt(uint index)

Removes the element at the specified index.

void removeLast()

Removes the last element of the array.

void removeRange(uint start, uint count)

Removes \a count elements starting from \a start.

void sortAsc()

void sortAsc(uint startAt, uint count)

Sorts the elements in the array in ascending order. For object types, this will use the type's opCmp method.

The second variant will sort only the elements starting at index \a startAt and the following \a count elements.

void sortDesc()

void sortDesc(uint startAt, uint count)

These does the same thing as sortAsc except sorts the elements in descending order.

void sort(const less &in compareFunc, uint startAt = 0, uint count = uint(-1))

This method takes as input a callback function to use for comparing two elements when sorting the array.

The callback function should take as parameters two references of the same type of the array elements and it
should return a bool. The return value should be true if the first argument should be placed before the second
argument.

  array<int> arr = {3,2,1};
  arr.sort(function(a,b) { return a < b; });

The example shows how to use the sort method with a callback to an \ref doc_script_anonfunc "anonymous function".

Here's another example where the callback function is declared explicitly:

  bool lessForInt(const int &in a, const int &in b)
  {
    return a < b;
  }
  bool lessForHandle(const obj \@ const &in a, const obj \@ const &in b)
  {
    return a < b;
  }
  void sortArrayOfInts(array<int> \@arr) { arr.sort(lessForInt); }
  void sortArrayOfHandles(array<obj\@> \@arr) { arr.sort(lessForHandle); }

int  find(const T& in)

int  find(uint startAt, const T& in)

These will return the index of the first element that has the same value as the wanted value.

For object types, this will use the type's opEquals or opCmp method to compare the value.
For arrays of handles any null handle will be skipped.

If no match is found the methods will return a negative value.

int  findByRef(const T& in)

int  findByRef(uint startAt, const T& in)

These will search for a matching address. These are especially useful for arrays of handles where
specific instances of objects are desired, and not just objects that happen to have equal value.

If no match is found the methods will return a negative value.

\subsection doc_datatypes_array_addon_example Script example

\todo update sample to use foreach

  int main()
  {
    array<int> arr = {1,2,3}; // 1,2,3
    arr.insertLast(0);        // 1,2,3,0
    arr.insertAt(2,4);        // 1,2,4,3,0
    arr.removeAt(1);          // 1,4,3,0

    arr.sortAsc();            // 0,1,3,4

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

    return sum;
  }

\page doc_datatypes_dictionary dictionary

\note Dictionaries are only available in the scripts if the application \ref doc_addon_dict "registers the support for them".
The syntax for using dictionaries may differ for the application you're working with so consult the application's manual
for more details.

\todo Explain the foreach support

The dictionary stores key-value pairs, where the key is a string, and the value can be of any type. Key-value
pairs can be added or removed dynamically, making the dictionary a good general purpose container object.

  obj object;
  obj \@handle;

  // Initialize with a list
  dictionary dict = {{'one', 1}, {'object', object}, {'handle', \@handle}};

  // Examine and access the values through get or set methods ...
  if( dict.exists('one') )
  {
    // get returns true if the stored type is compatible with the requested type
    bool isValid = dict.get('handle', \@handle);
    if( isValid )
    {
      dict.delete('object');
      dict.set('value', 1);
    }
  }

Dictionary values can also be accessed or added by using the index operator.

  // Read and modify an integer value
  int val = int(dict['value']);
  dict['value'] = val + 1;

  // Read and modify a handle to an object instance
  \@handle = cast<obj>(dict['handle']);
  if( handle is null )
    \@dict['handle'] = object;

Dictionaries can also be created and initialized within expressions as \ref anonobj "anonymous objects".

  // Call a function that expects a dictionary as input and no other overloads
  // In this case it is possible to inform the initialization list without explicitly giving the type
  foo({{'a', 1},{'b', 2}});

  // Call a function where there are multiple overloads expecting different
  // In this case it is necessary to explicitly define the type of the initialization list
  foo2(dictionary = {{'a', 1},{'b', 2}});

Dictionaries of dictionaries are created using \ref anonobj "anonymous objects" as well.

  dictionary d2 = {{'a', dictionary = {{'aa', 1}, {'ab', 2}}},
                   {'b', dictionary = {{'ba', 1}, {'bb', 2}}}};

\section doc_datatypes_dictionary_addon Supporting dictionary object

The dictionary object is a \ref doc_datatypes_obj "reference type", so it's possible
to use handles to the dictionary object when passing it around to avoid costly copies.

\subsection doc_datatypes_dictionary_addon_ops Operators

=       assignment

The assignment operator performs a shallow copy of the content.

[]      index operator

The index operator takes a string for the key, and returns a reference to the \ref doc_datatypes_dictionaryValue_addon "value".
If the key/value pair doesn't exist it will be inserted with a null value.

\subsection doc_datatypes_dictionary_addon_mthd Methods

void set(const string &in key, ? &in value)

void set(const string &in key, int64 &in value)

void set(const string &in key, double &in value)

Sets a key/value pair in the dictionary. If the key already exists, the value will be changed.

bool get(const string &in key, ? &out value) const

bool get(const string &in key, int64 &out value) const

bool get(const string &in key, double &out value) const

Retrieves the value corresponding to the key. The methods return false if the key is not
found, and in this case the value will maintain its default value based on the type.

array<string> \@getKeys() const

This method returns an array with all of the existing keys in the dictionary.
The order of the keys in the array is undefined.

bool exists(const string &in key) const

Returns true if the key exists in the dictionary.

bool delete(const string &in key)

Removes the key and the corresponding value from the dictionary. Returns false if the key wasn't found.

void deleteAll()

Removes all entries in the dictionary.

bool isEmpty() const

Returns true if the dictionary doesn't hold any entries.

uint getSize() const

Returns the number of keys in the dictionary.

\section doc_datatypes_dictionaryValue_addon Supporting dictionaryValue object

The dictionaryValue type is how the \ref doc_datatypes_dictionary_addon "dictionary" object stores the
values. When accessing the values through the dictionary index operator a reference to a dictionaryValue is returned.

The dictionaryValue type itself is a value type, i.e. no handles to it can be held, but it can hold handles
to other objects as well as values of any type.

\subsection doc_datatypes_dictionaryValue_addon_ops Operators

=       assignment

The value assignment operator should be used to copy a value into the dictionaryValue.

\@=     handle assignment

The handle assignment operator should be used to set the dictionaryValue to refer to an object instance.

cast<type>  cast operator

The cast operator is used to dynamically cast the handle held in the dictionaryValue to the desired type.
If the dictionaryValue doesn't hold a handle, or the handle is not compatible with the desired type, the
cast operator will return a null handle.

type()      conversion operator

The conversion operator is used to return a new value of the desired type. If no value conversion is found,
an uninitialized value of the desired type is returned.

\page doc_script_stdlib_string string

\todo Add format and scan

\note Strings are only available in the scripts if the application \ref doc_addon_std_string "registers the support for them".
The syntax for using strings may differ for the application you're working with so consult the application's manual
for more details.

\see \ref doc_datatypes_strings for information on syntax for string literals

\section doc_datatypes_strings_addon Supporting string object and functions

The string object supports a number of operators, and has several class methods and supporting
global functions to facilitate the manipulation of strings.

\subsection doc_datatypes_strings_addon_ops Operators

=            assignment

The assignment operator copies the content of the right hand string into the left hand string.

Assignment of primitive types is allowed, which will do a default transformation of the primitive to a string.

+, +=        concatenation

The concatenation operator appends the content of the right hand string to the end of the left hand string.

Concatenation of primitives types is allowed, which will do a default transformation of the primitive to a string.

==, !=       equality

Compares the content of the two strings.

<, >, <=, >= comparison

Compares the content of the two strings. The comparison is done on the byte values in the strings, which
may not correspond to alphabetical comparisons for some languages.

[]           index operator

The index operator gives access to a single byte in the string.

\subsection doc_datatypes_strings_addon_mthd Methods

uint           length() const

Returns the length of the string.

void           resize(uint)

Sets the length of the string.

bool           isEmpty() const

Returns true if the string is empty, i.e. the length is zero.

string         substr(uint start = 0, int count = -1) const

Returns a string with the content starting at \a start and the number of bytes given by count. The default arguments will return the whole string as the new string.

void insert(uint pos, const string &in other)

Inserts another string \a other at position \a pos in the original string.

void erase(uint pos, int count = -1)

Erases a range of characters from the string, starting at position \a pos and counting \a count characters.

int            findFirst(const string &in str, uint start = 0) const

Find the first occurrence of the value \a str in the string, starting at \a start. If no occurrence is found a negative value will be returned.

int            findLast(const string &in str, int start = -1) const

Find the last occurrence of the value \a str in the string. If \a start is informed the search will begin at that position, i.e. any potential occurrence after that position will not be searched. If no occurrence is found a negative value will be returned.

int            findFirstOf(const string &in chars, int start = 0) const

int            findFirstNotOf(const string &in chars, int start = 0) const

int            findLastOf(const string &in chars, int start = -1) const

int            findLastNotOf(const string &in chars, int start = -1) const

The first variant finds the first character in the string that matches on of the characters in \a chars, starting at \a start. If no occurrence is found a negative value will be returned.

The second variant finds the first character that doesn't match any of those in \a chars. The third and last variant are the same except they start the search from the end of the string.

\note These functions work on the individual bytes in the strings. They do not attempt to understand encoded characters, e.g. UTF-8 encoded characters that can take up to 4 bytes.

\todo Add info on regexFind (also doesn't handle utf-8)

array<string>@ split(const string &in delimiter) const

Splits the string in smaller strings where the delimiter is found.

\subsection doc_datatypes_strings_addon_funcs Functions

string join(const array<string> &in arr, const string &in delimiter)

Concatenates the strings in the array into a large string, separated by the delimiter.

int64  parseInt(const string &in str, uint base = 10, uint &out byteCount = 0)

uint64 parseUInt(const string &in str, uint base = 10, uint &out byteCount = 0)

Parses the string for an integer value. The \a base can be 10 or 16 to support decimal numbers or
hexadecimal numbers. If \a byteCount is provided it will be set to the number of bytes that were
considered as part of the integer value.

double parseFloat(const string &in, uint &out byteCount = 0)

Parses the string for a floating point value. If \a byteCount is provided it will be set to the
number of bytes that were considered as part of the value.

string formatInt(int64 val, const string &in options = '', uint width = 0)

string formatUInt(uint64 val, const string &in options = '', uint width = 0)

string formatFloat(double val, const string &in options = '', uint width = 0, uint precision = 0)

The format functions takes a string that defines how the number should be formatted. The string
is a combination of the following characters:

  - l = left justify
  - 0 = pad with zeroes
  - + = always include the sign, even if positive
  - space = add a space in case of positive number
  - h = hexadecimal integer small letters (not valid for formatFloat)
  - H = hexadecimal integer capital letters (not valid for formatFloat)
  - e = exponent character with small e (only valid for formatFloat)
  - E = exponent character with capital E (only valid for formatFloat)

Examples:

  // Left justify number in string with 10 characters
  string justified = formatInt(number, 'l', 10);

  // Create hexadecimal representation with capital letters, right justified
  string hex = formatInt(number, 'H', 10);

  // Right justified, padded with zeroes and two digits after decimal separator
  string num = formatFloat(number, '0', 8, 2);

\page doc_datatypes_ref ref

\note ref is only available in the scripts if the application \ref doc_addon_handle "registers the support for it".

The ref type works like a generic object handle. Normally a \ref handles "handle" can only refer to
objects of a specific type or those related to it, however not all object types are related, and this is
where ref comes in. Being completely generic it can refer to any object type (as long as it is a \ref doc_datatypes_obj "reference type").

  // Two unrelated types
  class car {}
  class banana {}

  // A function that take the ref type as argument can work on both types
  void func(ref \@handle)
  {
    // Cast the handle to the expected type and check which cast work
    car \@c = cast<car>(handle);
    banana \@b = cast<banana>(handle);
    if( c !is null )
      print('The handle refers to a car\\n');
    else if( b !is null )
      print('The handle refers to a banana\\n');
    else if( handle !is null )
      print('The handle refers to a different object\\n');
    else
      print('The handle is null\\n');
  }

  void main()
  {
    // Assigning a ref handle works the same way as ordinary handles
    ref \@r = car();
    func(r);
    \@r = banana();
    func(r);
  }

\section doc_datatypes_ref_addon Supporting ref object

The ref object supports only a few operators as it is just a place holder for handles.

\subsection doc_datatypes_ref_addon_ops Operators

\@=          handle assignment

The handle assignment operator is used to set the object that the referred to by the ref type.

is, !is      identity operator

The identity operators are used to compare the address of the object referred to by the ref type.

cast<type>   cast operator

The cast operator is used to perform a dynamic cast to the desired type.
If the type is not compatible with the object referred to by the ref type this will return null.

\page doc_datatypes_weakref weakref

\note weakref is only available in the scripts if the application \ref doc_addon_weakref "registers the support for it".

An object handle will keep the object it refers to alive as long as the handle itself exists. A weakref object
can be used in place of the handle where the reference to the object is needed but the object shouldn't be kept alive.

  class MyClass {}
  MyClass \@obj1 = MyClass();

  // Keep a weakref to the object
  weakref<MyClass> r1(obj1);

  // Keep a weakref to a readonly object
  const_weakref<MyClass> r2(obj1);

  // As long as there is a strong reference to the object,
  // the weakref will be able to return a handle to the object
  MyClass \@obj2 = r1.get();
  assert( obj2 !is null );

  // After all strong references are removed the
  // weakref will only return null
  \@obj1 = null;
  \@obj2 = null;

  const MyClass \@obj3 = r2.get();
  assert( obj3 is null );

\section doc_datatypes_weakref_addon Supporting weakref object

\subsection doc_datatypes_weakref_addon_construct Constructors

weakref<T>()

weakref<T>(T@) explicit

const_weakref<T>()

const_weakref<T>(const T@) explicit

\subsection doc_datatypes_weakref_addon_ops Operators

\@=          handle assignment

The handle assignment operator is used to set the object that the referred to by the ref type.

=            value assignment

The value assignment operator is used when one weakref object is copied to another.

is, !is      identity operator

The identity operators are used to compare the address of the object referred to by the ref type.

cast<type>   implicit cast operator

The implicit cast operator is used to cast the weak ref type to strong reference of the type.
If the object referred to by the weakref is already dead this operator will return null.

\subsection doc_datatypes_weakref_addon_mthd Methods

T@ get() const

This does the exact same thing as the implicit cast operator. It is just a more explicit way of
writing it.

\page doc_script_stdlib_datetime datetime

\note datetime is only available in the scripts if the application \ref doc_addon_datetime "registers support for it".

The datetime type represents a calendar date and time. It can be used to do math operations with
dates, such as comparing two dates, determining the difference between dates, and addition/substraction
on dates to form new dates.

It can also be used to get the current system time and thus allow measuring time for tasks, albeit with
a rather low precision of seconds only.

\section doc_datatype_datetime_addon Supporting datetime object

\todo describe weekday

\subsection doc_addon_datetime_2_construct Constructors

datetime()

datetime(const datetime &in other)

datetime(uint y, uint m, uint d, uint h = 0, uint mi = 0, uint s = 0)

The default constructor initializes the object with the current system time in the universal time zone (UTC). If you need
to consider a specific timezone with or without daylight savings then remember to adjust the time accordingly by
adding the number of seconds for the difference.

The copy constructor copíes the content of the other object.

The set constructor initializes the object with the given date and time.

\subsection doc_addon_datetime_2_methods Methods

uint get_year() const property

Returns the year of the date stored in the object.

uint get_month() const property

Returns the month of the date stored in the object. The range is 1 to 12, i.e. 1 is January, 12 is December, and so on.

uint get_day() const property

Returns the day of the month of the date stored in the object.

uint get_hour() const property

Returns the hour of the time stored in the object. The range is 0 to 23.

uint get_minute() const property

Returns the minute of the time stored in the object. The range is 0 to 59.

uint get_second() const property

Returns the second of the time stored in the object. The range is 0 to 59.

bool setDate(uint year, uint month, uint day)

bool setTime(uint hour, uint minute, uint second)

Sets the date or time. Returns true if the specified date or time is valid. Does not modify the object if not valid.

\subsection doc_addon_datetime_2_ops Operators

= assignment

The assignment operator copies the content of the other object.

- difference

When subtracting one datetime object from another the result is the number of seconds between them.

+ add

- subtract

+= add assign

-= subtract assign

The datetime object can be added or subtracted with seconds to form a new datetime object.

==, != equality

<, <=, >=, > comparison

The datetime object can be compared for equality or relativity.

\page doc_script_stdlib_coroutine Co-routines

\note Support for co-routines is only available in the scripts if the application \ref doc_addon_ctxmgr "registers support for it".

\section doc_script_stdlib_coroutine_1 Functions

funcdef void coroutine(dictionary@)

void createCoRoutine(coroutine @, dictionary @)

This function is used to create a co-routine. The co-routine will initiate in a
yielded state, i.e. it will only begin execution once the control is given to it
by the current thread.

Multiple co-routines can be created, and they will each take turn to execute in
round-robin fashion.

void yield()

Yields control of the execution for the next co-routine in the queue.

When a co-routine receives control it will resume execution from the last call to
yield, or the entry point if this is the first time the co-routine is allowed to execute.

\page doc_script_stdlib_file file

\note file is only available in the scripts if the application \ref doc_addon_file "registers support for it".

Script example:

  file f;
  // Open the file in 'read' mode
  if( f.open("file.txt", "r") >= 0 )
  {
      // Read the whole file into the string buffer
      string str = f.readString(f.getSize());
      f.close();
  }

\section doc_script_stdlib_file_1 Supporting file object

\subsection doc_script_stdlib_file_1_1 Methods

int open(const string &in filename, const string &in mode)

Opens a file. The mode can be "r" for reading, "w" for writing, or "a" for appending.

If the file couldn't be opened, a negative value is returned.

int close()

Closes the file.

If no file is open, a negative value is returned.

int getSize() const

Returns the size of the file, or a negative value if no file is open.

bool isEndOfFile() const

Returns true if the current position is at the end of the file.

string readString(uint length)

Reads \a length bytes into a string and returns it.

string readLine()

Reads until a new line character, e.g. '\\n', or end-of-file and returns the string. The new line character is also returned in the string.

int64 readInt(uint bytes)

Reads \a bytes as a signed integer number.

uint64 readUInt(uint bytes)

Reads \a bytes as an unsigned integer number.

float readFloat()

Reads 4 bytes as a float number.

double readDouble()

Reads 8 bytes as a double number.

int writeString(const string &in str)

Writes the bytes of the string into the file.

Returns the number of bytes written, or a negative value on error.

int writeInt(int64 value, uint bytes)

Writes \a bytes as a signed integer value.

Returns the number of bytes written, or a negative value on error.

int writeUInt(uint64 value, uint bytes)

Writes \a bytes as an unsigned integer value.

Returns the number of bytes written, or a negative value on error.

int writeFloat(float value)

Writes 4 bytes as a float value.

Returns the number of bytes written, or a negative value on error.

int writeDouble(double value)

Writes 8 bytes as a double value.

Returns the number of bytes written, or a negative value on error.

int getPos() const

Returns the current position in the file, or a negative value on error.

int setPos(int pos)

Sets the current position in the file. Returns the previous position or a negative value on error.

int movePos(int delta)

Moves the position \a delta bytes relative to the current position. Returns the previous position or a negative value on error.

\subsection doc_script_stdlib_file_1_2 Properties

bool mostSignificantByteFirst

This property should be set to true if the most significant bit should be read or written first in the methods that reads/writes numbers.

It is set to false by default, which is the standard on most platforms.

\page doc_script_stdlib_filesystem filesystem

\note filesystem is only available in the scripts if the application \ref doc_addon_filesystem "registers support for it".

\section doc_script_stdlib_filesystem_1 Supporting filesystem object

\subsection doc_script_stdlib_filesystem_1_1 Methods

bool changeCurrentPath(const string &in path)

This changes the current directory used by the filesystem object. It will return true if the given path is valid.

It doesn't change the application' working directory.

string getCurrentPath() const

Returns the current path used by the filesystem object.

array<string> \@getDirs()

Returns a list with the names of all directories in the current path.

array<string> \@getFiles()

Returns a list with the names of all files in the current path.

bool isDir(const string &in path)

Returns true if the given path is a directory.

bool isLink(const string &in path)

Returns true if the given path is a link.

int64 getSize(const string &in) const

Returns the size of a file.

Returns -1 if the file doesn't exist or cannot be accessed.

int makeDir(const string &in)

Creates a new directory. Returns 0 on success.

int removeDir(const string &in)

Removes a directory. Will only remove the directory if it is empty. Returns 0 on success.

int deleteFile(const string &in)

Deletes a file. Returns 0 on success.

int copyFile(const string &in, const string &in)

Copies a file. Returns 0 on success.

int move(const string &in, const string &in)

Moves or renames a file or directory. Returns 0 on success.

datetime getCreateDateTime(const string &in)

Returns the date and time of the file creation in UTC.

Raises an exception if the file doesn't exist or cannot be accessed.

datetime getModifyDateTime(const string &in)

Returns the date and time of the last modification of the file in UTC.

Raises an exception if the file doesn't exist or cannot be accessed.

\page doc_script_stdlib_system System functions

\note The system functions are only available in the scripts if the application \ref doc_samples_asrun "registers support for it".

\section doc_script_stdlib_system_1 Functions

void print(const string &in line)

Prints a line to the standard output.

\todo Describe how to set color on the output

string getInput()

Gets a line from the standard input.

array<string> \@getCommandLineArgs()

Gets the command line arguments as an array.

int exec(const string &in cmd)

int exec(const string &in cmd, string &out output)

Executes a system command.

Returns -1 on error or raises an exception. On success returns the exit code from the system commmand.

The second alternative allows to capture the stdout into a string, to be further processed.

*/


code:
/**

\page doc_serialization Serialization

To serialize scripts the application needs to be able to iterate through all variables, and objects that have any relation to the
script and store their content in a way that would allow it to be restored at a later time. For simple values this is trivial, but
for objects and handles it becomes more complex as it is necessary to keep track of references between objects and internal structure
of both classes defined by scripts and application registered types.

Iterating through the variables and members of objects is already described in the article about \ref doc_adv_reflection "reflection",
so this article will focus on the storing and restoring of values.

Look at the source code for the \ref doc_addon_serializer add-on for a sample implementation of serialization.

\see \ref doc_adv_dynamic_build_hot

\section doc_serialization_modules Serialization of modules

To serialize the script modules you'll need to enumerate all the global variables and \ref doc_serialization_vars "serialize each of them".

When deserializing the module, first compile it normally either from \ref doc_compile_script "source script" or
by \ref doc_adv_precompile "loading a pre-compiled byte code", except you first need to turn off initialization of
global variables by \ref asIScriptEngine::SetEngineProperty "turning off the engine property asEP_INIT_GLOBAL_VARS_AFTER_BUILD".

\section doc_serialization_vars Serialization of global variables

To serialize a global variable you'll need the name and namespace to use as the key for the variable, and then the type id and address
of the variable. You get these with the methods \ref asIScriptModule::GetGlobalVar and \ref asIScriptModule::GetAddressOfGlobalVar. If
the type id is for a primitive type, then the value can be stored as is. If it is a handle or reference you'll need to serialize the
reference itself and the object it refers to. If the type id is an object type then \ref doc_serialization_objects "serialize the object"
and its content.

To deserialize the global variable, you'll use the name and namespace to look it up, and then use GetAddressOfGlobalVar to get the
address of the memory that needs to be restored with the serialized content.

\section doc_serialization_objects Serialization of objects

To serialize script objects you'll use the \ref asIScriptObject interface to iterate over the members to store the content. Remember that objects can hold
references to other objects and even to itself so it is important to keep track of object instances already serialized and just store a reference if
the same object comes up again.

When deserializing the script objects you should first allocate the memory using \ref asIScriptEngine::CreateUninitializedScriptObject so that the constructor
is not executed, and then iterate over the members to restore their content.

For application registered types you obviously need to provide your own implementation as the script engine doesn't know the full content of the types
and thus cannot provide an interface for serialization.

\section doc_serialization_contexts Serialization of contexts

Serialization of a script context involves storing the full call stack with all the function calls, local variables, registers, etc. To do this you'll
use the \ref asIScriptContext interface.

 - Use \ref asIScriptContext::GetCallstackSize "GetCallstackSize" to get the size of the call stack
 - For each call stack entry do:
   - Use \ref asIScriptContext::GetCallStateRegisters "GetCallStateRegisters" to store the registers, i.e. program pointer, stack pointer, etc.
   - Use \ref asIScriptContext::GetVarCount "GetVarCount", \ref asIScriptContext::GetVar "GetVar", and \ref asIScriptContext::GetAddressOfVar "GetAddressOfVar" to store all local variables, including unnamed temporary variables
   - Use \ref asIScriptContext::GetArgsOnStackCount "GetArgsOnStackCount" and \ref asIScriptContext::GetArgOnStack "GetArgOnStack" to store values pushed on the stack for a subsequent function call
 - Use \ref asIScriptContext::GetStateRegisters "GetStateRegisters" to store additional context registers

To deserialize a context follow these steps:

 - Call \ref asIScriptContext::StartDeserialization "StartDeserialization" to tell the context that a deserialization will be done
 - For each call stack entry previously stored do:
   - Call \ref asIScriptContext::PushFunction "PushFunction" to reserve space for a call stack entry
   - Call \ref asIScriptContext::SetCallStateRegisters "SetCallStateRegisters" to restore the registers
   - Use \ref asIScriptContext::GetVar "GetVar" and \ref asIScriptContext::GetAddressOfVar "GetAddressOfVar" to restore all local variables
   - Use \ref asIScriptContext::GetArgOnStack "GetArgOnStack" to restore values pushed on the stack
 - Call \ref asIScriptContext::SetStateRegisters "SetStateRegisters" to restore additional context registers
 - Call \ref asIScriptContext::FinishDeserialization "FinishDeserialization" to conclude the serialization and allow the execution to resume

\subsection Limitations

The following are some limitations with serialization of contexts:

 - The serialization is platform dependent, i.e. it is not possible to serialize a context on a 32bit platform and then deserialize it on a 64bit platform or vice versa
 - Attempting to deserialize a context after \ref doc_adv_dynamic_build_hot "hot reloading" modified scripts has undefined behavior, and will most likely cause crashes

*/


code:
/**

\page doc_strings Custom string type

Almost all applications have some need to manipulate text strings in one way or another. However
most applications have very different needs, and also different ways of representing their string
types. For that reason, AngelScript doesn't come with its own built-in string type that the application
would be forced to adapt to, instead AngelScript allows the application to \ref doc_register_api "register its own string type".

This article presents the options for customizing the script language to the application's needs with regards
to strings. If you do not want, or do not need to have AngelScript use your own string type, then I suggest
you use the standard add-on for \ref doc_addon_std_string "std::string registration".

\section doc_string_register Registering the custom string type

To make the script language support strings, the string type must first be \ref doc_register_type "registered as type" with the engine.
The application is free to use any valid type name, not necessarily 'string', though it is probably the most commonly used name. The
custom string type can also be either value type or a reference type at the preference of the application developer.

Once the string type is registered, the application must also provide a string factory to allow the scripts
to use literal string constants. The string factory must implement the \ref asIStringFactory interface, and be
registered with the \ref asIScriptEngine::RegisterStringFactory method.

The string factory must implement all 3 methods of the asIStringFactory interface. The \ref asIStringFactory::GetStringConstant
"GetStringConstant" method receives the raw string data by the compiler and should return a pointer to the custom string object
that represents that string. The \ref asIStringFactory::ReleaseStringConstant "ReleaseStringConstant" is called when the engine no longer needs the
string constant, e.g. when discarding a module. The \ref asIStringFactory::GetRawStringData "GetRawStringData" is called by the
engine when the raw string data is needed, e.g. when saving bytecode or when requesting a copy of a string constant.

Although not necessary, the application should preferably implement caching of the string constants, so that if two calls to
GetStringConstant with the same raw string data is received the string factory returns the address of the same string instance
in both calls. This will reduce the amount of memory needed to store the string constants, especially when scripts use the same
string constants in many places. Remember, when using caching, the ReleaseStringConstant must only free the string object when
the last call for that same object is done.

\see \ref doc_addon_std_string "The standard string add-on"

\section doc_strings_1 Unicode vs ASCII

Is your application using Unicode or plain ASCII for the text? If you use Unicode, then you'll want to encode the scripts
in UTF-8, which the AngelScript compiler supports natively. By default AngelScript expects the scripts to have been encoded
in UTF-8, but should you prefer ASCII you can turn this off by setting the engine property \ref asEP_SCRIPT_SCANNER to 0 right
after creating the engine.

\code
// Set engine to use ASCII scanner for script code
engine->SetEngineProperty(asEP_SCRIPT_SCANNER, 0);
\endcode

If you do use Unicode, then you'll also want to choose the desired encoding for the string literals, either UTF-8 or UTF-16. By
default the string literals in AngelScript are encoded with UTF-8, but if your application is better prepared for UTF-16 then
you'll want to change this by setting the engine property \ref asEP_STRING_ENCODING to 1 before compiling your scripts.

\code
// Set engine to use UTF-16 encoding for string literals
engine->SetEngineProperty(asEP_STRING_ENCODING, 1);
\endcode

Observe that the \ref asIScriptEngine::RegisterStringFactory "string factory" called by the engine to create new strings gives the
size of the string data in bytes even for UTF-16 encoded strings, so you'll need to divide the size by two to get the number of
characters in the string.

\section doc_string_2 Multiline string literals

There is also a couple of options that affect the script language itself a bit. If you like the convenience of allowing string
literals to span multiple lines of code, then you can turn this on by setting the engine property \ref asEP_ALLOW_MULTILINE_STRINGS
to true. Without this the compiler will give an error if it encounters a line break before the end of the string.

\code
// Set engine to allow string literals with line breaks
engine->SetEngineProperty(asEP_ALLOW_MULTILINE_STRINGS, true);
\endcode

Observe that the line ending encoding of the source file will not be modified by the script compiler, so depending on how the file
has been saved, you may get strings using different line endings.

The \ref doc_datatypes_strings "heredoc strings" are not affected by this setting, as they are designed to support multiline text sections.

\section doc_string_3 Character literals

By default AngelScript doesn't have character literals as C and C++ does. A string literal can be written with double quotes or single
quotes and still have the same meaning. This makes it convenient to embed scripts in XML files or C/C++ source files where double
quotes would otherwise end the script code.

If you want to have single quoted literals mean a single character literal instead of a string, then you can do so by setting the
engine property \ref asEP_USE_CHARACTER_LITERALS to true. The compiler will then convert single quoted literals to an integer number
representing the first character.

\code
// Set engine to use character literals
engine->SetEngineProperty(asEP_USE_CHARACTER_LITERALS, true);
\endcode

Observe that the \ref asEP_SCRIPT_SCANNER property has great importance in this case, as an ASCII character can only represent values
between 0 and 255, whereas a Unicode character can represent values between 0 and 1,114,111.

*/


code:
/**

\page doc_understanding_as Understanding AngelScript

In order to successfully use AngelScript it is important to
understand some differences between AngelScript and C++. While
the library has been written so that it can be embedded within
the application with as little change to the application functions
and classes as possible, there are some care that must be taken
when passing objects between AngelScript and C++.

 - \subpage doc_versions
 - \subpage doc_module
 - \subpage doc_as_vs_cpp_types
 - \subpage doc_obj_handle
 - \subpage doc_memory
 - \subpage doc_typeid

\todo Add article on the calling conventions used by AngelScript

\todo Add article on sandboxing

\page doc_typeid Structure of the typeid

The typeid used in several functions of the AngelScript interface is a 32bit signed integer.
Negative values are not valid typeids, and functions returning a typeid can thus use negative
values to \ref asERetCodes "indicate errors".

The value contained in the typeid is composed to two parts, the lower bits indicated by \ref asTYPEID_MASK_SEQNBR
is a sequence that will increment with each new type registered by the application or declared in scripts. The
higher bits form a bit mask indicating the category of the type. The bits in the bit mask have
the following meaning:

 - bit \ref asTYPEID_APPOBJECT : The type is an application registered object
 - bit \ref asTYPEID_SCRIPTOBJECT : The type is a script declared type, i.e. object can be cast to \ref asIScriptObject
 - bit \ref asTYPEID_TEMPLATE : The type is a template, and cannot be instantiated
 - bit \ref asTYPEID_HANDLETOCONST : The type is a handle to a const object, i.e. the referenced object must not be modified
 - bit \ref asTYPEID_OBJHANDLE : The type is a object handle, i.e. the value must be dereferenced to get the address of the actual object
 - bit 32: The typeid is invalid, and the number indicates an error from \ref asERetCodes

To identify if a typeid is to a primitive check that the bits in \ref asTYPEID_MASK_OBJECT are zero. This will be true
for all built-in primitive types and for enums.

The built-in primitive types have pre-defined ids as seen in the enum \ref asETypeIdFlags, and can be directly compared
for their value, e.g. the typeid for a 32bit signed integer is \ref asTYPEID_INT32.

To get further information about the type, e.g. the exact object type, then use \ref asIScriptEngine::GetTypeInfoById which
will return a \ref asITypeInfo that can then be used to get all details about the type.

*/


code:
/**

\page doc_use_script_class Using script classes

When there are multiple objects controlled by the same script implementation it may be favourable to use script classes,
rather than global script functions. Using script classes each instance can have it's own set of variables within the
class, contrary to the global functions that needs to rely on global variables to store persistent information.

Of course, it would be possible to duplicate the script modules, so that there is one module for each object instance, but
that would be impose a rather big overhead for the application. Script classes don't have that overhead, as all instances
share the same module, and thus the same bytecode and function ids, etc.

\section doc_use_script_class_1 Instantiating the script class

Before instantiating the script class you need to know which class to instantiate. Exactly how this is done
depends on the application, but here are some suggestions.

If the application knows the name of the class, either hardcoded or from some configuration, the class type
can easily be obtained by calling the module's \ref asIScriptModule::GetTypeIdByDecl "GetTypeIdByDecl" with the name
of the class. The application can also choose to identify the class through some properties of the class, e.g.
if the class implements a predefined \ref asIScriptEngine::RegisterInterface "interface". Then the application
can enumerate the class types implemented in the script with \ref asIScriptModule::GetObjectTypeByIndex "GetObjectTypeByIndex"
and then examine the type through the \ref asITypeInfo interface.

A third option, if you're using the \ref doc_addon_build "script builder add-on", is to use the metadata to identify
the class. If you choose this option, use the \ref asIScriptModule to enumerate the declared types and then query the
\ref doc_addon_build "CScriptBuilder" for their metadata.

Once the object type is known you create the instance by calling the class' factory function, passing it the necessary
arguments, e.g. a pointer to the application object which the script class should be bound to. The factory function id
is found by querying the \ref asITypeInfo.

\code
// Get the object type
asIScriptModule *module = engine->GetModule("MyModule");
asITypeInfo *type = module->GetTypeInfoByDecl("MyClass");

// Get the factory function from the object type
asIScriptFunction *factory = type->GetFactoryByDecl("MyClass @MyClass()");

// Prepare the context to call the factory function
ctx->Prepare(factory);

// Execute the call
ctx->Execute();

// Get the object that was created
asIScriptObject *obj = *(asIScriptObject**)ctx->GetAddressOfReturnValue();

// If you're going to store the object you must increase the reference,
// otherwise it will be destroyed when the context is reused or destroyed.
obj->AddRef();
\endcode

The factory function is \ref doc_call_script_func "called as a regular global function" and returns a handle to
the newly instanciated class.

\section doc_use_script_class_2 Calling a method on the script class

Calling the methods of the script classes are similar to \ref doc_call_script_func "calling global functions" except
that you obtain the function id from the \ref asITypeInfo, and you must set the object pointer along with the
rest of the function arguments.

\code
// Obtain the function object that represents the class method
asIScriptFunction *func = type->GetMethodByDecl("void method()");

// Prepare the context for calling the method
ctx->Prepare(func);

// Set the object pointer
ctx->SetObject(obj);

// Execute the call
ctx->Execute();
\endcode

\section doc_use_script_class_3 Receiving script classes

In order for the application to register a function that receives a script class it must first know the type. Of course,
since the class is declared in the script it isn't possible to know the type before the script is compiled. Instead the
application can register an \ref doc_global_interface "interface" with the engine. The function can then be registered to receive a handle to that interface.

\code
// Register an interface
engine->RegisterInterface("IMyObj");

// You can also register methods with the interface if you wish to force the script class to implement them
engine->RegisterInterfaceMethod("IMyObj", "void RequiredMethod()");

// Register a function that receives a handle to the interface
engine->RegisterGlobalFunction("void ReceiveMyObj(IMyObj @obj)", asFUNCTION(ReceiveMyObj), asCALL_CDECL);
\endcode

The function that receives the interface should be implemented to take a pointer to an \ref asIScriptObject.

\code
asIScriptObject *gObj = 0;
void ReceiveMyObj(asIScriptObject *obj)
{
  // Do something with the object
  if( obj )
  {
    if( doStore )
    {
      // If the object is stored, we shouldn't release the handle
      gObj = obj;
    }
    else
    {
      // If the object is not stored, we must release the handle before returning
      obj->Release();
    }
  }
}
\endcode

If you don't want to use interfaces like this, then you may want to look into the
\ref doc_adv_var_type "variable argument type" or the generic \ref doc_addon_handle "script handle add-on",
which are ways that can be used to receive values and objects of which the type is not known beforehand.

\section doc_use_script_class_4 Returning script classes

Returning a script class from a registered function involves much of the same as
\ref doc_use_script_class_3 "receiving them". In order to register the function either an interface
needs to be used, or the generic \ref doc_addon_handle "script handle add-on" can
be used.

\code
// The global variable is initialized elsewhere
asIScriptObject *gObj;

asIScriptObject *ReturnMyObj()
{
  if( gObj == 0 )
    return 0;

  // Increase the refcount to account for the returned handle
  gObj->AddRef();
  return gObj;
}
\endcode

This function can be registered as following:

\code
// Register an interface
engine->RegisterInterface("IMyObj");

// Register a function that returns a handle to the interface
engine->RegisterGlobalFunction("IMyObj @ReturnMyObj()", asFUNCTION(ReturnMyObj), asCALL_CDECL);
\endcode

*/


code:
/**

\page doc_versions Versions

The library's version number is composed of 3 numbers, and sometimes an additional letter. Examples:

 - 1.10.1d
 - 2.8.0a
 - 2.30.2

The first number is the major version. This is updated whenever there is a major redesign, or a major milestone happens. When
this number is changed backwards compatibility is not necessarily maintained by the library.

The second number is the application interface version. This is updated whenever there is a change in the interface, e.g.
a new method is added or an existing method has its signature modified. Usually the change is incremental so that there is no
need to modify the application code unless the new functions are wanted, but a recompilation is still necessary. Sometimes parts
of the interface are deprecated, but whenever possible the deprecated parts can be turned back on through a compile time flag.

The third number is the minor version. This is updated when the back-end logic in the library is modified, e.g. adding
or modifying a script language feature, but no interface change is done. No change in the application code should be required
during an upgrade when only the minor version has changed.

The additional letter is used when the change is purely bug fixes. In this case the binary application interface should be
untouched, so an application that loads the library as a shared object (dll) should be able to upgrade the library without
recompiling the application.

\section doc_versions_milestones History

The following is a bit of history for the library that shows how it has evolved since the beginning to the current date. The
complete change list can be found on the AngelScript site and in the SDK.

\subsection doc_versions_2003 2003 - Birth and first public release

The library was first conceived in early 2003, with the first working (internal) version available in March, 2003.

At the end of June, 2003 the library's first public release with version 1.0 was made.

\subsection doc_versions_2005 2005 - Version 2, sand box, object handles, script classes, and garbage collection

In the beginning of 2005 I made the difficult decision to do a major change of direction. Version 1 had several flaws that
I couldn't solve without a major redesign. The worst was that the script language wasn't properly sand-boxed, i.e. the
script writer had to be careful when writing scripts in order to crash the application or cause worse problems. The script
compiler didn't make any attempts to guarantee that a value passed by reference to a function actually stayed alive during the
call, and the script was allowed to use and manipulate pointers to access memory directly.

Version 2.0 included the concept of object handles, \@, and parameter references with direction keywords, i.e. <tt>in</tt> & <tt>out</tt>.
Object handles are basically smart pointers that the compiler uses to guarantee the proper life time of objects, and the direction keywords
for parameter references are used to tell the compiler what the reference will be used for. This in turn allows the compiler to take
necessary actions to guarantee the lifetime of the value, e.g. to create a temporary object that will receive the output value, which
will only be assigned to the final destination after the called function returns to the caller.

With the release of 2.2.0 in mid-2005 the script language got its first version of script classes, at the time called <tt>struct</tt>. Before this
the script language didn't support defining any new types, and scripts could only implement global functions for interacting
the built-in types as well as application registered types.

With the introduction of classes the need for the incremental garbage collector was also born, as the scripts could now
create objects with circular relationships that the simple reference counting memory model couldn't handle by itself.

\subsection doc_versions_2006 2006 - Script interface

In 2006, with the release of 2.7.0, the concept of interfaces was introduced in the script language. Allowing the application
to register a script interface that the script class could implement made for an easier interaction between application and
script.

\subsection doc_versions_2009 2009 - Inheritance, template types, operator overloads, and JIT compilation

Only in 2009, with version 2.15.2, was class inheritance implemented, though only single inheritance, to avoid complicating both the library and script
language. Multiple interfaces are still allowed to support polymorphism.

Still in 2009, with version 2.16.1, the the library added support for registering templated types, to allow the application to
create its own custom container types. The built-in array type would eventually be completely replaced by this and a default
array add-on is provided.

With version 2.16.3 the script classes were enhanced to allow implementing operator overloads, thus making the language even
more flexible and powerful.

Version 2.17.0, released in August 2009, introduced an interface to support external JIT compilers. While the AngelScript
library doesn't provide its own JIT compiler, a third party JIT compiler was soon created with quick adoption by the community.

\subsection doc_versions_2010 2010 - Function pointers

Support for function pointers in the script language was added in 2010 with version 2.18.2. Now the application can allow
scripts to setup its own callbacks.

\subsection doc_versions_2011 2011 - Automatic garbage collection and debugging

With the release of version 2.21.0 in 2011 the script engine gained support for automatic garbage collection to simplify this
task for the application developer. Of course, the application developers that prefer to have full control can still do it
manually by turning off the automatic collection.

This release also saw the implementation of a first standard debugger add-on that can be used by applications to add support
for stepping through the scripts and inspecting variables for proper run-time debugging.

\subsection doc_versions_2012 2012 - Namespaces and mixins

Namespaces were added to the script language in 2012 with version 2.22.2.

Mixin classes were introduced with version 2.25.0 to provide better support for code re-use even without multiple inheritance.

\subsection doc_versions_2013 2013 - Improved template types, delegates, weak references, and initialization lists

The template types that were first introduced in 2009 were enhanced with version 2.26.1 to support multiple subtypes in order
to give greater flexibility for the application.

Support for delegates was added with version 2.26.3.

Version 2.27.0 included support for weak references, so that is possible to have greater control over which handles keep objects
alive or not.

Support for registrable factory functions that takes initialization lists was added in 2.28.0. This allows the application to
define the specific pattern that should be used for different types using a simple syntax.

\subsection doc_versions_2014 2014 - Named arguments and auto

In version 2.29.0 the script language gained support for named arguments, and <tt>auto</tt> for automatically determining the
type of variables based on the initialization expression.

\subsection doc_versions_2015 2015 - Anonymous functions

Anonymous functions were first implemented in version 2.30.2.

\subsection doc_versions_2016 2016 - Child funcdefs

Funcdefs can be declared as members of classes as of version 2.31.0.

\subsection doc_versions_2017 2017 - external keyword and anonymous initialization lists

The <tt>external</tt> keyword was introduced in version 2.32.0 to explicitly include shared entities from a previously compiled module. This version also introduced anonymouus initialization lists for more compact scripts.

\subsection doc_versions_2018 2018 - Try-catch statements and explicit constructors

In version 2.33.0 the language was improved to support try-catch statements, and for flagging constructors as explicit for better control over what type conversions can happen implicitly.

\subsection doc_versions_2019 2019 - Explicit property keyword

With version 2.34.0 virtual property access must be explicitly flagged with the property keyword so that functions starting with get_ or set_ won't automatically be interpreted as virtual properties.

\subsection doc_versions_2022 2022 - Serialization of the context stack

With version 2.36.0 the ability to serialize the context stack was implemented.

\subsection doc_versions_2024 2024 - Improved JIT compiler interface and auto generated copy constructors

With version 2.37.0 the JIT compiler interface was enhanced to enable better global optimizations in JIT compiled code.

The script language also received auto generated copy constructors for script classes, and ability to indicate when default constructor, copy constructor, and value assign operator should not be generated by the compiler.
*/