/**************************************************************************** * OBIDMS_column header file * ****************************************************************************/ /** * @file obidmscolumn.h * @author Celine Mercier * @date 12 May 2015 * @brief Header file for the shared elements of all the OBIDMS column structures. */ #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" #define ELEMENTS_NAMES_MAX (2048) #define INITIAL_LINE_COUNT (1000) typedef int32_t obiversion_t; /**< Used to store the column version number */ /** * @brief OBIColumnHeader 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 */ } OBIDMS_column_header_t, *OBIDMS_column_header_p; /** * @brief Structure describing a Column of the OBITools DMS * * 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 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. * * @warning never use this member directly * outside of the code of the * low level functions * of the OBITools DMS */ bool writable; /**< Indicates if the column is writable or not. * - `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 of a column in a column directory * * @param column_directory * * @return the latest version number kept in the version file * @return -1 if an error occurred */ 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 * * @param column_name * * @return the latest version number kept in the version file * @return -1 if an error occurred */ 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. * Up to now the header size is defined as one time the page size. * * @return a `size_t` value corresponding to 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. * * @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 * * @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, size_t nb_lines, size_t nb_elements_per_line, 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) * * @return a pointer to the opened column * * @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 number is retrieved) * @param clone_data whether the data should be copied or not * * @return a pointer to the created column * * @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 * * @return 0 if the operation was successfully completed * @return -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. * * @param column a pointer on an OBIDMS column * * @return 0 if the operation was successfully completed * @return -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 Truncates a column file to the number of lines used and closes it. * * @param column a pointer on an OBIDMS column * * @return 0 if the operation was successfully completed * @return -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 'writable' header attribute of an OBIDMS column to False. * * @param column a pointer on an OBIDMS column * * @since July 2015 * @author Celine Mercier (celine.mercier@metabarcoding.org) */ 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 * * @return the line count of the column * * @since July 2015 * @author Celine Mercier (celine.mercier@metabarcoding.org) */ 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 * * @return the number of lines used in the column * * @since August 2015 * @author Celine Mercier (celine.mercier@metabarcoding.org) */ 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 * * @return the data type of the column * * @since July 2015 * @author Celine Mercier (celine.mercier@metabarcoding.org) */ 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 * * @return the data type of the column * * @since July 2015 * @author Celine Mercier (celine.mercier@metabarcoding.org) */ OBIType_t obi_column_get_data_type_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 * * @return the elements names * * @since July 2015 * @author Celine Mercier (celine.mercier@metabarcoding.org) */ 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. * * @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 * * @since July 2015 * @author Celine Mercier (celine.mercier@metabarcoding.org) */ size_t obi_column_get_element_index_from_name(OBIDMS_column_p column, const char* element_name); /** * @brief Recovers the number of elements per line in an OBIDMS column. * * @param column a pointer on an OBIDMS column * * @return the number of elements per line * * @since July 2015 * @author Celine Mercier (celine.mercier@metabarcoding.org) */ size_t obi_column_get_nb_elements_per_line(OBIDMS_column_p column); #endif /* OBIDMSCOLUMN_H_ */