/******************************************************************** * 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 #include "obidms.h" #include "obidmscolumn.h" #include "obierrno.h" #include "hashtable.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 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 { 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; /**< 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. */ char comments[OBIVIEW_COMMENTS_MAX_LENGTH+1]; /**< 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 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. */ 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. * @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 * - 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. * * @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 * - 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. * * @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 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 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 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); #endif /* OBIVIEW_H_ */