obitools3/src/obiview.h

/********************************************************************
 * Obiview header file                                              *
 ********************************************************************/

/**
 * @file obiview.h
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 * @date 16 December 2015
 * @brief Header file for the OBIDMS view functions and structures.
 */


#ifndef OBIVIEW_H_
#define OBIVIEW_H_


#include <stdlib.h>
#include <errno.h>
#include <stdio.h>
#include <stdbool.h>
#include <time.h>
#include <math.h>

#include "obidms.h"
#include "obidmscolumn.h"
#include "obierrno.h"


#define OBIVIEW_NAME_MAX_LENGTH (1000)   /**< The maximum length of an OBIDMS view name.
                                	 	  */
#define OBIVIEW_COMMENTS_MAX_LENGTH (10000)

#define OBIVIEW_FILE_NAME "obiviews"

#define VIEW_TYPE_MAX_NAME (1024)

#define VIEW_TYPE_NUC_SEQS "NUC_SEQS_VIEW"

#define NUC_SEQUENCE_COLUMN "NUC_SEQ"
#define NUC_SEQUENCE_INDEXER "NUC_SEQ_INDEXER"

#define ID_COLUMN "ID"
#define ID_INDEXER "ID_INDEXER"

#define DEFINITION_COLUMN "DEFINITION"
#define DEFINITION_INDEXER "DEFINITION_INDEXER"

#define LINES_COLUMN_NAME "LINES"


/**
 * @brief .
 */
typedef struct Column_reference {
	char 	   	 column_name[OBIDMS_COLUMN_MAX_NAME+1];    /**< Name of the column.
	 	 	 	 	 	 	 	 	 	 	 	 	 	    */
	obiversion_t version;				   		    	   /**< Version of the column.
	 	 	 	 	 	 	 	 	 	 	 	 	 	    */
} Column_reference_t, *Column_reference_p;


/**
 * @brief .
 */
typedef struct Obiview {

	OBIDMS_p         	dms;

	bool             	read_only;

	OBIDMS_column_p  	line_selection;

	OBIDMS_column_p  	new_line_selection;

	index_t			 	line_count;

	int    			 	column_count;

	OBIDMS_column_p  	columns[MAX_NB_OPENED_COLUMNS];

	char   				name[OBIVIEW_NAME_MAX_LENGTH+1];

	char				created_from[OBIVIEW_NAME_MAX_LENGTH+1];

	int					view_number;

	char				view_type[VIEW_TYPE_MAX_NAME+1];

	char 				comments[OBIVIEW_COMMENTS_MAX_LENGTH+1];

} Obiview_t, *Obiview_p;


/**
 * @brief .
 */
typedef struct Obiview_infos {
	int					view_number;

	int 				column_count;

	index_t             line_count;

	char   				name[OBIVIEW_NAME_MAX_LENGTH+1];

	char				created_from[OBIVIEW_NAME_MAX_LENGTH+1];

	time_t 		 		creation_date;

	bool				all_lines;

	Column_reference_t	line_selection;

	Column_reference_t	column_references[MAX_NB_OPENED_COLUMNS];

	char				view_type[VIEW_TYPE_MAX_NAME+1];

	char 				comments[OBIVIEW_COMMENTS_MAX_LENGTH+1];

} Obiview_infos_t, *Obiview_infos_p;


/**
 * @brief .
 */
typedef struct Obiviews_header {
	size_t header_size;
	size_t views_size;
	int    view_count;
} Obiviews_header_t, *Obiviews_header_p;


/**
 * @brief .
 */
typedef struct Obiviews_infos_all {
	Obiviews_header_p	header;

	Obiview_infos_p 	view_infos;

} Obiviews_infos_all_t, *Obiviews_infos_all_p;


Obiview_p obi_new_view_nuc_seqs(OBIDMS_p dms, const char* view_name, Obiview_p view_to_clone, index_t* line_selection, const char* comments);

Obiview_p obi_new_view(OBIDMS_p dms, const char* view_name, Obiview_p view_to_clone, index_t* line_selection, const char* comments);

Obiview_p obi_new_view_cloned_from_name(OBIDMS_p dms, const char* view_name, const char* view_to_clone_name, index_t* line_selection, const char* comments);

Obiview_p obi_new_view_nuc_seqs_cloned_from_name(OBIDMS_p dms, const char* view_name, const char* view_to_clone_name, index_t* line_selection, const char* comments);

Obiview_p obi_open_view(OBIDMS_p dms, const char* view_name);

Obiviews_infos_all_p obi_read_views(OBIDMS_p dms);

int obi_unmap_read_views(Obiviews_infos_all_p views);

int obi_view_add_column(Obiview_p view,
						const char* column_name,
						obiversion_t version_number,
						OBIType_t data_type,
						index_t nb_lines,
						index_t nb_elements_per_line,
						const char* elements_names,
						const char* indexer_name,
						const char* comments,
						bool create);

int obi_view_delete_column(Obiview_p view, const char* column_name);

int obi_select_line(Obiview_p view, index_t line_nb);

int obi_select_lines(Obiview_p view, index_t* line_nbs);

int obi_view_update_lines(Obiview_p view, index_t line_count);

OBIDMS_column_p obi_view_clone_column(Obiview_p view, const char* column_name);

OBIDMS_column_p obi_view_get_column(Obiview_p view, const char* column_name);

OBIDMS_column_p* obi_view_get_pointer_on_column_in_view(Obiview_p view, const char* column_name);

int obi_save_view(Obiview_p view);

int obi_close_view(Obiview_p view);

int obi_save_and_close_view(Obiview_p view);

int obi_column_set_obibool_with_elt_idx_in_view(Obiview_p view, OBIDMS_column_p column, index_t line_nb, index_t element_idx, obibool_t value);


/**
 * @brief Sets a value in an OBIDMS column containing data with the type OBI_BOOL, using the index of the element in the line.
 *
 * @warning Pointers returned by obi_open_column() don't allow writing.
 *
 * @param column A pointer as returned by obi_create_column() or obi_clone_column().
 * @param line_nb The number of the line where the value should be set.
 * @param element_idx The index of the element that should be set in the line.
 * @param value The value that should be set.
 *
 * @returns An integer value indicating the success of the operation.
 * @retval 0 on success.
 * @retval -1 if an error occurred.
 *
 * @since February 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
int obi_column_set_obibool_with_elt_idx_in_view(Obiview_p view, OBIDMS_column_p column, index_t line_nb, index_t element_idx, obibool_t value);


/**
 * @brief Recovers a value in an OBIDMS column containing data with the type OBI_BOOL.
 *
 * @param column A pointer as returned by obi_create_column().
 * @param line_nb The number of the line where the value should be recovered.
 * @param element_idx The index of the element that should be recovered in the line.
 *
 * @returns The recovered value.
 * @retval OBIBool_NA the NA value of the type if an error occurred and obi_errno is set.
 *
 * @since February 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
obibool_t obi_column_get_obibool_with_elt_idx_in_view(Obiview_p view, OBIDMS_column_p column, index_t line_nb, index_t element_idx);


/**
 * @brief Sets a value in an OBIDMS column containing data with the type OBI_BOOL,
 *        using the name of the element in the line.
 *
 * @warning Pointers returned by obi_open_column() don't allow writing.
 *
 * @param column A pointer as returned by obi_create_column() or obi_clone_column().
 * @param line_nb The number of the line where the value should be set.
 * @param element_name The name of the element that should be set in the line.
 * @param value The value that should be set.
 *
 * @returns An integer value indicating the success of the operation.
 * @retval 0 on success.
 * @retval -1 if an error occurred.
 *
 * @since February 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
int obi_column_set_obibool_with_elt_name_in_view(Obiview_p view, OBIDMS_column_p column, index_t line_nb, const char* element_name, obibool_t value);


/**
 * @brief Recovers a value in an OBIDMS column containing data with the type OBI_BOOL,
 *        using the name of the element in the line.
 *
 * @param column A pointer as returned by obi_create_column() or obi_clone_column().
 * @param line_nb The number of the line where the value should be recovered.
 * @param element_name The name of the element that should be recovered in the line.
 *
 * @returns The recovered value.
 * @retval OBIBool_NA the NA value of the type if an error occurred and obi_errno is set.
 *
 * @since February 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
obibool_t obi_column_get_obibool_with_elt_name_in_view(Obiview_p view, OBIDMS_column_p column, index_t line_nb, const char* element_name);


/**
 * @brief Sets a value in an OBIDMS column containing data with the type OBI_CHAR, using the index of the element in the line.
 *
 * @warning Pointers returned by obi_open_column() don't allow writing.
 *
 * @param column A pointer as returned by obi_create_column() or obi_clone_column().
 * @param line_nb The number of the line where the value should be set.
 * @param element_idx The index of the element that should be set in the line.
 * @param value The value that should be set.
 *
 * @returns An integer value indicating the success of the operation.
 * @retval 0 on success.
 * @retval -1 if an error occurred.
 *
 * @since February 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
int obi_column_set_obichar_with_elt_idx_in_view(Obiview_p view, OBIDMS_column_p column, index_t line_nb, index_t element_idx, obichar_t value);


/**
 * @brief Recovers a value in an OBIDMS column containing data with the type OBI_CHAR.
 *
 * @param column A pointer as returned by obi_create_column().
 * @param line_nb The number of the line where the value should be recovered.
 * @param element_idx The index of the element that should be recovered in the line.
 *
 * @returns The recovered value.
 * @retval OBIChar_NA the NA value of the type if an error occurred and obi_errno is set.
 *
 * @since February 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
obichar_t obi_column_get_obichar_with_elt_idx_in_view(Obiview_p view, OBIDMS_column_p column, index_t line_nb, index_t element_idx);


/**
 * @brief Sets a value in an OBIDMS column containing data with the type OBI_CHAR,
 *        using the name of the element in the line.
 *
 * @warning Pointers returned by obi_open_column() don't allow writing.
 *
 * @param column A pointer as returned by obi_create_column() or obi_clone_column().
 * @param line_nb The number of the line where the value should be set.
 * @param element_name The name of the element that should be set in the line.
 * @param value The value that should be set.
 *
 * @returns An integer value indicating the success of the operation.
 * @retval 0 on success.
 * @retval -1 if an error occurred.
 *
 * @since February 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
int obi_column_set_obichar_with_elt_name_in_view(Obiview_p view, OBIDMS_column_p column, index_t line_nb, const char* element_name, obichar_t value);


/**
 * @brief Recovers a value in an OBIDMS column containing data with the type OBI_CHAR,
 *        using the name of the element in the line.
 *
 * @param column A pointer as returned by obi_create_column() or obi_clone_column().
 * @param line_nb The number of the line where the value should be recovered.
 * @param element_name The name of the element that should be recovered in the line.
 *
 * @returns The recovered value.
 * @retval OBIChar_NA the NA value of the type if an error occurred and obi_errno is set.
 *
 * @since February 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
obichar_t obi_column_get_obichar_with_elt_name_in_view(Obiview_p view, OBIDMS_column_p column, index_t line_nb, const char* element_name);


/**
 * @brief Sets a value in an OBIDMS column containing data with the type OBI_FLOAT, using the index of the element in the line.
 *
 * @warning Pointers returned by obi_open_column() don't allow writing.
 *
 * @param column A pointer as returned by obi_create_column() or obi_clone_column().
 * @param line_nb The number of the line where the value should be set.
 * @param element_idx The index of the element that should be set in the line.
 * @param value The value that should be set.
 *
 * @returns An integer value indicating the success of the operation.
 * @retval 0 on success.
 * @retval -1 if an error occurred.
 *
 * @since February 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
int obi_column_set_obifloat_with_elt_idx_in_view(Obiview_p view, OBIDMS_column_p column, index_t line_nb, index_t element_idx, obifloat_t value);


/**
 * @brief Recovers a value in an OBIDMS column containing data with the type OBI_FLOAT.
 *
 * @param column A pointer as returned by obi_create_column().
 * @param line_nb The number of the line where the value should be recovered.
 * @param element_idx The index of the element that should be recovered in the line.
 *
 * @returns The recovered value.
 * @retval OBIFloat_NA the NA value of the type if an error occurred and obi_errno is set.
 *
 * @since February 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
obifloat_t obi_column_get_obifloat_with_elt_idx_in_view(Obiview_p view, OBIDMS_column_p column, index_t line_nb, index_t element_idx);


/**
 * @brief Sets a value in an OBIDMS column containing data with the type OBI_FLOAT,
 *        using the name of the element in the line.
 *
 * @warning Pointers returned by obi_open_column() don't allow writing.
 *
 * @param column A pointer as returned by obi_create_column() or obi_clone_column().
 * @param line_nb The number of the line where the value should be set.
 * @param element_name The name of the element that should be set in the line.
 * @param value The value that should be set.
 *
 * @returns An integer value indicating the success of the operation.
 * @retval 0 on success.
 * @retval -1 if an error occurred.
 *
 * @since February 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
int obi_column_set_obifloat_with_elt_name_in_view(Obiview_p view, OBIDMS_column_p column, index_t line_nb, const char* element_name, obifloat_t value);


/**
 * @brief Recovers a value in an OBIDMS column containing data with the type OBI_FLOAT,
 *        using the name of the element in the line.
 *
 * @param column A pointer as returned by obi_create_column() or obi_clone_column().
 * @param line_nb The number of the line where the value should be recovered.
 * @param element_name The name of the element that should be recovered in the line.
 *
 * @returns The recovered value.
 * @retval OBIFloat_NA the NA value of the type if an error occurred and obi_errno is set.
 *
 * @since February 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
obifloat_t obi_column_get_obifloat_with_elt_name_in_view(Obiview_p view, OBIDMS_column_p column, index_t line_nb, const char* element_name);


/**
 * @brief Sets a value in an OBIDMS column containing data with the type OBI_INT, using the index of the element in the line.
 *
 * @warning Pointers returned by obi_open_column() don't allow writing.
 *
 * @param column A pointer as returned by obi_create_column() or obi_clone_column().
 * @param line_nb The number of the line where the value should be set.
 * @param element_idx The index of the element that should be set in the line.
 * @param value The value that should be set.
 *
 * @returns An integer value indicating the success of the operation.
 * @retval 0 on success.
 * @retval -1 if an error occurred.
 *
 * @since February 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
int obi_column_set_obiint_with_elt_idx_in_view(Obiview_p view, OBIDMS_column_p column, index_t line_nb, index_t element_idx, obiint_t value);


/**
 * @brief Recovers a value in an OBIDMS column containing data with the type OBI_INT.
 *
 * @param column A pointer as returned by obi_create_column().
 * @param line_nb The number of the line where the value should be recovered.
 * @param element_idx The index of the element that should be recovered in the line.
 *
 * @returns The recovered value.
 * @retval OBIBool_NA the NA value of the type if an error occurred and obi_errno is set.
 *
 * @since February 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
obiint_t obi_column_get_obiint_with_elt_idx_in_view(Obiview_p view, OBIDMS_column_p column, index_t line_nb, index_t element_idx);


/**
 * @brief Sets a value in an OBIDMS column containing data with the type OBI_INT,
 *        using the name of the element in the line.
 *
 * @warning Pointers returned by obi_open_column() don't allow writing.
 *
 * @param column A pointer as returned by obi_create_column() or obi_clone_column().
 * @param line_nb The number of the line where the value should be set.
 * @param element_name The name of the element that should be set in the line.
 * @param value The value that should be set.
 *
 * @returns An integer value indicating the success of the operation.
 * @retval 0 on success.
 * @retval -1 if an error occurred.
 *
 * @since February 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
int obi_column_set_obiint_with_elt_name_in_view(Obiview_p view, OBIDMS_column_p column, index_t line_nb, const char* element_name, obiint_t value);


/**
 * @brief Recovers a value in an OBIDMS column containing data with the type OBI_INT,
 *        using the name of the element in the line.
 *
 * @param column A pointer as returned by obi_create_column() or obi_clone_column().
 * @param line_nb The number of the line where the value should be recovered.
 * @param element_name The name of the element that should be recovered in the line.
 *
 * @returns The recovered value.
 * @retval OBIBool_NA the NA value of the type if an error occurred and obi_errno is set.
 *
 * @since February 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
obiint_t obi_column_get_obiint_with_elt_name_in_view(Obiview_p view, OBIDMS_column_p column, index_t line_nb, const char* element_name);


/**
 * @brief Sets a value in an OBIDMS column containing data in the form of indices referring
 * to DNA sequences handled by an indexer, using the index of the element in the line.
 *
 * @warning Pointers returned by obi_open_column() don't allow writing.
 *
 * @param column A pointer as returned by obi_create_column() or obi_clone_column().
 * @param line_nb The number of the line where the value should be set.
 * @param element_idx The index of the element that should be set in the line.
 * @param value The value that should be set.
 *
 * @returns An integer value indicating the success of the operation.
 * @retval 0 on success.
 * @retval -1 if an error occurred.
 *
 * @since February 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
int obi_column_set_obiseq_with_elt_idx_in_view(Obiview_p view, OBIDMS_column_p column, index_t line_nb, index_t element_idx, const char* value);


/**
 * @brief Recovers a value in an OBIDMS column containing data in the form of indices referring
 * to DNA sequences handled by an indexer, using the index of the element in the line.
 *
 * @param column A pointer as returned by obi_create_column().
 * @param line_nb The number of the line where the value should be recovered.
 * @param element_idx The index of the element that should be recovered in the line.
 *
 * @returns The recovered value.
 * @retval '\0' the NA value of the type if an error occurred and obi_errno is set.
 *
 * @since February 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
char* obi_column_get_obiseq_with_elt_idx_in_view(Obiview_p view, OBIDMS_column_p column, index_t line_nb, index_t element_idx);


/**
 * @brief Sets a value in an OBIDMS column containing data in the form of indices referring
 * to DNA sequences handled by an indexer, using the name of the element in the line.
 *
 * @warning Pointers returned by obi_open_column() don't allow writing.
 *
 * @param column A pointer as returned by obi_create_column() or obi_clone_column().
 * @param line_nb The number of the line where the value should be set.
 * @param element_name The name of the element that should be set in the line.
 * @param value The value that should be set.
 *
 * @returns An integer value indicating the success of the operation.
 * @retval 0 on success.
 * @retval -1 if an error occurred.
 *
 * @since February 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
int obi_column_set_obiseq_with_elt_name_in_view(Obiview_p view, OBIDMS_column_p column, index_t line_nb, const char* element_name, const char* value);


/**
 * @brief Recovers a value in an OBIDMS column containing data in the form of indices referring
 * to DNA sequences handled by an indexer, using the name of the element in the line.
 *
 * @param column A pointer as returned by obi_create_column() or obi_clone_column().
 * @param line_nb The number of the line where the value should be recovered.
 * @param element_name The name of the element that should be recovered in the line.
 *
 * @returns The recovered value.
 * @retval '\0' the NA value of the type if an error occurred and obi_errno is set.
 *
 * @since February 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
char* obi_column_get_obiseq_with_elt_name_in_view(Obiview_p view, OBIDMS_column_p column, index_t line_nb, const char* element_name);


/**
 * @brief Sets a value in an OBIDMS column containing data in the form of indices referring
 * to character strings handled by an indexer, using the index of the element in the line.
 *
 * @warning Pointers returned by obi_open_column() don't allow writing.
 *
 * @param column A pointer as returned by obi_create_column() or obi_clone_column().
 * @param line_nb The number of the line where the value should be set.
 * @param element_idx The index of the element that should be set in the line.
 * @param value The value that should be set.
 *
 * @returns An integer value indicating the success of the operation.
 * @retval 0 on success.
 * @retval -1 if an error occurred.
 *
 * @since February 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
int obi_column_set_obistr_with_elt_idx_in_view(Obiview_p view, OBIDMS_column_p column, index_t line_nb, index_t element_idx, const char* value);


/**
 * @brief Recovers a value in an OBIDMS column containing data in the form of indices referring
 * to character strings handled by an indexer, using the index of the element in the line.
 *
 * @param column A pointer as returned by obi_create_column().
 * @param line_nb The number of the line where the value should be recovered.
 * @param element_idx The index of the element that should be recovered in the line.
 *
 * @returns The recovered value.
 * @retval '\0' the NA value of the type if an error occurred and obi_errno is set.
 *
 * @since February 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
const char* obi_column_get_obistr_with_elt_idx_in_view(Obiview_p view, OBIDMS_column_p column, index_t line_nb, index_t element_idx);


/**
 * @brief Sets a value in an OBIDMS column containing data in the form of indices referring
 * to character strings handled by an indexer, using the name of the element in the line.
 *
 * @warning Pointers returned by obi_open_column() don't allow writing.
 *
 * @param column A pointer as returned by obi_create_column() or obi_clone_column().
 * @param line_nb The number of the line where the value should be set.
 * @param element_name The name of the element that should be set in the line.
 * @param value The value that should be set.
 *
 * @returns An integer value indicating the success of the operation.
 * @retval 0 on success.
 * @retval -1 if an error occurred.
 *
 * @since February 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
int obi_column_set_obistr_with_elt_name_in_view(Obiview_p view, OBIDMS_column_p column, index_t line_nb, const char* element_name, const char* value);


/**
 * @brief Recovers a value in an OBIDMS column containing data in the form of indices referring
 * to character strings handled by an indexer, using the name of the element in the line.
 *
 * @param column A pointer as returned by obi_create_column() or obi_clone_column().
 * @param line_nb The number of the line where the value should be recovered.
 * @param element_name The name of the element that should be recovered in the line.
 *
 * @returns The recovered value.
 * @retval '\0' the NA value of the type if an error occurred and obi_errno is set.
 *
 * @since February 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
const char* obi_column_get_obistr_with_elt_name_in_view(Obiview_p view, OBIDMS_column_p column, index_t line_nb, const char* element_name);


#endif /* OBIVIEW_H_ */