Storing Script Objects

Sometimes you may want to store script objects and use them later, or to implement your own container for script objects. There are some tools provided by asbind20 for storing script objects.

Storing a Single Script Object

class single

A set of helper for storing a single script object.

Get the address of the data

This can be used to implemented a function that return reference of data to script

static inline void *data_address(data_type &data, int type_id)

static inline const void *data_address(const data_type &data, int type_id)

Public Static Functions

static inline void *object_ref(const data_type &data) noexcept

Get the referenced object.

This allows direct interaction with the stored object, whether it’s an object handle or not

Note

Only valid if the type of stored data is NOT a primitive value

static inline bool construct(data_type &data, asIScriptEngine *engine, int type_id)

Construct the stored value using its default constructor.

Parameters:

data – Stored value
engine – Script engine
type_id – Type ID. Must NOT be void (asTYPEID_VOID)

Returns:

True if successful

static inline bool copy_construct(data_type &data, asIScriptEngine *engine, int type_id, const void *ref)

Copy construct the stored value from another value.

Note

Make sure this helper doesn’t contain a constructed object previously!

Parameters:

data – Stored value
engine – Script engine
type_id – Type ID. Must NOT be void (asTYPEID_VOID)
ref – Address of the value. Must NOT be nullptr

Returns:

True if successful

static inline bool copy_assign_from(data_type &data, asIScriptEngine *engine, int type_id, const void *ref)

Copy assign the stored value from another value.

Note

Make sure the stored value is valid!

Parameters:

data – Stored value
engine – Script engine
type_id – Type ID. Must NOT be void (asTYPEID_VOID)
ref – Address of the value. Must NOT be nullptr

Returns:

True if successful

static inline bool copy_assign_to(const data_type &data, asIScriptEngine *engine, int type_id, void *out)

Copy assign the stored value to destination.

Note

Make sure the stored value is valid!

Parameters:

data – Stored value
engine – Script engine
type_id – Type ID. Must NOT be void (asTYPEID_VOID)
out – Address of the destination. Must NOT be nullptr

Returns:

True if successful

static inline void destroy(data_type &data, asIScriptEngine *engine, int type_id)

Destroy the stored object.

Parameters:

data – Stored value
engine – Script engine
type_id – Type ID. Must NOT be void (asTYPEID_VOID)

static inline void enum_refs(data_type &data, asITypeInfo *ti)

Enumerate references of stored object for GC.

This function has no effect for non-garbage collected types

Parameters:

data – Stored value
ti – Type information

union data_type

Helper for storing data.

Note

This helper needs an external type ID for correctly handle the stored data, so it is recommended to use this helper as a member of container class, together with a member for storing type ID.

Public Functions

inline data_type()

data_type(const data_type&) = delete

inline data_type(data_type &&other) noexcept

inline ~data_type(): Warning

Due to limitations of the AngelScript interface, it won’t properly release the stored object. Remember to manually clear the stored object before destroying the helper!

inline data_type &operator=(data_type &&other) noexcept

Public Members

std::byte primitive[8]: primitive value

void *handle: script handle

void *ptr: script object

Containers

Policies of Type Information

Policies for how containers deal with the type information.

template<typename T> concept typeinfo_policy: #include <options.hpp>

Concept of type information policies.

struct typeinfo_identity: #include <options.hpp>

The type information itself is for the element.

template<asUINT Idx> struct typeinfo_subtype : public std::integral_constant<asUINT, Idx>

#include <options.hpp>

The subtype of type information is for the element.

Template Parameters:: Idx – Index of the subtype

Sequential Containers

small_vector is a sequential container for AngelScript objects with small-size optimization (SSO). It stores a fixed number of elements inline (on the stack) before falling back to heap allocation, similar to how std::string uses SSO for short strings.

Template parameters

TypeInfoPolicy — determines how the element type is derived from the type information. Use typeinfo_identity when the type info is the element type (e.g. int, a registered value class), or typeinfo_subtype<N> when the element is the N-th subtype of a template type (e.g. array<int> → typeinfo_subtype<0>).
StaticCapacityBytes — inline storage size in bytes. Must be a multiple of sizeof(void*). Defaults to 4 * sizeof(void*).
Allocator — allocator for heap-backed storage. Defaults to script_allocator<void>, which uses AngelScript’s memory API.

Constructing

A small_vector must be constructed with type information. There are three ways:

// From an asITypeInfo pointer
small_vector<typeinfo_identity> vec(some_typeinfo);

// From an asITypeInfo pointer with initializer list
small_vector<typeinfo_identity> vec(some_typeinfo, ilist);

// From an engine and type ID (for primitive types, engine can be null)
small_vector<typeinfo_identity> vec(nullptr, asTYPEID_INT32);

Element access returns void* / const void*. You cast to the concrete type:

small_vector<typeinfo_identity> vec(nullptr, asTYPEID_INT32);
int val = 42;
vec.push_back(&val);

int* p = static_cast<int*>(vec[0]);

The container provides standard std::vector-like modifiers: push_back, emplace_back, push_back_n, emplace_back_n, pop_back, insert, erase, resize, clear, reserve, shrink_to_fit, reverse, and assign.

Iterators

const_iterator is a random-access iterator that stores an offset into the vector rather than a raw pointer. This makes it safe against reallocation — an invalid iterator from script can be detected by the host without crashing. Dereferencing yields const void* to the element.

for(auto it = vec.begin(); it != vec.end(); ++it) {
    int val = *static_cast<const int*>(*it);
}

Visiting elements

The visit method applies a visitor to a range of elements, handling type-aware dispatch:

vec.visit(
    [](auto* begin, auto* end)
    {
        for(auto* p = begin; p != end; ++p)
            // Do something
    },
    0, vec.size()
);

GC integration

Call enum_refs() to enumerate references within the vector to the AngelScript GC. This should be called from the object type’s EnumReferences callback.

template<typeinfo_policy TypeInfoPolicy, std::size_t StaticCapacityBytes = 4 * sizeof(void*), typename Allocator = script_allocator<void>> class small_vector

Sequential container for AngelScript objects with small size optimization (SSO)

Most members have the same meaning as member functions of the same name in std::vector

Template Parameters:

TypeInfoPolicy – Type information policy for element type
StaticCapcityBytes – Static capacity in bytes. Must be aligned with the size of pointer, e.g. 4 * sizeof(void*).
Allocator – Allocator type which is able to rebind to multiple types. Its member pointer_type must be compatible with raw pointers.

Type information

inline auto get_type_info() const noexcept -> asITypeInfo*

inline auto element_type_info() const -> asITypeInfo*

inline int element_type_id() const

Capacity

inline size_type static_capacity() const noexcept

inline size_type capacity() const noexcept

inline void reserve(size_type new_cap)

inline void shrink_to_fit()

inline size_type size() const noexcept

inline bool empty() const noexcept

Element access

inline void *data() noexcept

inline const void *data() const noexcept

inline void *operator[](size_type idx) noexcept

inline const void *operator[](size_type idx) const noexcept

Iterators of small vector

inline const_iterator cbegin() const noexcept

inline const_iterator cend() const noexcept

inline const_iterator begin() const noexcept

inline const_iterator end() const noexcept

Modifiers

inline void resize(size_type new_size)

Resize the vector If new size is greater than the old size, new elements will be default constructed.

Parameters:: new_size – New size

inline void clear() noexcept: Clear stored elements.

Note

This method won’t deallocate memory

inline void push_back(const void *ref)

inline void emplace_back()

inline void push_back_n(size_type n, const void *ref)

inline void emplace_back_n(size_type n)

inline void pop_back() noexcept

inline void insert(size_type where, const void *ref)

inline void insert(const_iterator where, const void *ref)

inline void erase(size_type where, size_type count)

inline void erase(size_type where)

inline void erase(const_iterator start, const_iterator stop)

inline void erase(const_iterator where)

inline size_type remove(size_type where)

inline void assign(size_type where, const void *ref)

inline void assign(const_iterator where, const void *ref)

inline void reverse(size_type start, size_type n = -1)

inline void *data_at(size_type idx) noexcept

inline const void *data_at(size_type idx) const noexcept

Visiting members

template<typename Visitor> inline decltype(auto) visit(Visitor &&vis, size_type start, size_type count)

template<typename Visitor> inline decltype(auto) visit(Visitor &&vis, const_iterator start, const_iterator stop)

Public Types

using size_type = std::size_t

using difference_type = std::ptrdiff_t

using allocator_type = Allocator 

using pointer = void*

using const_pointer = const void*

Public Functions

small_vector() = delete

inline ~small_vector()

inline small_vector(const small_vector &other)

inline small_vector(small_vector &&other) noexcept

inline explicit small_vector(asITypeInfo *ti)

inline small_vector(asITypeInfo *ti, script_init_list_repeat ilist)

inline small_vector(asIScriptEngine *engine, int type_id)

inline void enum_refs(): Enumerate references for GC.

class const_iterator

Const iterator of small vector.

Public Types

using value_type = const void*

using iterator_category = std::random_access_iterator_tag

using size_type = std::size_t

using difference_type = std::ptrdiff_t

using pointer = const void*

using reference = const void*

using const_reference = const void*

Public Functions

const_iterator() noexcept = default

const_iterator(const const_iterator&) noexcept = default

inline reference operator*() const noexcept

inline bool operator==(const const_iterator &rhs) const noexcept

inline std::strong_ordering operator<=>(const const_iterator &rhs) const noexcept

inline const_iterator &operator++() noexcept

inline const_iterator &operator--() noexcept

inline const_iterator &operator++(int) noexcept

inline const_iterator &operator--(int) noexcept

inline const_iterator &operator+=(difference_type diff) noexcept

inline const_iterator &operator-=(difference_type diff) noexcept

inline reference operator[](difference_type off) const noexcept

inline const small_vector *get_container() const noexcept

inline explicit operator bool() const noexcept

Friends

inline friend const_iterator operator+(const_iterator lhs, const_iterator rhs) noexcept

inline friend const_iterator operator+(const_iterator lhs, difference_type rhs) noexcept

inline friend const_iterator operator+(difference_type lhs, const_iterator rhs) noexcept

inline friend difference_type operator-(const_iterator lhs, const_iterator rhs) noexcept

inline friend const_iterator operator-(const_iterator lhs, difference_type rhs) noexcept

Associative Containers

Not implemented yet