Detailed Description

Provides prototype and status code information for use of CreateVector, CreateArray, ResizeVector, ResizeArray, DestroyVector and DestroyArray.

Synopsis

#include <lal/AVFactories.h>

XLAL Functions

REAL4Vector * XLALCreateVector(UINT4 length);
REAL4Vector * XLALResizeVector(REAL4Vector *vector, UINT4 length);
void XLALDestroyVector(REAL4Vector *vector, UINT4 length);
 
<vectype> * XLALCreate<vectype>(UINT4 length );
<vectype> * XLALResize<vectype>(<vectype> *vector, UINT4 length );
void XLALDestroy<vectype>(<vectype> *vector);
 
REAL4Array * XLALCreateArrayL(UINT4 ndim, ...);
REAL4Array * XLALCreateArrayV(UINT4 ndim, UINT4 *dims);
REAL4Array * XLALCreateArray(UINT4Vector *dimLength);
REAL4Array * XLALResizeArrayL(REAL4Array *array, UINT4 ndim, ...);
REAL4Array * XLALResizeArrayV(REAL4Array *array, UINT4 ndim, UINT4 *dims);
REAL4Array * XLALResizeArray(REAL4Array *array, UINT4Vector *dimLength);
void XLALDestroyArray(REAL4Array *array);
 
<arrtype> * XLALCreate<arrtype>L(UINT4 ndim, ...);
<arrtype> * XLALCreate<arrtype>V(UINT4 ndim, UINT4 *dims);
<arrtype> * XLALCreate<arrtype>(UINT4Vector *dimLength);
<arrtype> * XLALResize<arrtype>L(<arrtype> *array, UINT4 ndim, ...);
<arrtype> * XLALResize<arrtype>V(<arrtype> *array, UINT4 ndim, UINT4 *dims);
<arrtype> * XLALResize<arrtype>(<arrtype> *array, UINT4Vector *dimLength);
void XLALDestroy<arrtype>(<arrtype> *array);

Here <vectype> is one of COMPLEX16Vector, COMPLEX8Vector, REAL8Vector, REAL4Vector, INT8Vector, INT4Vector, INT2Vector, UINT8Vector, UINT4Vector, UINT2Vector, or CHARVector, and <arrtype> is one of COMPLEX16Array, COMPLEX8Array, REAL8Array, REAL4Array, INT8Array, INT4Array, INT2Array, UINT8Array, UINT4Array, or UINT2Array.

Description

The XLALCreate<type>Vector functions create vectors of the specified length number of objects of type <type>. The function XLALCreateVector() is the same as XLALCreateREAL4Vector().

The XLALDestroy<type>Vector functions deallocate the memory allocation pointed to by vector including its contents. The function XLALDestroyVector() is the same as XLALDestroyREAL4Vector().

The XLALResize<type>Vector functions resize the supplied vector vector to the new size length. If vector is NULL then this is equivalent to XLALCreate<type>Vector. If length is zero then this is equivalent to XLALDestroy<type>Vector and the routine returns NULL. Otherwise, the amount of data in the vector is realloced using LALRealloc(). The function XLALResizeVector() is the same as XLALResizeREAL4Vector().

The XLALCreate<type>Array XLALCreate<type>ArrayL XLALCreate<type>ArrayV all create an object of type <type>Array. They differ in the way that the dimensions of the array are specified. The function XLALCreate<type>Array allocates an array with dimensions specified by the UINT4Vector dimLength which is a vector of dimension lengths for the array. The function XLALCreate<type>ArrayV provides these dimensions with two arguments: ndim is the number of dimensions and dims is an array of UINT4 values for the dimensions. The function XLALCreate<type>ArrayL also specifies the dimensions as arguments. Here, the first argument, ndim, is the number of dimensions, and this is followed by ndim arguments that provide the dimensions. Note that for this function, a maximum of 16 dimensions can be provided (that is, ndim cannot be more than 16 and there cannot be more than 16 arguments after the first). The XLALCreateArray() XLALCreateArrayL() XLALCreateArrayV() functions are equivalent to the XLALCreateREAL4Array() XLALCreateREAL4ArrayL() XLALCreateREAL4ArrayV() functions respectively.

The XLALDestroy<type>Array functions deallocate the memory allocation pointed to by array including its contents. The function XLALDestroyArray() is the same as XLALDestroyREAL4Array().

The XLALResize<type>Array XLALResize<type>ArrayL XLALResize<type>ArrayV functions resize the provided array array. The arguments after the first are interpreted in the same way as for the XLALCreate<type>Array XLALCreate<type>ArrayL XLALCreate<type>ArrayV functions. If array is NULL, the resize functions are equivalent to the corresponding create function. If ndim is zero for XLALResize<type>ArrayL or XLALResize<type>ArrayV, or if dimLength is NULL for XLALResize<type>Array, then these functions are equivalent to XLALDestroy<type>Array. The XLALResizeArray() XLALResizeArrayL() XLALResizeArrayV() functions are equivalent to the XLALResizeREAL4Array() XLALResizeREAL4ArrayL() XLALResizeREAL4ArrayV() functions respectively.

Return Values

If successful, the create and resize functions return a pointer to the same data that was passed to the function. The resize functions will return a NULL pointer if the size of the new object was zero. Upon failure these routines will return NULL and will set xlalErrno to one of these values: XLAL_ENOMEM if a memory allocation failed, XLAL_EBADLEN if an invalid length was provided (for example, a zero-size allocation with a create function), XLAL_EINVAL if an invalid argument is provided (for example, if the pointer to an array of dimensions is NULL).

The destroy function does not return any value. If the function is passed a NULL pointer, it will set xlalErrno to XLAL_EFAULT. If the function is passed an object that appears corrupted (e.g., a vector with zero length or will a NULL data pointer) it will set xlalErrno to XLAL_EINVAL.

Modules
	Module ArrayFactories.c
	Create/destroy <datatype>Array objects.

	Module VectorFactories.c
	Create/destroy <datatype>Vector objects.

Files
file	ArrayFactoriesTest.c
	A program to test create/destroy array routines.

file	VectorFactoriesTest.c
	A program to test create/destroy vector routines.

Error Codes
#define	AVFACTORIESH_ELENGTH 1
	Illegal length. More...

#define	AVFACTORIESH_EVPTR 2
	Null vector/array handle. More...

#define	AVFACTORIESH_EUPTR 4
	Non-null vector/array pointer. More...

#define	AVFACTORIESH_EDPTR 8
	Null vector/array data. More...

#define	AVFACTORIESH_EMALLOC 16
	Malloc failure. More...

Macro Definition Documentation

◆ AVFACTORIESH_ELENGTH

#define AVFACTORIESH_ELENGTH 1

Illegal length.

Definition at line 176 of file AVFactories.h.

◆ AVFACTORIESH_EVPTR

#define AVFACTORIESH_EVPTR 2

Null vector/array handle.

Definition at line 177 of file AVFactories.h.

◆ AVFACTORIESH_EUPTR

#define AVFACTORIESH_EUPTR 4

Non-null vector/array pointer.

Definition at line 178 of file AVFactories.h.

◆ AVFACTORIESH_EDPTR

#define AVFACTORIESH_EDPTR 8

Null vector/array data.

Definition at line 179 of file AVFactories.h.

◆ AVFACTORIESH_EMALLOC

#define AVFACTORIESH_EMALLOC 16

Malloc failure.

Definition at line 180 of file AVFactories.h.