obitools/obitools3
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 66 Wiki Activity

Documentation for views and reworked the code a little

Browse Source
This commit is contained in:
Celine Mercier
2016-04-25 17:58:12 +02:00
parent 0a55e26520
commit 8cdfbb379e
3 changed files with 618 additions and 221 deletions
Download Patch File Download Diff File Expand all files Collapse all files

39
python/obitools3/obidms/capi/obiview.pxd
View File

@ -20,6 +20,22 @@ cdef extern from "obiview.h" nogil:
extern const_char_p ID_COLUMN extern const_char_p ID_COLUMN
extern const_char_p DEFINITION_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 : struct Column_reference_t :
const_char_p column_name const_char_p column_name
obiversion_t version obiversion_t version
@ -27,32 +43,17 @@ cdef extern from "obiview.h" nogil:
ctypedef Column_reference_t* Column_reference_p 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 : struct Obiview_infos_t :
int view_number int view_number
int column_count time_t creation_date
index_t line_count
const_char_p name const_char_p name
const_char_p created_from const_char_p created_from
time_t creation_date const_char_p view_type
bint all_lines bint all_lines
Column_reference_t line_selection Column_reference_t line_selection
index_t line_count
int column_count
Column_reference_p column_references Column_reference_p column_references
const_char_p view_type
const_char_p comments const_char_p comments
ctypedef Obiview_infos_t* Obiview_infos_p ctypedef Obiview_infos_t* Obiview_infos_p

55
src/obiview.c
View File

@ -78,12 +78,41 @@ static char* build_obiview_file_name();
int create_obiview_file(int dms_file_descriptor); 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); 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)) 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; return NULL;
view->line_count = view_to_clone->line_count; 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) 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); 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; 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; view_number = -1;
if (view_name == NULL) // If view name is NULL, open the latest view TODO discuss if (view_name == NULL) // If view name is NULL, open the latest view TODO discuss
view_number = (header->view_count) - 1; view_number = (header->view_count) - 1;
@ -927,7 +956,7 @@ int obi_select_line(Obiview_p view, index_t line_nb)
return -1; 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) 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); 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) 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 OBIBool_NA;
return obi_column_get_obibool_with_elt_idx(column, line_nb, element_idx); 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) 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 OBIChar_NA;
return obi_column_get_obichar_with_elt_idx(column, line_nb, element_idx); 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) 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 OBIFloat_NA;
return obi_column_get_obifloat_with_elt_idx(column, line_nb, element_idx); 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) 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 OBIInt_NA;
return obi_column_get_obiint_with_elt_idx(column, line_nb, element_idx); 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) 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 OBISeq_NA;
return obi_column_get_obiseq_with_elt_idx(column, line_nb, element_idx); 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) 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 OBIStr_NA;
return obi_column_get_obistr_with_elt_idx(column, line_nb, element_idx); return obi_column_get_obistr_with_elt_idx(column, line_nb, element_idx);
} }

741
src/obiview.h
View File

@ -28,28 +28,80 @@
#define OBIVIEW_NAME_MAX_LENGTH (1000) /**< The maximum length of an OBIDMS view name. #define OBIVIEW_NAME_MAX_LENGTH (1000) /**< The maximum length of an OBIDMS view name.
*/ */
#define OBIVIEW_COMMENTS_MAX_LENGTH (10000) #define OBIVIEW_COMMENTS_MAX_LENGTH (10000) /**< The maximum length of the comments associated
* with a view.
#define OBIVIEW_FILE_NAME "obiviews" */
#define VIEW_TYPE_MAX_LENGTH (1024) /**< The maximum length of the type name of a view.
#define VIEW_TYPE_MAX_NAME (1024) */
#define OBIVIEW_FILE_NAME "obiviews" /**< The default name of a view file.
#define VIEW_TYPE_NUC_SEQS "NUC_SEQS_VIEW" */
#define LINES_COLUMN_NAME "LINES" /**< The name of the column containing the line selections
#define NUC_SEQUENCE_COLUMN "NUC_SEQ" * in all views.
#define NUC_SEQUENCE_INDEXER "NUC_SEQ_INDEXER" */
#define VIEW_TYPE_NUC_SEQS "NUC_SEQS_VIEW" /**< The type name of views based on nucleotide sequences
#define ID_COLUMN "ID" * and their metadata.
#define ID_INDEXER "ID_INDEXER" */
#define NUC_SEQUENCE_COLUMN "NUC_SEQ" /**< The name of the column containing the nucleotide sequences
#define DEFINITION_COLUMN "DEFINITION" * in NUC_SEQS_VIEW views.
#define DEFINITION_INDEXER "DEFINITION_INDEXER" */
#define NUC_SEQUENCE_INDEXER "NUC_SEQ_INDEXER" /**< The name of the indexer containing the nucleotide sequences
#define LINES_COLUMN_NAME "LINES" * 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 { typedef struct Column_reference {
char column_name[OBIDMS_COLUMN_MAX_NAME+1]; /**< Name of the column. char column_name[OBIDMS_COLUMN_MAX_NAME+1]; /**< Name of the column.
@ -60,101 +112,237 @@ typedef struct Column_reference {
/** /**
* @brief . * @brief Structure for a closed view stored in the view file.
*/ * Views are identified by their name.
typedef struct Obiview { * Once a view has been written in the view file, it can not be modified and can only be read.
OBIDMS_p dms;
bool read_only;
OBIDMS_column_p line_selection;
OBIDMS_column_p new_line_selection;
index_t line_count;
int column_count;
OBIDMS_column_p columns[MAX_NB_OPENED_COLUMNS];
char name[OBIVIEW_NAME_MAX_LENGTH+1];
char created_from[OBIVIEW_NAME_MAX_LENGTH+1];
int view_number;
char view_type[VIEW_TYPE_MAX_NAME+1];
char comments[OBIVIEW_COMMENTS_MAX_LENGTH+1];
} Obiview_t, *Obiview_p;
/**
* @brief .
*/ */
typedef struct Obiview_infos { typedef struct Obiview_infos {
int view_number; int view_number; /**< Number of the view in the view file.
*/
int column_count; time_t creation_date; /**< Time at which the view was written in the view file.
*/
index_t line_count; char name[OBIVIEW_NAME_MAX_LENGTH+1]; /**< Name of the view, used to identify it.
*/
char name[OBIVIEW_NAME_MAX_LENGTH+1]; char created_from[OBIVIEW_NAME_MAX_LENGTH+1]; /**< Name of the view from which that view was cloned, if it was cloned.
*/
char created_from[OBIVIEW_NAME_MAX_LENGTH+1]; char view_type[VIEW_TYPE_MAX_NAME+1]; /**< Type of the view if there is one.
* Types existing: NUC_SEQS_VIEW.
time_t creation_date; */
bool all_lines; /**< Whether there is a line selection associated with the view.
bool all_lines; */
Column_reference_t line_selection; /**< Whether there is a line selection associated with the view.
Column_reference_t line_selection; */
index_t line_count; /**< The number of lines in the view.
Column_reference_t column_references[MAX_NB_OPENED_COLUMNS]; */
int column_count; /**< The number of columns in the view.
char view_type[VIEW_TYPE_MAX_NAME+1]; */
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]; */
char comments[OBIVIEW_COMMENTS_MAX_LENGTH+1]; /**< Comments, additional informations on the view.
*/
} Obiview_infos_t, *Obiview_infos_p; } 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 { typedef struct Obiviews_header {
size_t header_size; size_t header_size; /**< Size of the header in bytes.
size_t views_size; */
int view_count; size_t views_size; /**< Size of the views in bytes.
*/
int view_count; /**< Number of views saved.
*/
} Obiviews_header_t, *Obiviews_header_p; } Obiviews_header_t, *Obiviews_header_p;
/** /**
* @brief . * @brief Structure for the information stored in view files.
*/ */
typedef struct Obiviews_infos_all { typedef struct Obiviews_infos_all {
Obiviews_header_p header; Obiviews_header_p header; /**< Pointer on the header of the view file.
*/
Obiview_infos_p view_infos; Obiview_infos_p view_infos; /**< Pointer on the beginning (first view) of the informations on views.
*/
} Obiviews_infos_all_t, *Obiviews_infos_all_p; } 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); 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); 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); 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); 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, int obi_view_add_column(Obiview_p view,
const char* column_name, const char* column_name,
obiversion_t version_number, obiversion_t version_number,
@ -166,35 +354,202 @@ int obi_view_add_column(Obiview_p view,
const char* comments, const char* comments,
bool create); 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_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 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 element_idx The index of the element that should be set in the line.
* @param value The value that should be set. * @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 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 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, * @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 view A pointer on the opened writable view.
* * @param column A pointer on the column.
* @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 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 element_name The name of the element that should be set in the line.
* @param value The value that should be set. * @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, * @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 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 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 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 element_idx The index of the element that should be set in the line.
* @param value The value that should be set. * @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 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 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, * @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 view A pointer on the opened writable view.
* * @param column A pointer on the column.
* @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 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 element_name The name of the element that should be set in the line.
* @param value The value that should be set. * @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, * @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 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 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 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 element_idx The index of the element that should be set in the line.
* @param value The value that should be set. * @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 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 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, * @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 view A pointer on the opened writable view.
* * @param column A pointer on the column.
* @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 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 element_name The name of the element that should be set in the line.
* @param value The value that should be set. * @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, * @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 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 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 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 element_idx The index of the element that should be set in the line.
* @param value The value that should be set. * @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 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 element_idx The index of the element that should be recovered in the line.
* *
* @returns The recovered value. * @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 * @since February 2016
* @author Celine Mercier (celine.mercier@metabarcoding.org) * @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, * @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 view A pointer on the opened writable view.
* * @param column A pointer on the column.
* @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 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 element_name The name of the element that should be set in the line.
* @param value The value that should be set. * @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, * @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 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 element_name The name of the element that should be recovered in the line.
* *
* @returns The recovered value. * @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 * @since February 2016
* @author Celine Mercier (celine.mercier@metabarcoding.org) * @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 * @brief Sets a value in an OBIDMS column containing data with the type OBI_SEQ, using the index of the element in the line,
* to DNA sequences handled by an indexer, 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 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 element_idx The index of the element that should be set in the line.
* @param value The value that should be set. * @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 * @brief Recovers a value in an OBIDMS column containing data with the type OBI_SEQ, in the context of a view.
* to DNA sequences handled by an indexer, using the index of the element in the line.
* *
* @param column A pointer as returned by obi_create_column(). * @param 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 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 element_idx The index of the element that should be recovered in the line.
* *
* @returns The recovered value. * @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 * @since February 2016
* @author Celine Mercier (celine.mercier@metabarcoding.org) * @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 * @brief Sets a value in an OBIDMS column containing data with the type OBI_SEQ,
* to DNA sequences handled by an indexer, 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 view A pointer on the opened writable view.
* * @param column A pointer on the column.
* @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 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 element_name The name of the element that should be set in the line.
* @param value The value that should be set. * @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 * @brief Recovers a value in an OBIDMS column containing data with the type OBI_SEQ,
* to DNA sequences handled by an indexer, 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 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 element_name The name of the element that should be recovered in the line.
* *
* @returns The recovered value. * @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 * @since February 2016
* @author Celine Mercier (celine.mercier@metabarcoding.org) * @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 * @brief Sets a value in an OBIDMS column containing data with the type OBI_STR, using the index of the element in the line,
* to character strings handled by an indexer, 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 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 element_idx The index of the element that should be set in the line.
* @param value The value that should be set. * @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 * @brief Recovers a value in an OBIDMS column containing data with the type OBI_STR, in the context of a view.
* to character strings handled by an indexer, using the index of the element in the line.
* *
* @param column A pointer as returned by obi_create_column(). * @param 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 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 element_idx The index of the element that should be recovered in the line.
* *
* @returns The recovered value. * @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 * @since February 2016
* @author Celine Mercier (celine.mercier@metabarcoding.org) * @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 * @brief Sets a value in an OBIDMS column containing data with the type OBI_STR,
* to character strings handled by an indexer, 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 view A pointer on the opened writable view.
* * @param column A pointer on the column.
* @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 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 element_name The name of the element that should be set in the line.
* @param value The value that should be set. * @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 * @brief Recovers a value in an OBIDMS column containing data with the type OBI_STR,
* to character strings handled by an indexer, 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 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 element_name The name of the element that should be recovered in the line.
* *
* @returns The recovered value. * @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 * @since February 2016
* @author Celine Mercier (celine.mercier@metabarcoding.org) * @author Celine Mercier (celine.mercier@metabarcoding.org)