obitools3/src/obiarray.h

/****************************************************************************
 * 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_ */