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

Doxygen documentation corrected and completed.

Browse Source
This commit is contained in:
Celine Mercier
2015-09-30 12:03:46 +02:00
parent 45af8396b8
commit 4b7f2d268b
25 changed files with 670 additions and 689 deletions
Download Patch File Download Diff File Expand all files Collapse all files

252
src/obidmscolumn.h
View File

@ -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)