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)
It it possible to create Array object from CallProxy invocation:
CallProxy
Array (const CallProxy& p)
however, please note, that the CallProxy will be called in scalar context. If the list context is needed, then instead of Array class it's descendant class List should be used.
List
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) Array& operator= (const CallProxy& p)
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) void store (size_t key, const CallProxy& p)
The store method is used store item in the array. If underlyging Perl array AV* is NULL, then store will throw exception. The last method invokes CallProxy in scalar context, as the array elements are always scalars.
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 push (const CallProxy& p) 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) void unshift (const CallProxy& p)
Please note, that push and unshift are NULL-unsafe methods. The CallProxy is invoked in scalar context.
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.