obitools/obitools3
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 66 Wiki Activity

Major update: obiarrays with columns containing indices referring to

Browse Source 
character strings.
This commit is contained in:
Celine Mercier
2015-11-06 17:55:15 +01:00
parent 456551ffeb
commit 9b066f4327
35 changed files with 632 additions and 532 deletions
Download Patch File Download Diff File Expand all files Collapse all files

152
src/obiarray.h
View File

@ -3,15 +3,15 @@
****************************************************************************/
/**
* @file array.h
* @file obiarray.h
* @author Celine Mercier
* @date October 19th 2015
* @brief Header file for handling arrays for storing and retrieving data arrays (i.e. character strings).
* @brief Header file for handling arrays for storing and retrieving byte arrays (i.e. coding for character strings).
*/
#ifndef ARRAY_H_
#define ARRAY_H_
#ifndef OBIARRAY_H_
#define OBIARRAY_H_
#include <stdlib.h>
@ -29,9 +29,10 @@
*/
#define ARRAY_GROWTH_FACTOR (2) /**< The growth factor when an array is enlarged.
*/
#define BYTE_ARRAY_HEADER_SIZE (5) /**< The size of the header of a byte array.
*/
typedef int32_t index_t; /**< Type of the array indices.
*/
typedef char byte_t; /**< Defining byte type since data is stored in bits
* and char (stored on one byte) is the smallest addressable unit.
*/
@ -43,9 +44,9 @@ typedef char byte_t; /**< Defining byte type since data is stored in bits
typedef struct OBIDMS_array_data_header {
int header_size; /**< Size of the header in bytes.
*/
int64_t data_size_used; /**< Size of the data used in bytes. // TODO not sure about type
index_t data_size_used; /**< Size of the data used in bytes.
*/
int64_t data_size_max; /**< Max size of the data in bytes. // TODO not sure about type
index_t data_size_max; /**< Max size of the data in bytes.
*/
index_t nb_items; /**< Number of items.
*/
@ -73,6 +74,8 @@ typedef struct OBIDMS_array_data {
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.
@ -102,76 +105,181 @@ typedef struct OBIDMS_array {
/**
* @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.
*
*/
//int obi_delete_array(OBIDMS_p dms, const char* array_name);
/**
* The header is already in the byte array
* @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);
/**
* Returns the entire array including the header
* @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);
/**
* TODO LATER
*/
// OBIDMS_array_p obi_column_arrayify(FILE, encoding);
#endif /* ARRAY_H_ */
#endif /* OBIARRAY_H_ */