NAME

XS::Framework::Manual::SVAPI::Array - XS::Framework Array C++ class reference

Array

Overview

The Array class is the wrapper around Perls AV* type, which is a variant of SV*. As with Sv, it might hold an underlying Perl array AV* or might not.

Construction

static Array noinc  (SV* val)
static Array noinc  (AV* val)

Array (std::nullptr_t = nullptr)
Array (SV* sv, bool policy = INCREMENT)
Array (AV* sv, bool policy = INCREMENT)

The new Array is created, and it either takes ownership on the underlying SV*/AV* with corresponding refcounting policy, or just empty wrapper is created, which holds no value. On invalid SV*, e.g. pointer to Hash, an exception will be thrown. The valid SV* should be either AV* or reference to AV* or undef.

Please, note, that empty Array means that it holds no value (aka NULL), it is not the same, when it holds underlying empty AV* with zero items.

static Array create()
static Array create (size_t cap)

It is possible to create new Array with empty underlying AV*, optionally reserving space for cap items (SV*).

If there is a list of items, it it possible to create new Array filled with them. However, the SV* values can be either copied/cloned into new values, or may be just aliased; in the later case refcounter just increased. The inteface is the following:

enum create_type_t { ALIAS, COPY };

static Array create (size_t size, SV** content, create_type_t type = ALIAS);
static Array create (std::initializer_list<Scalar> l, create_type_t type = ALIAS)
static Array create (const Array& from, create_type_t type = ALIAS)
Array (std::initializer_list<Scalar> l, create_type_t type = ALIAS);

For example,

Array source = ...;
Array dest = Array::create(source, Array::COPY);

The copy and move constructors are also available:

Array (const Array& oth)
Array (Array&& oth)
Array (const Sv& oth)
Array (Sv&& oth)

assignment operators

Array& operator= (SV* val)
Array& operator= (AV* val)
Array& operator= (const Array& oth)
Array& operator= (Array&& oth)
Array& operator= (const Sv& oth)
Array& operator= (Sv&& oth)

The assignment operators are complementaty to the constructors above. They inherit behaviour from Sv, including NULL-safety. The previously held SV* will be dec-remented.

The last operator performs proxy call in scalar context, the same as in appropriate constructor above.

void set (SV* val)

The set method directly assigns the value to the underlying SV*, bypassing all checks. Use the method with caution.

getters

There are zero-cost NULL-safe getters:

operator AV* () const
AV* operator-> () const
template <typename T = SV> one_of_t<T,SV,AV>* get () const

For example,

Array arr = ...;
AV* av = *arr;

element access

Scalar front () const
Scalar back  () const

To access first or last element of an array the front and back methods can be used (simiar to std::vector). The result type is always Scalar. The both methods are NULL-safe.

Scalar fetch (size_t key) const
Scalar at (size_t key) const
Scalar operator[] (size_t key) const
KeyProxy operator[] (size_t key)

The first three methods return Scalar type. fetch provides bounary-safe access to the elements, if the index is out of bounds, then empty Scalar is returned and underlying AV* is kept untouched. The at method also checks array bounds, and if the index is out of bounds, then exception will be thrown (similar to std::vector::at()). The operator[] does not boundary check, so this is the fastest method, however memory corruption is possible on usafe usage. The non-const acccessor is needed to allow in-place fast modification of underlying element, i.e.

Array arr = ...;
arr[10] = Simple(10);

fetch is NULL-safe method, while at and operator[] are NULL-unsafe.

void store (size_t key, const Scalar& val);
void store (size_t key, std::nullptr_t)
void store (size_t key, SV* v)
void store (size_t key, const Sv& v)

The store method is used store item in the array. If underlyging Perl array AV* is NULL, then store will throw exception.

To check element existance, the NULL-safe exist method can be used:

bool exists (size_t key) const

To delete arbitrary element by index the NULL-safe and boundary-safe del method can be used (the previous value is returned).

Scalar del (size_t key)

To access the first element with discarding it, as well as to access the last element with discarding it the shift/pop NULL-safe methods can be used.

Scalar shift()
Scalar pop()

The opposite operations, i.e. push and unshift

void push (const std::initializer_list<Scalar>& l)
void push (const List& l)
void push (const Scalar& v)
void push (SV* v)
void push (const Sv& v)

void unshift (const std::initializer_list<Scalar>& l);
void unshift (const List& l);
void unshift (const Scalar& v);
void unshift (SV* v)
void unshift (const Sv& v)

Please note, that push and unshift are NULL-unsafe methods.

clear()

void clear ()

Frees all items in the underlying AV* array. This is NULL-safe method.

undef()

void undef()

Frees all items in the underlying AV* array; the array container AV* itself remains alive. This is NULL-safe method.

push_on_stack()

U32 push_on_stack (SV** sp, U32 max = 0) const

This method copies all array items into perl stack SV**, possibly extending it upto max size. If max is less then the actual number of elemetns, then max value is ignored.

It returns the count of copied items. The method takes care of all needed mechanis, e.g. sv_2mortal and increasing refcounter of the items.

This is NULL-unsafe method.

size()

size_t  size      () const

Returns size of underlying array. If it is NULL, then 0 is returned. In other words, this method is NULL-safe.

capacity()

size_t  capacity  () const

Returns capacity of underlying array. If it is NULL, then 0 is returned. In other words, this method is NULL-safe.

top_index ()

SSize_t top_index () const

Returns index of top element of underlying array. If it is NULL, then -1 is returned. In other words, this method is NULL-safe.

resize()

void resize  (size_t newsz)

Resizes the container to contain count elements. If the current size is greater than count, the container is reduced to its first count elements.