/**************************************************************************** * OBIDMS columns header file * ****************************************************************************/ /** * @file obidmscolumn.h * @author Celine Mercier (celine.mercier@metabarcoding.org) * @date 12 May 2015 * @brief Header file for the functions and structures shared by all the OBIDMS columns. */ #ifndef OBIDMSCOLUMN_H_ #define OBIDMSCOLUMN_H_ #include #include #include #include #include #include #include "obidms.h" #include "obitypes.h" #include "obierrno.h" #include "obilittlebigman.h" #include "obidmscolumndir.h" #include "obiarray.h" #define ONE_IF_ZERO(x) (((x)==0)?1:(x)) /**< If x is equal to 0, x takes the value 1. */ #define ELEMENTS_NAMES_MAX (2048) /**< The maximum length of the list of elements names. */ #define COLUMN_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 */ #define FORMATTED_TIME_LENGTH (1024) /**< The length allocated for the character string containing a formatted date */ typedef int32_t obiversion_t; /**< Used to store the column version number */ /** * @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() */ size_t header_size; /**< Size of the header in bytes. */ index_t line_count; /**< Number of lines of data allocated. */ index_t lines_used; /**< Number of lines of data used. */ index_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 array_name[ARRAY_MAX_NAME+1]; /**< If there is one, the obi_array 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 OBIDMS column structure. * * A data structure of this type is returned by the functions * creating, opening or cloning an OBIDMS column. */ typedef struct OBIDMS_column { 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. */ OBIDMS_array_p array; /**< A pointer to the array associated with the column if there is one. */ 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 OBIDMS. */ bool writable; /**< Indicates if the column is writable or not. TODO delete? * - `true` the column is writable * - `false` the column is read-only * * A column is writable only by its creator * until it closes it. */ } OBIDMS_column_t, *OBIDMS_column_p; /** * @brief Returns the latest version number of a column in a column directory using the column directory structure. * * @param column_directory A pointer as returned by obi_create_column_directory() or obi_open_column_directory(). * * @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 using the column name. * * @param dms A pointer on an OBIDMS. * @param column_name The column name. * * @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); /** * @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. * As of now the header size is defined as one time the page size. * * @returns The header size in bytes. * * @since May 2015 * @author Eric Coissac (eric.coissac@metabarcoding.org) */ size_t obi_get_platform_header_size(); /** * @brief Creates a column. * * The minimum data size allocated is one memory page, and the data is initialized to the NA value of the OBIType. * If there is an array associated with the column, it is opened or created if it does not already exist. * * @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. * @param array_name The name of the array if there is one associated with the column. * * @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 data_type, index_t nb_lines, index_t nb_elements_per_line, const char* elements_names, const char* array_name); /** * @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 is retrieved). * * @returns A pointer on the opened column structure. * @retval NULL if an error occurred. * * @since July 2015 * @author Celine Mercier (celine.mercier@metabarcoding.org) */ OBIDMS_column_p obi_open_column(OBIDMS_p dms, const char* column_name, obiversion_t version_number); /** * @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 is retrieved). * @param clone_data Whether the data should be copied or not. * * @returns A pointer to the created column. * @retval NULL if an error occurred. * * @since August 2015 * @author Celine Mercier (celine.mercier@metabarcoding.org) */ OBIDMS_column_p obi_clone_column(OBIDMS_p dms, const char* column_name, obiversion_t version_number, bool clone_data); /** * @brief Closes a column. * * @param column A pointer on an OBIDMS column. * * @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_close_column(OBIDMS_column_p column); /** * @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. * * @retval 0 if the operation was successfully completed. * @retval -1 if an error occurred. * * @since August 2015 * @author Celine Mercier (celine.mercier@metabarcoding.org) */ int obi_truncate_column_to_lines_used(OBIDMS_column_p column); /** * @brief Enlarges a column file. * * @param column A pointer on an OBIDMS column. * * @retval 0 if the operation was successfully completed. * @retval -1 if an error occurred. * * @since August 2015 * @author Celine Mercier (celine.mercier@metabarcoding.org) */ int obi_enlarge_column(OBIDMS_column_p column); /** * @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. * * @retval 0 if the operation was successfully completed. * @retval -1 if an error occurred. * * @since August 2015 * @author Celine Mercier (celine.mercier@metabarcoding.org) */ int obi_truncate_and_close_column(OBIDMS_column_p column); /* * @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. * * @since August 2015 * @author Celine Mercier (celine.mercier@metabarcoding.org) */ void obi_ini_to_NA_values(OBIDMS_column_p column, index_t first_line_nb, index_t nb_lines); // TO make private? /** * @brief Recovers the header of an OBIDMS column from the column name. * * @warning The header structure has to be munmapped by the caller. * * @param dms A pointer on an OBIDMS. * @param column_name The name of an OBIDMS column. * * @returns A pointer on the mmapped header of the column. * @retval NULL if an error occurred. * * @since October 2015 * @author Celine Mercier (celine.mercier@metabarcoding.org) */ OBIDMS_column_header_p obi_column_get_header_from_name(OBIDMS_p dms, const char* column_name); /** * @brief Munmap a mmapped header as returned by obi_column_get_header_from_name(). * * @param header A pointer on the mmapped header structure. * * @retval 0 if the operation was successfully completed. * @retval -1 if an error occurred. * * @since October 2015 * @author Celine Mercier (celine.mercier@metabarcoding.org) */ int obi_unmap_header(OBIDMS_column_header_p header); /** * @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. * * @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) */ index_t obi_column_get_element_index_from_name(OBIDMS_column_p column, const char* element_name); /** * @brief Formats a date in a way that is easy to read. * * @warning The pointer returned must be freed by the caller. * * @param date A date. * * @returns The date formatted in a way that is easy to read. * * @since October 2015 * @author Celine Mercier (celine.mercier@metabarcoding.org) */ char* obi_column_format_date(time_t date); #endif /* OBIDMSCOLUMN_H_ */