318 lines
10 KiB
C
318 lines
10 KiB
C
/****************************************************************************
|
|
* OBIDMS array header file *
|
|
****************************************************************************/
|
|
|
|
/**
|
|
* @file obiarray.h
|
|
* @author Celine Mercier
|
|
* @date October 19th 2015
|
|
* @brief Header file for handling arrays for storing and retrieving byte arrays (i.e. coding for character strings).
|
|
*/
|
|
|
|
|
|
#ifndef OBIARRAY_H_
|
|
#define OBIARRAY_H_
|
|
|
|
|
|
#include <stdlib.h>
|
|
#include <stdio.h>
|
|
#include <stdint.h>
|
|
#include <time.h>
|
|
#include <sys/types.h>
|
|
#include <dirent.h>
|
|
|
|
#include "obidms.h"
|
|
#include "obitypes.h"
|
|
|
|
|
|
#define ARRAY_MAX_NAME (1024) /**< The maximum length of an array name.
|
|
*/
|
|
#define ARRAY_GROWTH_FACTOR (2) /**< The growth factor when an array is enlarged.
|
|
*/
|
|
#define BYTE_ARRAY_HEADER_SIZE (9) /**< The size of the header of a byte array.
|
|
*/
|
|
|
|
|
|
typedef char byte_t; /**< Defining byte type since data is stored in bits
|
|
* and char (stored on one byte) is the smallest addressable unit.
|
|
*/
|
|
|
|
|
|
/**
|
|
* @brief OBIDMS array data header structure.
|
|
*/
|
|
typedef struct OBIDMS_array_data_header {
|
|
int header_size; /**< Size of the header in bytes.
|
|
*/
|
|
index_t data_size_used; /**< Size of the data used in bytes.
|
|
*/
|
|
index_t data_size_max; /**< Max size of the data in bytes.
|
|
*/
|
|
index_t nb_items; /**< Number of items.
|
|
*/
|
|
char array_name[ARRAY_MAX_NAME+1]; /**< The array name as a NULL terminated string.
|
|
*/
|
|
time_t creation_date; /**< Date of creation of the file.
|
|
*/
|
|
} OBIDMS_array_data_header_t, *OBIDMS_array_data_header_p;
|
|
|
|
|
|
/**
|
|
* @brief OBIDMS array data structure.
|
|
*/
|
|
typedef struct OBIDMS_array_data {
|
|
OBIDMS_array_data_header_p header; /**< A pointer to the header of the array data.
|
|
*/
|
|
byte_t* data; /**< A pointer to the beginning of the data.
|
|
*/
|
|
} OBIDMS_array_data_t, *OBIDMS_array_data_p;
|
|
|
|
|
|
/**
|
|
* @brief OBIDMS array header structure.
|
|
*/
|
|
typedef struct OBIDMS_array_header {
|
|
int header_size; /**< Size of the header in bytes.
|
|
*/
|
|
size_t array_size; /**< Size of the array in bytes.
|
|
*/
|
|
index_t nb_items; /**< Number of items in the array.
|
|
*/
|
|
index_t nb_items_max; /**< Maximum number of items in the array before it has to be enlarged.
|
|
*/
|
|
char array_name[ARRAY_MAX_NAME+1]; /**< The array name as a NULL terminated string.
|
|
*/
|
|
time_t creation_date; /**< Date of creation of the file.
|
|
*/
|
|
} OBIDMS_array_header_t, *OBIDMS_array_header_p;
|
|
|
|
|
|
/**
|
|
* @brief OBIDMS array structure.
|
|
*/
|
|
typedef struct OBIDMS_array {
|
|
OBIDMS_array_header_p header; /**< A pointer to the header of the array.
|
|
*/
|
|
index_t* first; /**< A pointer to the beginning of the array itself.
|
|
*/
|
|
OBIDMS_array_data_p data; /**< A pointer to the structure containing the data
|
|
* that the array references.
|
|
*/
|
|
DIR* directory; /**< A directory entry usable to
|
|
* refer and scan the array directory.
|
|
*/
|
|
int dir_fd; /**< The file descriptor of the directory entry
|
|
* usable to refer and scan the array directory.
|
|
*/
|
|
} OBIDMS_array_t, *OBIDMS_array_p;
|
|
|
|
|
|
/**
|
|
* @brief Checks if an obiarray already exists or not.
|
|
*
|
|
* @param dms The OBIDMS to which the obiarray belongs.
|
|
* @param array_name The name of the obiarray.
|
|
*
|
|
* @returns A value indicating whether the obiarray exists or not.
|
|
* @retval 1 if the obiarray exists.
|
|
* @retval 0 if the obiarray does not exist.
|
|
* @retval -1 if an error occurred.
|
|
*
|
|
* @since October 2015
|
|
* @author Celine Mercier (celine.mercier@metabarcoding.org)
|
|
*/
|
|
int obi_array_exists(OBIDMS_p dms, const char* array_name);
|
|
|
|
|
|
/**
|
|
* @brief Opens an obiarray and creates it if it does not already exist.
|
|
*
|
|
* Note: An obiarray is made of two files (referred to by two structures).
|
|
* One file contains the indices referring to the data, and the other
|
|
* file contains the data itself. The obiarray as a whole is referred
|
|
* to via the OBIDMS_array structure.
|
|
*
|
|
* @param dms The OBIDMS to which the obiarray belongs.
|
|
* @param array_name The name of the obiarray.
|
|
*
|
|
* @returns A pointer to the obiarray structure.
|
|
* @retval NULL if an error occurred.
|
|
*
|
|
* @since October 2015
|
|
* @author Celine Mercier (celine.mercier@metabarcoding.org)
|
|
*/
|
|
OBIDMS_array_p obi_array(OBIDMS_p dms, const char* array_name);
|
|
|
|
|
|
/**
|
|
* @brief Creates an obiarray. Fails if it already exists.
|
|
*
|
|
* Note: An obiarray is made of two files (referred to by two structures).
|
|
* One file contains the indices referring to the data, and the other
|
|
* file contains the data itself. The obiarray as a whole is referred
|
|
* to via the OBIDMS_array structure.
|
|
*
|
|
* @param dms The OBIDMS to which the obiarray belongs.
|
|
* @param array_name The name of the obiarray.
|
|
*
|
|
* @returns A pointer to the newly created obiarray structure.
|
|
* @retval NULL if an error occurred.
|
|
*
|
|
* @since October 2015
|
|
* @author Celine Mercier (celine.mercier@metabarcoding.org)
|
|
*/
|
|
OBIDMS_array_p obi_create_array(OBIDMS_p dms, const char* array_name);
|
|
|
|
|
|
/**
|
|
* @brief Opens an obiarray. Fails if it does not already exist.
|
|
*
|
|
* Note: An obiarray is made of two files (referred to by two structures).
|
|
* One file contains the indices referring to the data, and the other
|
|
* file contains the data itself. The obiarray as a whole is referred
|
|
* to via the OBIDMS_array structure.
|
|
*
|
|
* @param dms The OBIDMS to which the obiarray belongs.
|
|
* @param array_name The name of the obiarray.
|
|
*
|
|
* @returns A pointer to the obiarray structure.
|
|
* @retval NULL if an error occurred.
|
|
*
|
|
* @since October 2015
|
|
* @author Celine Mercier (celine.mercier@metabarcoding.org)
|
|
*/
|
|
OBIDMS_array_p obi_open_array(OBIDMS_p dms, const char* array_name);
|
|
|
|
|
|
/**
|
|
* @brief Closes an obiarray.
|
|
*
|
|
* Note: An obiarray is made of two files (referred to by two structures).
|
|
* One file contains the indices referring to the data, and the other
|
|
* file contains the data itself. The obiarray as a whole is referred
|
|
* to via the OBIDMS_array structure.
|
|
*
|
|
* @param array A pointer to the obiarray structure to close and free.
|
|
*
|
|
* @retval 0 if the operation was successfully completed.
|
|
* @retval -1 if an error occurred.
|
|
*
|
|
* @since October 2015
|
|
* @author Celine Mercier (celine.mercier@metabarcoding.org)
|
|
*/
|
|
int obi_close_array(OBIDMS_array_p array);
|
|
|
|
|
|
/**
|
|
* @brief Adds a value (byte array) in an obiarray, checking first if it is already in it.
|
|
*
|
|
* @warning The byte array to add must already be encoded and contain its header.
|
|
*
|
|
* @param array A pointer to the obiarray.
|
|
* @param value The byte array to add in the obiarray.
|
|
*
|
|
* @returns The index of the value, whether it was added or already in the obiarray.
|
|
* @retval -1 if an error occurred.
|
|
*
|
|
* @since October 2015
|
|
* @author Celine Mercier (celine.mercier@metabarcoding.org)
|
|
*/
|
|
index_t obi_array_add(OBIDMS_array_p array, byte_t* value);
|
|
|
|
|
|
/**
|
|
* @brief Recovers a value (byte array) in an obiarray.
|
|
*
|
|
* @warning The byte array recovered is encoded and contains its header.
|
|
*
|
|
* @param array A pointer to the obiarray.
|
|
* @param index The index of the value in the data array.
|
|
*
|
|
* @returns A pointer to the byte array recovered.
|
|
*
|
|
* @since October 2015
|
|
* @author Celine Mercier (celine.mercier@metabarcoding.org)
|
|
*/
|
|
byte_t* obi_array_get(OBIDMS_array_p array, index_t index);
|
|
|
|
|
|
/**
|
|
* @brief Searches a value (byte array) in an obiarray performing a binary search.
|
|
*
|
|
* @warning The byte array to search must already be encoded and contain its header.
|
|
*
|
|
* @param array A pointer to the obiarray.
|
|
* @param value The byte array to add in the obiarray.
|
|
*
|
|
* @returns If the value is found, its data index is returned.
|
|
* If the value is not found, the array index indicating where the value's data index
|
|
* should be in the array is returned in the form (- (index + 1)), as data indices in an
|
|
* obiarray are sorted according to the ascending order of the values (byte arrays) themselves.
|
|
*
|
|
* @since October 2015
|
|
* @author Celine Mercier (celine.mercier@metabarcoding.org)
|
|
*/
|
|
index_t obi_array_search(OBIDMS_array_p array, byte_t* value);
|
|
|
|
|
|
/**
|
|
* @brief Converts a character string to a byte array with a header.
|
|
*
|
|
* @warning The byte array must be freed by the caller.
|
|
*
|
|
* @param value The character string to convert.
|
|
*
|
|
* @returns A pointer to the byte array created.
|
|
* @retval NULL if an error occurred.
|
|
*
|
|
* @since October 2015
|
|
* @author Celine Mercier (celine.mercier@metabarcoding.org)
|
|
*/
|
|
byte_t* obi_str_to_obibytes(char* value);
|
|
|
|
|
|
/**
|
|
* @brief Converts a byte array to a character string.
|
|
*
|
|
* @param value_b The byte array to convert.
|
|
*
|
|
* @returns A pointer to the character string contained in the byte array.
|
|
*
|
|
* @since October 2015
|
|
* @author Celine Mercier (celine.mercier@metabarcoding.org)
|
|
*/
|
|
const char* obi_obibytes_to_str(byte_t* value_b);
|
|
|
|
|
|
/**
|
|
* @brief Converts a DNA sequence to a byte array with a header.
|
|
*
|
|
* @warning The byte array must be freed by the caller.
|
|
*
|
|
* @param value The DNA sequence to convert.
|
|
*
|
|
* @returns A pointer to the byte array created.
|
|
* @retval NULL if an error occurred.
|
|
*
|
|
* @since November 2015
|
|
* @author Celine Mercier (celine.mercier@metabarcoding.org)
|
|
*/
|
|
byte_t* obi_seq_to_obibytes(char* seq);
|
|
|
|
|
|
/**
|
|
* @brief Converts a byte array to a DNA sequence.
|
|
*
|
|
* @param value_b The byte array to convert.
|
|
*
|
|
* @returns A pointer to the DNA sequence contained in the byte array.
|
|
*
|
|
* @since November 2015
|
|
* @author Celine Mercier (celine.mercier@metabarcoding.org)
|
|
*/
|
|
const char* obi_obibytes_to_seq(byte_t* value_b);
|
|
|
|
|
|
#endif /* OBIARRAY_H_ */
|
|
|