C++ Portable Types Library (PTypes) Version 1.7

Top: Basic types: variant: Arrays

#include <ptypes.h>
void aclear(variant& a);
variant aclone(const variant& a); void put(variant& a, <key>, const variant& item); const variant& get(const variant& a, <key>); const variant& variant::operator[](<key>) const; void del(variant& a, <key>); int alength(const variant& a); bool anext(const variant& array, int& index, variant& item);

A variant object can hold an associative array of variants. The variant changes its type to an array as soon as put() or aclear() is called for an object. When assigning variants, only a reference to an array is being copied, which means, modifying an array through one variant object affects all other objects that hold a reference to the same array. To duplicate the contents of an array use aclone().

PTypes uses reference counting on arrays to properly clean up unused dynamic structures. However, since variant arrays may recursively contain arrays and in some situations there may be a circular reference, it is possible to have memory leak when using such structures. Since PTypes does not provide garbage collection (e.g. like in Java), compound variant data structures should be designed so that variants never reference each other circularly.

void aclear(variant& a) clears the variant array. This function may affect other variant objects holding a reference to the same array data.

variant aclone(const variant& a) creates a copy of an array or creates an empty array if a is of any other variant type. If a contains variant arrays as elements, only their references are being copied.

void put(variant& a, <key>, const variant& item) associates item with key in the variant array a. Key can be either a string or an integer. The previous value associated with this key, if any, is replaced with the new value. If item is an unassigned variant, the new value is not stored in the array.

const variant& get(const variant& a, <key>) retrieves an element associated with key in the array a. If the element does not exist, or a is not an array, this function returns an unassigned variant (a reference to nullvar). Key can be either a string or an integer. Variant arrays use hashing to retrieve elements by keys.

const variant& variant::operator[](<key>) equivalent to get(). This operator can be used only for retrieving elements.

void del(variant& a, <key>) removes the element associated with key from the array a. Does nothing if the element does not exist or a is not an array. Equivalent to calling put() with an unassigned variant item.

int alength(const variant& a) returns the length of an array.

bool anext(const variant& a, int& index, variant& item) iterates through array elements (please see examples in the introduction to variants). Each time anext() is called it assigns the next item in the array to item. Index must be zero when calling this function first time; it will be then incremented automatically. If there are no items left in the array (index is out of range), or a is not an array, this function returns false.

See also: string, Assignments and typecasts, Object references, Utilities

PTypes home