synopsis.
The array databag object (array_dbag_o) is a mechanism for storing a list of strings. It is designed to work in conjunction with the matrix databag object. It is very similar to a the list databag object and at first glance it may appear confusing to differentiate the two. Array-type databags hold simple strings; list-type databags can hold other databags (of various types) and form the foundation of recursive databags :

It is highly recommended that you read the databag intro page prior to looking at any specific databag object reference page, in order to familirize yourself with the over-all mechanics of databags.

description.
array_dbag_o is a child class of the "databag" class (dbag_o), which is top-level class (eg has no parent class). It is used to hold an array of data elements, stored as strings. An array databag is often embedded in a recursive databag. It is also heavily used by the 'matrix' databag object (matrix_dbag_o).

By default, each array databag has a token that acts as an identifier, or index value. This can be used to assign a name to a given array instance. However, this is not required if the array databag is part of a matrix. In that case, the row number acts as the array databag's identifier. This class can accomodate both cases by being able to operate in 2 modes: "table mode", and "not table mode". In table mode, the text format for an array data bag is (as given in the table above):

"< col1 col2 col3 .. coln >"

The get() and put() databag member functions, common to all types of databags, in this case use an index number to access a string-token in the array. A get() can also be done in the more traditional array access notation:

static const char *adat_US[] = "row < John Smith male American >";
static const char *adat_SA[] = "row < Mohammed Khomeini male Arab >";
void main()
{
    array_dbag_o john(adat_US);
    array_dbag_o arab(adat_SA);
    string_o sfname1 = john.get(0);     // returns "John"
    string_o sfname2 = john[0];         // also returns "John"
    string_o slname1 = arab.get(1);     // returns "Khomeini"
    string_o slname2 = arab[1];         // also returns "Khomeini"
}

member functions (primary)

array_dbag_o()
SIGNATURE: array_dbag_o ()
SYNOPSIS: creates a a new array databag object, completely devoid of name or contents.
 

array_dbag_o(array_dbag_o)
SIGNATURE: array_dbag_o (const array_dbag_o &rhs)
SYNOPSIS: creates a a new array databag object. The contents is copied from 'rhs' (deep copy).
 

operator = (array_dbag_o)
SIGNATURE: const array_dbag_o &operator = (const array_dbag_o &rhs)
SYNOPSIS: the databag object's contents is replaced with that of 'rhs'.
 

array_dbag_o(<args>)
SIGNATURE: array_dbag_o (const string_o &s)
SYNOPSIS:
creates a new array databag instance and sets the contents to that of 's'. This constructor is equivalent to the default constructor and member function load().
PARAMETERS

s: a string containing a valid text representation of an array databag. If the string is invalid, the load will fail and the object will be as if the default constructgor was exercised.

 

array_dbag_o(<args>)
SIGNATURE: array_dbag_o (const string_o &s, count_t idx)
SYNOPSIS: constructor. Creates a new array databag instance; allocates 'n' postions and name the instance that of 's'.
PARAMETERS

• s: a string containing the name of the array databag. 's' must be of type like a simple variable name (letters, numbers, underscores).
• idx: the number of array elements to create. Must be 1 or greater. There is no check for excessively large values.

 

array_dbag_o(<args>)
SIGNATURE: array_dbag_o (const string_o &s, count_t idx, const char *, ...)
SYNOPSIS:
creates a new array databag with name 's'. Allocates 'idx' slots and assigns the positions in the string array values following the parameter 'idx'. Example:

array_dbag_o isms ("ideaology", 3, "communist", "socialist", "aanarchist");

This allocates a string array with 3 slots, assigning the values of the last 3 strings. The number of strings must match
PARAMETERS

• s: a string containing the name of the array databag.
• idx: the number of strings to be allocated to the object. Also means the number of arguments following this one.
• [list]: A list of 'char *' strings. The number in the list must match the value of 'idx'.

TRAITS: this is a var-args function. Use with caution; failure to provide enough arguments may cause the program to crash.
 

array_dbag_o(<args>)
SIGNATURE: array_dbag_o (const string_o &s, count_t idx, va_list)
SYNOPSIS: this is a more obscure variation of the previous constructor. it is most likely going to be phased out soon.
PARAMETERS

• s: a string containing the name of the array databag.
• idx: the number of strings to be allocated to the object. Also means the number of strings in 'va_list'

TRAITS: this is a var-args function. Use with caution. Avoid using this function - it is MARKED FOR TERMINATION.
 

destructor
SIGNATURE: ~array_dbag_o ()
SYNOPSIS: destroys the class object instance. Any contents and name for the object are destroyed.
TRAITS: this is a virtual function.
 

clone()
SIGNATURE: dbag_o *clone () const
SYNOPSIS:
makes an exact copy of the array databag and returns a pointer to the newlya aloocated object. The application should use delete to destroy the object at the end of its lifecycle:

void function()
{
    const char *str = "stuff < first \"second 2nd\" third >";
    array_dbag_o x(str);
    array_dbag_o *clone = x.clone();
    // --use "clone" --
    delete clone;
}

 

size()
SIGNATURE: count_t size () const
SYNOPSIS: The number of string values-tokens assigned to the object.
TRAITS: this function is inline.
 

capacity()
SIGNATURE: count_t capacity () const
SYNOPSIS:
The maximum number of string values-tokens the object can hold. This number is at least the value of size(). The difference between size and capacity: size represents the actual number of elements residing in the array databag; the capacity is the number of pointers to elements the object has available at the moment, some of which may be allocated. The unallocated ones can accomodate new elements.
TRAITS: this function is inline.
 

is_tablemode()
SIGNATURE: boolean is_tablemode () const
SYNOPSIS:
returns TRUE / FALSE, depending if the object is in "table mode". See main discussion on this page for more info on the meaning of table mode.
TRAITS: this function is inline.
 

iprint()
SIGNATURE: const string_o &iprint (string_o &s, const count_t n) const
SYNOPSIS:
returns the contents of the class instance, as a string. The output is "pretty formatted", with indentation, using spaces. The number of spaces used is determined by input parameter 'n'. The output of this function is both the return value and the output string object-parameter 's'. There is no difference between the return value or parameter 's'. In fact, the return value is simply a reference to 's'.
PARAMETERS

• s: a string to recieve the formatted output (textual representation) of the array databag.
• idx: the number of strings to be allocated to the object. Also means the number of strings in 'va_list'

RETURNS:
[string reference]: a "handle" to 's'
["bad string object"]: if an error occurs. The only possible error in this member function is if memory is exhausted and cannot be allocated (a panic condition).
 

operator ==()
SIGNATURE: int operator == (const array_dbag_o &that) const
SYNOPSIS:
compares the current array databag object to 'that' for equality. In order for two array databags to be equal, they must have the same number of elmenents, and each element must have the same name.
RETURNS:
1: the objects are "equal"
0: the objects are different
 

operator !=()
SIGNATURE: int operator != (const array_dbag_o &that) const
SYNOPSIS:
this function (written in operator notation) compares the current object to 'that', and returns 1 if they are different. This function is the exact converse of "operator == ()" (see which for more info).
RETURNS:
1: the objects are different
0: the objects are "equal"
TRAITS: this function is inline.
 

set_tablemode()
SIGNATURE: int set_tablemode (boolean istab = TRUE)
SYNOPSIS:
This member function sets or unsets the object so that it can be used in a matrix databag. Usage of this function is intended to be used sparsely and primarily just after the object is constructed.
If this function is called and the result is a change in mode, any subsequent load() operations or printing of contents will be affected. this function is intended to be called 0 or 1 times during the lifetime of the object.
PARAMETERS

• istab: boolean flag (TRUE/FALSE). If true, sets the
• object to "table mode" so that it can be used in a matrix
• databag; FALSE otherwise.

TRAITS: This function is inline. Use this function with caution.
 

operator []()
SIGNATURE: string_o &operator [] (count_t i)
SYNOPSIS:
This function acts exacly like get(i). It can be used to get or set a string element (see example above on this page). Example:

void some_function()
{
    array_dbag_o m ("platoon", 3, "Charley", "Bravo", "Delta");
    string_o &s = m[2];         // gets [reference to] "Delta"
    m[1] = "Tango";             // "Bravo" -> "Tango"
}

 

get()
SIGNATURE: const string_o &get (count_t i, int *pi) const
SYNOPSIS: returns the ith element of the object. 'i' must be in bounds ([0..size()-1].
PARAMETERS

• i: integral value index (use 0 for 1st element) into array of internal strings. Value must be in [0..size()-1].
• pi: [output] error indicator variable. values:
  0: OK (fetched)
  1: out of range
  2: object has no data (size is 0)

RETURNS:
[string] (const reference) handle to the element, a string object.
[string_o::bad_reference()]: reference to the "bad string", meaning an error occurred.
 

get()
SIGNATURE: const string_o &get (const string_o &s, int *pi) const
SYNOPSIS:
This function normally is intended to return a databag's name given the path in 's'. However, this functionality has no meaning for this specific class. The function is provided in order to complete the requirements of a data bag, but will always return an error condition.
Bottom line: do not use this function. It is an error to do so. It exists solely to satisfy C++ framework requirements.
PARAMETERS

• s: path to the sub-databag desired. This parameter is ignored
• pi: [output] error indicator variable. value(s):
  zErr_UnsupportedProto: operation not supported

TRAITS: this function is inline. This function is BOGUS in terms of real-world use, and has no true functionality.
 

get_idx()
SIGNATURE: count_t get_idx (const string_o &s, int *pi, count_t start = 0) const
SYNOPSIS:
searches for 's' in the list of elements, and if an exact match is found, returns the element offset into the list (ie array).
PARAMETERS

• s: element to search for. Value must match exactly in order to be considered the same.
• pi: [output] error indicator variable. values:
  0: success; item found
  1: item not found (no match)
  zErr_NoData: object has no elements (warning - notification only)
  zErr_Index_OutofBounds: invalid 'start' value
• start: starting position index value. This defaults to 0. If a non-zero value is [explicitly] specified, the search will skip over the first (start-1) elements.

DESCRIPTION:
This differs from the similar member function get(string_o) in that it is designed to search for an element in the array. That is, this member function is specific to this class.
RETURNS:
0: successfully found
1: no match or object has nothing
-1: error, 'start' value out of bounds
 

put()
SIGNATURE: int put (count_t i, const string_o &s, boolean do_force = FALSE, int *pi = NULL)
SYNOPSIS:
This "puts", that is, updates, the ith element to 's'. The elemement (as indicated by its position 'i') must exist. If 's' differs from the existing contents (eg not an exact match), the object state is set to "modified".
PARAMETERS

• i: integral value index (use 0 for 1st element) into array of internal strings. Value must be in [0..size()-1].
• s: the string to set the element to. Can be anything.
• do_force: if set to TRUE, the object's "is-modified" will be [always] set. If FALSE, the "is-modified" property will be set only if the new value is different
• pi: [output] error indicator variable. values:
  0: OK (fetched)
  zErr_NoData: object has no elements (notification only)
  zErr_Index_OutofBounds: out of range

 

put()
SIGNATURE: int put (const string_o &u1, const string_o &s, boolean do_force = FALSE, int *pi = NULL)
SYNOPSIS: This function is a relic and does nothing. Ignore it.
PARAMETERS

• u1: not applicable
• s: not applicable
• do_force: not applicable
• pi: [output] error indicator variable. value(s):
  zErr_UnsupportedProto: operation not supported

RETURNS: 1
 

contains()
SIGNATURE: boolean contains (const dbag_o &x) const
SYNOPSIS: This function allegedly checks to see if the databag 'x' is "contained within" the object.
TRAITS:
this function is under investigation to determine why it exists. Please do not use this function until after the investigation.
 

load()
SIGNATURE: int load (const string_o &s)
SYNOPSIS: parse the input string into a data bag. The databag is "loaded" from 's'.
DESCRIPTION:
This routine converts a character array text string to an array data bag. The string 's' is expected to conform to the proper syntax of an array databag. If it does not (eg, there is a syntax error), the routine aborts and returns an error condition.
The structure of the contents of 's' must be correct: if the object is not in table mode, it expects a "word" (variable-type name) initially. After that, or if in table mode it would be the first token, a '<'. This is followed by 0 or more tokens (either words or quoted strings), followed by a terminating '>':

table mode: [row-name] < col0 col1 col2 etc >>
non-table mode: < col0 col1 col2 etc >

RETURNS:
0: successful load
1: error occured: memory exhaustion, or syntax error in 's'
 

reset()
SIGNATURE: int reset ()
SYNOPSIS: empties out the contents of the object.
 

empty_out()
SIGNATURE: int empty_out ()
SYNOPSIS: "empties out" the current object. This will remove all elements of the object's array. The object's name is unaffected.
DESCRIPTION:
This member function "empties out" all data rows of the array databag. The object's structure is intact, allowing new elements to be added afterwards. This function differs from reset() in that if there is a change in the number of elements, the "is-modified" flag is set. When the object is reset, this flag is cleared.
 

add_value()
SIGNATURE: int add_value (const string_o &s)
SYNOPSIS: adds a new element 's' to the internal array of strings. The contents of 's' need not be unique to the other elements.
 

update_value()
SIGNATURE: int update_value (count_t i, const string_o &s)
SYNOPSIS: updates string element number 'i' to 's.
RETURNS:
0: successful update
1: index 'i' out of bounds
 

delete_value()
SIGNATURE: int delete_value (count_t i)
SYNOPSIS: deletes the ith string element from the internal array.
DESCRIPTION:
this function completely removes the ith element. If i exceeds the number of elements in the array, -1 is returned and nothing gets accomplished. This function handles crunching the arrsy so that there are no gaps post-deletion.
RETURNS:
0: successful update
1: index 'i' out of bounds
 

merge_dbag()
SIGNATURE: int merge_dbag (const dbag_o &that, boolean enforce = FALSE, int *pi = NULL)
SYNOPSIS: this merges 'that' into the "this" (the current object).
PARAMETERS

• that: reference handle to an array databag (upcast to data bag).
• enforce: x..
• pi: [output] error indicator variable. values:
  0: success
  zErr_Param_BadType: 'that' not a array databag
  zErr_Require_Failure: different names (only if 'enforce' is set to TRUE)

DESCRIPTION:
if both objects are have the same name, any new items in 'that' are added into the current databag. if the 'enforce' flag is TRUE, new items in 'that' are added into the bag, whether or not they have the same name.
RETURNS:
0: successful merge
-1: error; 'that' not an array databag, or 'enforce' is set (TRUE) and the names are different.
 

bad_reference()
SIGNATURE: const array_dbag_o &bad_reference ()
SYNOPSIS: standard "orthodox" function
TRAITS: this is a static function. No instance is used with its usage.