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.

Because arguments of all macros which return a result (`VLO_LENGTH', `VLO_BEGIN', `VLO_BOUND', and `VLO_END') may be evaluated many times no side-effects should be in the arguments.

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 package macros usage disables fixing some internal errors and errors of usage of the package. The implementation part is file `vlobject.c'. The interface contains the following definitions and macros:

Type `vlo_t'

describes a descriptor of variable length object. All work with variable length object is executed by the following macros through the descriptors. Structure (implementation) of this type is not needed for using variable length object. But 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 zero 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 any using the package macros.

Macro `VLO_CREATE'

          `VLO_CREATE(vlo, initial_length)'
          

is used for creation of VLO with initial zero length. Initial memory allocated for VLO whose descriptor is given as the first macro parameter is given as the second parameter. If the second parameter is equal to zero then the initial allocated memory length is equal to `VLO_DEFAULT_LENGTH'.

`VLO_DELETE'

          `VLO_DELETE(vlo)'
          

is used for freeing memory used by VLO whose descriptor is given as the macro parameter.

Macro `VLO_NULLIFY'

          `VLO_NULLIFY(vlo)'
          

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

Macro `VLO_TAILOR'

          `VLO_TAILOR(vlo)'
          

makes that length of memory allocated for VLO whose descriptor is given as the macro parameter becomes equal to VLO length.

Macro `VLO_LENGTH'

          `VLO_LENGTH(vlo)'
          

returns current length of VLO whose descriptor is given as the macro parameter.

Macros `VLO_BEGIN', `VLO_END', `VLO_BOUND'

          `VLO_BEGIN(vlo)', `VLO_END(vlo)', `VLO_BOUND(vlo)'
          

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

Macro `VLO_SHORTEN'

          `VLO_SHORTEN(vlo, n)'
          

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

Macro `VLO_EXPAND'

          `VLO_EXPAND(vlo, length)'
          

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

Macro `VLO_ADD_BYTE'

          `VLO_ADD_BYTE(vlo, b)'
          

adds byte given as the second parameter to the end of VLO whose descriptor is given as the first parameter.

Macro `VLO_ADD_MEMORY'

          `VLO_ADD_MEMORY(vlo, str, length)'
          

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

Macro `VLO_ADD_STRING'

          `VLO_ADD_STRING(vlo, str)'
          

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