3. Package for work with variable length objects

The package `vlobject' implements work with variable length object (VLO) and uses package `allocate'. Any number of bytes may be added to and removed from the end of VLO. If it is needed the memory allocated for storing variable length object may be expanded possibly with changing the object place. But between any additions of the bytes (or tailoring) the object place is not changed. To decrease number of changes of the object place the memory being allocated for the object is longer than the current object length.

The package uses package `allocate'. The interface part of the package is file `vlobject.h'. Defining macro `NDEBUG' (e.g. by option `-D' in C++ compiler command line) before the inclusion of the interface file disables fixing some internal errors and errors of usage of the package. The implementation part is file `vlobject.cpp'. The interface contains the following objects:

Type `vlo_t'

describes a descriptor variable length object. The type is simply synonym of `class vlo'. All work with stack of objects is executed through the descriptors. It should remember that work with the object through several descriptors is not safe.

Macro `VLO_DEFAULT_LENGTH'

has value which is default initial size of memory is allocated for VLO when the object is created (with not given initial size). Original value of the macros is equal to 512. This macro can be redefined in C++ compiler command line or with the aid of directive `#undef' before including the interface file.

Class `vlo'

The class contains the following functions:

Public constructor `vlo'

             `vlo (size_t initial_length = VLO_DEFAULT_LENGTH)'
             

is used for creation of descriptor of VLO with initial zero length. If the parameter value is absent, the value is equal to zero then the VLO initial allocated memory length is equal to `VLO_DEFAULT_LENGTH'.

Public destructor ` vlo'

             `~vlo (void)'
             

is used for deleting the descritor of VLO and freeing memory used by the VLO.

Public function `nullify'

             `void nullify (void)'
             

makes that length of VLO of given descriptor will be equal to zero (but memory for VLO is not freed and not reallocated).

Public function `tailor'

             `void tailor (void)'
             

makes that length of memory allocated for VLO of given descriptor becomes equal to VLO length.

Public function `length'

             `size_t length (void)'
             

returns current length of VLO of given descriptor.

Public functions `begin', `end', `bound'

             `void *begin(void)', `void *end(void)', `void *bound(void)'
             

return pointer (of type `void *') to correspondingly the first, the last byte of VLO of given descriptor, and pointer to the last byte plus one. Remember that the object may change own place after any addition.

Public function `shorten'

             `void shorten (size_t n)'
             

removes n bytes from the end of VLO of given descriptor. VLO is nullified if its length is less than n.

Public function `expand'

             `void expand (size_t length)'
             

increases length of VLO of given descriptor on number of bytes given as the parameter. The values of bytes added to the end of VLO will be not defined.

Public function `add_byte'

             `void add_byte (int b)'
             

adds byte given as the parameter to the end of VLO of given descriptor.

Public function `add_memory'

             `void add_memory (void *str, size_t length)'
             

adds memory starting with address given as the first macro parameter and with length given as the second parameter to the end of VLO of given descriptor.

Public function `add_string'

             `void add_string (const char *str)'
             

adds C string (with end marker 0) given as the parameter to the end of VLO of given descriptor. Before the addition the macro deletes last character of the VLO. The last character is suggested to be C string end marker 0.