obitools3/src/obidmscolumn.h

/****************************************************************************
 * 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 <stdio.h>
#include <sys/types.h>
#include <unistd.h>
#include <stdbool.h>
#include <time.h>
#include <stdbool.h>

#include "obidms.h"
#include "obitypes.h"
#include "obierrno.h"
#include "obilittlebigman.h"
#include "obidmscolumndir.h"

#define ELEMENTS_NAMES_MAX (2048)
#define GROWTH_FACTOR (2)
#define MAXIMUM_LINE_COUNT (1000000)


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 Enlarges a column file.
 *
 * @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_enlarge_column(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 data in a column to the NA value of the data type.
 *
 * @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, size_t start, size_t nb_lines);


/**
 * @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 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
 *
 * @return the line count of the column
 *
 * @since September 2015
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
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
 *
 * @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_ */