Array handling is greatly simplified in EMBOSS. AJAX provides dynamic array objects which grow automatically as required thereby saving you the bother of managing the memory yourself. This makes your code cleaner and less error-prone. Objects are provided for handling arrays of various dimensions (1D, 2D or 3D) of the following C datatypes:

The objects can be allocated to a default or a specified reserved size. Each object keeps track of the reserved space available (in case a function is called which must extend the array) and the actual length of the array. Arrays of higher dimensions can nest arrays of lower dimensions.

Functions are provided for returning the current length and for getting and setting array elements. The array elements should only ever be accessed using these functions. If you assign a value to an element which is beyond the current size of the array, then the array will be dynamically reallocated to a sufficient size to accommodate the new element. In contrast, if you try to retrieve an element beyond the current size of the array an error will be generated.

The C-type array may be retrieved from any of the array objects should this be required. This allows standard array notation to be used to access array elements. Functions are provided to sort C-type arrays of integers, unsigned integers and floating point numbers in various ways.

Array objects are typically created directly within the C source code. A floating point array can however be specified in the ACD file (the array ACD datatype) and a pointer to a corresponding AJAX object (AjPFloat) retrieved by the program.

AJAX library files for handling arrays are listed in the table (Table 6.29, “AJAX Library Files for Handling Arrays”). Library file documentation, including a complete description of datatypes and functions, is available at:

ajarr.h/c. Defines the various array objects and functions for handling dynamic arrays. It also contains static functions for handling them at a low level. You are unlikely to need these unless you plan to extend the core functionality of the library.

ajsort.h/c. Functions for sorting arrays (Section 6.17.10, “Sorting Arrays”).

For handling an input array defined in the ACD file use:

AJAX provides dynamic array objects for the fundamental C datatypes (Section 5.1, “Basic Datatypes”) below.

The ACD datatype for handling array input is:

A typical ACD definition for array input:

array: thresholds
[
    information: "Values to represent 'identical',  'similar' and 'related'"
    default: "-1.5,0.0,1.5"
    minimum: "0.0"
    size: "3"
    sum: "0"
    sumtest: "Y"
]

Datatypes and functions for handling arrays via the ACD file are shown below (Table 6.30, “Datatypes and Functions for Array Input and Output”).

Your application code will call embInit to process the ACD file and command line (see Section 6.3, “Handling ACD Files”). All values from the ACD file are read into memory and files are opened as necessary. You have a handle on the files and memory through the ajAcdGet* family of functions which return pointers to appropriate objects.

    AjPFloat thresholds=NULL;

    thresholds = ajAcdGetArray("thresholds");

Functions for handling arrays have consistent names with a prefix of the following general form:

ajTypeDim

Type is the type of the array and is one of:

Dim is the dimensionality of the array. It is not given for 1D arrays:

For example, all functions for handling 2-dimensional arrays of unsigned integers have the prefix ajUint2d whereas all functions for handling 1-dimensional arrays of floats have the prefix ajFloat.

Functions are provided for handling 1D, 2D and 3D arrays however only 1D character arrays are supported.

If you assign a value to an element array which is beyond the current size of the array, then the array will be dynamically reallocated to a sufficient size to accommodate the new element. If you try to retrieve an array element beyond the current size of the array an error will be generated.

It is therefore handy to know the size of an array in advance. Functions for retrieving the size of an array have the suffix Len and either return the array length (for 1D arrays) or write the lengths by argument (2D and 3D arrays). Again, just a few functions are shown:

ajint  ajChararrLen (const AjPChar arr); 
ajint  ajShortLen (const AjPShort arr);
void   ajShort2dLen (const AjPShort2d arr, ajint* Pn1, ajint* Pn2);
void   ajShort3dLen (const AjPShort3d arr,ajint* Pn1, ajint* Pn2, ajint* Pn3);
ajint  ajUintLen (const AjPUint arr);
void   ajUint2dLen (const AjPUint2d arr, ajint* Pn1, ajint* Pn2);
...

For example, to get the sizes of a 3D double array:

AjPDouble3d arr = NULL;
ajint dim1;
ajint dim2;
ajint dim3;

/* Allocate array */
ajDouble3dLen(arr, &dim1, &dim2, &dim3);

Functions to retrieve an element of an array have the suffix Get. They take the index of the element to retrieve and return the appropriate datatype:

char    ajChararrGet (const AjPChar arr, ajint n);
short   ajShortGet (const AjPShort arr, ajint n);
short   ajShort2dGet (const AjPShort2d arr, ajint n1, ajint n2);
short   ajShort3dGet (const AjPShort3d arr, ajint n1, ajint n2, ajint n3);
ajuint  ajUintGet (const AjPUint arr, ajint n);
ajuint  ajUint2dGet (const AjPUint2d arr, ajint n1, ajint n2);
...

For example, to retrieve the very first element of a 3-dimensional float array:

    AjPFloat3d arr = NULL;
    float    val;

    ...
    /* Allocate array */

    val = ajFloat3dGet(arr, 0, 0, 0);

Functions to set an element of an array have the suffix Put. They take the address of an array, the index of the element to set and of course the value to set. They return ajTrue if the element was set successfully:

AjBool  ajChararrPut (const AjPChar* Parr, ajint n, char chr);
AjBool  ajShortPut (const AjPShort* Parr, ajint n, short i);
AjBool  ajShort2dPut (const AjPShort2d* Parr, ajint n1, ajint n2, short i);
AjBool  ajShort3dPut (const AjPShort3d* Parr, ajint n1, ajint n2, ajint n3, short i);
AjBool  ajUintPut (const AjPUint* Parr, ajint n, ajuint i);
AjBool  ajUint2dPut (const AjPUint2d* Parr, ajint n1, ajint n2, ajuint i);
...

For example, to set the very first element of a 3-dimensional float array:

    AjPFloat3d arr = NULL;
    float    val = 1.0;

    arr = ajFloat3dNew();

    ajFloat3dPut(&arr, 0, 0, 0, val);

Functions are provided in ajsort.h/c to sort C-type arrays of integers, unsigned integers and floating point numbers. Arrays may be sorted in the following ways:

Functions for array sorting have the prefix ajSortInc (for sorting in incremental ascending order) or prefix ajSortDec (for sorting in descending order), followed by the datatype (Int, Uint or Float) of the array(s) that is sorted. The array size must be provided.

The basic sort functions include:

extern void  ajSortIntDec (ajint *a, ajuint n);
extern void  ajSortUintDec (ajuint *a, ajuint n);
extern void  ajSortFloatDec (float *a, ajuint n);
extern void  ajSortIntInc (ajint *a, ajuint n);
extern void  ajSortUintInc (ajuint *a, ajuint n);
extern void  ajSortFloatInc (float *a, ajuint n);

There are functions for sorting a single array (p) by the order of elements in another array (a):

void  ajSortFloatDecI (const float *a, ajuint *p, ajuint n);
void  ajSortIntDecI (const ajint *a, ajuint *p, ajuint n);
void  ajSortUintDecI (const ajuint *a, ajuint *p, ajuint n);
void  ajSortFloatIncI (const float *a, ajuint *p, ajuint n);
void  ajSortIntIncI (const ajint *a, ajuint *p, ajuint n);
void  ajSortUintIncI (const ajuint *a, ajuint *p, ajuint n);

Functions for sorting two arrays simultaneously:

void  ajSorttwoIntIncI (ajint *a, ajuint n, ajuint *p);
void  ajSorttwoUintIncI (ajuint *a, ajuint n, ajuint *p);

The C-type array may be retrieved from any of the array objects using the following functions. The function naming scheme should be obvious. Again, not all variants are shown:

char*     ajChararrChararr (const AjPChar arr);   

short*    ajShortShort (const AjPShort arr); 
short**   ajShort2dShort (const AjPShort2d arr);    
short***  ajShort3dShort (const AjPShort3d arr); 

ajuint*   ajUintUint (const AjPUint arr); 
ajuint**  ajUint2dUint (const AjPUint2d arr); 
...

Once the C-type array is retrieved then standard array notation can be used to access array elements. It is of course your responsibility to ensure you do not try to access an array element that is out of bounds. To help avoid doing so you can use the *Len functions (see above) to return the array size(s).