obitools3/src/obidmscolumn.h

/****************************************************************************
 * 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 <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"
#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()
											     	 	 	 */
	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            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 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.
 *
 * 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 data_type,
								  size_t nb_lines,
								  size_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, size_t first_line_nb, size_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)
 */
size_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.
 *
 * @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_ */