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 "obidms.h"
#include "obitypes.h"
#include "obierrno.h"
#include "obilittlebigman.h"
#include "obidmscolumndir.h"


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;				/**< 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 */
	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 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 column
 * @param column_name the name of the new column
 * @param type the OBIType code used to create the column
 * @param nb_elements the number of elements 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_elements,
								  size_t nb_elements_per_line,
								  const char*  elements_names);


/**
 * @brief Returns the latest column version in the `dms` database
 *
 * @param dms a pointer as returned by obi_create_dms() or obi_open_dms()
 * @param column_name the name of the column
 *
 * @return the bigger version number used for this column
 * @return -1 if the column does not exist
 */
obiversion_t obi_get_latest_version_number(OBIDMS_column_directory_p column_directory);


#endif /* OBIDMSCOLUMN_H_ */