Script Initialization List

Types can be registered to allow them to be created from initialization lists.

List Factories and Constructors

Similar to normal factories and constructors, the list factories for reference types and list constructors for value types can be registered by .list_factory and .list_constructor, respectively.

If you already have wrapper functions, you can register them by .list_factory_function or .list_constructor_function

This kind of helper needs you to provide the pattern of the initialization list, such as float, float or repeat int. For helpers using the constructors of C++ class directly, you can also specify the optional template parameter ElementType for the element type of initialization list. If the list pattern contains repeat or ? that need to parse manually, you can just use the default template parameter, which is void.

The helpers expect the constructors or wrapper functions use a pointer (ElementType*) to receive the buffer of initialization list. The requirements about return value and other parameters are the same as normal factories and constructors, which is described in how to register an object type.

struct my_val_class
{
    my_val_class(int* il);
};

struct my_ref_class
{
    my_ref_class(void* il);
};

struct my_class
{ /* ... */};

void init_from_list(my_class* mem, void* il);

asbind20::value_class<my_val_class>(/* ... */)
    .list_constructor<int>("int, int");

asbind20::ref_class<my_ref_class>(/* ... */)
    .list_factory("repeat int"); // Equivalent to .list_factory<void>("repeat int")

asbind20::value_class<my_class>(/* ... */)
    .list_constructor_function("repeat int", &init_from_list);

Note

Unlike C++, each type in AngelScript can only have one list factory or constructor.

For repeated pattern, asbind20 provides a helper class to parse it from a raw void*.

class script_init_list_repeat

Proxy for the initialization list of AngelScript with repeated values.

Warning

Never use this proxy with a pattern of limited size, e.g., {int, int}

Public Types

using size_type = asUINT

Public Functions

script_init_list_repeat() = delete
script_init_list_repeat(const script_init_list_repeat&) noexcept = default
explicit script_init_list_repeat(std::nullptr_t) = delete
inline explicit script_init_list_repeat(void *list_buf) noexcept

Construct from the initialization list buffer.

Parameters:

list_buf – Address of the buffer

inline explicit script_init_list_repeat(generic_pointer gen, size_type idx = 0)

Construct from the interface for generic calling convention.

Parameters:

  • gen – The interface for the generic calling convention

  • idx – The parameter index of the list. Usually, this should be 0 for ordinary types and 1 for template classes.

script_init_list_repeat &operator=(const script_init_list_repeat&) noexcept = default
inline bool operator==(const script_init_list_repeat &rhs) const noexcept
inline size_type size() const noexcept

Size of the initialization list.

inline void *data() const noexcept

Data address of the elements.

inline void *forward() const noexcept

Revert to raw pointer for forwarding list buffer to another function.

Initialization List Policies

The asbind20 provides some policies for adapting existing C++ paradigm for constructing from a range of value.

Policies are passed via use_policy, which accepts one or more policy types:

// Single policy
.list_factory<int>("repeat int", use_policy<policies::as_span>)

// Multiple policies combined (e.g. init list policy + factory policy)
.list_factory<int>("repeat int", use_policy<policies::as_span, policies::notify_gc>)

Quick summary of available initialization list policies:

Policy

Signature of C++ function to receive

Notes

(default, no policy)

void*

Raw AS initialization list. It’s useful when you want to deal with the raw data.

repeat_list_proxy

script_init_list_repeat

Convert the memory to proxy.

apply_to<Size>

Individual arguments
(e.g. int, int, int for Size=3)

Only works with fixed-size patterns like {int, int, int}, not repeat int

pointer_and_size

T* data, asUINT size

Traditional C pointer + length pair

as_iterators

T* begin, T* end

Iterator pair compatible with STL algorithms

as_span

std::span<T>

Modern C++20 span

as_initializer_list

std::initializer_list<T>

Platform-dependent. Prefer other policies when possible

as_from_range

C++23 std::from_range_t tag

Requires __cpp_lib_containers_ranges

List Pattern with Limited Elements

Policies for the pattern with limited elements, i.e., no repeat in the pattern.

  1. Applying

template<std::size_t Size>
struct apply_to

Apply each elements of the initialization list to constructor, similar to std::apply.

Note

Unlike other policies, this can only be used with list pattern with known type and limited size, e.g. {int, int}. DO NOT use this with patterns like { repeat_same int }!

Example

struct vec3f
{
    vec3f(float x, float y, float z);
};

using namespace asbind20;
value_class<vec3f>(/* ... */)
    .list_constructor<float>("float,float,float", use_policy<policies::apply_to<3>>);

List Pattern with Repeated Elements

Policies for the pattern with repeated elements, i.e., containing repeat in the pattern.

  1. Automatically convert to script_init_list_repeat

struct repeat_list_proxy

Convert script list to a proxy class.

See also

script_init_list_repeat

Example

class int_list
{
public:
    int_list(asbind20::script_init_list_repeat il);
};

using namespace asbind20;
ref_class<int_list>(/* ... */)
    .list_factory("repeat int", use_policy<policies::repeat_list_proxy>);

  1. As an iterator pair of [begin, end)

struct as_iterators

Convert the initialization list to an iterator pair of [begin, end).

Example

class int_list
{
public:
    // Expects iterator to int
    template <typename Iterator>
    int_list(Iterator start, Iterator stop);
};

using namespace asbind20;
ref_class<int_list>(/* ... */)
    .list_factory("repeat int", use_policy<policies::as_iterators>);

  1. As a pair of pointer and size

struct pointer_and_size

Convert the initialization list to a pointer and an asUINT indicating its size.

Example

class int_list
{
public:
    int_list<int>(int* ptr, std::size_t count);
};

using namespace asbind20;
ref_class<int_list>(/* ... */)
    .list_factory<int>("repeat int", use_policy<policies::pointer_and_size>);

  1. As the std::initializer_list

struct as_initializer_list

Convert the initialization list to an initializer list of C++.

Warning

C++ doesn’t provide a standard way to construct an initializer list from user. You should try other policies at first.

Example

class int_list
{
public:
    int_list(std::initializer_list<int> il);
};

using namespace asbind20;
ref_class<int_list>(/* ... */)
    .list_factory<int>("repeat int", use_policy<policies::as_initializer_list>);

Note

This policy is implemented by non-standard code, please check the macro ASBIND20_HAS_AS_INITIALIZER_LIST at first.

Currently, this policy are supported on MSVC STL, libstdc++, and libc++.

  1. As the std::span

struct as_span

Convert the initialization list to a span.

Example

class int_list
{
public:
    int_list(std::span<int> sp);
};

using namespace asbind20;
ref_class<int_list>(/* ... */)
    .list_factory<int>("repeat int", use_policy<policies::as_span>);

  1. std::from_range and a range

struct as_from_range

Converting the initialization list for constructors accepting C++23 std::from_range(_t)

Example

class int_list
{
public:
    template <typename Range>
    int_list(std::from_range_t, Range&& rng);
};

using namespace asbind20;
ref_class<int_list>(/* ... */)
    .list_factory<int>("repeat int", use_policy<policies::as_from_range>);

Note

This policy is only available when compiler supports C++23 __cpp_lib_containers_ranges. You can check whether the macro ASBIND20_HAS_CONTAINERS_RANGES is defined.