diff --git a/src/obidebug.h b/src/obidebug.h index c6b4519..287af22 100644 --- a/src/obidebug.h +++ b/src/obidebug.h @@ -1,8 +1,12 @@ -/* - * obidebug.h - * - * Created on: June 25th 2015 - * Author: Celine Mercier (celine.mercier@metabarcoding.org) +/**************************************************************************** + * Header file for the debugging code * + ****************************************************************************/ + +/** + * @file obidebug.h + * @author Celine Mercier (celine.mercier@metabarcoding.org) + * @date 25 June 2015 + * @brief Header file for the debugging code. */ @@ -12,7 +16,7 @@ #include -//#ifndef DEBUG_LEVEL +//#ifndef DEBUG_LEVEL // TODO //#define DEBUG_LEVEL MAXINT //#endif diff --git a/src/obidms.c b/src/obidms.c index 595dfa5..06ff2c4 100644 --- a/src/obidms.c +++ b/src/obidms.c @@ -1,10 +1,15 @@ -/* - * obidms.c - * - * @date 23 May 2015 - * @Author: coissac +/******************************************************************** + * OBIDMS functions * + ********************************************************************/ + +/** + * @file obidms.c + * @author Eric Coissac (eric.coissac@metabarcoding.org) + * @date 23 May 2015 + * @brief OBIDMS functions. */ + #include #include #include @@ -18,7 +23,7 @@ #include "obidmscolumn.h" -#define DEBUG_LEVEL 0 +#define DEBUG_LEVEL 0 // TODO has to be defined somewhere else (cython compil flag?) /************************************************************************** @@ -29,27 +34,22 @@ /** - * Internal function building the directory name from an OBIDMS name. + * Internal function building the OBIDMS directory name from an OBIDMS name. * * The function builds the directory name corresponding to an OBIDMS. - * It checks also that the name is not too long. + * It also checks that the name is not too long. * * @warning The returned pointer has to be freed by the caller. * - * @param dms_name the name of the OBIDMS + * @param dms_name The name of the OBIDMS. * - * @return a pointer to the directory name - * @retvalue if everything is ok - * @retvalue NULL if an error occurs - * - * ###Error values - * - OBIDMS_MEMORY_ERROR : something wrong occurred during memory allocation. - * - OBIDMS_LONG_NAME_ERROR : the database name exceeds the limit. + * @returns A pointer to the directory name. + * @retval NULL if an error occurred. * * @since May 2015 * @author Eric Coissac (eric.coissac@metabarcoding.org) */ -static char *build_directory_name(const char *dms_name); +static char* build_directory_name(const char* dms_name); /************************************************************************ @@ -58,9 +58,9 @@ static char *build_directory_name(const char *dms_name); * ************************************************************************/ -static char *build_directory_name(const char *dms_name) +static char* build_directory_name(const char* dms_name) { - char *directory_name; + char* directory_name; // Build the database directory name if (asprintf(&directory_name, "%s.obidms", dms_name) < 0) diff --git a/src/obidms.h b/src/obidms.h index aa001df..4065006 100644 --- a/src/obidms.h +++ b/src/obidms.h @@ -1,13 +1,19 @@ -/* - * obidms.h - * - * Created on: 23 mai 2015 - * Author: coissac +/******************************************************************** + * OBIDMS header file * + ********************************************************************/ + +/** + * @file obidmscolumn.h + * @author Eric Coissac (eric.coissac@metabarcoding.org) + * @date 23 May 2015 + * @brief Header file for the OBIDMS functions and structures. */ + #ifndef OBIDMS_H_ #define OBIDMS_H_ + #include #include #include @@ -17,38 +23,37 @@ #include "obierrno.h" + #define OBIDMS_MAX_NAME (2048) /**< The maximum length of an OBIDMS name */ -/** @brief A structure describing an OBIDMS instance + +/** + * @brief A structure describing an OBIDMS instance * * A pointer to this structure is returned on creation * and opening of an OBITools Data Management System (DMS) */ - typedef struct OBIDMS { char directory_name[OBIDMS_MAX_NAME+1]; /**< The name of the directory - * containing the DMS + * containing the DMS. */ DIR* directory; /**< A directory entry usable to - * refer and scan the database directory + * refer and scan the database directory. */ } OBIDMS_t, *OBIDMS_p; -/*@ - * @brief Checks if an OBIDMS exists +/** + * @brief Checks if an OBIDMS exists. * - * @param dms_name a pointer to a C string containing the name of the database. - * The actual directory name used to store the DMS will be - * `.obidms`. + * @param dms_name A pointer to a C string containing the name of the database. * - * @return an integer value indicating the status of the database - * @retvalue 1 the database exist - * @retvalue 0 the database does not exist - * @retvalue -1 an error occurred + * @returns An integer value indicating the status of the database + * @retval 1 if the database exists. + * @retval 0 if the database does not exist. + * @retval -1 if an error occurred. * - * @see obi_close_dms() * @since May 2015 * @author Eric Coissac (eric.coissac@metabarcoding.org) */ @@ -62,79 +67,62 @@ int obi_dms_exists(const char* dms_name); * if a directory with this name does not already exist * before creating the new database. * - * @param dms_name a pointer to a C string containing the name of the database. - * The actual directory name used to store the DMS will be - * `.obidms` + * @param dms_name A pointer to a C string containing the name of the database. + * The actual directory name used to store the DMS will be + * `.obidms`. * - * @return a pointer to an OBIDMS structure describing the newly created DMS - * @retval NULL on error and the `obi_errno` variable is set. - * - * ###Error values - * - OBIDMS_EXIST_ERROR : a database with the same name already exists. - * - OBIDMS_LONG_NAME_ERROR : the database name exceeds the limit. - * - OBIDMS_MEMORY_ERROR : something wrong occurred during memory allocation. + * @returns A pointer to an OBIDMS structure describing the newly created DMS. + * @retval NULL if an error occurred. * * @see obi_close_dms() * @since May 2015 * @author Eric Coissac (eric.coissac@metabarcoding.org) */ -OBIDMS_p obi_create_dms(const char *dms_name); +OBIDMS_p obi_create_dms(const char* dms_name); /** * @brief Opens an existing OBITools Data Management instance (OBIDMS). * - * @param dms_name a pointer to a C string containing the name of the database. - * The actual directory name used to store the DMS will be - * `.obidms` + * @param dms_name A pointer to a C string containing the name of the database. * - * @return a pointer to an OBIDMS structure describing the newly created DMS - * @retval NULL on error and the `obi_errno`variable is set. - * - * ###Error values - * - OBIDMS_LONG_NAME_ERROR : the database name exceeds the limit. - * - OBIDMS_MEMORY_ERROR : something wrong occurred during memory allocation. + * @returns A pointer to an OBIDMS structure describing the opened DMS. + * @retval NULL if an error occurred. * * @see obi_close_dms() * @since May 2015 * @author Eric Coissac (eric.coissac@metabarcoding.org) */ -OBIDMS_p obi_open_dms(const char *dms_name); +OBIDMS_p obi_open_dms(const char* dms_name); /** - * @brief Creates a new OBIDMS instance. + * @brief Creates or opens a new OBIDMS instance. * * If the database already exists, this function opens it, otherwise it * creates a new database. * - * @param dms_name a pointer to a C string containing the name of the database. - * The actual directory name used to store the DMS is - * `.obidms` + * @param dms_name A pointer to a C string containing the name of the database. * - * @return a pointer to an OBIDMS structure describing the newly created DMS - * @retval NULL on error and the `obi_errno`variable is set. - * - * ###Error values - * - OBIDMS_LONG_NAME_ERROR : the database name exceeds the limit. - * - OBIDMS_MEMORY_ERROR : something wrong occurred during memory allocation. + * @returns A pointer to an OBIDMS structure describing the OBIDMS. + * @retval NULL if an error occurred. * * @see obi_close_dms() * @since May 2015 * @author Eric Coissac (eric.coissac@metabarcoding.org) */ -OBIDMS_p obi_dms(const char *dms_name); +OBIDMS_p obi_dms(const char* dms_name); /** * @brief Closes an opened OBITools Data Management instance (OBIDMS). * - * @param dms a pointer as returned by obi_create_dms() or obi_open_dms() + * @param dms A pointer as returned by obi_create_dms() or obi_open_dms(). * - * @return an integer value indicating the success of the operation. Even on - * error, the `OBIDMS` structure is freed - * @retvalue 0 on success - * @retvalue -1 on failure and the `obi_errno` variable is set. + * @returns An integer value indicating the success of the operation. Even on + * error, the `OBIDMS` structure is freed. + * @retval 0 on success. + * @retval -1 if an error occurred?-. * * @see obi_create_dms() * @see obi_open_dms() diff --git a/src/obidmscolumn.c b/src/obidmscolumn.c index dcc2d69..df321ed 100644 --- a/src/obidmscolumn.c +++ b/src/obidmscolumn.c @@ -1,12 +1,12 @@ /**************************************************************************** - * OBIDMS_column functions * + * OBIDMS columns functions * ****************************************************************************/ /** * @file obidmscolumn.c - * @author Celine Mercier + * @author Celine Mercier (celine.mercier@metabarcoding.org) * @date 22 May 2015 - * @brief Functions for the shared elements of all the OBIColumn structures. + * @brief Functions shared by all the OBIDMS columns. */ @@ -19,7 +19,7 @@ #include #include #include -#include /* mmap() is defined in this header */ +#include #include "obidmscolumn.h" #include "obidmscolumndir.h" @@ -30,7 +30,7 @@ #include "obilittlebigman.h" -#define DEBUG_LEVEL 0 +#define DEBUG_LEVEL 0 // TODO has to be defined somewhere else (cython compil flag?) /************************************************************************** @@ -47,18 +47,16 @@ * * @warning The returned pointer has to be freed by the caller. * - * @param column_name the name of the OBIDMS column. + * @param column_name The name of the OBIDMS column file. + * @param version_number The version number of the OBIDMS column file. * - * @return a pointer to the column file name - * @retvalue NULL if an error occurs - * - * ###Error values - * - OBIDMS_MEMORY_ERROR : something wrong occurred during memory allocation. + * @returns A pointer to the column file name. + * @retval NULL if an error occurred. * * @since May 2015 * @author Eric Coissac (eric.coissac@metabarcoding.org) */ -static char *build_column_file_name(const char *column_name, obiversion_t version_number); +static char* build_column_file_name(const char* column_name, obiversion_t version_number); /** @@ -69,32 +67,28 @@ static char *build_column_file_name(const char *column_name, obiversion_t versio * * @warning The returned pointer has to be freed by the caller. * - * @param column_name the name of the OBIDMS column. + * @param column_name The name of the OBIDMS column. * - * @return a pointer to the version file name - * @retvalue NULL if an error occurs - * - * ###Error values - * - OBIDMS_MEMORY_ERROR : something wrong occurs during memory allocation. + * @returns A pointer to the version file name. + * @retval NULL if an error occurred. * * @since May 2015 * @author Eric Coissac (eric.coissac@metabarcoding.org) */ -static char *build_version_file_name(const char *column_name); +static char* build_version_file_name(const char* column_name); /** * @brief Internal function returning a new column version number - * in the `dms` database + * in the OBIDMS database. * - * @param dms a pointer as returned by obi_create_dms() or obi_open_dms() - * @param column_name the name of the column - * @param block is the call is blocking or not - * - `true` the call is blocking - * - `false` the call is not blocking + * @param column_directory A pointer as returned by obi_create_column_directory() or obi_open_column_directory(). + * @param block Whether the call is blocking or not: + * - `true` the call is blocking + * - `false` the call is not blocking. * - * @return the bigger version number used for this column - * @retvalue -1 if the column does not exist + * @returns The next version number for this column. + * @retval -1 if an error occurred. * * @since May 2015 * @author Eric Coissac (eric.coissac@metabarcoding.org) @@ -104,50 +98,50 @@ static obiversion_t obi_get_new_version_number(OBIDMS_column_directory_p column_ /** * @brief Internal function creating a new column version file - * in the `dms` database + * in the OBIDMS database. * * The new file is initialized with the minimum version number `0`. * - * @param dms a pointer as returned by obi_create_dms() or obi_open_dms() - * @param column_name the name of the column + * @param column_directory A pointer as returned by obi_create_column_directory() or obi_open_column_directory(). * - * @return the next usable version number for this column : `0` - * @retvalue -1 if the column does not exist + * @returns The next usable version number for this column : `0`. + * @retval -1 if an error occurred. * * @since May 2015 * @author Eric Coissac (eric.coissac@metabarcoding.org) */ -static int create_version_file(OBIDMS_column_directory_p column_directory); +static obiversion_t create_version_file(OBIDMS_column_directory_p column_directory); /** * @brief Internal function setting the elements names of the lines of a - * column in the header of the OBIDMS column structure. + * column in the header of the OBIDMS column structure. * - * @param column a pointer as returned by obi_create_column() - * @param elements_names the names of the elements with ';' as separator + * @param column A pointer as returned by obi_create_column(). + * @param elements_names The names of the elements with ';' as separator. * - * @return 0 if the operation was successfully completed - * @retvalue -1 if an error occurred + * @retval 0 if the operation was successfully completed. + * @retval -1 if an error occurred. * * @since July 2015 * @author Celine Mercier (celine.mercier@metabarcoding.org) */ -int obi_column_set_elements_names(OBIDMS_column_p column, const char* elements_names); +static int obi_column_set_elements_names(OBIDMS_column_p column, const char* elements_names); /** - * @brief Internal function computing how many lines of an OBIDMS column fill in a memory page. + * @brief Internal function computing how many lines of an OBIDMS column + * fit in a memory page. * - * @param data_type the data OBIType - * @param nb_elements_per_line the number of elements per line + * @param data_type The data OBIType. + * @param nb_elements_per_line The number of elements per line. * - * @return the line count for one memory page + * @returns The line count for one memory page. * * @since September 2015 * @author Celine Mercier (celine.mercier@metabarcoding.org) */ -size_t get_line_count_per_page(OBIType_t data_type, size_t nb_elements_per_line); +static size_t get_line_count_per_page(OBIType_t data_type, size_t nb_elements_per_line); /************************************************************************ @@ -232,10 +226,10 @@ static obiversion_t obi_get_new_version_number(OBIDMS_column_directory_p column_ else { obi_set_errno(OBICOL_UNKNOWN_ERROR); + obidebug(1, "\nError opening a version file"); + free(version_file_name); return -1; } - obidebug(1, "\nError opening a version file"); - free(version_file_name); } // Test if the version file size is ok @@ -346,7 +340,7 @@ static obiversion_t obi_get_new_version_number(OBIDMS_column_directory_p column_ } -static int create_version_file(OBIDMS_column_directory_p column_directory) +static obiversion_t create_version_file(OBIDMS_column_directory_p column_directory) { off_t loc_size; obiversion_t version_number; @@ -652,7 +646,6 @@ OBIDMS_column_p obi_create_column(OBIDMS_p dms, nb_lines = minimum_line_count; // The number of elements names should be equal to the number of elements per line - if ((elements_names == NULL) && (nb_elements_per_line > 1)) { obidebug(1, "\nCan't create column because no elements names were given for a number of elements per line greater than 1"); @@ -723,6 +716,7 @@ OBIDMS_column_p obi_create_column(OBIDMS_p dms, if (column_file_descriptor < 0) { obi_set_errno(OBICOL_UNKNOWN_ERROR); + obidebug(1, "\nError opening a column file"); free(column_file_name); return NULL; } @@ -800,11 +794,11 @@ OBIDMS_column_p obi_create_column(OBIDMS_p dms, header->creation_date = time(NULL); header->version = version_number; header->cloned_from = -1; - header->comments[0] = 0x0; + header->comments[0] = 0x0; // TODO obi_column_set_elements_names(new_column, elements_names); - strncpy(header->name, column_name, OBIDMS_MAX_COLNAME); + strncpy(header->name, column_name, OBIDMS_COLUMN_MAX_NAME); // Fill the data with NA values obi_ini_to_NA_values(new_column, 0, nb_lines); @@ -816,7 +810,9 @@ OBIDMS_column_p obi_create_column(OBIDMS_p dms, } -OBIDMS_column_p obi_open_column(OBIDMS_p dms, const char* column_name, obiversion_t version_number) +OBIDMS_column_p obi_open_column(OBIDMS_p dms, + const char* column_name, + obiversion_t version_number) { OBIDMS_column_p column; OBIDMS_column_directory_p column_directory; @@ -941,7 +937,10 @@ OBIDMS_column_p obi_open_column(OBIDMS_p dms, const char* column_name, obiversio } -OBIDMS_column_p obi_clone_column(OBIDMS_p dms, const char* column_name, obiversion_t version_number, bool clone_data) +OBIDMS_column_p obi_clone_column(OBIDMS_p dms, + const char* column_name, + obiversion_t version_number, + bool clone_data) { OBIDMS_column_p column_to_clone; OBIDMS_column_p new_column; @@ -1032,7 +1031,7 @@ int obi_close_column(OBIDMS_column_p column) } -int obi_truncate_column_to_lines_used(OBIDMS_column_p column) +int obi_truncate_column_to_lines_used(OBIDMS_column_p column) // TODO is it necessary to unmap/remap? { size_t file_size; size_t data_size; @@ -1193,7 +1192,8 @@ int obi_enlarge_column(OBIDMS_column_p column) return -1; } - // Remap the data: try enlarging mapped region (this actually never works on my mac without the MAP_FIXED flag which overwrites everything) + // Remap the data: try enlarging mapped region (TODO this actually never works on my mac without the MAP_FIXED flag which overwrites everything) + // TODO : makes separate function even if it's only used here? //obidebug(2, "\ntry enlarging mapped region: old size = %ld, new size = %ld, size = %ld", old_data_size, new_data_size, new_data_size - old_data_size); new_data = mmap(column->data, new_data_size - old_data_size, @@ -1267,7 +1267,9 @@ int obi_truncate_and_close_column(OBIDMS_column_p column) } -void obi_ini_to_NA_values(OBIDMS_column_p column, size_t start, size_t nb_lines) +void obi_ini_to_NA_values(OBIDMS_column_p column, + size_t start, + size_t nb_lines) { size_t i, end, nb_elements; @@ -1311,7 +1313,7 @@ void obi_ini_to_NA_values(OBIDMS_column_p column, size_t start, size_t nb_lines) } -void obi_column_make_unwritable(OBIDMS_column_p column) +void obi_column_make_unwritable(OBIDMS_column_p column) // TODO this might be irrelevant { column->writable = false; } @@ -1410,7 +1412,7 @@ OBIType_t obi_column_get_data_type_from_name(OBIDMS_p dms, const char* column_na return -1; } - // Check endianness? + // TODO Check endianness? data_type = header->data_type; @@ -1496,7 +1498,7 @@ size_t obi_column_get_line_count_from_name(OBIDMS_p dms, const char* column_name return -1; } - // Check endianness? + // TODO Check endianness? line_count = header->line_count; @@ -1524,7 +1526,7 @@ size_t obi_column_get_element_index_from_name(OBIDMS_column_p column, const char if (elements_names == NULL) { obidebug(1, "\nError strdup-ing the elements names"); - return -1; + return SIZE_MAX; //TODO } element_index = 0; @@ -1550,7 +1552,7 @@ size_t obi_column_get_element_index_from_name(OBIDMS_column_p column, const char obidebug(1, "\nCan't find an element name"); free(elements_names); - return -1; + return SIZE_MAX; //TODO } diff --git a/src/obidmscolumn.h b/src/obidmscolumn.h index 3d670b3..85ba2d3 100644 --- a/src/obidmscolumn.h +++ b/src/obidmscolumn.h @@ -1,14 +1,15 @@ /**************************************************************************** - * OBIDMS_column header file * + * OBIDMS columns header file * ****************************************************************************/ /** * @file obidmscolumn.h - * @author Celine Mercier + * @author Celine Mercier (celine.mercier@metabarcoding.org) * @date 12 May 2015 - * @brief Header file for the shared elements of all the OBIDMS column structures. + * @brief Header file for the functions and structures shared by all the OBIDMS columns. */ + #ifndef OBIDMSCOLUMN_H_ #define OBIDMSCOLUMN_H_ @@ -25,64 +26,76 @@ #include "obilittlebigman.h" #include "obidmscolumndir.h" -#define ELEMENTS_NAMES_MAX (2048) -#define GROWTH_FACTOR (2) -#define MAXIMUM_LINE_COUNT (1000000) + +#define ELEMENTS_NAMES_MAX (2048) /**< The maximum length of the list of elements names. + */ +#define GROWTH_FACTOR (2) /**< The growth factor when a column is enlarged. + */ +#define MAXIMUM_LINE_COUNT (1000000) /**< The maximum line count for the data of a column. //TODO + */ typedef int32_t obiversion_t; /**< Used to store the column version number */ -/** - * @brief OBIColumnHeader structure. - */ +/** + * @brief OBIDMS column header structure. + */ typedef struct OBIDMS_column_header { - bool little_endian; /**< endianness of the column: - * - `true` on little endian platforms - * - `false` on big endian platforms - * - * @see obi_is_little_endian() - */ - int header_size; /**< size of the header in bytes */ - size_t line_count; /**< number of lines of data */ - size_t lines_used; /**< number of lines of data used */ - size_t nb_elements_per_line; /**< number of elements per line (default : 1) */ - char elements_names[ELEMENTS_NAMES_MAX+1]; /**< names of the line elements (default : "["column_name"]") */ - OBIType_t data_type; /**< type of the data */ - time_t creation_date; /**< date of creation of the file */ - obiversion_t version; /**< version of the OBIColumn */ - obiversion_t cloned_from; /**< version of the OBIColumn from which the column was cloned from (-1 if it does not come from cloning).*/ - char name[OBIDMS_MAX_COLNAME+1]; /**< The column name as a NULL - * terminated string. - */ - char comments[1]; /**< comments stored as a classical - zero end C string. - The size of the comment is only limited - by the header size - */ + bool little_endian; /**< Endianness of the column: + * - `true` on little endian platforms + * - `false` on big endian platforms + * @see obi_is_little_endian() + */ + int header_size; /**< Size of the header in bytes. + */ + size_t line_count; /**< Number of lines of data allocated. + */ + size_t lines_used; /**< Number of lines of data used. + */ + size_t nb_elements_per_line; /**< Number of elements per line (default: 1). + */ + char elements_names[ELEMENTS_NAMES_MAX+1]; /**< Names of the line elements with ';' as separator + * (should be the column name if one element per line). + */ + OBIType_t data_type; /**< Type of the data. + */ + time_t creation_date; /**< Date of creation of the file. + */ + obiversion_t version; /**< Version of the column. + */ + obiversion_t cloned_from; /**< Version of the column from which this column + * was cloned from (-1 if it was not created by cloning + * another column). + */ + char name[OBIDMS_COLUMN_MAX_NAME+1]; /**< The column name as a NULL terminated string. + */ + char comments[1]; /**< Comments stored as a classical zero end C string. + * The size of the comment is only limited by the header size. + */ } OBIDMS_column_header_t, *OBIDMS_column_header_p; /** - * @brief Structure describing a Column of the OBITools DMS + * @brief OBIDMS column structure. * * A data structure of this type is returned by the functions - * creating, opening or cloning an OBIDMS_column. + * creating, opening or cloning an OBIDMS column. */ typedef struct OBIDMS_column { - OBIDMS_p dms; /**< A pointer to a DMS instance */ - OBIDMS_column_directory_p column_directory; /**< A pointer to an OBIDMS column directory instance */ - OBIDMS_column_header_p header; /**< A pointer to the header of the column */ - void* data; /**< A `void` pointer to the beginning of the - * data. + OBIDMS_p dms; /**< A pointer to the OBIDMS structure to which the column belongs. + */ + OBIDMS_column_directory_p column_directory; /**< A pointer to the OBIDMS column directory structure to which the column belongs. + */ + OBIDMS_column_header_p header; /**< A pointer to the header of the column. + */ + void* data; /**< A `void` pointer to the beginning of the data. * - * @warning never use this member directly - * outside of the code of the - * low level functions - * of the OBITools DMS + * @warning Never use this member directly outside of the code of the + * low level functions of the OBIDMS. */ - bool writable; /**< Indicates if the column is writable or not. + bool writable; /**< Indicates if the column is writable or not. TODO delete? * - `true` the column is writable * - `false` the column is read-only * @@ -93,23 +106,30 @@ typedef struct OBIDMS_column { /** - * @brief Returns the latest version of a column in a column directory + * @brief Returns the latest version number of a column in a column directory using the column directory structure. * - * @param column_directory + * @param column_directory A pointer as returned by obi_create_column_directory() or obi_open_column_directory(). * - * @return the latest version number kept in the version file - * @return -1 if an error occurred + * @returns The latest version number kept in the version file. + * @retval -1 if an error occurred. + * + * @since May 2015 + * @author Eric Coissac (eric.coissac@metabarcoding.org) */ obiversion_t obi_get_latest_version_number(OBIDMS_column_directory_p column_directory); /** - * @brief Returns the latest version of a column in a column directory + * @brief Returns the latest version of a column in a column directory using the column name. * - * @param column_name + * @param dms A pointer on an OBIDMS. + * @param column_name The column name. * - * @return the latest version number kept in the version file - * @return -1 if an error occurred + * @returns The latest version number kept in the version file. + * @retval -1 if an error occurred. + * + * @since May 2015 + * @author Eric Coissac (eric.coissac@metabarcoding.org) */ obiversion_t obi_column_get_latest_version_from_name(OBIDMS_p dms, const char* column_name); @@ -118,9 +138,9 @@ obiversion_t obi_column_get_latest_version_from_name(OBIDMS_p dms, const char* c * @brief Returns the header size in bytes of a column on this platform. * * The header size is defined as a multiple of the memory page size. - * Up to now the header size is defined as one time the page size. + * As of now the header size is defined as one time the page size. * - * @return a `size_t` value corresponding to the header size in bytes + * @returns a `size_t` value corresponding to the header size in bytes. * * @since May 2015 * @author Eric Coissac (eric.coissac@metabarcoding.org) @@ -131,30 +151,40 @@ size_t obi_get_platform_header_size(); /** * @brief Creates a column. * - * @param dms a pointer on an OBIDMS - * @param column_name the name of the new column - * @param type the OBIType code used to create the column - * @param nb_lines the number of lines to be stored + * The minimum data size allocated is one memory page, and the data is initialized to the NA value of the OBIType. + * + * @warning If there is one element per line, elements_names should be equal to column_name. // TODO change this condition? + * + * @param dms A pointer on an OBIDMS. + * @param column_name The name of the new column. + * @param data_type The OBIType code of the data. + * @param nb_lines The number of lines to be stored. + * @param nb_elements_per_line The number of elements per line. + * @param elements_names The names of the elements with ';' as separator. + * + * @returns A pointer on the newly created column structure. + * @retval NULL if an error occurred. * * @since May 2015 * @author Eric Coissac (eric.coissac@metabarcoding.org) */ OBIDMS_column_p obi_create_column(OBIDMS_p dms, const char* column_name, - OBIType_t type, + OBIType_t data_type, size_t nb_lines, size_t nb_elements_per_line, - const char* elements_names); + const char* elements_names); /** * @brief Opens a column in read-only mode. * - * @param dms a pointer on an OBIDMS - * @param column_name the name of the column - * @param version_number the version of the column that should be opened (if -1, the latest version number is retrieved) + * @param dms A pointer on an OBIDMS. + * @param column_name The name of the column. + * @param version_number The version of the column that should be opened (if -1, the latest version is retrieved). * - * @return a pointer to the opened column + * @returns A pointer on the opened column structure. + * @retval NULL if an error occurred. * * @since July 2015 * @author Celine Mercier (celine.mercier@metabarcoding.org) @@ -165,12 +195,13 @@ OBIDMS_column_p obi_open_column(OBIDMS_p dms, const char* column_name, obiversio /** * @brief Clones a column, and returns a pointer to the writable new column. * - * @param dms a pointer on an OBIDMS - * @param column_name the name of the column to clone - * @param version_number the version of the column that should be cloned (if -1, the latest version number is retrieved) - * @param clone_data whether the data should be copied or not + * @param dms A pointer on an OBIDMS. + * @param column_name The name of the column to clone. + * @param version_number The version of the column that should be cloned (if -1, the latest version is retrieved). + * @param clone_data Whether the data should be copied or not. * - * @return a pointer to the created column + * @returns A pointer to the created column. + * @retval NULL if an error occurred. * * @since August 2015 * @author Celine Mercier (celine.mercier@metabarcoding.org) @@ -181,10 +212,10 @@ OBIDMS_column_p obi_clone_column(OBIDMS_p dms, const char* column_name, obiversi /** * @brief Closes a column. * - * @param column a pointer on an OBIDMS column + * @param column A pointer on an OBIDMS column. * - * @return 0 if the operation was successfully completed - * @return -1 if an error occurred + * @retval 0 if the operation was successfully completed. + * @retval -1 if an error occurred. * * @since July 2015 * @author Celine Mercier (celine.mercier@metabarcoding.org) @@ -193,12 +224,13 @@ int obi_close_column(OBIDMS_column_p column); /** - * @brief Truncates a column file to the number of lines used. + * @brief Truncates a column file to the number of lines used rounded to the nearest + * greater multiple of the page size. * - * @param column a pointer on an OBIDMS column + * @param column A pointer on an OBIDMS column. * - * @return 0 if the operation was successfully completed - * @return -1 if an error occurred + * @retval 0 if the operation was successfully completed. + * @retval -1 if an error occurred. * * @since August 2015 * @author Celine Mercier (celine.mercier@metabarcoding.org) @@ -209,10 +241,10 @@ int obi_truncate_column_to_lines_used(OBIDMS_column_p column); /** * @brief Enlarges a column file. * - * @param column a pointer on an OBIDMS column + * @param column A pointer on an OBIDMS column. * - * @return 0 if the operation was successfully completed - * @return -1 if an error occurred + * @retval 0 if the operation was successfully completed. + * @retval -1 if an error occurred. * * @since August 2015 * @author Celine Mercier (celine.mercier@metabarcoding.org) @@ -221,12 +253,13 @@ int obi_enlarge_column(OBIDMS_column_p column); /** - * @brief Truncates a column file to the number of lines used and closes it. + * @brief Truncates a column file to the number of lines used rounded to the nearest + * greater multiple of the page size and closes it. * - * @param column a pointer on an OBIDMS column + * @param column A pointer on an OBIDMS column. * - * @return 0 if the operation was successfully completed - * @return -1 if an error occurred + * @retval 0 if the operation was successfully completed. + * @retval -1 if an error occurred. * * @since August 2015 * @author Celine Mercier (celine.mercier@metabarcoding.org) @@ -235,11 +268,11 @@ int obi_truncate_and_close_column(OBIDMS_column_p column); /* - * @brief Sets the data in a column to the NA value of the data type. + * @brief Sets the data in a column to the NA value of the data OBIType. * - * @param column a pointer on an OBIDMS column - * @param start the first line number of the block that should be set - * @param nb_lines the number of lines that should be set + * @param column A pointer on an OBIDMS column. + * @param start The first line number of the block that should be set. + * @param nb_lines The number of lines that should be set. * * @since August 2015 * @author Celine Mercier (celine.mercier@metabarcoding.org) @@ -248,9 +281,9 @@ void obi_ini_to_NA_values(OBIDMS_column_p column, size_t start, size_t nb_lines) /** - * @brief Sets the 'writable' header attribute of an OBIDMS column to False. + * @brief Sets the 'writable' header attribute of an OBIDMS column to False. // TODO delete? * - * @param column a pointer on an OBIDMS column + * @param column A pointer on an OBIDMS column * * @since July 2015 * @author Celine Mercier (celine.mercier@metabarcoding.org) @@ -261,9 +294,9 @@ void obi_column_make_unwritable(OBIDMS_column_p column); /** * @brief Recovers the line count of an OBIDMS column. * - * @param column a pointer on an OBIDMS column + * @param column A pointer on an OBIDMS column. * - * @return the line count of the column + * @returns The line count of the column. * * @since July 2015 * @author Celine Mercier (celine.mercier@metabarcoding.org) @@ -274,9 +307,9 @@ size_t obi_column_get_line_count(OBIDMS_column_p column); /** * @brief Recovers the number of lines used in an OBIDMS column. * - * @param column a pointer on an OBIDMS column + * @param column A pointer on an OBIDMS column. * - * @return the number of lines used in the column + * @returns The number of lines used in the column. * * @since August 2015 * @author Celine Mercier (celine.mercier@metabarcoding.org) @@ -287,9 +320,9 @@ size_t obi_column_get_nb_lines_used(OBIDMS_column_p column); /** * @brief Recovers the data type of an OBIDMS column. * - * @param column a pointer on an OBIDMS column + * @param column A pointer on an OBIDMS column. * - * @return the data type of the column + * @returns The data type of the column. * * @since July 2015 * @author Celine Mercier (celine.mercier@metabarcoding.org) @@ -300,10 +333,10 @@ OBIType_t obi_column_get_data_type(OBIDMS_column_p column); /** * @brief Recovers the data type of an OBIDMS column from the column name. * - * @param dms a pointer on an OBIDMS - * @param column_name the name of an OBIDMS column + * @param dms A pointer on an OBIDMS. + * @param column_name The name of an OBIDMS column. * - * @return the data type of the column + * @returns The data type of the column. * * @since July 2015 * @author Celine Mercier (celine.mercier@metabarcoding.org) @@ -314,10 +347,10 @@ OBIType_t obi_column_get_data_type_from_name(OBIDMS_p dms, const char* column_na /** * @brief Recovers the line count of an OBIDMS column from the column name. * - * @param dms a pointer on an OBIDMS - * @param column_name the name of an OBIDMS column + * @param dms A pointer on an OBIDMS. + * @param column_name The name of an OBIDMS column. * - * @return the line count of the column + * @returns The line count of the column. * * @since September 2015 * @author Celine Mercier (celine.mercier@metabarcoding.org) @@ -328,9 +361,9 @@ size_t obi_column_get_line_count_from_name(OBIDMS_p dms, const char* column_name /** * @brief Recovers the elements names of an OBIDMS column. * - * @param column a pointer on an OBIDMS column + * @param column A pointer on an OBIDMS column. * - * @return the elements names + * @returns The elements names. * * @since July 2015 * @author Celine Mercier (celine.mercier@metabarcoding.org) @@ -339,12 +372,13 @@ const char* obi_column_get_elements_names(OBIDMS_column_p column); /** - * @brief Recovers the index of an element in an OBIDMS column from its name. + * @brief Recovers the index of an element in an OBIDMS column from the element's name. * - * @param column a pointer on an OBIDMS column - * @param element_name the name of the element + * @param column A pointer on an OBIDMS column. + * @param element_name The name of the element. * - * @return the index of the element in a line of the column + * @returns The index of the element in a line of the column. + * @retval SIZE_MAX if an error occurred. * * @since July 2015 * @author Celine Mercier (celine.mercier@metabarcoding.org) @@ -355,9 +389,9 @@ size_t obi_column_get_element_index_from_name(OBIDMS_column_p column, const char /** * @brief Recovers the number of elements per line in an OBIDMS column. * - * @param column a pointer on an OBIDMS column + * @param column A pointer on an OBIDMS column. * - * @return the number of elements per line + * @returns The number of elements per line * * @since July 2015 * @author Celine Mercier (celine.mercier@metabarcoding.org) diff --git a/src/obidmscolumn_bool.c b/src/obidmscolumn_bool.c index d9b1d92..e4d8487 100644 --- a/src/obidmscolumn_bool.c +++ b/src/obidmscolumn_bool.c @@ -1,5 +1,5 @@ /**************************************************************************** - * OBIDMS_column_bool functions * + * OBIDMS_column_bool functions * ****************************************************************************/ /** @@ -19,7 +19,7 @@ #include "obidebug.h" -#define DEBUG_LEVEL 0 +#define DEBUG_LEVEL 0 // TODO has to be defined somewhere else (cython compil flag?) /********************************************************************** @@ -69,7 +69,7 @@ obibool_t obi_column_get_obibool_with_elt_idx(OBIDMS_column_p column, size_t lin } -int obi_column_set_obibool_with_elt_name(OBIDMS_column_p column, size_t line_nb, char* element_name, obibool_t value) +int obi_column_set_obibool_with_elt_name(OBIDMS_column_p column, size_t line_nb, const char* element_name, obibool_t value) { size_t element_idx; @@ -87,7 +87,7 @@ int obi_column_set_obibool_with_elt_name(OBIDMS_column_p column, size_t line_nb, else { element_idx = obi_column_get_element_index_from_name(column, element_name); - if (element_idx == -1) + if (element_idx == SIZE_MAX) //TODO return -1; } @@ -97,7 +97,7 @@ int obi_column_set_obibool_with_elt_name(OBIDMS_column_p column, size_t line_nb, } -obibool_t obi_column_get_obibool_with_elt_name(OBIDMS_column_p column, size_t line_nb, char* element_name) +obibool_t obi_column_get_obibool_with_elt_name(OBIDMS_column_p column, size_t line_nb, const char* element_name) { size_t element_idx; @@ -115,7 +115,7 @@ obibool_t obi_column_get_obibool_with_elt_name(OBIDMS_column_p column, size_t li else { element_idx = obi_column_get_element_index_from_name(column, element_name); - if (element_idx == -1) + if (element_idx == SIZE_MAX) //TODO return OBIBool_NA; } diff --git a/src/obidmscolumn_bool.h b/src/obidmscolumn_bool.h index 928a7f6..1b48416 100644 --- a/src/obidmscolumn_bool.h +++ b/src/obidmscolumn_bool.h @@ -10,6 +10,10 @@ */ +#ifndef OBIDMSCOLUMN_BOOL_H_ +#define OBIDMSCOLUMN_BOOL_H_ + + #include #include @@ -20,19 +24,16 @@ /** * @brief Sets a value in an OBIDMS column containing data with the type OBI_BOOL, using the index of the element in the line. * - * @param column a pointer as returned by obi_create_column() * @warning Pointers returned by obi_open_column() don't allow writing. * - * @param line_nb the number of the line where the value should be set + * @param column A pointer as returned by obi_create_column() or obi_clone_column(). + * @param line_nb The number of the line where the value should be set. + * @param element_idx The index of the element that should be set in the line. + * @param value The value that should be set. * - * @param element_idx the index of the element that should be set in the line - * - * @param value the value that should be set - * - * @return an integer value indicating the success of the operation. - * - * @retvalue 0 on success - * @retvalue -1 on failure and the `obi_errno` variable is set. + * @returns An integer value indicating the success of the operation. + * @retvalue 0 on success. + * @retvalue -1 if an error occurred. * * @since July 2015 * @author Celine Mercier (celine.mercier@metabarcoding.org) @@ -43,13 +44,12 @@ int obi_column_set_obibool_with_elt_idx(OBIDMS_column_p column, size_t line_nb, /** * @brief Recovers a value in an OBIDMS column containing data with the type OBI_BOOL. * - * @param column a pointer as returned by obi_create_column() + * @param column A pointer as returned by obi_create_column(). + * @param line_nb The number of the line where the value should be recovered. + * @param element_idx The index of the element that should be recovered in the line. * - * @param line_nb the number of the line where the value should be recovered - * - * @param element_idx the index of the element that should be recovered in the line - * - * @return the recovered value + * @returns The recovered value. + * @retval OBIBool_NA the NA value of the type if an error occurred and obi_errno is set. * * @since July 2015 * @author Celine Mercier (celine.mercier@metabarcoding.org) @@ -58,44 +58,44 @@ obibool_t obi_column_get_obibool_with_elt_idx(OBIDMS_column_p column, size_t lin /** - * @brief Sets a value in an OBIDMS column containing data with the type OBI_BOOL, using the name of the element in the line. + * @brief Sets a value in an OBIDMS column containing data with the type OBI_BOOL, + * using the name of the element in the line. * - * @param column a pointer as returned by obi_create_column() * @warning Pointers returned by obi_open_column() don't allow writing. * - * @param line_nb the number of the line where the value should be set + * @param column A pointer as returned by obi_create_column() or obi_clone_column(). + * @param line_nb The number of the line where the value should be set. + * @param element_name The name of the element that should be set in the line. + * If empty, it is checked that there is only one element per line. + * @param value The value that should be set. * - * @param element_name the name of the element that should be set in the line - * If empty, it is checked that there is only one element per line - * - * @param value the value that should be set - * - * @return an integer value indicating the success of the operation. - * - * @retvalue 0 on success - * @retvalue -1 on failure and the `obi_errno` variable is set. + * @returns An integer value indicating the success of the operation. + * @retval 0 on success. + * @retvalue -1 if an error occurred. * * @since August 2015 * @author Celine Mercier (celine.mercier@metabarcoding.org) */ -int obi_column_set_obibool_with_elt_name(OBIDMS_column_p column, size_t line_nb, char* element_name, obibool_t value); +int obi_column_set_obibool_with_elt_name(OBIDMS_column_p column, size_t line_nb, const char* element_name, obibool_t value); /** - * @brief Recovers a value in an OBIDMS column containing data with the type OBI_BOOL, using the name of the element in the line. + * @brief Recovers a value in an OBIDMS column containing data with the type OBI_BOOL, + * using the name of the element in the line. * - * @param column a pointer as returned by obi_create_column() + * @param column A pointer as returned by obi_create_column() or obi_clone_column(). + * @param line_nb The number of the line where the value should be recovered. + * @param element_name The name of the element that should be recovered in the line. + * If empty, it is checked that there is only one element per line. * - * @param line_nb the number of the line where the value should be recovered - * - * @param element_name the name of the element that should be recovered in the line - * If empty, it is checked that there is only one element per line - * - * @return the recovered value - * @retvalue -1 on failure and the `obi_errno` variable is set. TODO an other value must be chosen + * @returns The recovered value. + * @retval OBIBool_NA the NA value of the type if an error occurred and obi_errno is set. * * @since August 2015 * @author Celine Mercier (celine.mercier@metabarcoding.org) */ -obibool_t obi_column_get_obibool_with_elt_name(OBIDMS_column_p column, size_t line_nb, char* element_name); +obibool_t obi_column_get_obibool_with_elt_name(OBIDMS_column_p column, size_t line_nb, const char* element_name); + + +#endif /* OBIDMSCOLUMN_BOOL_H_ */ diff --git a/src/obidmscolumn_char.c b/src/obidmscolumn_char.c index 6071dbb..4b99870 100644 --- a/src/obidmscolumn_char.c +++ b/src/obidmscolumn_char.c @@ -19,7 +19,7 @@ #include "obidebug.h" -#define DEBUG_LEVEL 0 +#define DEBUG_LEVEL 0 // TODO has to be defined somewhere else (cython compil flag?) /********************************************************************** @@ -70,7 +70,7 @@ obichar_t obi_column_get_obichar_with_elt_idx(OBIDMS_column_p column, size_t lin } -int obi_column_set_obichar_with_elt_name(OBIDMS_column_p column, size_t line_nb, char* element_name, obichar_t value) +int obi_column_set_obichar_with_elt_name(OBIDMS_column_p column, size_t line_nb, const char* element_name, obichar_t value) { size_t element_idx; @@ -88,7 +88,7 @@ int obi_column_set_obichar_with_elt_name(OBIDMS_column_p column, size_t line_nb, else { element_idx = obi_column_get_element_index_from_name(column, element_name); - if (element_idx == -1) + if (element_idx == SIZE_MAX) //TODO return -1; } @@ -98,7 +98,7 @@ int obi_column_set_obichar_with_elt_name(OBIDMS_column_p column, size_t line_nb, } -obichar_t obi_column_get_obichar_with_elt_name(OBIDMS_column_p column, size_t line_nb, char* element_name) +obichar_t obi_column_get_obichar_with_elt_name(OBIDMS_column_p column, size_t line_nb, const char* element_name) { size_t element_idx; @@ -116,7 +116,7 @@ obichar_t obi_column_get_obichar_with_elt_name(OBIDMS_column_p column, size_t li else { element_idx = obi_column_get_element_index_from_name(column, element_name); - if (element_idx == -1) + if (element_idx == SIZE_MAX) //TODO return OBIChar_NA; } diff --git a/src/obidmscolumn_char.h b/src/obidmscolumn_char.h index 96089b8..ecebf21 100644 --- a/src/obidmscolumn_char.h +++ b/src/obidmscolumn_char.h @@ -10,6 +10,10 @@ */ +#ifndef OBIDMSCOLUMN_CHAR_H_ +#define OBIDMSCOLUMN_CHAR_H_ + + #include #include @@ -20,82 +24,78 @@ /** * @brief Sets a value in an OBIDMS column containing data with the type OBI_CHAR, using the index of the element in the line. * - * @param column a pointer as returned by obi_create_column() * @warning Pointers returned by obi_open_column() don't allow writing. * - * @param line_nb the number of the line where the value should be set + * @param column A pointer as returned by obi_create_column() or obi_clone_column(). + * @param line_nb The number of the line where the value should be set. + * @param element_idx The index of the element that should be set in the line. + * @param value The value that should be set. * - * @param element_idx the index of the element that should be set in the line - * - * @param value the value that should be set - * - * @return an integer value indicating the success of the operation. - * - * @retvalue 0 on success - * @retvalue -1 on failure and the `obi_errno` variable is set. + * @returns An integer value indicating the success of the operation. + * @retvalue 0 on success. + * @retvalue -1 if an error occurred. * * @since July 2015 * @author Celine Mercier (celine.mercier@metabarcoding.org) */ -int obi_column_set_obichar_with_elt_idx(OBIDMS_column_p column, size_t line_nb, size_t element_idx, obichar_t* value); +int obi_column_set_obichar_with_elt_idx(OBIDMS_column_p column, size_t line_nb, size_t element_idx, obichar_t value); /** * @brief Recovers a value in an OBIDMS column containing data with the type OBI_CHAR. * - * @param column a pointer as returned by obi_create_column() + * @param column A pointer as returned by obi_create_column(). + * @param line_nb The number of the line where the value should be recovered. + * @param element_idx The index of the element that should be recovered in the line. * - * @param line_nb the number of the line where the value should be recovered - * - * @param element_idx the index of the element that should be recovered in the line - * - * @return the recovered value + * @returns The recovered value. + * @retval OBIBool_NA the NA value of the type if an error occurred and obi_errno is set. * * @since July 2015 * @author Celine Mercier (celine.mercier@metabarcoding.org) */ -obichar_t* obi_column_get_obichar_with_elt_idx(OBIDMS_column_p column, size_t line_nb, size_t element_idx); +obichar_t obi_column_get_obichar_with_elt_idx(OBIDMS_column_p column, size_t line_nb, size_t element_idx); /** - * @brief Sets a value in an OBIDMS column containing data with the type OBI_CHAR, using the name of the element in the line. + * @brief Sets a value in an OBIDMS column containing data with the type OBI_CHAR, + * using the name of the element in the line. * - * @param column a pointer as returned by obi_create_column() * @warning Pointers returned by obi_open_column() don't allow writing. * - * @param line_nb the number of the line where the value should be set + * @param column A pointer as returned by obi_create_column() or obi_clone_column(). + * @param line_nb The number of the line where the value should be set. + * @param element_name The name of the element that should be set in the line. + * If empty, it is checked that there is only one element per line. + * @param value The value that should be set. * - * @param element_name the name of the element that should be set in the line - * If empty, it is checked that there is only one element per line - * - * @param value the value that should be set - * - * @return an integer value indicating the success of the operation. - * - * @retvalue 0 on success - * @retvalue -1 on failure and the `obi_errno` variable is set. + * @returns An integer value indicating the success of the operation. + * @retval 0 on success. + * @retvalue -1 if an error occurred. * * @since August 2015 * @author Celine Mercier (celine.mercier@metabarcoding.org) */ -int obi_column_set_obichar_with_elt_name(OBIDMS_column_p column, size_t line_nb, char* element_name, obichar_t value); +int obi_column_set_obichar_with_elt_name(OBIDMS_column_p column, size_t line_nb, const char* element_name, obichar_t value); /** - * @brief Recovers a value in an OBIDMS column containing data with the type OBI_CHAR, using the name of the element in the line. + * @brief Recovers a value in an OBIDMS column containing data with the type OBI_CHAR, + * using the name of the element in the line. * - * @param column a pointer as returned by obi_create_column() + * @param column A pointer as returned by obi_create_column() or obi_clone_column(). + * @param line_nb The number of the line where the value should be recovered. + * @param element_name The name of the element that should be recovered in the line. + * If empty, it is checked that there is only one element per line. * - * @param line_nb the number of the line where the value should be recovered - * - * @param element_name the name of the element that should be recovered in the line - * If empty, it is checked that there is only one element per line - * - * @return the recovered value - * @retvalue NULL on failure and the `obi_errno` variable is set. TODO an other value should be chosen maybe + * @returns The recovered value. + * @retval OBIBool_NA the NA value of the type if an error occurred and obi_errno is set. * * @since August 2015 * @author Celine Mercier (celine.mercier@metabarcoding.org) */ -obichar_t obi_column_get_obichar_with_elt_name(OBIDMS_column_p column, size_t line_nb, char* element_name); +obichar_t obi_column_get_obichar_with_elt_name(OBIDMS_column_p column, size_t line_nb, const char* element_name); + + +#endif /* OBIDMSCOLUMN_CHAR_H_ */ diff --git a/src/obidmscolumn_float.c b/src/obidmscolumn_float.c index 9019a0a..50e26db 100644 --- a/src/obidmscolumn_float.c +++ b/src/obidmscolumn_float.c @@ -19,7 +19,7 @@ #include "obidebug.h" -#define DEBUG_LEVEL 0 +#define DEBUG_LEVEL 0 // TODO has to be defined somewhere else (cython compil flag?) /********************************************************************** @@ -69,7 +69,7 @@ obifloat_t obi_column_get_obifloat_with_elt_idx(OBIDMS_column_p column, size_t l } -int obi_column_set_obifloat_with_elt_name(OBIDMS_column_p column, size_t line_nb, char* element_name, obifloat_t value) +int obi_column_set_obifloat_with_elt_name(OBIDMS_column_p column, size_t line_nb, const char* element_name, obifloat_t value) { size_t element_idx; @@ -87,7 +87,7 @@ int obi_column_set_obifloat_with_elt_name(OBIDMS_column_p column, size_t line_nb else { element_idx = obi_column_get_element_index_from_name(column, element_name); - if (element_idx == -1) + if (element_idx == SIZE_MAX) //TODO return -1; } @@ -97,7 +97,7 @@ int obi_column_set_obifloat_with_elt_name(OBIDMS_column_p column, size_t line_nb } -obifloat_t obi_column_get_obifloat_with_elt_name(OBIDMS_column_p column, size_t line_nb, char* element_name) +obifloat_t obi_column_get_obifloat_with_elt_name(OBIDMS_column_p column, size_t line_nb, const char* element_name) { size_t element_idx; @@ -115,7 +115,7 @@ obifloat_t obi_column_get_obifloat_with_elt_name(OBIDMS_column_p column, size_t else { element_idx = obi_column_get_element_index_from_name(column, element_name); - if (element_idx == -1) + if (element_idx == SIZE_MAX) //TODO return OBIFloat_NA; } diff --git a/src/obidmscolumn_float.h b/src/obidmscolumn_float.h index 13de51f..a1d59ff 100644 --- a/src/obidmscolumn_float.h +++ b/src/obidmscolumn_float.h @@ -10,6 +10,10 @@ */ +#ifndef OBIDMSCOLUMN_FLOAT_H_ +#define OBIDMSCOLUMN_FLOAT_H_ + + #include #include @@ -20,19 +24,16 @@ /** * @brief Sets a value in an OBIDMS column containing data with the type OBI_FLOAT, using the index of the element in the line. * - * @param column a pointer as returned by obi_create_column() * @warning Pointers returned by obi_open_column() don't allow writing. * - * @param line_nb the number of the line where the value should be set + * @param column A pointer as returned by obi_create_column() or obi_clone_column(). + * @param line_nb The number of the line where the value should be set. + * @param element_idx The index of the element that should be set in the line. + * @param value The value that should be set. * - * @param element_idx the index of the element that should be set in the line - * - * @param value the value that should be set - * - * @return an integer value indicating the success of the operation. - * - * @retvalue 0 on success - * @retvalue -1 on failure and the `obi_errno` variable is set. + * @returns An integer value indicating the success of the operation. + * @retvalue 0 on success. + * @retvalue -1 if an error occurred. * * @since July 2015 * @author Celine Mercier (celine.mercier@metabarcoding.org) @@ -43,13 +44,12 @@ int obi_column_set_obifloat_with_elt_idx(OBIDMS_column_p column, size_t line_nb, /** * @brief Recovers a value in an OBIDMS column containing data with the type OBI_FLOAT. * - * @param column a pointer as returned by obi_create_column() + * @param column A pointer as returned by obi_create_column(). + * @param line_nb The number of the line where the value should be recovered. + * @param element_idx The index of the element that should be recovered in the line. * - * @param line_nb the number of the line where the value should be recovered - * - * @param element_idx the index of the element that should be recovered in the line - * - * @return the recovered value + * @returns The recovered value. + * @retval OBIBool_NA the NA value of the type if an error occurred and obi_errno is set. * * @since July 2015 * @author Celine Mercier (celine.mercier@metabarcoding.org) @@ -58,44 +58,44 @@ obifloat_t obi_column_get_obifloat_with_elt_idx(OBIDMS_column_p column, size_t l /** - * @brief Sets a value in an OBIDMS column containing data with the type OBI_FLOAT, using the name of the element in the line. + * @brief Sets a value in an OBIDMS column containing data with the type OBI_FLOAT, + * using the name of the element in the line. * - * @param column a pointer as returned by obi_create_column() * @warning Pointers returned by obi_open_column() don't allow writing. * - * @param line_nb the number of the line where the value should be set + * @param column A pointer as returned by obi_create_column() or obi_clone_column(). + * @param line_nb The number of the line where the value should be set. + * @param element_name The name of the element that should be set in the line. + * If empty, it is checked that there is only one element per line. + * @param value The value that should be set. * - * @param element_name the name of the element that should be set in the line - * If empty, it is checked that there is only one element per line - * - * @param value the value that should be set - * - * @return an integer value indicating the success of the operation. - * - * @retvalue 0 on success - * @retvalue -1 on failure and the `obi_errno` variable is set. + * @returns An integer value indicating the success of the operation. + * @retval 0 on success. + * @retvalue -1 if an error occurred. * * @since August 2015 * @author Celine Mercier (celine.mercier@metabarcoding.org) */ -int obi_column_set_obifloat_with_elt_name(OBIDMS_column_p column, size_t line_nb, char* element_name, obifloat_t value); +int obi_column_set_obifloat_with_elt_name(OBIDMS_column_p column, size_t line_nb, const char* element_name, obifloat_t value); /** - * @brief Recovers a value in an OBIDMS column containing data with the type OBI_FLOAT, using the name of the element in the line. + * @brief Recovers a value in an OBIDMS column containing data with the type OBI_FLOAT, + * using the name of the element in the line. * - * @param column a pointer as returned by obi_create_column() + * @param column A pointer as returned by obi_create_column() or obi_clone_column(). + * @param line_nb The number of the line where the value should be recovered. + * @param element_name The name of the element that should be recovered in the line. + * If empty, it is checked that there is only one element per line. * - * @param line_nb the number of the line where the value should be recovered - * - * @param element_name the name of the element that should be recovered in the line - * If empty, it is checked that there is only one element per line - * - * @return the recovered value - * @retvalue -1 on failure and the `obi_errno` variable is set. TODO an other value must be chosen + * @returns The recovered value. + * @retval OBIBool_NA the NA value of the type if an error occurred and obi_errno is set. * * @since August 2015 * @author Celine Mercier (celine.mercier@metabarcoding.org) */ -obifloat_t obi_column_get_obifloat_with_elt_name(OBIDMS_column_p column, size_t line_nb, char* element_name); +obifloat_t obi_column_get_obifloat_with_elt_name(OBIDMS_column_p column, size_t line_nb, const char* element_name); + + +#endif /* OBIDMSCOLUMN_FLOAT_H_ */ diff --git a/src/obidmscolumn_idx.c b/src/obidmscolumn_idx.c index cb8d682..c9569e3 100644 --- a/src/obidmscolumn_idx.c +++ b/src/obidmscolumn_idx.c @@ -19,7 +19,7 @@ #include "obidebug.h" -#define DEBUG_LEVEL 0 +#define DEBUG_LEVEL 0 // TODO has to be defined somewhere else (cython compil flag?) /********************************************************************** @@ -69,7 +69,7 @@ obiidx_t obi_column_get_obiidx_with_elt_idx(OBIDMS_column_p column, size_t line_ } -int obi_column_set_obiidx_with_elt_name(OBIDMS_column_p column, size_t line_nb, char* element_name, obiidx_t value) +int obi_column_set_obiidx_with_elt_name(OBIDMS_column_p column, size_t line_nb, const char* element_name, obiidx_t value) { size_t element_idx; @@ -87,7 +87,7 @@ int obi_column_set_obiidx_with_elt_name(OBIDMS_column_p column, size_t line_nb, else { element_idx = obi_column_get_element_index_from_name(column, element_name); - if (element_idx == -1) + if (element_idx == SIZE_MAX) //TODO return -1; } @@ -97,7 +97,7 @@ int obi_column_set_obiidx_with_elt_name(OBIDMS_column_p column, size_t line_nb, } -obiidx_t obi_column_get_obiidx_with_elt_name(OBIDMS_column_p column, size_t line_nb, char* element_name) +obiidx_t obi_column_get_obiidx_with_elt_name(OBIDMS_column_p column, size_t line_nb, const char* element_name) { size_t element_idx; @@ -115,7 +115,7 @@ obiidx_t obi_column_get_obiidx_with_elt_name(OBIDMS_column_p column, size_t line else { element_idx = obi_column_get_element_index_from_name(column, element_name); - if (element_idx == -1) + if (element_idx == SIZE_MAX) //TODO return OBIIdx_NA; } diff --git a/src/obidmscolumn_idx.h b/src/obidmscolumn_idx.h index 86a69fa..6f339cc 100644 --- a/src/obidmscolumn_idx.h +++ b/src/obidmscolumn_idx.h @@ -10,6 +10,10 @@ */ +#ifndef OBIDMSCOLUMN_IDX_H_ +#define OBIDMSCOLUMN_IDX_H_ + + #include #include @@ -20,19 +24,16 @@ /** * @brief Sets a value in an OBIDMS column containing data with the type OBI_IDX, using the index of the element in the line. * - * @param column a pointer as returned by obi_create_column() * @warning Pointers returned by obi_open_column() don't allow writing. * - * @param line_nb the number of the line where the value should be set + * @param column A pointer as returned by obi_create_column() or obi_clone_column(). + * @param line_nb The number of the line where the value should be set. + * @param element_idx The index of the element that should be set in the line. + * @param value The value that should be set. * - * @param element_idx the index of the element that should be set in the line - * - * @param value the value that should be set - * - * @return an integer value indicating the success of the operation. - * - * @retvalue 0 on success - * @retvalue -1 on failure and the `obi_errno` variable is set. + * @returns An integer value indicating the success of the operation. + * @retvalue 0 on success. + * @retvalue -1 if an error occurred. * * @since July 2015 * @author Celine Mercier (celine.mercier@metabarcoding.org) @@ -43,13 +44,12 @@ int obi_column_set_obiidx_with_elt_idx(OBIDMS_column_p column, size_t line_nb, s /** * @brief Recovers a value in an OBIDMS column containing data with the type OBI_IDX. * - * @param column a pointer as returned by obi_create_column() + * @param column A pointer as returned by obi_create_column(). + * @param line_nb The number of the line where the value should be recovered. + * @param element_idx The index of the element that should be recovered in the line. * - * @param line_nb the number of the line where the value should be recovered - * - * @param element_idx the index of the element that should be recovered in the line - * - * @return the recovered value + * @returns The recovered value. + * @retval OBIBool_NA the NA value of the type if an error occurred and obi_errno is set. * * @since July 2015 * @author Celine Mercier (celine.mercier@metabarcoding.org) @@ -58,44 +58,44 @@ obiidx_t obi_column_get_obiidx_with_elt_idx(OBIDMS_column_p column, size_t line_ /** - * @brief Sets a value in an OBIDMS column containing data with the type OBI_IDX, using the name of the element in the line. + * @brief Sets a value in an OBIDMS column containing data with the type OBI_IDX, + * using the name of the element in the line. * - * @param column a pointer as returned by obi_create_column() * @warning Pointers returned by obi_open_column() don't allow writing. * - * @param line_nb the number of the line where the value should be set + * @param column A pointer as returned by obi_create_column() or obi_clone_column(). + * @param line_nb The number of the line where the value should be set. + * @param element_name The name of the element that should be set in the line. + * If empty, it is checked that there is only one element per line. + * @param value The value that should be set. * - * @param element_name the name of the element that should be set in the line - * If empty, it is checked that there is only one element per line - * - * @param value the value that should be set - * - * @return an integer value indicating the success of the operation. - * - * @retvalue 0 on success - * @retvalue -1 on failure and the `obi_errno` variable is set. + * @returns An integer value indicating the success of the operation. + * @retval 0 on success. + * @retvalue -1 if an error occurred. * * @since August 2015 * @author Celine Mercier (celine.mercier@metabarcoding.org) */ -int obi_column_set_obiidx_with_elt_name(OBIDMS_column_p column, size_t line_nb, char* element_name, obiidx_t value); +int obi_column_set_obiidx_with_elt_name(OBIDMS_column_p column, size_t line_nb, const char* element_name, obiidx_t value); /** - * @brief Recovers a value in an OBIDMS column containing data with the type OBI_IDX, using the name of the element in the line. + * @brief Recovers a value in an OBIDMS column containing data with the type OBI_IDX, + * using the name of the element in the line. * - * @param column a pointer as returned by obi_create_column() + * @param column A pointer as returned by obi_create_column() or obi_clone_column(). + * @param line_nb The number of the line where the value should be recovered. + * @param element_name The name of the element that should be recovered in the line. + * If empty, it is checked that there is only one element per line. * - * @param line_nb the number of the line where the value should be recovered - * - * @param element_name the name of the element that should be recovered in the line - * If empty, it is checked that there is only one element per line - * - * @return the recovered value - * @retvalue -1 on failure and the `obi_errno` variable is set. TODO an other value must be chosen + * @returns The recovered value. + * @retval OBIBool_NA the NA value of the type if an error occurred and obi_errno is set. * * @since August 2015 * @author Celine Mercier (celine.mercier@metabarcoding.org) */ -obiidx_t obi_column_get_obiidx_with_elt_name(OBIDMS_column_p column, size_t line_nb, char* element_name); +obiidx_t obi_column_get_obiidx_with_elt_name(OBIDMS_column_p column, size_t line_nb, const char* element_name); + + +#endif /* OBIDMSCOLUMN_IDX_H_ */ diff --git a/src/obidmscolumn_int.c b/src/obidmscolumn_int.c index 131e725..1c43a4a 100644 --- a/src/obidmscolumn_int.c +++ b/src/obidmscolumn_int.c @@ -19,7 +19,7 @@ #include "obidebug.h" -#define DEBUG_LEVEL 0 +#define DEBUG_LEVEL 0 // TODO has to be defined somewhere else (cython compil flag?) /********************************************************************** @@ -69,7 +69,7 @@ obiint_t obi_column_get_obiint_with_elt_idx(OBIDMS_column_p column, size_t line_ } -int obi_column_set_obiint_with_elt_name(OBIDMS_column_p column, size_t line_nb, char* element_name, obiint_t value) +int obi_column_set_obiint_with_elt_name(OBIDMS_column_p column, size_t line_nb, const char* element_name, obiint_t value) { size_t element_idx; @@ -87,7 +87,7 @@ int obi_column_set_obiint_with_elt_name(OBIDMS_column_p column, size_t line_nb, else { element_idx = obi_column_get_element_index_from_name(column, element_name); - if (element_idx == -1) + if (element_idx == SIZE_MAX) //TODO return -1; } @@ -97,7 +97,7 @@ int obi_column_set_obiint_with_elt_name(OBIDMS_column_p column, size_t line_nb, } -obiint_t obi_column_get_obiint_with_elt_name(OBIDMS_column_p column, size_t line_nb, char* element_name) +obiint_t obi_column_get_obiint_with_elt_name(OBIDMS_column_p column, size_t line_nb, const char* element_name) { size_t element_idx; @@ -115,7 +115,7 @@ obiint_t obi_column_get_obiint_with_elt_name(OBIDMS_column_p column, size_t line else { element_idx = obi_column_get_element_index_from_name(column, element_name); - if (element_idx == -1) + if (element_idx == SIZE_MAX) //TODO return OBIInt_NA; } diff --git a/src/obidmscolumn_int.h b/src/obidmscolumn_int.h index a3e64d2..cdff7f3 100644 --- a/src/obidmscolumn_int.h +++ b/src/obidmscolumn_int.h @@ -5,11 +5,15 @@ /** * @file obidsmcolumn_int.h * @author Celine Mercier - * @date July 21st 2015 + * @date August 10th 2015 * @brief Header file for the functions handling OBIColumns containing data with the OBIType OBI_INT. */ +#ifndef OBIDMSCOLUMN_INT_H_ +#define OBIDMSCOLUMN_INT_H_ + + #include #include @@ -20,19 +24,16 @@ /** * @brief Sets a value in an OBIDMS column containing data with the type OBI_INT, using the index of the element in the line. * - * @param column a pointer as returned by obi_create_column() * @warning Pointers returned by obi_open_column() don't allow writing. * - * @param line_nb the number of the line where the value should be set + * @param column A pointer as returned by obi_create_column() or obi_clone_column(). + * @param line_nb The number of the line where the value should be set. + * @param element_idx The index of the element that should be set in the line. + * @param value The value that should be set. * - * @param element_idx the index of the element that should be set in the line - * - * @param value the value that should be set - * - * @return an integer value indicating the success of the operation. - * - * @retvalue 0 on success - * @retvalue -1 on failure and the `obi_errno` variable is set. + * @returns An integer value indicating the success of the operation. + * @retvalue 0 on success. + * @retvalue -1 if an error occurred. * * @since July 2015 * @author Celine Mercier (celine.mercier@metabarcoding.org) @@ -43,13 +44,12 @@ int obi_column_set_obiint_with_elt_idx(OBIDMS_column_p column, size_t line_nb, s /** * @brief Recovers a value in an OBIDMS column containing data with the type OBI_INT. * - * @param column a pointer as returned by obi_create_column() + * @param column A pointer as returned by obi_create_column(). + * @param line_nb The number of the line where the value should be recovered. + * @param element_idx The index of the element that should be recovered in the line. * - * @param line_nb the number of the line where the value should be recovered - * - * @param element_idx the index of the element that should be recovered in the line - * - * @return the recovered value + * @returns The recovered value. + * @retval OBIBool_NA the NA value of the type if an error occurred and obi_errno is set. * * @since July 2015 * @author Celine Mercier (celine.mercier@metabarcoding.org) @@ -58,44 +58,44 @@ obiint_t obi_column_get_obiint_with_elt_idx(OBIDMS_column_p column, size_t line_ /** - * @brief Sets a value in an OBIDMS column containing data with the type OBI_INT, using the name of the element in the line. + * @brief Sets a value in an OBIDMS column containing data with the type OBI_INT, + * using the name of the element in the line. * - * @param column a pointer as returned by obi_create_column() * @warning Pointers returned by obi_open_column() don't allow writing. * - * @param line_nb the number of the line where the value should be set + * @param column A pointer as returned by obi_create_column() or obi_clone_column(). + * @param line_nb The number of the line where the value should be set. + * @param element_name The name of the element that should be set in the line. + * If empty, it is checked that there is only one element per line. + * @param value The value that should be set. * - * @param element_name the name of the element that should be set in the line - * If empty, it is checked that there is only one element per line - * - * @param value the value that should be set - * - * @return an integer value indicating the success of the operation. - * - * @retvalue 0 on success - * @retvalue -1 on failure and the `obi_errno` variable is set. + * @returns An integer value indicating the success of the operation. + * @retval 0 on success. + * @retvalue -1 if an error occurred. * * @since August 2015 * @author Celine Mercier (celine.mercier@metabarcoding.org) */ -int obi_column_set_obiint_with_elt_name(OBIDMS_column_p column, size_t line_nb, char* element_name, obiint_t value); +int obi_column_set_obiint_with_elt_name(OBIDMS_column_p column, size_t line_nb, const char* element_name, obiint_t value); /** - * @brief Recovers a value in an OBIDMS column containing data with the type OBI_INT, using the name of the element in the line. + * @brief Recovers a value in an OBIDMS column containing data with the type OBI_INT, + * using the name of the element in the line. * - * @param column a pointer as returned by obi_create_column() + * @param column A pointer as returned by obi_create_column() or obi_clone_column(). + * @param line_nb The number of the line where the value should be recovered. + * @param element_name The name of the element that should be recovered in the line. + * If empty, it is checked that there is only one element per line. * - * @param line_nb the number of the line where the value should be recovered - * - * @param element_name the name of the element that should be recovered in the line - * If empty, it is checked that there is only one element per line - * - * @return the recovered value - * @retvalue -1 on failure and the `obi_errno` variable is set. TODO an other value must be chosen + * @returns The recovered value. + * @retval OBIBool_NA the NA value of the type if an error occurred and obi_errno is set. * * @since August 2015 * @author Celine Mercier (celine.mercier@metabarcoding.org) */ -obiint_t obi_column_get_obiint_with_elt_name(OBIDMS_column_p column, size_t line_nb, char* element_name); +obiint_t obi_column_get_obiint_with_elt_name(OBIDMS_column_p column, size_t line_nb, const char* element_name); + + +#endif /* OBIDMSCOLUMN_INT_H_ */ diff --git a/src/obidmscolumndir.c b/src/obidmscolumndir.c index 6a347e2..850320b 100644 --- a/src/obidmscolumndir.c +++ b/src/obidmscolumndir.c @@ -4,7 +4,7 @@ /** * @file obidmscolumndir.c - * @author Celine Mercier + * @author Celine Mercier (celine.mercier@metabarcoding.org) * @date 18 June 2015 * @brief Functions for OBIDMS column directories. */ @@ -25,7 +25,7 @@ #include "obidebug.h" -#define DEBUG_LEVEL 0 +#define DEBUG_LEVEL 0 // TODO has to be defined somewhere else (cython compil flag?) /************************************************************************** @@ -43,15 +43,10 @@ * * @warning The returned pointer has to be freed by the caller. * - * @param column_name the name of the OBIDMS column + * @param column_name The name of the OBIDMS column. * - * @return a pointer to the OBIDMS column directory name - * @retvalue if everything is ok - * @retvalue NULL if an error occurs - * - * ###Error values - * - OBIDMS_MEMORY_ERROR : something wrong occurred during memory allocation. - * - OBIDMS_LONG_NAME_ERROR : the database name exceeds the limit. + * @returns A pointer to the OBIDMS column directory name. + * @retval NULL if an error occurred. * * @since June 2015 * @author Celine Mercier (celine.mercier@metabarcoding.org) @@ -78,10 +73,10 @@ static char* build_column_directory_name(const char* column_name) } // Test if the database name is not too long - if (strlen(column_directory_name) >= OBIDMS_COLUMN_DIR_MAX_NAME) + if (strlen(column_directory_name) >= OBIDMS_COLUMN_MAX_NAME) { obi_set_errno(OBICOLDIR_LONG_NAME_ERROR); - obidebug(1, "\nError building a column directory name"); + obidebug(1, "\nError due to column name too long"); free(column_directory_name); return NULL; } diff --git a/src/obidmscolumndir.h b/src/obidmscolumndir.h index 006e39b..8ed5045 100644 --- a/src/obidmscolumndir.h +++ b/src/obidmscolumndir.h @@ -6,57 +6,56 @@ * @file obidmscolumndir.h * @author Celine Mercier * @date 18 June 2015 - * @brief Header file for OBIDMS column directories. + * @brief Header file for the OBIDMS column directories structures and functions. */ + #ifndef OBIDMSCOLUMNGROUP_H_ #define OBIDMSCOLUMNGROUP_H_ + #include #include #include #include "obidms.h" -#define OBIDMS_MAX_COLNAME (128) /**< The maximum length of an OBIDMS column name - */ -#define OBIDMS_COLUMN_DIR_MAX_NAME (2048) /**< The maximum length of an OBIDMS column directory name - */ +#define OBIDMS_COLUMN_MAX_NAME (2048) /**< The maximum length of an OBIDMS column name. + */ -/** @brief A structure describing an OBIDMS column directory instance + +/** + * @brief A structure describing an OBIDMS column directory instance. * * A pointer to this structure is returned on creation * and opening of an OBIDMS column directory. */ - typedef struct OBIDMS_column_directory { - OBIDMS_p dms; /**< A pointer to a DMS instance. + OBIDMS_p dms; /**< A pointer to a DMS instance. */ - char column_name[OBIDMS_MAX_COLNAME+1]; /**< The name of the column - * contained in the directory. + char column_name[OBIDMS_COLUMN_MAX_NAME+1]; /**< The name of the column + * contained in the directory. */ - char directory_name[OBIDMS_COLUMN_DIR_MAX_NAME+1]; /**< The name of the directory - * containing the column. + char directory_name[OBIDMS_COLUMN_MAX_NAME+1]; /**< The name of the directory + * containing the column. */ - DIR* directory; /**< A directory entry usable to - * refer and scan the database directory. + DIR* directory; /**< A directory entry usable to + * refer and scan the database directory. */ } OBIDMS_column_directory_t, *OBIDMS_column_directory_p; -/*@ - * @brief Checks if an OBIDMS column directory exists +/** + * @brief Checks if an OBIDMS column directory exists. * - * @param dms a pointer to an OBIDMS as returned by obi_create_dms() or obi_open_dms() - * @param column_name a pointer to a C string containing the name of the column. - * The actual directory name used to store the column is - * `.obicol`. + * @param dms A pointer to an OBIDMS as returned by obi_create_dms() or obi_open_dms(). + * @param column_name A pointer to a C string containing the name of the column. * - * @return an integer value indicating the status of the column directory - * @retvalue 1 the directory exist - * @retvalue 0 the directory does not exist - * @retvalue -1 an error occurred + * @returns An integer value indicating the status of the column directory. + * @retval 1 if the directory exists. + * @retval 0 if the directory does not exist. + * @retval -1 if an error occurred. * * @see obi_close_column_directory() * @since June 2015 @@ -72,17 +71,14 @@ int obi_column_directory_exists(OBIDMS_p dms, const char* column_name); * if a directory with this name does not already exist * before creating the new column directory. * - * @param dms a pointer to an OBIDMS as returned by obi_create_dms() or obi_open_dms() - * @param column_name a pointer to a C string containing the name of the column. + * @param dms A pointer to an OBIDMS as returned by obi_create_dms() or obi_open_dms(). + * @param column_name A pointer to a C string containing the name of the column. * The actual directory name used to store the column will be * `.obicol`. * - * @return a pointer to an OBIDMS column directory structure describing the newly created - * directory - * @retval NULL on error and the `obi_errno` variable is set. - * - * ###Error values - * - OBIDMS_COL_DIR_EXIST_ERROR : xxxxx a database with the same name already exists. + * @returns A pointer to an OBIDMS column directory structure describing the newly created + * directory. + * @retval NULL if an error occurred. * * @see obi_close_column_directory() * @since June 2015 @@ -94,16 +90,13 @@ OBIDMS_column_directory_p obi_create_column_directory(OBIDMS_p dms, const char* /** * @brief Opens an existing OBIDMS column directory instance. * - * @param dms a pointer to an OBIDMS as returned by obi_create_dms() or obi_open_dms() - * @param column_name a pointer to a C string containing the name of the column. + * @param dms A pointer to an OBIDMS as returned by obi_create_dms() or obi_open_dms(). + * @param column_name A pointer to a C string containing the name of the column. * The actual directory name used to store the column is * `.obicol`. * - * @return a pointer to the OBIDMS column directory structure describing the directory - * @retval NULL on error and the `obi_errno`variable is set. - * - * ###Error values - * - OBIDMS_COL_DIR_ERROR : xxxxx a database with the same name already exists. + * @returns A pointer to the OBIDMS column directory structure describing the directory. + * @retval NULL if an error occurred. * * @see obi_close_column_directory() * @since June 2015 @@ -118,17 +111,13 @@ OBIDMS_column_directory_p obi_open_column_directory(OBIDMS_p dms, const char* co * If the directory already exists, this function opens it, otherwise it * creates a new column directory. * - * @param dms a pointer to an OBIDMS as returned by obi_create_dms() or obi_open_dms() - * @param column_name a pointer to a C string containing the name of the column. + * @param dms A pointer to an OBIDMS as returned by obi_create_dms() or obi_open_dms(). + * @param column_name A pointer to a C string containing the name of the column. * The actual directory name used to store the column is * `.obicol`. * - * @return a pointer to the OBIDMS column directory structure describing the directory - * @retval NULL on error and the `obi_errno`variable is set. - * - * ###Error values - * - OBIDMS_LONG_NAME_ERROR : the database name exceeds the limit. - * - OBIDMS_MEMORY_ERROR : something wrong occurred during memory allocation. + * @returns A pointer to the OBIDMS column directory structure describing the directory. + * @retval NULL if an error occurred. * * @since June 2015 * @author Celine Mercier (celine.mercier@metabarcoding.org) @@ -139,13 +128,13 @@ OBIDMS_column_directory_p obi_column_directory(OBIDMS_p dms, const char* column_ /** * @brief Closes an opened OBIDMS column directory instance. * - * @param column_directory a pointer to an OBIDMS column directory as returned by - * obi_create_column_directory() or obi_open_column_directory() + * @param column_directory A pointer to an OBIDMS column directory as returned by + * obi_create_column_directory() or obi_open_column_directory(). * - * @return an integer value indicating the success of the operation. Even on - * error, the `OBIDMS_column_directory` structure is freed - * @retvalue 0 on success - * @retvalue -1 on failure and the `obi_errno` variable is set. + * @returns An integer value indicating the success of the operation. Even on + * error, the `OBIDMS_column_directory` structure is freed. + * @retval 0 on success. + * @retval -1 if an error occurred. * * @see obi_create_column_directory() * @see obi_open_column_directory() diff --git a/src/obierrno.c b/src/obierrno.c index 9b9f00b..06eb768 100644 --- a/src/obierrno.c +++ b/src/obierrno.c @@ -1,8 +1,12 @@ -/* - * obierrno.c - * - * Created on: 23 mai 2015 - * Author: coissac +/**************************************************************************** + * Code for obi errnos * + ****************************************************************************/ + +/** + * @file obierrno.c + * @author Eric Coissac (eric.coissac@metabarcoding.org) + * @date 23 May 2015 + * @brief Code for obi errnos. */ diff --git a/src/obierrno.h b/src/obierrno.h index b8812f0..d0a5a95 100644 --- a/src/obierrno.h +++ b/src/obierrno.h @@ -1,20 +1,26 @@ -/* - * obierrno.h - * - * Created on: 23 mai 2015 - * Author: coissac +/**************************************************************************** + * Header file for obi errnos * + ****************************************************************************/ + +/** + * @file obierrno.h + * @author Eric Coissac (eric.coissac@metabarcoding.org) + * @date 23 May 2015 + * @brief Header file for obi errnos. */ + #ifndef OBIERRNO_H_ #define OBIERRNO_H_ + /** * @brief The declaration of the external variable `obi_errno`. * * `obi_errno` is an equivalent of `errno` for the system level error, - * but for errors generated by the C layer of the OBITools framework. + * but for errors generated by the C layer of the OBITools3 framework. * - * @todo We have to look into defining this variable as thread specific. + * @TODO We have to look into defining this variable as thread specific. */ extern int obi_errno; @@ -24,8 +30,8 @@ extern int obi_errno; * the specified `err` code * * This function is defined as a macro to reduce the risk - * of increasing the problem generating the error by calling - * a new function. + * of increasing the problem by generating another error by calling + * another function. * * @param err The error code as an integer value. * @@ -41,6 +47,8 @@ extern int obi_errno; * Error codes set in errno following an error related * to the manipulation of an OBIDMS. * + * @TODO + * * @{ */ #define OBIDMS_EXIST_ERROR (1) /**< Trying to create an OBIDMS with a name diff --git a/src/obilittlebigman.c b/src/obilittlebigman.c index 76dd025..3931dd8 100644 --- a/src/obilittlebigman.c +++ b/src/obilittlebigman.c @@ -1,8 +1,12 @@ -/* - * littlebigman.c - * - * Created on: 23 mai 2015 - * Author: coissac +/**************************************************************************** + * Code for endianness checking * + ****************************************************************************/ + +/** + * @file obilittlebigman.c + * @author Eric Coissac (eric.coissac@metabarcoding.org) + * @date 23 May 2015 + * @brief Code endianness checking. */ #include "obilittlebigman.h" diff --git a/src/obilittlebigman.h b/src/obilittlebigman.h index d43f1e6..da97d22 100644 --- a/src/obilittlebigman.h +++ b/src/obilittlebigman.h @@ -1,15 +1,22 @@ -/* - * littlebigman.h - * - * Created on: 23 mai 2015 - * Author: coissac +/**************************************************************************** + * Header file for endianness checking * + ****************************************************************************/ + +/** + * @file obilittlebigman.h + * @author Eric Coissac (eric.coissac@metabarcoding.org) + * @date 23 May 2015 + * @brief Header file for endianness checking. */ + #ifndef OBILITTLEBIGMAN_H_ #define OBILITTLEBIGMAN_H_ + #include + /** * Test if the architecture of the processor is little endian. * @@ -41,7 +48,7 @@ * In this architecture, the last address is * used to store the byte of lighter weight (LITTLE ENDian) * - * @return a `bool` value: + * @returns a `bool` value: * - `true` if the architecture is little endian * - `false` if the architecture is big endian * diff --git a/src/obitypes.c b/src/obitypes.c index 12b1fb1..c37e3a8 100644 --- a/src/obitypes.c +++ b/src/obitypes.c @@ -1,8 +1,12 @@ -/* - * obitypes.c - * - * Created on: 23 mai 2015 - * Author: coissac +/**************************************************************************** + * OBITypes functions * + ****************************************************************************/ + +/** + * @file obitypes.h + * @author Eric Coissac (eric.coissac@metabarcoding.org) + * @date 23 May 2015 + * @brief Functions for the handling of OBITypes. */ @@ -13,7 +17,7 @@ #include "obierrno.h" -#define DEBUG_LEVEL 0 +#define DEBUG_LEVEL 0 // TODO has to be defined somewhere else (cython compil flag?) size_t obi_sizeof(OBIType_t type) diff --git a/src/obitypes.h b/src/obitypes.h index dd09133..5fd9655 100644 --- a/src/obitypes.h +++ b/src/obitypes.h @@ -1,10 +1,15 @@ +/**************************************************************************** + * Header file for OBITypes * + ****************************************************************************/ + /** * @file obitypes.h - * @author Celine Mercier + * @author Celine Mercier (celine.mercier@metabarcoding.org) * @date 18 May 2015 - * @brief Header file for the OBITypes. + * @brief Header file for the handling of OBITypes. */ + #ifndef OBITYPES_H_ #define OBITYPES_H_ @@ -13,10 +18,11 @@ #include -#define OBIInt_NA (INT32_MIN) -#define OBIIdx_NA (SIZE_MAX) -#define OBIFloat_NA (float_NA()) -#define OBIChar_NA (0) // TODO not sure about this one as it can be impossible to distinguish from uninitialized values +#define OBIInt_NA (INT32_MIN) /**< NA value for the type OBI_INT */ +#define OBIIdx_NA (SIZE_MAX) /**< NA value for the type OBI_IDX */ +#define OBIFloat_NA (float_NA()) /**< NA value for the type OBI_FLOAT */ +#define OBIChar_NA (0) /**< NA value for the type OBI_CHAR */ + // TODO not sure about this one as it can be impossible to distinguish from uninitialized values /** @@ -48,6 +54,9 @@ typedef char obichar_t; typedef size_t obiidx_t; +/** + * @brief Union used to compute the NA value of the OBI_FLOAT OBIType. + */ typedef union { double value; @@ -55,7 +64,11 @@ typedef union } ieee_double; -static double float_NA(void) // as defined in R +/** + * @brief Returns the NA value of the OBI_FLOAT OBIType. + * This value corresponds to the float NA value as defined in R. + */ +static double float_NA(void) { volatile ieee_double x; x.word[0] = 0x7ff00000; @@ -65,12 +78,12 @@ static double float_NA(void) // as defined in R /** - * @brief returns the memory size in bytes of an OBIType + * @brief Returns the memory size in bytes of an OBIType. * - * @param type the OBIType code used as query + * @param type The OBIType code used as query. * - * @return the size in bytes of the type - * @retval 0 on error (unknown type) + * @returns The size in bytes of the type. + * @retval 0 if an error occurred (unknown type). * * @since May 2015 * @author Eric Coissac (eric.coissac@metabarcoding.org) @@ -79,31 +92,32 @@ size_t obi_sizeof(OBIType_t type); /** - * @brief returns the size requested to store an array of OBIType + * @brief Returns the size required to store an array of elements with an OBIType. * - * The returned size is large enough to store an array of size nbelement - * but rounded at a multiple of the memory page size. + * The returned size is large enough to store an array large enough + * to store all the elements but rounded at a multiple of the memory page size. // TODO this might be redundant but still a good thing * - * @param type the OBIType code used as query - * @param nbelement the number of elements to be stored + * @param data_type The OBIType of the elements. + * @param nb_lines The number of lines to be stored. + * @param nb_elements_per_line The number of elements per line. * - * @return the size in bytes of the array - * @retval 0 on error (unknown type) + * @returns The size in bytes of the array. + * @retval 0 if an error occurred (unknown type). * * @since May 2015 * @author Eric Coissac (eric.coissac@metabarcoding.org) */ -size_t obi_array_sizeof(OBIType_t type, size_t nbelements, size_t nb_elements_per_line); +size_t obi_array_sizeof(OBIType_t data_type, size_t nb_lines, size_t nb_elements_per_line); /** - * @brief returns the name in the form of a character string of an OBIType + * @brief Returns the name in the form of a character string of an OBIType. * * - * @param data_type the OBIType code used as query + * @param data_type The OBIType code used as query. * - * @return the name of the OBIType - * @retval NULL on error (unknown type or error allocating the memory for the character string) + * @returns The name of the OBIType. + * @retval NULL if an error occurred (unknown type or error allocating the memory for the character string). * * @since August 2015 * @author Celine Mercier (celine.mercier@metabarcoding.org) diff --git a/src/private_at_functions.c b/src/private_at_functions.c index 3383a5f..e06bd58 100644 --- a/src/private_at_functions.c +++ b/src/private_at_functions.c @@ -3,8 +3,8 @@ ****************************************************************************/ /** - * @file private_at_functions.h - * @author Celine Mercier + * @file private_at_functions.c + * @author Celine Mercier (celine.mercier@metabarcoding.org) * @date 15 June 2015 * @brief Private replacement functions for *at functions. */ @@ -23,14 +23,7 @@ #include "obierrno.h" -#define DEBUG_LEVEL 0 - - -/********************************************************************** - * - * D E F I N I T I O N O F T H E P U B L I C F U N C T I O N S - * - **********************************************************************/ +#define DEBUG_LEVEL 0 // TODO has to be defined somewhere else (cython compil flag?) char* get_full_path(int directory_file_descriptor, const char* path_name) @@ -77,39 +70,3 @@ DIR* private_opendirat(int directory_file_descriptor, const char* path_name) } -//int private_openat(int directory_file_descriptor, const char* path_name, int flags) -//{ -// char* full_path; -// int file_descriptor; -// -// full_path = get_full_path(directory_file_descriptor, path_name); -// if (full_path == NULL) -// return -1; -// -// file_descriptor = open(full_path, flags); -// -// free(full_path); -// -// return file_descriptor; -//} -// -// -//int private_mkdirat(int directory_file_descriptor, const char* path_name, mode_t mode) -//{ -// char* full_path; -// -// full_path = get_full_path(directory_file_descriptor, path_name); -// if (full_path == NULL) -// return -1; -// -// if (mkdir(full_path, mode) < 0) -// { -// free(full_path); -// return -1; -// } -// -// free(full_path); -// -// return 0; -//} - diff --git a/src/private_at_functions.h b/src/private_at_functions.h index f055fa2..d32a47b 100644 --- a/src/private_at_functions.h +++ b/src/private_at_functions.h @@ -1,10 +1,15 @@ +/**************************************************************************** + * Header file for private *at functions * + ****************************************************************************/ + /** - * @file private_openat.h - * @author Celine Mercier + * @file private_at_functions.h + * @author Celine Mercier (celine.mercier@metabarcoding.org) * @date 15 June 2015 - * @brief Header file for the replacement *at function. + * @brief Header file for the private replacement functions for *at functions. */ + #ifndef PRIVATE_OPENAT_H_ #define PRIVATE_OPENAT_H_ @@ -12,27 +17,22 @@ #include -#define MAX_PATH_LEN 4096 +#define MAX_PATH_LEN 4096 /**< Maximum length for the character string defining a + file or directory path */ /** - * Internal function getting the full path of a file or a directory from its - * path relative to a directory file descriptor. - * + * @brief Internal function getting the full path of a file or a directory from its + * path relative to a directory file descriptor. * * @warning The returned pointer has to be freed by the caller. * - * @param directory_file_descriptor the file descriptor for the directory to which - * path_name is relative - * @param path_name the path name for the file or directory, relative to directory_file_descriptor + * @param directory_file_descriptor The file descriptor for the directory to which + * path_name is relative. + * @param path_name The path name for the file or directory, relative to directory_file_descriptor. * - * @return a pointer to the full path - * @retvalue if everything is ok - * @retvalue NULL if an error occurs - * - * ###Error values - * - OBIDMS_MEMORY_ERROR : something wrong occurred during memory allocation. - * - OBIDMS_LONG_NAME_ERROR : the database name exceeds the limit. + * @returns A pointer to the full path. + * @retval NULL if an error occurs. * * @since June 2015 * @author Celine Mercier (celine.mercier@metabarcoding.org) @@ -43,10 +43,11 @@ char* get_full_path(int directory_file_descriptor, const char* path_name); /** * @brief Replacement function for opendirat() : open a directory relative to a directory file descriptor. * - * @param directory_file_descriptor the file descriptor for the directory in which the directory should be opened - * @param path_name the path name for the directory to be opened, relative to directory_file_descriptor + * @param directory_file_descriptor The file descriptor for the directory in which the directory should be opened. + * @param path_name The path name for the directory to be opened, relative to directory_file_descriptor. * - * @return the file descriptor of the opened directory + * @returns The file descriptor of the opened directory. + * @retval NULL if an error occurred. * * @since June 2015 * @author Celine Mercier (celine.mercier@metabarcoding.org) @@ -54,34 +55,4 @@ char* get_full_path(int directory_file_descriptor, const char* path_name); DIR* private_opendirat(int directory_file_descriptor, const char* path_name); -///** -// * @brief Replacement function for openat() : open a file relative to a directory file descriptor. -// * -// * @param directory_file_descriptor the file descriptor for the directory in which the file should be opened -// * @param path_name the path name for the file, relative to directory_file_descriptor -// * @param flags the access modes -// * -// * @return the file descriptor of the opened file -// * -// * @since June 2015 -// * @author Celine Mercier (celine.mercier@metabarcoding.org) -// */ -//int private_openat(int directory_file_descriptor, const char* path_name, int flags); -// -// -///** -// * @brief Replacement function for mkdirat() : create a directory relative to a directory file descriptor. -// * -// * @param directory_file_descriptor the file descriptor for the directory in which the directory should be created -// * @param path_name the path name for the new directory, relative to directory_file_descriptor -// * @param mode the access mode -// * -// * @return the file descriptor of the created directory -// * -// * @since June 2015 -// * @author Celine Mercier (celine.mercier@metabarcoding.org) -// */ -//int private_mkdirat(int directory_file_descriptor, const char* path_name, mode_t mode); - - #endif /* PRIVATEOPENAT_H_ */