Next: bpipe_hdrf_string_add, Previous: bpipe_hdrf_next, Up: Header Field Manipulations
Resize the storage space associated with a header field.
#include <bpipe/bpipe.h>int bpipe_hdrf_resize( BPipe *bpipe, char *name, size_t index, BPMatrix *matrix, size_t src_off[], size_t dst_off[], size_t extent[], void *init, size_t n_init );
BPipe *bpipe
- binary pipe with which this field is associated
char *name
- the field's name
size_t index
- the field's index. set to
BPHdrfIdx_LAST
to select the last one.BPMatrix *matrix
- the new matrix specification
size_t src_off[]
- offset of source submatrix to copy to destination. extent is equal to the dimensions of the source matrix.
size_t dst_off[]
- offset of destination submatrix. extent is equal to the dimensions of the destination matrix.
size_t extent[]
- the extents of the submatrix to copy. the extent of this array is equal to the dimensions of the source matrix.
void *init
- an array of data which will be used to initialize the new field array elements before copying data from the old field array. The data must have the same type as the header field. Set to
NULL
to use the default initialization.size_t n_init
- the number of initializing elements
This routine resizes the storage space associated with a header data
field. The user must have created a BPMatrix
structure
(using one of the bpipe_matrix_new
routines or
bpipe_matrix_dup
) for the new representation of the data.
This routine will allocate space for the new matrix, copy over the
specified submatrix, and delete the old space.
The submatrix to be copied is specified via the src_off
,
dst_off
, and extent
arguments. They specify,
respectively, the offset of the origin of the submatrix in the
original matrix, its offset from the origin of the new matrix, and
the extents of the submatrix. The submatrix offsets are arrays of
integers, one element per dimension. Either may be NULL
,
indicating that the submatrix's origin coincides with that of the
matrix. The extent argument is an array with as many elements as
there are dimensions in the original matrix. It may be NULL
,
in which case the maximum extents possible will be automatically
calculated.
Before any data is copied from the old field into the resized field, the new field is first initialized, so that any holes in the data will have deterministic values. By default the field is filled with zeroes of the appropriate type. The calling routine may also specify an array of data to be used to initialize the field. If the number of data elements in this array is less than that needed to initialize the field, it will be repeated.
Note that bpipe_hdrf_resize
uses the matrix specification
structure and all of the offset and extent arrays as is, directing
the BPipe
cleanup code to take responsibility for freeing
them. The application should not free them, nor should it
pass them to any other BPipe
routine which takes
responsibility for freeing them. After passing them to
bpipe_hdrf_resize
, it should not alter them in any fashion.
It returns zero upon success and non-zero if the data field doesn't exist.
If there was an error it returns non-zero and sets bpipe_errno
.
Upon error bpipe_errno
is set to one of the following:
BPEBADARG
BPENOMEM