/******************************************************************** * 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 #include #include #include #include #include #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) /**< The maximum length of the comments associated * with a view. */ #define VIEW_TYPE_MAX_LENGTH (1024) /**< The maximum length of the type name of a view. */ #define OBIVIEW_FILE_NAME "obiviews" /**< The default name of a view file. */ #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. */ /** * @brief Structure for an opened view. */ typedef struct Obiview { OBIDMS_p dms; /**< A pointer on the DMS to which the view belongs. */ char name[OBIVIEW_NAME_MAX_LENGTH+1]; /**< Name of the view. */ char created_from[OBIVIEW_NAME_MAX_LENGTH+1]; /**< Name of the view from which that view was cloned if the view was cloned. */ char view_type[VIEW_TYPE_MAX_LENGTH+1]; /**< Type of the view if there is one. * Types existing: NUC_SEQS_VIEW. */ 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 new_line_selection; /**< A pointer on the column containing the new line selection being built * to associate with the view, if there is one. * When a line is selected with obi_select_line() or obi_select_lines(), * it is recorded in this line selection. */ index_t line_count; /**< The number of lines in the view. Refers to the number of lines in each * column of the view if line_selection is NULL, or to the line count of * line_selection if it is not NULL. */ int column_count; /**< The number of columns in the view. */ OBIDMS_column_p columns[MAX_NB_OPENED_COLUMNS]; /**< Array of pointers on all the columns of the view. */ char comments[OBIVIEW_COMMENTS_MAX_LENGTH+1]; /**< Comments, additional informations on the view. */ } Obiview_t, *Obiview_p; /** * @brief Structure referencing a column by its name and its version. */ 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 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 { int view_number; /**< Number of the view in the view file. */ time_t creation_date; /**< Time at which the view was written in the view file. */ 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; /**< Whether there is a line selection associated with the view. */ index_t line_count; /**< The number of lines in the view. */ int column_count; /**< The number of columns in the view. */ Column_reference_t column_references[MAX_NB_OPENED_COLUMNS]; /**< References (name and version) for all the columns in the view. */ char comments[OBIVIEW_COMMENTS_MAX_LENGTH+1]; /**< Comments, additional informations on the view. */ } Obiview_infos_t, *Obiview_infos_p; // TODO : Combine the common elements of the Obiview_infos and Obiview structures in one structure used by both? /** * @brief Structure for the header of view files. */ typedef struct Obiviews_header { size_t header_size; /**< Size of the header in bytes. */ size_t views_size; /**< Size of the views in bytes. */ int view_count; /**< Number of views saved. */ } Obiviews_header_t, *Obiviews_header_p; /** * @brief Structure for the information stored in view files. */ typedef struct Obiviews_infos_all { Obiviews_header_p header; /**< Pointer on the header of the view file. */ Obiview_infos_p view_infos; /**< Pointer on the beginning (first view) of the informations on views. */ } Obiviews_infos_all_t, *Obiviews_infos_all_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. * @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 * * @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. * * @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); /** * @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 * * @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 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); /** * @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 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, 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); /** * @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 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 Use 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). * * @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 Opens the structure containing all the informations written in the view file. * * @param dms A pointer on the OBIDMS to which the view file belongs. * * @returns A pointer on the view informations structure. * @retval NULL if an error occurred. * * @since February 2016 * @author Celine Mercier (celine.mercier@metabarcoding.org) */ Obiviews_infos_all_p obi_read_view_infos(OBIDMS_p dms); /** * @brief Closes the structure containing all the informations written in the view file. * * @param views A pointer on the view informations 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 February 2016 * @author Celine Mercier (celine.mercier@metabarcoding.org) */ int obi_close_view_infos(Obiviews_infos_all_p views); // TODO in following functions would it be better to use column names instead of column pointers? // check if it would be a gain or loss of time /** * @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 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_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, 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 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, 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_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, 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 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, * 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_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, 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_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, 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_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, 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_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, * 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_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, 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_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, 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_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, 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_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, * 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_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, 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_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, 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_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, 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_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 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_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 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_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 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_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 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_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 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_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 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_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 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_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 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_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_ */