synopsis.
The simple databag object ( simple_dbag_o ) is a type of databag that, as the name implies, is quite simple. It has a name and a value. Besides the databag name and type (eg class) name maintained by its parent class, the simple databag also has a value. Its size is always exactly 1. All get() operations return the contents of the "value" [internal string object]. It does not implement any "[xxx]_dbag()" member functions, such as get_dbag(), put_dbag(), or add_dbag(), since it has no subsidiary databags within itself. It leaves these functions to its parent class, which also has no use for them. Neither the dbag_o class nor the simple_dbag_o class can fetch a databag from within itself. They cannot store a databag inside themselves, either. So, such functions either return *this - as that is the most sensible (albeit still incorrect) return value, or the operation fails and returns -1.

What the simple databag object can do is set and put values. The object has a solitary value that it can access. There are a variety of get() and put() [eg overloaded] member functions, designed to accomodate a variety of databag subtypes. In order to maintain a consistent and uniform interface across all databag types, these functions have been made to work in the most logical way possible for this class. In the following list, the functions are all members of simple_dbag_o, and the argument list has been shortened to just the relevant parameter:

• get() - returns the value string, unconditionally;
• get(count_t i) - the index counter variable is ignored;
• get(string_o s) or put(string_o s) - s must be "" (empty string), since that is the only path to the value (any other string, that is, a non-empty path, would lead to a path that does not exist in this object)

member functions (primary)

simple_dbag_o()
SIGNATURE: simple_dbag_o ()
SYNOPSIS:
creates a a new simple dbag object, completely devoid of contents. The object's "name" and "value" string is set to empty.
 

simple_dbag_o(simple_dbag_o)
SIGNATURE: simple_dbag_o (const simple_dbag_o &that)
SYNOPSIS: copy constructor: creates a a new simple databag object which is an exact image of the copied simple databag object "that".
 

operator = (simple_dbag_o)
SIGNATURE: const simple_dbag_o &operator = (const simple_dbag_o &rhs)
SYNOPSIS: copies exactly the RHS object ("rhs"), to the existing simple databag object.
RETURNS: a reference to the current databag object
 

destructor
SIGNATURE: ~simple_dbag_o ()
SYNOPSIS: virtual destructor. The databag instance is wiped out and all contents are reinitialized to the at-construction state.
 

clone()
SIGNATURE: dbag_o *clone () const
SYNOPSIS: [DOC NOT YET WRITTEN .. CURRENTLY THIS IS A STUB]
 

bad_reference()
SIGNATURE: const simple_dbag_o &bad_reference ()
SYNOPSIS: A static function. [DOC NOT YET WRITTEN .. CURRENTLY THIS IS A STUB]
 

simple_dbag_o(<args>)
SIGNATURE: simple_dbag_o (const string_o &s)
SYNOPSIS:
create a new simple databag object. This constructor just sets the name and value of the databag, to what is found in parameter "s".
PARAMETERS

• s: this should be a string containing 2 logical components -
• a "name" and a "value". The syntax of the name field should be a standard compuer language variable name (1st char a letter, followed by [optional] numbers, letters, or underscore) and a value string. If the value is not like a variable name - eg, contains punctuation and/or whitespace - it should be wrapped in single or double quotes. 's' can have text following this name-value pair. In fact, this is typical during processing of string-to-databag parsing (see the "load()" member function for more info).

 

simple_dbag_o(<args>)
SIGNATURE: simple_dbag_o (const string_o &snam, const string_o &sval)
SYNOPSIS: [DOC NOT YET WRITTEN .. CURRENTLY THIS IS A STUB]
 

operator == (simple_dbag_o)
SIGNATURE: int operator == (const dbag_o &) const
SYNOPSIS: [DOC WIP / CURRENTLY THIS IS A STUB]
 

operator == (simple_dbag_o)
SIGNATURE: int operator == (const simple_dbag_o &) const
SYNOPSIS: [DOC WIP / CURRENTLY THIS IS A STUB]
 

operator != (simple_dbag_o)
SIGNATURE: int operator != (const simple_dbag_o &) const
SYNOPSIS: [DOC WIP / CURRENTLY THIS IS A STUB]
 

get()
SIGNATURE: const string_o &get (int * = NULL) const
SYNOPSIS: A virtual function. [DOC NOT YET WRITTEN .. CURRENTLY A STUB]
 

get()
SIGNATURE: const string_o &get (count_t, int * = NULL) const
SYNOPSIS: A virtual function. [WIP .. CURRENTLY THIS IS A STUB]
 

get()
SIGNATURE: const string_o &get (const string_o &, int * = NULL) const
SYNOPSIS: A virtual function. [DOC NOT YET WRITTEN .. CURRENTLY A STUB]
 

iprint()
SIGNATURE: const string_o &iprint (string_o &, const count_t) const
SYNOPSIS: [DOC NOT YET WRITTEN .. CURRENTLY THIS IS A STUB]
 

contains()
SIGNATURE: boolean contains (const dbag_o &) const
SYNOPSIS: A virtual function. [DOC WIP .. CURRENTLY A STUB]
 

reset()
SIGNATURE: int reset ()
SYNOPSIS: [DOC NOT YET WRITTEN .. CURRENTLY THIS IS A STUB]
 

empty_out()
SIGNATURE: int empty_out ()
SYNOPSIS:
"empties out" the current object. In the case of the simple databag, the value of the object is set to an empty string (""). The object's name is unaffected.
DESCRIPTION:
The intent of this member function, common to all databag subtypes, is to "empty out" all data in the object. For type matrix, this means rows. For lists, this is all sub databags contained in the list.
 

load()
SIGNATURE: int load (const string_o &)
SYNOPSIS: [DOC NOT YET WRITTEN .. CURRENTLY THIS IS A STUB]
 

put()
SIGNATURE: int put (const string_o &s, boolean force = FALSE, int *pi = NULL)
SYNOPSIS: stores the contents of input parameter 's' into the data bag
PARAMETERS

• s: the value to put into this objects' "value" string object
• force: if TRUE, the object is designated as having been modified. if FALSE (the default), the "is-modified" status depends on whether the updated value has changed.
• pi: [optional] error [output] indicator variable. values:
  0: 's' successfully written into the current object

RETURNS:
0: "val" written to object's value string
-1: failed (see 'pi' output indicator value)
 

put()
SIGNATURE: int put (const string_o &path, const string_o &val, boolean force = FALSE, int *pi = NULL)
SYNOPSIS: puts the text in 'val' into the databag specified by 'path'
PARAMETERS

• path: this must be "" (empty {but set to empty} string) in order for this function to succeed.
• val: the string object containing the text to put into the current object.
• force: if TRUE, the object is designated as having been modified. if FALSE (the default), the "is-modified" status depends on whether the updated value has changed.
• pi: [optional] error [output] indicator variable. values:
  0: "val" successfully written into the current object
  1: "path" - illegal value

RETURNS:
0: "val" written to object's value string
-1: failed (see 'pi' output indicator value)
 

merge_dbag()
SIGNATURE: int merge_dbag (const dbag_o &bag, int *pi = NULL)
SYNOPSIS:
combines the contents of 'bag' with the current bag. In the case of the simple databag, this will over-write the current contents with that of 'bag' (if successful). In order for this to succeed, 'bag' must also be of type ( simple_dbag_o ), and:
The databag names must match, or
If the name of 'bag' differs, 'stomp' must be set to TRUE.
PARAMETERS

• bag: this must be a simple databag. Since a simple databag cannot expand, this (the current object) will recieve the contents of 'bag.value'.
• pi: [optional] error [output] indicator variable. values:
  0: "val" successfully written into the current object;
  zErr_Param_BadFormat: type mismatch, eg, 'bag' is not of type simple databag;

RETURNS:
0: contents of 'bag' transferred to the current object
-1: failed (see 'pi' output indicator value)
 

get_idx()
SIGNATURE: count_t get_idx (const string_o &, int *, count_t = 0) const
SYNOPSIS: A virtual function. [DOC NOT YET WRITTEN .. CURRENTLY THIS IS A STUB]
 

is_ok()
SIGNATURE: boolean is_ok (dbag_o &)
SYNOPSIS: A static function. [DOC NOT YET WRITTEN .. CURRENTLY THIS IS A STUB]
 

is_valid_string()
SIGNATURE: boolean is_valid_string (const string_o &)
SYNOPSIS: A static function. [DOC NOT YET READY .. CURRENTLY THIS IS A STUB]
 

note.
The name given to a simple databag (and actually, all databags) must be a simple "word" - comprised of alphanumeric characters (including '_'). However, you can embed other characters by wrapping the name in quotes (preferably double-quotes). That can be accomplished by using a textstring object, and calling wrap_quotes():

  textstring_o ts = "complex:name";
  ts.wrap_quotes();
  simple_dbag_o sbag (ts);
  sbag.put ("", "a_value");