The XB element class is used to represent binary objects in the XB trees.
namespace xb {
class element {
public:
element ();
element (const element &);
element (const void *, xb::size_type);
element & operator = (const element &);
~element () throw ();
protected:
template <typename T> element (T *);
template <typename T> element (const T *);
public:
element (char *);
element (const char *);
element (wchar_t *);
element (const wchar_t *);
template <typename T>
element (const std::basic_string <T> &);
template <typename T>
element (const T &);
template <typename T>
element & operator = (const T &);
public:
void acquire (unsigned char *, xb::size_type);
void release () throw ();
bool empty () const throw ();
bool operator ! () const throw ();
const unsigned char * data () const throw ();
xb::size_type size () const throw ();
};
bool operator == (const element &, const element &);
bool operator != (const element &, const element &);
bool operator < (const element &, const element &);
bool operator <= (const element &, const element &);
bool operator > (const element &, const element &);
bool operator >= (const element &, const element &);
};
The xb::element is default-constructible thus can be constructed as empty, then assigned a value.
The xb::element can also be constructed from any particular object, using the templated constructor xb::element (const T &);. This simply copies raw binary content of the object into the element, thus you must ensure that this can be safely done (no pointers, no allocated memory, ...prefferably POD type).
The constructor is also overloaded for ANSI and wide-character strings. The content of this way created element is the string. In case of null-terminated strings (char * and wchar_t *), the null terminator is not stored.
The pointer and const pointer constructor templates are protected from user because serializing pointer values does not have sense. The protected access is used solely to make the error message a little more meaningful than it would be with private. You will get an error message like this if you'll try to use this constructor: 'template<class T> xb::element::element(T*)' is protected within this context.
The .acquire () member function instructs element to free data it contains and to work over provided data (given by pointer and size). After calling this member function the object becomes owner of the data.
The .release () member function instructs element to drop control over the data. The user must store the pointer to the data and its size (using the .data () and .size () member function) before calling this. Otherwise a memory will leak. After calling this member function, the element is empty and the user is responsible for any further manipulation and destruction of the data.
Note that the .acquire () and .release () member functions are indended for internal purposes and should be used only when absolutely neccessary. You should review the source code of the xb::element before using these member functions.
The .empty () returns true if the object does not contain any data (and thus can be ignored under certain circumstances), otherwise it returns false. The .operator ! () is just an alias to this member function.
This member function returns pointer to constant raw data in the xb::element.
This member function returns size of the raw data in the xb::element in bytes.
// ...
struct {
int i;
char c [2];
} s;
xb::element e1 ("some string value");
xb::element e2 (s);
if (e1 == e2) { ... } else { ... };
// ...
Use the xb::parser::element functions to parse or serialize xb::element objects directly to and from raw memory.
[index]