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>


#define OBIDMS_MAX_COLNAME (128) /**< The maximum length of an OBIDMS column name
                                  */

typedef int32_t obiversion_t; 	/**< Used to store the column version number
                                 */

/**
 * @brief OBIColumnHeader structure.
 */

typedef struct OBIDMS_column_header {
	bool			little_endian;		    /**< endianess of the column:
													- `true`  on little endian platforms
													- `false` on big endian platforms

												@see obi_is_little_end()
	 	 	 	 	 	 	 	 	 	 	 */
	int				header_size;		    /**< size of the header in bytes */
	size_t			line_count;				/**< number of lines of data */
	size_t			line_used;				/**< number of lines of data used*/
	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. T
												 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_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.
 *
 * 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 as returned by obi_create_dms() or obi_open_dms()
 * @param name the name of the new column
 * @param type the OBIType code used to create the column
 * @param nbelements 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,
								 char* name,
								 OBIType_t type,
								 size_t nbelements);


/**
 * @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 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_latest_version(OBIDMS_p dms,char *name);


#endif /* OBIDMSCOLUMN_H_ */