XS::Framework::Manual::SVAPI::Array - XS::Framework Array C++ class reference
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.
Array
AV*
SV*
Sv
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.
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*).
cap
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)
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.
dec
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.
set
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
Array arr = ...; AV* av = *arr;
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.
front
back
std::vector
Scalar
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.
fetch
at
std::vector::at()
operator[]
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.
store
To check element existance, the NULL-safe exist method can be used:
exist
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).
del
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.
shift
pop
Scalar shift() Scalar pop()
The opposite operations, i.e. push and unshift
push
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.
void clear ()
Frees all items in the underlying AV* array. This is NULL-safe method.
void undef()
Frees all items in the underlying AV* array; the array container AV* itself remains alive. This is NULL-safe method.
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.
SV**
max
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.
sv_2mortal
This is NULL-unsafe method.
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.
0
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.
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.
-1
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.
void reserve (size_t newsz)
Increases the capacity of the container. This is NULL-unsafe method.
Array provides iterator and const-iterator random-access accessors for it's content:
const_iterator cbegin () const const_iterator cend () const const_iterator begin () const const_iterator end () const iterator begin () iterator end ()
This methods are NULL-safe. As usually, when underlying array is modified, the used iterators become invalid, and should not used any longer.
XS::Framework
XS::Framework::Manual::SVAPI
XS::Framework::Manual::SVAPI::Sv
XS::Framework::Manual::SVAPI::List
To install XS::Framework, copy and paste the appropriate command in to your terminal.
cpanm
cpanm XS::Framework
CPAN shell
perl -MCPAN -e shell install XS::Framework
For more information on module installation, please visit the detailed CPAN module installation guide.