From 8cdfbb379ea858b62cc35c474fe490e343a880c2 Mon Sep 17 00:00:00 2001 From: Celine Mercier Date: Mon, 25 Apr 2016 17:58:12 +0200 Subject: [PATCH] Documentation for views and reworked the code a little --- python/obitools3/obidms/capi/obiview.pxd | 39 +- src/obiview.c | 55 +- src/obiview.h | 745 +++++++++++++++++------ 3 files changed, 618 insertions(+), 221 deletions(-) diff --git a/python/obitools3/obidms/capi/obiview.pxd b/python/obitools3/obidms/capi/obiview.pxd index f383238..8c8ff54 100644 --- a/python/obitools3/obidms/capi/obiview.pxd +++ b/python/obitools3/obidms/capi/obiview.pxd @@ -20,6 +20,22 @@ cdef extern from "obiview.h" nogil: extern const_char_p ID_COLUMN extern const_char_p DEFINITION_COLUMN + struct Obiview_t : + OBIDMS_p dms + const_char_p name + const_char_p created_from + const_char_p view_type + bint read_only + OBIDMS_column_p line_selection + OBIDMS_column_p new_line_selection + index_t line_count + int column_count + OBIDMS_column_p columns + const_char_p comments + + ctypedef Obiview_t* Obiview_p + + struct Column_reference_t : const_char_p column_name obiversion_t version @@ -27,32 +43,17 @@ cdef extern from "obiview.h" nogil: ctypedef Column_reference_t* Column_reference_p - struct Obiview_t : - OBIDMS_p dms - const_char_p name - OBIDMS_column_p line_selection - OBIDMS_column_p new_line_selection - OBIDMS_column_p columns - bint read_only - Column_reference_t line_selection_reference - index_t line_count - int column_count - const_char_p comments - - ctypedef Obiview_t* Obiview_p - - struct Obiview_infos_t : int view_number - int column_count - index_t line_count + time_t creation_date const_char_p name const_char_p created_from - time_t creation_date + const_char_p view_type bint all_lines Column_reference_t line_selection + index_t line_count + int column_count Column_reference_p column_references - const_char_p view_type const_char_p comments ctypedef Obiview_infos_t* Obiview_infos_p diff --git a/src/obiview.c b/src/obiview.c index 223df1b..4d0b4a6 100644 --- a/src/obiview.c +++ b/src/obiview.c @@ -78,12 +78,41 @@ static char* build_obiview_file_name(); int create_obiview_file(int dms_file_descriptor); -// TODO doc +/** + * Internal function preparing to set a value in a column, in the context of a view. + * + * The function checks that the view is not read-only, clones the column or all columns if needed, + * and updates the line count if needed. + * + * @param view The view. + * @param column_pp A pointer on the pointer on the column, to allow replacing the column if it is cloned. + * @param line_nb_p A pointer on the index of the line that will be modified, to allow replacing it if needed. + * + * @retval 0 if the operation was successfully completed. + * @retval -1 if an error occurred. + * + * @since April 2016 + * @author Celine Mercier (celine.mercier@metabarcoding.org) + */ int prepare_to_set_value_in_column(Obiview_p view, OBIDMS_column_p* column_pp, index_t* line_nb_p); -// TODO doc -int prepare_to_get_value_in_column(Obiview_p view, OBIDMS_column_p column, index_t* line_nb_p); +/** + * Internal function preparing to get a value from a column, in the context of a view. + * + * The function checks that the line index is not beyond the current line count of the view, + * and modifies it if there is a line selection associated with the view. + * + * @param view The view. + * @param line_nb_p A pointer on the index of the line, to allow replacing it if needed. + * + * @retval 0 if the operation was successfully completed. + * @retval -1 if an error occurred. + * + * @since April 2016 + * @author Celine Mercier (celine.mercier@metabarcoding.org) + */ +int prepare_to_get_value_from_column(Obiview_p view, index_t* line_nb_p); /************************************************************************ @@ -256,7 +285,7 @@ int prepare_to_set_value_in_column(Obiview_p view, OBIDMS_column_p* column_pp, i } -int prepare_to_get_value_from_column(Obiview_p view, OBIDMS_column_p column, index_t* line_nb_p) +int prepare_to_get_value_from_column(Obiview_p view, index_t* line_nb_p) { if (((*line_nb_p)+1) > (view->line_count)) { @@ -379,7 +408,7 @@ Obiview_p obi_new_view(OBIDMS_p dms, const char* view_name, Obiview_p view_to_cl return NULL; view->line_count = view_to_clone->line_count; } - // If there is a new line selection, build it by combining it with the pre-existing one if there is one + // If there is a new line selection, build it by combining it with the one from the view to clone if there is one else if (line_selection != NULL) { view->line_selection = obi_create_column(view->dms, LINES_COLUMN_NAME, OBI_IDX, 0, 1, LINES_COLUMN_NAME, NULL, NULL); @@ -566,7 +595,7 @@ Obiview_p obi_open_view(OBIDMS_p dms, const char* view_name) return NULL; } - // Find and open view that should be read with the line selection associated + // Find and open the view that should be read with the line selection associated view_number = -1; if (view_name == NULL) // If view name is NULL, open the latest view TODO discuss view_number = (header->view_count) - 1; @@ -927,7 +956,7 @@ int obi_select_line(Obiview_p view, index_t line_nb) return -1; } - // If column for line selection doesn't already exists, create it and store its informations + // If the column for line selection doesn't already exists, create it and store its informations if ((view->new_line_selection) == NULL) { view->new_line_selection = obi_create_column(view->dms, LINES_COLUMN_NAME, OBI_IDX, 0, 1, LINES_COLUMN_NAME, NULL, NULL); @@ -1240,7 +1269,7 @@ int obi_column_set_obibool_with_elt_idx_in_view(Obiview_p view, OBIDMS_column_p 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) { - if (prepare_to_get_value_from_column(view, column, &line_nb) < 0) + if (prepare_to_get_value_from_column(view, &line_nb) < 0) return OBIBool_NA; return obi_column_get_obibool_with_elt_idx(column, line_nb, element_idx); } @@ -1278,7 +1307,7 @@ int obi_column_set_obichar_with_elt_idx_in_view(Obiview_p view, OBIDMS_column_p 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) { - if (prepare_to_get_value_from_column(view, column, &line_nb) < 0) + if (prepare_to_get_value_from_column(view, &line_nb) < 0) return OBIChar_NA; return obi_column_get_obichar_with_elt_idx(column, line_nb, element_idx); } @@ -1316,7 +1345,7 @@ int obi_column_set_obifloat_with_elt_idx_in_view(Obiview_p view, OBIDMS_column_p 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) { - if (prepare_to_get_value_from_column(view, column, &line_nb) < 0) + if (prepare_to_get_value_from_column(view, &line_nb) < 0) return OBIFloat_NA; return obi_column_get_obifloat_with_elt_idx(column, line_nb, element_idx); } @@ -1354,7 +1383,7 @@ int obi_column_set_obiint_with_elt_idx_in_view(Obiview_p view, OBIDMS_column_p c 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) { - if (prepare_to_get_value_from_column(view, column, &line_nb) < 0) + if (prepare_to_get_value_from_column(view, &line_nb) < 0) return OBIInt_NA; return obi_column_get_obiint_with_elt_idx(column, line_nb, element_idx); } @@ -1392,7 +1421,7 @@ int obi_column_set_obiseq_with_elt_idx_in_view(Obiview_p view, OBIDMS_column_p c 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) { - if (prepare_to_get_value_from_column(view, column, &line_nb) < 0) + if (prepare_to_get_value_from_column(view, &line_nb) < 0) return OBISeq_NA; return obi_column_get_obiseq_with_elt_idx(column, line_nb, element_idx); } @@ -1430,7 +1459,7 @@ int obi_column_set_obistr_with_elt_idx_in_view(Obiview_p view, OBIDMS_column_p c 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) { - if (prepare_to_get_value_from_column(view, column, &line_nb) < 0) + if (prepare_to_get_value_from_column(view, &line_nb) < 0) return OBIStr_NA; return obi_column_get_obistr_with_elt_idx(column, line_nb, element_idx); } diff --git a/src/obiview.h b/src/obiview.h index ec0d0c3..1b0095d 100644 --- a/src/obiview.h +++ b/src/obiview.h @@ -26,30 +26,82 @@ #include "obierrno.h" -#define OBIVIEW_NAME_MAX_LENGTH (1000) /**< The maximum length of an OBIDMS view name. - */ -#define OBIVIEW_COMMENTS_MAX_LENGTH (10000) - -#define OBIVIEW_FILE_NAME "obiviews" - -#define VIEW_TYPE_MAX_NAME (1024) - -#define VIEW_TYPE_NUC_SEQS "NUC_SEQS_VIEW" - -#define NUC_SEQUENCE_COLUMN "NUC_SEQ" -#define NUC_SEQUENCE_INDEXER "NUC_SEQ_INDEXER" - -#define ID_COLUMN "ID" -#define ID_INDEXER "ID_INDEXER" - -#define DEFINITION_COLUMN "DEFINITION" -#define DEFINITION_INDEXER "DEFINITION_INDEXER" - -#define LINES_COLUMN_NAME "LINES" +#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 NUC_SEQUENCE_INDEXER "NUC_SEQ_INDEXER" /**< The name of the indexer 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 ID_INDEXER "ID_INDEXER" /**< The name of the indexer 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 DEFINITION_INDEXER "DEFINITION_INDEXER" /**< The name of the indexer containing the sequence definitions + * in NUC_SEQS_VIEW views. + */ /** - * @brief . + * @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_NAME+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. @@ -60,101 +112,237 @@ typedef struct Column_reference { /** - * @brief . - */ -typedef struct Obiview { - - OBIDMS_p dms; - - bool read_only; - - OBIDMS_column_p line_selection; - - OBIDMS_column_p new_line_selection; - - index_t line_count; - - int column_count; - - OBIDMS_column_p columns[MAX_NB_OPENED_COLUMNS]; - - char name[OBIVIEW_NAME_MAX_LENGTH+1]; - - char created_from[OBIVIEW_NAME_MAX_LENGTH+1]; - - int view_number; - - char view_type[VIEW_TYPE_MAX_NAME+1]; - - char comments[OBIVIEW_COMMENTS_MAX_LENGTH+1]; - -} Obiview_t, *Obiview_p; - - -/** - * @brief . + * @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; - - int column_count; - - index_t line_count; - - char name[OBIVIEW_NAME_MAX_LENGTH+1]; - - char created_from[OBIVIEW_NAME_MAX_LENGTH+1]; - - time_t creation_date; - - bool all_lines; - - Column_reference_t line_selection; - - Column_reference_t column_references[MAX_NB_OPENED_COLUMNS]; - - char view_type[VIEW_TYPE_MAX_NAME+1]; - - char comments[OBIVIEW_COMMENTS_MAX_LENGTH+1]; - + 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_NAME+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 . + * @brief Structure for the header of view files. */ typedef struct Obiviews_header { - size_t header_size; - size_t views_size; - int view_count; + 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 . + * @brief Structure for the information stored in view files. */ typedef struct Obiviews_infos_all { - Obiviews_header_p header; - - Obiview_infos_p view_infos; - + 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; -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. + * + * 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); -Obiviews_infos_all_p obi_read_views(OBIDMS_p dms); -int obi_unmap_read_views(Obiviews_infos_all_p views); +/** + * @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); + + +/** + * @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, @@ -166,35 +354,202 @@ int obi_view_add_column(Obiview_p view, 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); -int obi_select_line(Obiview_p view, index_t line_nb); - -int obi_select_lines(Obiview_p view, index_t* line_nbs); - -int obi_view_update_lines(Obiview_p view, index_t line_count); - -OBIDMS_column_p obi_view_clone_column(Obiview_p view, const char* column_name); - -OBIDMS_column_p obi_view_get_column(Obiview_p view, const char* column_name); - -OBIDMS_column_p* obi_view_get_pointer_on_column_in_view(Obiview_p view, const char* column_name); - -int obi_save_view(Obiview_p view); - -int obi_close_view(Obiview_p view); - -int obi_save_and_close_view(Obiview_p view); - -int obi_column_set_obibool_with_elt_idx_in_view(Obiview_p view, OBIDMS_column_p column, index_t line_nb, index_t element_idx, obibool_t value); - /** - * @brief Sets a value in an OBIDMS column containing data with the type OBI_BOOL, using the index of the element in the line. + * @brief Selects a line in the context of a view. * - * @warning Pointers returned by obi_open_column() don't allow writing. + * If no line selection exists for the view, it will be created. * - * @param column A pointer as returned by obi_create_column() or obi_clone_column(). + * @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 Update the line count in the context of a view. + * + * All columns of the view are enlarged to contain at least the new line count. + * + * @warning The view must be writable. + * + * @param view A pointer on the view. + * @param line_count The new line count. + * + * @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_update_lines(Obiview_p view, index_t line_count); + + +/** + * @brief Clones a column in the context of a view. + * + * Clones with the right line selection and replaces the cloned columns with the new ones in the view. + * If there is a line selection, all columns have to be cloned, otherwise only the column of interest is cloned. + * + * @param view A pointer on the view. + * @param column_name The name of the column in the view that should be cloned. + * + * @returns A pointer on the new column. + * @retval NULL if an error occurred. + * + * @since February 2016 + * @author Celine Mercier (celine.mercier@metabarcoding.org) + */ +OBIDMS_column_p obi_view_clone_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 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); + + +// 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. @@ -210,9 +565,10 @@ int obi_column_set_obibool_with_elt_idx_in_view(Obiview_p view, OBIDMS_column_p /** - * @brief Recovers a value in an OBIDMS column containing data with the type OBI_BOOL. + * @brief Recovers a value in an OBIDMS column containing data with the type OBI_BOOL, in the context of a view. * - * @param column A pointer as returned by obi_create_column(). + * @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. * @@ -227,11 +583,10 @@ obibool_t obi_column_get_obibool_with_elt_idx_in_view(Obiview_p view, OBIDMS_col /** * @brief Sets a value in an OBIDMS column containing data with the type OBI_BOOL, - * using the name of the element in the line. + * using the name of the element in the line, in the context of a view. * - * @warning Pointers returned by obi_open_column() don't allow writing. - * - * @param column A pointer as returned by obi_create_column() or obi_clone_column(). + * @param 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. @@ -248,9 +603,10 @@ int obi_column_set_obibool_with_elt_name_in_view(Obiview_p view, OBIDMS_column_p /** * @brief Recovers a value in an OBIDMS column containing data with the type OBI_BOOL, - * using the name of the element in the line. + * using the name of the element in the line, in the context of a view. * - * @param column A pointer as returned by obi_create_column() or obi_clone_column(). + * @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. * @@ -264,11 +620,13 @@ obibool_t obi_column_get_obibool_with_elt_name_in_view(Obiview_p view, OBIDMS_co /** - * @brief Sets a value in an OBIDMS column containing data with the type OBI_CHAR, using the index of the element in the line. + * @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. * - * @warning Pointers returned by obi_open_column() don't allow writing. + * 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 column A pointer as returned by obi_create_column() or obi_clone_column(). + * @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. @@ -284,9 +642,10 @@ int obi_column_set_obichar_with_elt_idx_in_view(Obiview_p view, OBIDMS_column_p /** - * @brief Recovers a value in an OBIDMS column containing data with the type OBI_CHAR. + * @brief Recovers a value in an OBIDMS column containing data with the type OBI_CHAR, in the context of a view. * - * @param column A pointer as returned by obi_create_column(). + * @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. * @@ -301,11 +660,10 @@ obichar_t obi_column_get_obichar_with_elt_idx_in_view(Obiview_p view, OBIDMS_col /** * @brief Sets a value in an OBIDMS column containing data with the type OBI_CHAR, - * using the name of the element in the line. + * using the name of the element in the line, in the context of a view. * - * @warning Pointers returned by obi_open_column() don't allow writing. - * - * @param column A pointer as returned by obi_create_column() or obi_clone_column(). + * @param 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. @@ -322,9 +680,10 @@ int obi_column_set_obichar_with_elt_name_in_view(Obiview_p view, OBIDMS_column_p /** * @brief Recovers a value in an OBIDMS column containing data with the type OBI_CHAR, - * using the name of the element in the line. + * using the name of the element in the line, in the context of a view. * - * @param column A pointer as returned by obi_create_column() or obi_clone_column(). + * @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. * @@ -338,11 +697,13 @@ obichar_t obi_column_get_obichar_with_elt_name_in_view(Obiview_p view, OBIDMS_co /** - * @brief Sets a value in an OBIDMS column containing data with the type OBI_FLOAT, using the index of the element in the line. + * @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. * - * @warning Pointers returned by obi_open_column() don't allow writing. + * 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 column A pointer as returned by obi_create_column() or obi_clone_column(). + * @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. @@ -358,9 +719,10 @@ int obi_column_set_obifloat_with_elt_idx_in_view(Obiview_p view, OBIDMS_column_p /** - * @brief Recovers a value in an OBIDMS column containing data with the type OBI_FLOAT. + * @brief Recovers a value in an OBIDMS column containing data with the type OBI_FLOAT, in the context of a view. * - * @param column A pointer as returned by obi_create_column(). + * @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. * @@ -375,11 +737,10 @@ obifloat_t obi_column_get_obifloat_with_elt_idx_in_view(Obiview_p view, OBIDMS_c /** * @brief Sets a value in an OBIDMS column containing data with the type OBI_FLOAT, - * using the name of the element in the line. + * using the name of the element in the line, in the context of a view. * - * @warning Pointers returned by obi_open_column() don't allow writing. - * - * @param column A pointer as returned by obi_create_column() or obi_clone_column(). + * @param 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. @@ -396,9 +757,10 @@ int obi_column_set_obifloat_with_elt_name_in_view(Obiview_p view, OBIDMS_column_ /** * @brief Recovers a value in an OBIDMS column containing data with the type OBI_FLOAT, - * using the name of the element in the line. + * using the name of the element in the line, in the context of a view. * - * @param column A pointer as returned by obi_create_column() or obi_clone_column(). + * @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. * @@ -412,11 +774,13 @@ obifloat_t obi_column_get_obifloat_with_elt_name_in_view(Obiview_p view, OBIDMS_ /** - * @brief Sets a value in an OBIDMS column containing data with the type OBI_INT, using the index of the element in the line. + * @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. * - * @warning Pointers returned by obi_open_column() don't allow writing. + * 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 column A pointer as returned by obi_create_column() or obi_clone_column(). + * @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. @@ -432,14 +796,15 @@ int obi_column_set_obiint_with_elt_idx_in_view(Obiview_p view, OBIDMS_column_p c /** - * @brief Recovers a value in an OBIDMS column containing data with the type OBI_INT. + * @brief Recovers a value in an OBIDMS column containing data with the type OBI_INT, in the context of a view. * - * @param column A pointer as returned by obi_create_column(). + * @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. + * @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) @@ -449,11 +814,10 @@ obiint_t obi_column_get_obiint_with_elt_idx_in_view(Obiview_p view, OBIDMS_colum /** * @brief Sets a value in an OBIDMS column containing data with the type OBI_INT, - * using the name of the element in the line. + * using the name of the element in the line, in the context of a view. * - * @warning Pointers returned by obi_open_column() don't allow writing. - * - * @param column A pointer as returned by obi_create_column() or obi_clone_column(). + * @param 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. @@ -470,14 +834,15 @@ int obi_column_set_obiint_with_elt_name_in_view(Obiview_p view, OBIDMS_column_p /** * @brief Recovers a value in an OBIDMS column containing data with the type OBI_INT, - * using the name of the element in the line. + * using the name of the element in the line, in the context of a view. * - * @param column A pointer as returned by obi_create_column() or obi_clone_column(). + * @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. + * @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) @@ -486,12 +851,13 @@ obiint_t obi_column_get_obiint_with_elt_name_in_view(Obiview_p view, OBIDMS_colu /** - * @brief Sets a value in an OBIDMS column containing data in the form of indices referring - * to DNA sequences handled by an indexer, using the index of the element in the line. + * @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. * - * @warning Pointers returned by obi_open_column() don't allow writing. + * 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 column A pointer as returned by obi_create_column() or obi_clone_column(). + * @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. @@ -507,15 +873,15 @@ int obi_column_set_obiseq_with_elt_idx_in_view(Obiview_p view, OBIDMS_column_p c /** - * @brief Recovers a value in an OBIDMS column containing data in the form of indices referring - * to DNA sequences handled by an indexer, using the index of the element in the line. + * @brief Recovers a value in an OBIDMS column containing data with the type OBI_SEQ, in the context of a view. * - * @param column A pointer as returned by obi_create_column(). + * @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 '\0' the NA value of the type if an error occurred and obi_errno is set. + * @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) @@ -524,12 +890,11 @@ char* obi_column_get_obiseq_with_elt_idx_in_view(Obiview_p view, OBIDMS_column_p /** - * @brief Sets a value in an OBIDMS column containing data in the form of indices referring - * to DNA sequences handled by an indexer, using the name of the element in the line. + * @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. * - * @warning Pointers returned by obi_open_column() don't allow writing. - * - * @param column A pointer as returned by obi_create_column() or obi_clone_column(). + * @param 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. @@ -545,15 +910,16 @@ int obi_column_set_obiseq_with_elt_name_in_view(Obiview_p view, OBIDMS_column_p /** - * @brief Recovers a value in an OBIDMS column containing data in the form of indices referring - * to DNA sequences handled by an indexer, using the name of the element in the line. + * @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 column A pointer as returned by obi_create_column() or obi_clone_column(). + * @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 '\0' the NA value of the type if an error occurred and obi_errno is set. + * @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) @@ -562,12 +928,13 @@ char* obi_column_get_obiseq_with_elt_name_in_view(Obiview_p view, OBIDMS_column_ /** - * @brief Sets a value in an OBIDMS column containing data in the form of indices referring - * to character strings handled by an indexer, using the index of the element in the line. + * @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. * - * @warning Pointers returned by obi_open_column() don't allow writing. + * 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 column A pointer as returned by obi_create_column() or obi_clone_column(). + * @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. @@ -583,15 +950,15 @@ int obi_column_set_obistr_with_elt_idx_in_view(Obiview_p view, OBIDMS_column_p c /** - * @brief Recovers a value in an OBIDMS column containing data in the form of indices referring - * to character strings handled by an indexer, using the index of the element in the line. + * @brief Recovers a value in an OBIDMS column containing data with the type OBI_STR, in the context of a view. * - * @param column A pointer as returned by obi_create_column(). + * @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 '\0' the NA value of the type if an error occurred and obi_errno is set. + * @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) @@ -600,12 +967,11 @@ const char* obi_column_get_obistr_with_elt_idx_in_view(Obiview_p view, OBIDMS_co /** - * @brief Sets a value in an OBIDMS column containing data in the form of indices referring - * to character strings handled by an indexer, using the name of the element in the line. + * @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. * - * @warning Pointers returned by obi_open_column() don't allow writing. - * - * @param column A pointer as returned by obi_create_column() or obi_clone_column(). + * @param 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. @@ -621,15 +987,16 @@ int obi_column_set_obistr_with_elt_name_in_view(Obiview_p view, OBIDMS_column_p /** - * @brief Recovers a value in an OBIDMS column containing data in the form of indices referring - * to character strings handled by an indexer, using the name of the element in the line. + * @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 column A pointer as returned by obi_create_column() or obi_clone_column(). + * @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 '\0' the NA value of the type if an error occurred and obi_errno is set. + * @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)