Next: , Previous: bpipe_hdrf_next, Up: Header Field Manipulations


A.2.8 bpipe_hdrf_resize

Resize the storage space associated with a header field.

Synopsis

     #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 );

Parameters

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

Description

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.

Returns

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.

Errors

Upon error bpipe_errno is set to one of the following:

BPEBADARG

BPENOMEM
a memory allocation failed