# slow5_aux_get_\<array_datatype\>

## NAME

slow5_aux_get_\<array_datatype\> - fetches an auxiliary field (an array datatype) of a SLOW5 record

## SYNOPSYS

```
int8_t *slow5_aux_get_int8_array(const slow5_rec_t *read, const char *field, uint64_t *len, int *err)
int16_t *slow5_aux_get_int16_array(const slow5_rec_t *read, const char *field, uint64_t *len, int *err)
int32_t *slow5_aux_get_int32_array(const slow5_rec_t *read, const char *field, uint64_t *len, int *err)
int64_t *slow5_aux_get_int64_array(const slow5_rec_t *read, const char *field, uint64_t *len, int *err)

uint8_t *slow5_aux_get_uint8_array(const slow5_rec_t *read, const char *field, uint64_t *len, int *err)
uint16_t *slow5_aux_get_uint16_array(const slow5_rec_t *read, const char *field, uint64_t *len, int *err)
uint32_t *slow5_aux_get_uint32_array(const slow5_rec_t *read, const char *field, uint64_t *len, int *err)
uint64_t *slow5_aux_get_uint64_array(const slow5_rec_t *read, const char *field, uint64_t *len, int *err)

float *slow5_aux_get_float_array(const slow5_rec_t *read, const char *field, uint64_t *len, int *err)
double *slow5_aux_get_double_array(const slow5_rec_t *read, const char *field, uint64_t *len, int *err)

char *slow5_aux_get_string(const slow5_rec_t *read, const char *field, uint64_t *len, int *err)
```


## DESCRIPTION
`slow5_aux_get_<array_datatype>()` fetches the value of an auxiliary field of an array datatype specified by the filed name *field* from the slow5 record pointed by *read*.  User has to choose the appropriate function so that the returned datatype matches the correct datatype of the stored field, because the data stored in memory as a series of bytes will be reinterpreted as the requested type.

The argument *len* is an address of a *uint64_t* unsigned integer which will be set inside the function to indicate the length of the returned array.

The argument *err* is an address of an integer which will be set inside the function call to indicate an error. Unless *err* is NULL, `slow5_aux_get_<array_datatype>()`sets a non zero error code in **err* in case of failure.


## RETURN VALUE

Upon successful completion, `slow5_aux_get_<array_datatype>()` returns a pointer to an array.  Otherwise, NULL is returned and `slow5_errno` is set to indicate the error.

## ERRORS

In case of an error, `slow5_errno` or the non zero error code is set in *err* (unless *err* is NULL) are as follows.

`SLOW5_ERR_NOFLD`
    &nbsp;&nbsp;&nbsp;&nbsp; The requested field was not found.
`SLOW5_ERR_NOAUX`
    &nbsp;&nbsp;&nbsp;&nbsp; Auxiliary hash map for the record was not found.
`SLOW5_ERR_ARG`   
    &nbsp;&nbsp;&nbsp;&nbsp; Invalid argument - read or field is NULL
`SLOW5_ERR_TYPE`  
    &nbsp;&nbsp;&nbsp;&nbsp; Type conversion was not possible - an primitives data type field cannot be converted to an array type.

## NOTES

The returned pointer is from an internal data structure and the user must NOT free this.

`slow5_aux_get_string()` is used to fetch an array of chars.

More error may be introduced in future.


## EXAMPLES
```
#include <stdio.h>
#include <stdlib.h>
#include <slow5/slow5.h>

#define FILE_PATH "examples/example2.slow5"

int main(){

    slow5_file_t *sp = slow5_open(FILE_PATH,"r");
    if(sp==NULL){
        fprintf(stderr,"Error in opening file\n");
        exit(EXIT_FAILURE);
    }
    slow5_rec_t *rec = NULL;
    int ret=0;
    ret = slow5_get_next(&rec,sp);
    if(ret<0){
        fprintf(stderr,"Error in slow5_get_next. Error code %d\n",ret);
        exit(EXIT_FAILURE);
    }

    //------------------------------------------------------------------------
    //              get auxiliary values with array datatype
    //------------------------------------------------------------------------

    uint64_t *len;
    char* channel_number = slow5_aux_get_string(rec, "channel_number", len, &ret);
    if(ret!=0){
        fprintf(stderr,"Error in getting auxiliary attribute from the file. Error code %d\n",ret);
        exit(EXIT_FAILURE);
    }
    fprintf(stderr,"channel_number = %s\n", channel_number);

    slow5_rec_free(rec);
    slow5_close(sp);

}
```

## SEE ALSO
[`slow5_aux_get_<primitive_datatype>()`](slow5_aux_get.md).
