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 <stdint.h>
#include <stdbool.h>
#include <time.h>
#include <math.h>

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


#define OBIVIEW_NAME_MAX_LENGTH (249)   		/**< The maximum length of an OBIDMS view name, without the extension.
                                	 	  	  	 */
#define VIEW_TYPE_MAX_LENGTH (1024)   			/**< The maximum length of the type name of a view.
                                	 	  	  	 */
#define LINES_COLUMN_NAME "LINES"				/**< The name of the column containing the line selections
 	 	 	 	 	 	 	 	 	 	 	 	 *   in all views.
                                	 	  	  	 */
#define VIEW_TYPE_NUC_SEQS "NUC_SEQS_VIEW"   	/**< The type name of views based on nucleotide sequences
												 *   and their metadata.
                                	 	  	  	 */
#define NUC_SEQUENCE_COLUMN "NUC_SEQ"			/**< The name of the column containing the nucleotide sequences
 	 	 	 	 	 	 	 	 	 	 	 	 *   in NUC_SEQS_VIEW views.
                                	 	  	  	 */
#define ID_COLUMN "ID"							/**< The name of the column containing the sequence identifiers
 	 	 	 	 	 	 	 	 	 	 	 	 *   in NUC_SEQS_VIEW views.
                                	 	  	  	 */
#define DEFINITION_COLUMN "DEFINITION"			/**< The name of the column containing the sequence definitions
 	 	 	 	 	 	 	 	 	 	 	 	 *   in NUC_SEQS_VIEW views.
                                	 	  	  	 */
#define QUALITY_COLUMN "QUALITY"				/**< The name of the column containing the sequence qualities
 	 	 	 	 	 	 	 	 	 	 	 	 *   in NUC_SEQS_VIEW views.
                                	 	  	  	 */


/**
 * @brief Structure for column aliases.
 * 		  Column aliases are alternative names used to identify a column in the context of a view.
 */
typedef struct Alias_column_pair {
	Column_reference_t	column_refs;   						/**< References (name and version) of the column.
		 	 	 	 	 	 	 	 	 	 	 	 	 	 */
	char 				alias[OBIDMS_COLUMN_MAX_NAME+1];	/**< Alias of the column in the context of a view.
	 	 	 								 	 	 	 	 */
} Alias_column_pair_t, *Alias_column_pair_p;


/**
 * @brief Structure for a closed view stored in the view file.
 * 		  Views are identified by their name.
 * 		  Once a view has been written in the view file, it can not be modified and can only be read.
 */
typedef struct Obiview_infos {
	size_t				file_size;    								/**< View file size in bytes.
	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 */
	size_t				used_size;    								/**< Used size in bytes.
	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 */
	time_t 		 		creation_date;    							/**< Time at which the view was created.
		 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 */
	char   				name[OBIVIEW_NAME_MAX_LENGTH+1];    		/**< Name of the view, used to identify it.
	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 */
	char				created_from[OBIVIEW_NAME_MAX_LENGTH+1];    /**< Name of the view from which that view was cloned, if it was cloned.
	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 */
	char				view_type[VIEW_TYPE_MAX_LENGTH+1];			/**< Type of the view if there is one.
	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 *   Types existing: NUC_SEQS_VIEW.
	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 */
	bool				all_lines;									/**< Whether there is a line selection associated with the view.
	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 */
	Column_reference_t	line_selection;								/**< The references of the line selection associated with the view if there is one.
 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 */
	index_t             line_count;    								/**< The number of lines in the view.
																	 */
	int 				column_count;    							/**< The number of columns in the view.
	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 */
	Alias_column_pair_t column_references[MAX_NB_OPENED_COLUMNS];   /**< References (name, version and alias) for all the columns in the view.
	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 */
	bool				finished;									/** Whether the view is finished and can be read.
																	 */
	char 				comments[];									/**< Comments, additional informations on the view.
 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 */
} Obiview_infos_t, *Obiview_infos_p;


/**
 * @brief Structure for an opened view.
 */
typedef struct Obiview {
	Obiview_infos_p  infos;												/**< A pointer on the mapped view informations.
		 	 	 	  	 	 	 	 	 	 	 	 	 	 	 	 	 */
	OBIDMS_p         dms;    											/**< A pointer on the DMS to which the view belongs.
	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 */
	bool             read_only;    										/**< Whether the view is read-only or can be modified.
																	 	 */
	OBIDMS_column_p  line_selection;    								/**< A pointer on the column containing the line selection
																	 	 *   associated with the view if there is one.
																	 	 *   This line selection is read-only, and when a line from the view is read,
																	 	 *   it is this line selection that is used.
																	 	 */
	OBIDMS_column_p  columns[MAX_NB_OPENED_COLUMNS];    				/**< Array of pointers on all the columns of the view.
	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 */
	hashtable_p		 column_dict;										/**< Hash table storing the pairs of column names or aliases with the associated
																		 *   column pointers.
																		 */
	int				 nb_predicates;    									/**< Number of predicates to test when closing the view.
 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 */
	char* 			 (**predicate_functions)(struct Obiview* view);     /**< Array of pointers on all predicate functions to test when closing the view.
	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 */
} Obiview_t, *Obiview_p;


/**
 * @brief Creates a new view.
 *
 * Fails if a view with the same name already exists.
 *
 * @param dms A pointer on the OBIDMS.
 * @param view_name The unique name of the view.
 * @param view_to_clone Eventually a pointer on the opened view to clone to create the new one, if there is one. NULL if not.
 * @param line_selection Eventually a pointer on a list of indexes corresponding to a line selection to use with the view to clone
 * 						 if there is one. NULL if there is no line selection or no view to clone.
 * 						 The end of the index array is flagged by a -1 value.
 * @param comments Eventually, comments to associate with the view. NULL if not.
 *
 * @returns A pointer to the newly created view structure.
 * @retval NULL if an error occurred.
 *
 * @since December 2015
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
Obiview_p obi_new_view(OBIDMS_p dms, const char* view_name, Obiview_p view_to_clone, index_t* line_selection, const char* comments);


/**
 * @brief Creates a new view by cloning another view written in the view file and identified by its name.
 *
 * Note : obi_new_view can clone from a pointer on an opened view, while this function will read the view to clone
 * 		  from the view file.
 *
 * Fails if a view with the same name already exists.
 *
 * @param dms A pointer on the OBIDMS.
 * @param view_name The unique name of the new view.
 * @param view_to_clone_name The name of the view to clone stored in the view file of the OBIDMS.
 * @param line_selection Eventually a pointer on a list of indexes corresponding to a line selection to use with the view to clone
 * 						 if there is one. NULL if there is no line selection or no view to clone.
 * @param comments Eventually, comments to associate with the view. NULL if not.
 *
 * @returns A pointer to the newly created view structure.
 * @retval NULL if an error occurred.
 *
 * @since December 2015
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
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);


/**
 * @brief Creates a new view with the type NUC_SEQ_VIEW, based on nucleotide sequences and their metadata.
 *
 * Fails if a view with the same name already exists.
 *
 * The obligatory columns specific to the view type are created too and opened:
 * 	- NUC_SEQUENCE_COLUMN where nucleotide sequences are stored
 * 	- ID_COLUMN			  where sequence identifiers are stored
 * 	- DEFINITION_COLUMN   where sequence definitions are stored
 * 	And, if quality_column is True:
 * 	- QUALITY_COLUMN   	  where sequence qualities are stored
 *
 * @param dms A pointer on the OBIDMS.
 * @param view_name The unique name of the view.
 * @param view_to_clone Eventually a pointer on the opened view to clone to create the new one, if there is one. NULL if not.
 * @param line_selection Eventually a pointer on a list of indexes corresponding to a line selection to use with the view to clone
 * 						 if there is one. NULL if there is no line selection or no view to clone.
 * @param comments Eventually, comments to associate with the view. NULL if not.
 * @param quality_column Whether or not a sequence quality column is associated with the view.
 *
 * @returns A pointer to the newly created view structure.
 * @retval NULL if an error occurred.
 *
 * @since February 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
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, bool quality_column);


/**
 * @brief Creates a new view with the type NUC_SEQ_VIEW, based on nucleotide sequences and their metadata,
 *        by cloning another NUC_SEQ_VIEW view written in the view file and identified by its name.
 *
 * Note : obi_new_view_nuc_seqs can clone from a pointer on an opened view, while this function will read the view to clone
 * 		  from the view file.
 *
 * Fails if a view with the same name already exists.
 * Fails if the view to clone doesn't have the type NUC_SEQ_VIEW.
 *
 * The obligatory columns specific to the view type are created too and opened:
 * 	- NUC_SEQUENCE_COLUMN where nucleotide sequences are stored
 * 	- ID_COLUMN			  where sequence identifiers are stored
 * 	- DEFINITION_COLUMN   where sequence definitions are stored
 * 	And, if quality_column is True:
 * 	- QUALITY_COLUMN   	  where sequence qualities are stored
 *
 * @param dms A pointer on the OBIDMS.
 * @param view_name The unique name of the new view.
 * @param view_to_clone_name The name of the view to clone stored in the view file of the OBIDMS.
 * @param line_selection Eventually a pointer on a list of indexes corresponding to a line selection to use with the view to clone
 * 						 if there is one. NULL if there is no line selection or no view to clone.
 * @param comments Eventually, comments to associate with the view. NULL if not.
 * @param quality_column Whether or not a sequence quality column is associated with the view.
 *
 * @returns A pointer to the newly created view structure.
 * @retval NULL if an error occurred.
 *
 * @since February 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
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, bool quality_column);


/**
 * @brief Maps a view file and returns the mapped structure stored in it.
 *
 * @param dms A pointer on the OBIDMS.
 * @param view_name The unique name identifying the view.
 *
 * @returns A pointer on the mapped view infos structure.
 * @retval NULL if an error occurred.
 *
 * @since June 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
Obiview_infos_p obi_view_map_file(OBIDMS_p dms, const char* view_name);


/**
 * @brief Unmaps a view file.
 *
 * @param dms A pointer on the OBIDMS.
 * @param view_infos A pointer on the mapped view infos structure.
 *
 * @returns A value indicating the success of the operation.
 * @retval 0 if the operation was successfully completed.
 * @retval -1 if an error occurred.
 *
 * @since June 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
int obi_view_unmap_file(OBIDMS_p dms, Obiview_infos_p view_infos);


/**
 * @brief Opens a view identified by its name stored in the view file.
 *
 * When opening a view, all the columns and eventually the line selection belonging to it are opened with it.
 *
 * @warning The opened view is read-only.
 *
 * @param dms A pointer on the OBIDMS.
 * @param view_name The unique name identifying the view.
 *
 * @returns A pointer on the opened view structure.
 * @retval NULL if an error occurred.
 *
 * @since December 2015
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
Obiview_p obi_open_view(OBIDMS_p dms, const char* view_name);


/**
 * @brief Adds a column to a view.
 *
 * @warning The view must be writable.
 *
 * @param view A pointer on the view.
 * @param column_name The name of the column.
 * @param version_number The version of the column if it should be opened and not created (if -1, the latest version is retrieved).
 * @param alias The unique name used to identify the column in the context of this view.
 * @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.
 * @param indexer_name The name of the indexer if there is one associated with the column.
 * @param comments Optional comments associated with the column.
 * @param create Whether the column should be created (create == true) or opened (create == false).
 *
 * @returns A value indicating the success of the operation.
 * @retval 0 if the operation was successfully completed.
 * @retval -1 if an error occurred.
 *
 * @since February 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
int obi_view_add_column(Obiview_p view,
						const char* column_name,
						obiversion_t version_number,
						const char* alias,
						OBIType_t data_type,
						index_t nb_lines,
						index_t nb_elements_per_line,
						const char* elements_names,
						const char* indexer_name,
						const char* associated_column_name,
						obiversion_t associated_column_version,
						const char* comments,
						bool create);


/**
 * @brief Deletes a column from a view.
 *
 * @warning The view must be writable.
 *
 * @param view A pointer on the view.
 * @param column_name The name of the column that should be deleted from the view.
 *
 * @returns A value indicating the success of the operation.
 * @retval 0 if the operation was successfully completed.
 * @retval -1 if an error occurred.
 *
 * @since February 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
int obi_view_delete_column(Obiview_p view, const char* column_name);


/**
 * @brief Gets the pointer on a column from its name in a view.
 *
 * @param view A pointer on the view.
 * @param column_name The name of the column in the view.
 *
 * @returns A pointer on the column.
 * @retval NULL if an error occurred.
 *
 * @since February 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
OBIDMS_column_p obi_view_get_column(Obiview_p view, const char* column_name);


/**
 * @brief Gets the pointer on the pointer on a column from its name in a view.
 *
 * Note: This is used to replace old cloned columns with new ones in views in layers above the C layer.
 *
 * @param view A pointer on the view.
 * @param column_name The name of the column in the view.
 *
 * @returns A pointer on the pointer on the column.
 * @retval NULL if an error occurred.
 *
 * @since February 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
OBIDMS_column_p* obi_view_get_pointer_on_column_in_view(Obiview_p view, const char* column_name);


/**
 * @brief Changes the name that identifies a column in the context of a view.
 *
 * In the context of a view, each column is identified by a name that is unique in this view.
 *
 * @warning The view must be writable.
 *
 * @param view A pointer on the view.
 * @param current_name The current name that identifies the column in this view.
 * @param alias The new name that should be used to identify the column in this view.
 *
 * @returns A value indicating the success of the operation.
 * @retval 0 if the operation was successfully completed.
 * @retval -1 if an error occurred.
 *
 * @since July 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
int obi_view_create_column_alias(Obiview_p view, const char* current_name, const char* alias);


/**
 * @brief Selects a line in the context of a view.
 *
 * If no line selection exists for the view, it will be created.
 *
 * @warning The view must be writable.
 * @warning The new line index will be simply added at the end of the current
 *          new line selection.
 *
 * @param view A pointer on the view.
 * @param line_nb The index of the line that should be added in the selection.
 *
 * @returns A value indicating the success of the operation.
 * @retval 0 if the operation was successfully completed.
 * @retval -1 if an error occurred.
 *
 * @since February 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
int obi_select_line(Obiview_p view, index_t line_nb);


/**
 * @brief Selects a list of line in the context of a view.
 *
 * If no line selection exists for the view, it will be created.
 *
 * @warning The view must be writable.
 * @warning The new line indexes will be simply added at the end of the current
 *          new line selection.
 *
 * @param view A pointer on the view.
 * @param line_nbs A pointer on an array of indexes corresponding to the lines that
 *                 should be added in the selection.
 *
 * @returns A value indicating the success of the operation.
 * @retval 0 if the operation was successfully completed.
 * @retval -1 if an error occurred.
 *
 * @since February 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
int obi_select_lines(Obiview_p view, index_t* line_nbs);


/**
 * @brief Saves a view, writing it in the view file.
 *
 * The view is written at the end of the view file, following the latest written view.
 *
 * @warning The view must be writable.
 *
 * @param view A pointer on the view.
 *
 * @returns A value indicating the success of the operation.
 * @retval 0 if the operation was successfully completed.
 * @retval -1 if an error occurred.
 *
 * @since February 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
int obi_save_view(Obiview_p view);


/**
 * @brief Closes an opened view.
 *
 * @warning Uses obi_save_and_close_view() to automatically save the view if it's not already saved in the view file.
 *
 * @param view A pointer on the view.
 *
 * @returns A value indicating the success of the operation.
 * @retval 0 if the operation was successfully completed.
 * @retval -1 if an error occurred.
 *
 * @since February 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
int obi_close_view(Obiview_p view);


/**
 * @brief Closes an opened view, and saves it if it is not read-only (meaning it is not already saved in the view file).
 *
 * The predicates associated with the view are checked before saving it, and -1 is returned if at
 * least one predicate is not respected.
 *
 * @param view A pointer on the view.
 *
 * @returns A value indicating the success of the operation.
 * @retval 0 if the operation was successfully completed.
 * @retval -1 if an error occurred.
 *
 * @since February 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
int obi_save_and_close_view(Obiview_p view);


/**
 * @brief Recovers an obiblob from an OBIDMS column containing indices referring to obiblobs, in the context of a view.
 *
 * @param view A pointer on the opened view.
 * @param column_p A pointer on the 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 obiblob.
 * @retval OBIBlob_NA the NA value of the type if an error occurred and obi_errno is set.
 *
 * @since November 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
Obi_blob_p obi_get_blob_with_elt_idx_and_col_p_in_view(Obiview_p view, OBIDMS_column_p column_p, index_t line_nb, index_t element_idx);

// TODO
Obi_blob_p obi_get_blob_with_elt_idx_and_col_name_in_view(Obiview_p view, const char* column_name, index_t line_nb, index_t element_idx);


/**
 * @brief Recovers an obiblob from an OBIDMS column containing indices referring to obiblobs,
 *        using the name of the element in the line, in the context of a view.
 *
 * @param view A pointer on the opened view.
 * @param column_p A pointer on the 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 obiblob.
 * @retval OBIBlob_NA the NA value of the type if an error occurred and obi_errno is set.
 *
 * @since November 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
Obi_blob_p obi_get_blob_with_elt_name_and_col_p_in_view(Obiview_p view, OBIDMS_column_p column_p, index_t line_nb, const char* element_name);


// TODO
Obi_blob_p obi_get_blob_with_elt_name_and_col_name_in_view(Obiview_p view, const char* column_name, index_t line_nb, const char* element_name);


/**
 * @brief Sets a value in an OBIDMS column containing data with the type OBI_BOOL, using the index of the element in the line,
 *        in the context of a view.
 *
 *  Note: If the column is read-only or if there is a line selection associated with the view (making columns non-writable), it is cloned.
 *
 * @param view A pointer on the opened writable view.
 * @param column_p A pointer on the 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_set_bool_with_elt_idx_and_col_p_in_view(Obiview_p view, OBIDMS_column_p column_p, index_t line_nb, index_t element_idx, obibool_t value);

// TODO
int obi_set_bool_with_elt_idx_and_col_name_in_view(Obiview_p view, const char* column_name, 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, in the context of a view.
 *
 * @param view A pointer on the opened view.
 * @param column_p A pointer on the 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_get_bool_with_elt_idx_and_col_p_in_view(Obiview_p view, OBIDMS_column_p column_p, index_t line_nb, index_t element_idx);

// TODO
obibool_t obi_get_bool_with_elt_idx_and_col_name_in_view(Obiview_p view, const char* column_name, 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, in the context of a view.
 *
 * @param view A pointer on the opened writable view.
 * @param column_p A pointer on the 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_set_bool_with_elt_name_and_col_p_in_view(Obiview_p view, OBIDMS_column_p column_p, index_t line_nb, const char* element_name, obibool_t value);


// TODO
int obi_set_bool_with_elt_name_and_column_name_in_view(Obiview_p view, const char* column_name, 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, in the context of a view.
 *
 * @param view A pointer on the opened view.
 * @param column_p A pointer on the 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_get_bool_with_elt_name_and_col_p_in_view(Obiview_p view, OBIDMS_column_p column_p, index_t line_nb, const char* element_name);


// TODO
obibool_t obi_get_bool_with_elt_name_and_col_name_in_view(Obiview_p view, const char* column_name, 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,
 *        in the context of a view.
 *
 *  Note: If the column is read-only or if there is a line selection associated with the view (making columns non-writable), it is cloned.
 *
 * @param view A pointer on the opened writable view.
 * @param column A pointer on the 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_set_char_with_elt_idx_and_col_p_in_view(Obiview_p view, OBIDMS_column_p column_p, index_t line_nb, index_t element_idx, obichar_t value);


// TODO
int obi_set_char_with_elt_idx_and_col_name_in_view(Obiview_p view, const char* column_name, 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, in the context of a view.
 *
 * @param view A pointer on the opened view.
 * @param column A pointer on the 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_get_char_with_elt_idx_and_col_p_in_view(Obiview_p view, OBIDMS_column_p column_p, index_t line_nb, index_t element_idx);


// TODO
obichar_t obi_get_char_with_elt_idx_and_col_name_in_view(Obiview_p view, const char* column_name, 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, in the context of a view.
 *
 * @param view A pointer on the opened writable view.
 * @param column A pointer on the 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_set_char_with_elt_name_and_col_p_in_view(Obiview_p view, OBIDMS_column_p column_p, index_t line_nb, const char* element_name, obichar_t value);


// TODO
int obi_set_char_with_elt_name_and_col_name_in_view(Obiview_p view, const char* column_name, 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, in the context of a view.
 *
 * @param view A pointer on the opened view.
 * @param column A pointer on the 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_get_char_with_elt_name_and_col_p_in_view(Obiview_p view, OBIDMS_column_p column_p, index_t line_nb, const char* element_name);


// TODO
obichar_t obi_get_char_with_elt_name_and_col_name_in_view(Obiview_p view, const char* column_name, 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,
 *        in the context of a view.
 *
 *  Note: If the column is read-only or if there is a line selection associated with the view (making columns non-writable), it is cloned.
 *
 * @param view A pointer on the opened writable view.
 * @param column A pointer on the 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_set_float_with_elt_idx_and_col_p_in_view(Obiview_p view, OBIDMS_column_p column_p, index_t line_nb, index_t element_idx, obifloat_t value);


// TODO
int obi_set_float_with_elt_idx_and_col_name_in_view(Obiview_p view, const char* column_name, 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, in the context of a view.
 *
 * @param view A pointer on the opened view.
 * @param column A pointer on the 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_get_float_with_elt_idx_and_col_p_in_view(Obiview_p view, OBIDMS_column_p column_p, index_t line_nb, index_t element_idx);


// TODO
obifloat_t obi_get_float_with_elt_idx_and_col_name_in_view(Obiview_p view, const char* column_name, 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, in the context of a view.
 *
 * @param view A pointer on the opened writable view.
 * @param column A pointer on the 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_set_float_with_elt_name_and_col_p_in_view(Obiview_p view, OBIDMS_column_p column_p, index_t line_nb, const char* element_name, obifloat_t value);


// TODO
int obi_set_float_with_elt_name_and_col_name_in_view(Obiview_p view, const char* column_name, 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, in the context of a view.
 *
 * @param view A pointer on the opened view.
 * @param column A pointer on the 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_get_float_with_elt_name_and_col_p_in_view(Obiview_p view, OBIDMS_column_p column_p, index_t line_nb, const char* element_name);


// TODO
obifloat_t obi_get_float_with_elt_name_and_col_name_in_view(Obiview_p view, const char* column_name, 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,
 *        in the context of a view.
 *
 *  Note: If the column is read-only or if there is a line selection associated with the view (making columns non-writable), it is cloned.
 *
 * @param view A pointer on the opened writable view.
 * @param column A pointer on the 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_set_int_with_elt_idx_and_col_p_in_view(Obiview_p view, OBIDMS_column_p column_p, index_t line_nb, index_t element_idx, obiint_t value);


// TODO
int obi_set_int_with_elt_idx_and_col_name_in_view(Obiview_p view, const char* column_name, 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, in the context of a view.
 *
 * @param view A pointer on the opened view.
 * @param column A pointer on the 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 OBIInt_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_get_int_with_elt_idx_and_col_p_in_view(Obiview_p view, OBIDMS_column_p column_p, index_t line_nb, index_t element_idx);


// TODO
obiint_t obi_get_int_with_elt_idx_and_col_name_in_view(Obiview_p view, const char* column_name, 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, in the context of a view.
 *
 * @param view A pointer on the opened writable view.
 * @param column A pointer on the 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_set_int_with_elt_name_and_col_p_in_view(Obiview_p view, OBIDMS_column_p column_p, index_t line_nb, const char* element_name, obiint_t value);


// TODO
int obi_set_int_with_elt_name_and_col_name_in_view(Obiview_p view, const char* column_name, 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, in the context of a view.
 *
 * @param view A pointer on the opened view.
 * @param column A pointer on the 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 OBIInt_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_get_int_with_elt_name_and_col_p_in_view(Obiview_p view, OBIDMS_column_p column_p, index_t line_nb, const char* element_name);


// TODO
obiint_t obi_get_int_with_elt_name_and_col_name_in_view(Obiview_p view, const char* column_name, 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 sequence qualities handled by an indexer, and using the index of the element in the column's line,
 * 		  in the context of a view.
 *
 * This function is for qualities in the character string format.
 *
 * @warning Pointers returned by obi_open_column() don't allow writing.
 *
 * @param view A pointer on the opened view.
 * @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, in the character string format.
 *
 * @returns An integer value indicating the success of the operation.
 * @retval 0 on success.
 * @retval -1 if an error occurred.
 *
 * @since May 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
int obi_set_qual_char_with_elt_idx_and_col_p_in_view(Obiview_p view, OBIDMS_column_p column_p, index_t line_nb, index_t element_idx, const char* value);


// TODO
int obi_set_qual_char_with_elt_idx_and_col_name_in_view(Obiview_p view, const char* column_name, index_t line_nb, index_t element_idx, const char* value);


/**
 * @brief Sets a value in an OBIDMS column containing data in the form of indices referring
 * 		  to sequence qualities handled by an indexer, and using the index of the element in the column's line,
 * 		  in the context of a view.
 *
 * This function is for qualities in the integer format.
 *
 * @warning Pointers returned by obi_open_column() don't allow writing.
 *
 * @param view A pointer on the opened view.
 * @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, in the integer array format.
 * @param value_length The length of the integer array.
 *
 * @returns An integer value indicating the success of the operation.
 * @retval 0 on success.
 * @retval -1 if an error occurred.
 *
 * @since May 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
int obi_set_qual_int_with_elt_idx_and_col_p_in_view(Obiview_p view, OBIDMS_column_p column_p, index_t line_nb, index_t element_idx, const uint8_t* value, int value_length);


// TODO
int obi_set_qual_int_with_elt_idx_and_col_name_in_view(Obiview_p view, const char* column_name, index_t line_nb, index_t element_idx, const uint8_t* value, int value_length);


/**
 * @brief Recovers a value in an OBIDMS column containing data in the form of indices referring
 * 		  to sequence qualities handled by an indexer, and using the index of the element in the column's line,
 * 		  in the context of a view.
 *
 * This function returns quality scores in the character string format.
 *
 * @param view A pointer on the opened view.
 * @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, in the character string format.
 * @retval OBIQual_char_NA the NA value of the type if an error occurred and obi_errno is set.
 *
 * @since May 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
char* obi_get_qual_char_with_elt_idx_and_col_p_in_view(Obiview_p view, OBIDMS_column_p column_p, index_t line_nb, index_t element_idx);


// TODO
char* obi_get_qual_char_with_elt_idx_and_col_name_in_view(Obiview_p view, const char* column_name, index_t line_nb, index_t element_idx);


/**
 * @brief Recovers a value in an OBIDMS column containing data in the form of indices referring
 * 		  to sequence qualities handled by an indexer, and using the index of the element in the column's line,
 * 		  in the context of a view.
 *
 * This function returns quality scores in the integer format.
 *
 * @param view A pointer on the opened view.
 * @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.
 * @param value_length A pointer on an integer to store the length of the integer array recovered.
 *
 * @returns The recovered value, in the integer array format.
 * @retval OBIQual_int_NA the NA value of the type if an error occurred and obi_errno is set.
 *
 * @since May 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
const uint8_t* obi_get_qual_int_with_elt_idx_and_col_p_in_view(Obiview_p view, OBIDMS_column_p column_p, index_t line_nb, index_t element_idx, int* value_length);


// TODO
const uint8_t* obi_get_qual_int_with_elt_idx_and_col_name_in_view(Obiview_p view, const char* column_name, index_t line_nb, index_t element_idx, int* value_length);


/**
 * @brief Sets a value in an OBIDMS column containing data in the form of indices referring
 * 		  to sequence qualities handled by an indexer, and using the index of the element in the column's line,
 * 	 	  in the context of a view.
 *
 * This function is for quality scores in the character string format.
 *
 * @warning Pointers returned by obi_open_column() don't allow writing.
 *
 * @param view A pointer on the opened view.
 * @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, in the character string format.
 *
 * @returns An integer value indicating the success of the operation.
 * @retval 0 on success.
 * @retval -1 if an error occurred.
 *
 * @since May 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
int obi_set_qual_char_with_elt_name_and_col_p_in_view(Obiview_p view, OBIDMS_column_p column_p, index_t line_nb, const char* element_name, const char* value);


// TODO
int obi_set_qual_char_with_elt_name_and_col_name_in_view(Obiview_p view, const char* column_name, index_t line_nb, const char* element_name, const char* value);


/**
 * @brief Sets a value in an OBIDMS column containing data in the form of indices referring
 * 		  to sequence qualities handled by an indexer, and using the index of the element in the column's line,
 * 		  in the context of a view.
 *
 * This function is for quality scores in the integer array format.
 *
 * @warning Pointers returned by obi_open_column() don't allow writing.
 *
 * @param view A pointer on the opened view.
 * @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, in the integer format.
 * @param value_length The length of the integer array.
 *
 * @returns An integer value indicating the success of the operation.
 * @retval 0 on success.
 * @retval -1 if an error occurred.
 *
 * @since May 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
int obi_set_qual_int_with_elt_name_and_col_p_in_view(Obiview_p view, OBIDMS_column_p column_p, index_t line_nb, const char* element_name, const uint8_t* value, int value_length);


// TODO
int obi_set_qual_int_with_elt_name_and_col_name_in_view(Obiview_p view, const char* column_name, index_t line_nb, const char* element_name, const uint8_t* value, int value_length);


/**
 * @brief Recovers a value in an OBIDMS column containing data in the form of indices referring
 * 	      to sequence qualities handled by an indexer, and using the index of the element in the column's line,
 * 	  	  in the context of a view.
 *
 * This function returns quality scores in the character string format.
 *
 * @param view A pointer on the opened view.
 * @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, in the character string format.
 * @retval OBIQual_char_NA the NA value of the type if an error occurred and obi_errno is set.
 *
 * @since May 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
char* obi_get_qual_char_with_elt_name_and_col_p_in_view(Obiview_p view, OBIDMS_column_p column_p, index_t line_nb, const char* element_name);


// TODO
char* obi_get_qual_char_with_elt_name_and_col_name_in_view(Obiview_p view, const char* column_name, index_t line_nb, const char* element_name);


/**
 * @brief Recovers a value in an OBIDMS column containing data in the form of indices referring
 * 		  to sequence qualities handled by an indexer, and using the index of the element in the column's line,
 * 		  in the context of a view.
 *
 * This function returns quality scores in the integer array format.
 *
 * @param view A pointer on the opened view.
 * @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.
 * @param value_length A pointer on an integer to store the length of the integer array recovered.
 *
 * @returns The recovered value, in the integer format.
 * @retval OBIQual_int_NA the NA value of the type if an error occurred and obi_errno is set.
 *
 * @since May 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
const uint8_t* obi_get_qual_int_with_elt_name_and_col_p_in_view(Obiview_p view, OBIDMS_column_p column_p, index_t line_nb, const char* element_name, int* value_length);


// TODO
const uint8_t* obi_get_qual_int_with_elt_name_and_col_name_in_view(Obiview_p view, const char* column_name, index_t line_nb, const char* element_name, int* value_length);


/**
 * @brief Sets a value in an OBIDMS column containing data with the type OBI_SEQ, using the index of the element in the line,
 *        in the context of a view.
 *
 *  Note: If the column is read-only or if there is a line selection associated with the view (making columns non-writable), it is cloned.
 *
 * @param view A pointer on the opened writable view.
 * @param column A pointer on the 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_set_seq_with_elt_idx_and_col_p_in_view(Obiview_p view, OBIDMS_column_p column_p, index_t line_nb, index_t element_idx, const char* value);


// TODO
int obi_set_seq_with_elt_idx_and_col_name_in_view(Obiview_p view, const char* column_name, index_t line_nb, index_t element_idx, const char* value);


/**
 * @brief Recovers a value in an OBIDMS column containing data with the type OBI_SEQ, in the context of a view.
 *
 * @param view A pointer on the opened view.
 * @param column A pointer on the 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 OBISeq_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)
 */
char* obi_get_seq_with_elt_idx_and_col_p_in_view(Obiview_p view, OBIDMS_column_p column_p, index_t line_nb, index_t element_idx);


// TODO
char* obi_get_seq_with_elt_idx_and_col_name_in_view(Obiview_p view, const char* column_name, index_t line_nb, index_t element_idx);


/**
 * @brief Sets a value in an OBIDMS column containing data with the type OBI_SEQ,
 *        using the name of the element in the line, in the context of a view.
 *
 * @param view A pointer on the opened writable view.
 * @param column A pointer on the 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_set_seq_with_elt_name_and_col_p_in_view(Obiview_p view, OBIDMS_column_p column_p, index_t line_nb, const char* element_name, const char* value);


// TODO
int obi_set_seq_with_elt_name_and_col_name_in_view(Obiview_p view, const char* column_name, index_t line_nb, const char* element_name, const char* value);


/**
 * @brief Recovers a value in an OBIDMS column containing data with the type OBI_SEQ,
 *        using the name of the element in the line, in the context of a view.
 *
 * @param view A pointer on the opened view.
 * @param column A pointer on the 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 OBISeq_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)
 */
char* obi_get_seq_with_elt_name_and_col_p_in_view(Obiview_p view, OBIDMS_column_p column_p, index_t line_nb, const char* element_name);


// TODO
char* obi_get_seq_with_elt_name_and_col_name_in_view(Obiview_p view, const char* column_name, index_t line_nb, const char* element_name);


/**
 * @brief Sets a value in an OBIDMS column containing data with the type OBI_STR, using the index of the element in the line,
 *        in the context of a view.
 *
 *  Note: If the column is read-only or if there is a line selection associated with the view (making columns non-writable), it is cloned.
 *
 * @param view A pointer on the opened writable view.
 * @param column A pointer on the 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_set_str_with_elt_idx_and_col_p_in_view(Obiview_p view, OBIDMS_column_p column_p, index_t line_nb, index_t element_idx, const char* value);


// TODO
int obi_set_str_with_elt_idx_and_col_name_in_view(Obiview_p view, const char* column_name, index_t line_nb, index_t element_idx, const char* value);


/**
 * @brief Recovers a value in an OBIDMS column containing data with the type OBI_STR, in the context of a view.
 *
 * @param view A pointer on the opened view.
 * @param column A pointer on the 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 OBIStr_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)
 */
const char* obi_get_str_with_elt_idx_and_col_p_in_view(Obiview_p view, OBIDMS_column_p column_p, index_t line_nb, index_t element_idx);


// TODO
const char* obi_get_str_with_elt_idx_and_col_name_in_view(Obiview_p view, const char* column_name, index_t line_nb, index_t element_idx);


/**
 * @brief Sets a value in an OBIDMS column containing data with the type OBI_STR,
 *        using the name of the element in the line, in the context of a view.
 *
 * @param view A pointer on the opened writable view.
 * @param column A pointer on the 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_set_str_with_elt_name_and_col_p_in_view(Obiview_p view, OBIDMS_column_p column_p, index_t line_nb, const char* element_name, const char* value);


// TODO
int obi_set_str_with_elt_name_and_col_name_in_view(Obiview_p view, const char* column_name, index_t line_nb, const char* element_name, const char* value);


/**
 * @brief Recovers a value in an OBIDMS column containing data with the type OBI_STR,
 *        using the name of the element in the line, in the context of a view.
 *
 * @param view A pointer on the opened view.
 * @param column A pointer on the 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 OBIStr_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)
 */
const char* obi_get_str_with_elt_name_and_col_p_in_view(Obiview_p view, OBIDMS_column_p column_p, index_t line_nb, const char* element_name);


// TODO
const char* obi_get_str_with_elt_name_and_col_name_in_view(Obiview_p view, const char* column_name, index_t line_nb, const char* element_name);


/**
 * @brief Sets a value in an OBIDMS column containing indices, using the index of the element in the line,
 *        in the context of a view.
 *
 *  Note: If the column is read-only or if there is a line selection associated with the view (making columns non-writable), it is cloned.
 *
 *	Note: Columns containing indices refer to data stored elsewhere, for example lines in other columns,
 *	      or data stored in indexers.
 *
 * In the case of columns referring to values stored in indexers, this allows to directly set already-known
 * indices without going through the time-consuming step of indexing the value.
 *
 * @param view A pointer on the opened writable view.
 * @param column A pointer on the 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 November 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
int obi_set_index_with_elt_idx_and_col_p_in_view(Obiview_p view, OBIDMS_column_p column_p, index_t line_nb, index_t element_idx, index_t value);


// TODO
int obi_set_index_with_elt_idx_and_col_name_in_view(Obiview_p view, const char* column_name, index_t line_nb, index_t element_idx, index_t value);


/**
 * @brief Recovers a value in an OBIDMS column containing indexes, in the context of a view.
 *
 * This enables to recover the indexes in columns containing any type of indexed data (OBI_SEQ, OBI_STR...), for example to quickly test if
 * the values are identical (same index in the same indexer).
 *
 * @param view A pointer on the opened view.
 * @param column A pointer on the 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 OBIIdx_NA the NA value of the type if an error occurred and obi_errno is set.
 *
 * @since November 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
index_t obi_get_index_with_elt_idx_and_col_p_in_view(Obiview_p view, OBIDMS_column_p column_p, index_t line_nb, index_t element_idx);


// TODO
index_t obi_get_index_with_elt_idx_and_col_name_in_view(Obiview_p view, const char* column_name, index_t line_nb, index_t element_idx);


/**
 * @brief Sets a value in an OBIDMS column containing indices, using the index of the element in the line,
 *        in the context of a view.
 *
 *  Note: If the column is read-only or if there is a line selection associated with the view (making columns non-writable), it is cloned.
 *
 *	Note: Columns containing indices refer to data stored elsewhere, for example lines in other columns,
 *	      or data stored in indexers.
 *
 * In the case of columns referring to values stored in indexers, this allows to directly set already-known
 * indices without going through the time-consuming step of indexing the value.
 *
 * @param view A pointer on the opened writable view.
 * @param column A pointer on the 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 recovered 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 November 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
int obi_set_index_with_elt_name_and_col_p_in_view(Obiview_p view, OBIDMS_column_p column_p, index_t line_nb, const char* element_name, index_t value);


// TODO
int obi_set_index_with_elt_name_and_col_name_in_view(Obiview_p view, const char* column_name, index_t line_nb, const char* element_name, index_t value);


/**
 * @brief Recovers a value in an OBIDMS column containing indexes,
 *        using the name of the element in the line, in the context of a view.
 *
 * This enables to recover the indexes in columns containing any type of indexed data (OBI_SEQ, OBI_STR...), for example to quickly test if
 * the values are identical (same index in the same indexer).
 *
 * @param view A pointer on the opened view.
 * @param column A pointer on the 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 OBIIdx_NA the NA value of the type if an error occurred and obi_errno is set.
 *
 * @since November 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
index_t obi_get_index_with_elt_name_and_col_p_in_view(Obiview_p view, OBIDMS_column_p column_p, index_t line_nb, const char* element_name);


// TODO
index_t obi_get_index_with_elt_name_and_col_name_in_view(Obiview_p view, const char* column_name, index_t line_nb, const char* element_name);


#endif /* OBIVIEW_H_ */