PTypes: 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>);

bool anext(const variant& array, int& index, variant& item, [ string& key ]);

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().

Variant arrays can associate values with either strings or integers (32 or 64 bit). Integer keys are not required to be consecutive. It should be noted that in the current implementation there is no difference in performance between these two methods. Both methods can be mixed in one array.

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 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.

bool anext(const variant& a, int& index, variant& item, [ string& key ]) 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 and optionally assigns its key value to key. Index must be zero when calling this function first time. If there are no items left in the array, or a is not an array, this function returns false.

PTypes home