From e60497651c6a7e821cb4b781316fce45d982afb2 Mon Sep 17 00:00:00 2001 From: Celine Mercier Date: Wed, 30 Nov 2016 12:22:47 +0100 Subject: [PATCH] Updated the documentation for the functions to set and get in the context of a view --- src/obiview.h | 903 +++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 776 insertions(+), 127 deletions(-) diff --git a/src/obiview.h b/src/obiview.h index de34e0d..df842da 100644 --- a/src/obiview.h +++ b/src/obiview.h @@ -497,7 +497,8 @@ int obi_save_and_close_view(Obiview_p view); /** - * @brief Recovers an obiblob from an OBIDMS column containing indices referring to obiblobs, in the context of a view. + * @brief Recovers an obiblob from an OBIDMS column containing indices referring to obiblobs, + * using the index of the element in the line, and the column pointer, in the context of a view. * * @param view A pointer on the opened view. * @param column_p A pointer on the column. @@ -512,13 +513,28 @@ int obi_save_and_close_view(Obiview_p view); */ Obi_blob_p obi_get_blob_with_elt_idx_and_col_p_in_view(Obiview_p view, OBIDMS_column_p column_p, index_t line_nb, index_t element_idx); -// TODO + +/** + * @brief Recovers an obiblob from an OBIDMS column containing indices referring to obiblobs, + * using the index of the element in the line, and the column name, in the context of a view. + * + * @param view A pointer on the opened view. + * @param column_name The alias of the column in the view. + * @param line_nb The number of the line where the value should be recovered. + * @param element_idx The index of the element that should be recovered in the line. + * + * @returns The recovered obiblob. + * @retval OBIBlob_NA the NA value of the type if an error occurred and obi_errno is set. + * + * @since November 2016 + * @author Celine Mercier (celine.mercier@metabarcoding.org) + */ Obi_blob_p obi_get_blob_with_elt_idx_and_col_name_in_view(Obiview_p view, const char* column_name, index_t line_nb, index_t element_idx); /** * @brief Recovers an obiblob from an OBIDMS column containing indices referring to obiblobs, - * using the name of the element in the line, in the context of a view. + * using the name of the element in the line, and the column pointer, in the context of a view. * * @param view A pointer on the opened view. * @param column_p A pointer on the column. @@ -534,13 +550,27 @@ Obi_blob_p obi_get_blob_with_elt_idx_and_col_name_in_view(Obiview_p view, const Obi_blob_p obi_get_blob_with_elt_name_and_col_p_in_view(Obiview_p view, OBIDMS_column_p column_p, index_t line_nb, const char* element_name); -// TODO +/** + * @brief Recovers an obiblob from an OBIDMS column containing indices referring to obiblobs, + * using the name of the element in the line, and the column name, in the context of a view. + * + * @param view A pointer on the opened view. + * @param column_name The alias of the column in the view. + * @param line_nb The number of the line where the value should be recovered. + * @param element_name The name of the element that should be recovered in the line. + * + * @returns The recovered obiblob. + * @retval OBIBlob_NA the NA value of the type if an error occurred and obi_errno is set. + * + * @since November 2016 + * @author Celine Mercier (celine.mercier@metabarcoding.org) + */ Obi_blob_p obi_get_blob_with_elt_name_and_col_name_in_view(Obiview_p view, const char* column_name, index_t line_nb, const char* element_name); /** - * @brief Sets a value in an OBIDMS column containing data with the type OBI_BOOL, using the index of the element in the line, - * in the context of a view. + * @brief Sets a value in an OBIDMS column containing data with the type OBI_BOOL, + * using the index of the element in the line, and the column pointer, 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. * @@ -559,12 +589,32 @@ Obi_blob_p obi_get_blob_with_elt_name_and_col_name_in_view(Obiview_p view, const */ int obi_set_bool_with_elt_idx_and_col_p_in_view(Obiview_p view, OBIDMS_column_p column_p, index_t line_nb, index_t element_idx, obibool_t value); -// TODO + +/** + * @brief Sets a value in an OBIDMS column containing data with the type OBI_BOOL, + * using the index of the element in the line, and the column name, 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_name The alias of the column in the view. + * @param line_nb The number of the line where the value should be set. + * @param element_idx The index of the element that should be set in the line. + * @param value The value that should be set. + * + * @returns An integer value indicating the success of the operation. + * @retval 0 on success. + * @retval -1 if an error occurred. + * + * @since August 2016 + * @author Celine Mercier (celine.mercier@metabarcoding.org) + */ int obi_set_bool_with_elt_idx_and_col_name_in_view(Obiview_p view, const char* column_name, index_t line_nb, index_t element_idx, obibool_t value); /** - * @brief Recovers a value in an OBIDMS column containing data with the type OBI_BOOL, in the context of a view. + * @brief Recovers a value in an OBIDMS column containing data with the type OBI_BOOL, + * using the index of the element in the line, and the column pointer, in the context of a view. * * @param view A pointer on the opened view. * @param column_p A pointer on the column. @@ -579,13 +629,28 @@ int obi_set_bool_with_elt_idx_and_col_name_in_view(Obiview_p view, const char* c */ obibool_t obi_get_bool_with_elt_idx_and_col_p_in_view(Obiview_p view, OBIDMS_column_p column_p, index_t line_nb, index_t element_idx); -// TODO + +/** + * @brief Recovers a value in an OBIDMS column containing data with the type OBI_BOOL, + * using the index of the element in the line, and the column name, in the context of a view. + * + * @param view A pointer on the opened view. + * @param column_name The alias of the column in the view. + * @param line_nb The number of the line where the value should be recovered. + * @param element_idx The index of the element that should be recovered in the line. + * + * @returns The recovered value. + * @retval OBIBool_NA the NA value of the type if an error occurred and obi_errno is set. + * + * @since August 2016 + * @author Celine Mercier (celine.mercier@metabarcoding.org) + */ obibool_t obi_get_bool_with_elt_idx_and_col_name_in_view(Obiview_p view, const char* column_name, index_t line_nb, index_t element_idx); /** * @brief Sets a value in an OBIDMS column containing data with the type OBI_BOOL, - * using the name of the element in the line, in the context of a view. + * using the name of the element in the line, and the column pointer, in the context of a view. * * @param view A pointer on the opened writable view. * @param column_p A pointer on the column. @@ -603,13 +668,29 @@ obibool_t obi_get_bool_with_elt_idx_and_col_name_in_view(Obiview_p view, const c int obi_set_bool_with_elt_name_and_col_p_in_view(Obiview_p view, OBIDMS_column_p column_p, index_t line_nb, const char* element_name, obibool_t value); -// TODO +/** + * @brief Sets a value in an OBIDMS column containing data with the type OBI_BOOL, + * using the name of the element in the line, and the column name, in the context of a view. + * + * @param view A pointer on the opened writable view. + * @param column_name The alias of the column in the view. + * @param line_nb The number of the line where the value should be set. + * @param element_name The name of the element that should be set in the line. + * @param value The value that should be set. + * + * @returns An integer value indicating the success of the operation. + * @retval 0 on success. + * @retval -1 if an error occurred. + * + * @since August 2016 + * @author Celine Mercier (celine.mercier@metabarcoding.org) + */ int obi_set_bool_with_elt_name_and_column_name_in_view(Obiview_p view, const char* column_name, index_t line_nb, const char* element_name, obibool_t value); /** * @brief Recovers a value in an OBIDMS column containing data with the type OBI_BOOL, - * using the name of the element in the line, in the context of a view. + * using the name of the element in the line, and the column pointer, in the context of a view. * * @param view A pointer on the opened view. * @param column_p A pointer on the column. @@ -625,18 +706,32 @@ int obi_set_bool_with_elt_name_and_column_name_in_view(Obiview_p view, const cha obibool_t obi_get_bool_with_elt_name_and_col_p_in_view(Obiview_p view, OBIDMS_column_p column_p, index_t line_nb, const char* element_name); -// TODO +/** + * @brief Recovers a value in an OBIDMS column containing data with the type OBI_BOOL, + * using the name of the element in the line, and the column name, in the context of a view. + * + * @param view A pointer on the opened view. + * @param column_name The alias of the column in the view. + * @param line_nb The number of the line where the value should be recovered. + * @param element_name The name of the element that should be recovered in the line. + * + * @returns The recovered value. + * @retval OBIBool_NA the NA value of the type if an error occurred and obi_errno is set. + * + * @since August 2016 + * @author Celine Mercier (celine.mercier@metabarcoding.org) + */ obibool_t obi_get_bool_with_elt_name_and_col_name_in_view(Obiview_p view, const char* column_name, index_t line_nb, const char* element_name); /** - * @brief Sets a value in an OBIDMS column containing data with the type OBI_CHAR, using the index of the element in the line, - * in the context of a view. + * @brief Sets a value in an OBIDMS column containing data with the type OBI_CHAR, + * using the index of the element in the line, and the column pointer, 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 column_p A pointer on the column. * @param line_nb The number of the line where the value should be set. * @param element_idx The index of the element that should be set in the line. * @param value The value that should be set. @@ -651,15 +746,34 @@ obibool_t obi_get_bool_with_elt_name_and_col_name_in_view(Obiview_p view, const int obi_set_char_with_elt_idx_and_col_p_in_view(Obiview_p view, OBIDMS_column_p column_p, index_t line_nb, index_t element_idx, obichar_t value); -// TODO +/** + * @brief Sets a value in an OBIDMS column containing data with the type OBI_CHAR, + * using the index of the element in the line, and the column name, 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_name The alias of the column in the view. + * @param line_nb The number of the line where the value should be set. + * @param element_idx The index of the element that should be set in the line. + * @param value The value that should be set. + * + * @returns An integer value indicating the success of the operation. + * @retval 0 on success. + * @retval -1 if an error occurred. + * + * @since August 2016 + * @author Celine Mercier (celine.mercier@metabarcoding.org) + */ int obi_set_char_with_elt_idx_and_col_name_in_view(Obiview_p view, const char* column_name, index_t line_nb, index_t element_idx, obichar_t value); /** - * @brief Recovers a value in an OBIDMS column containing data with the type OBI_CHAR, in the context of a view. + * @brief Recovers a value in an OBIDMS column containing data with the type OBI_CHAR, + * using the index of the element in the line, and the column pointer, in the context of a view. * * @param view A pointer on the opened view. - * @param column A pointer on the column. + * @param column_p A pointer on the column. * @param line_nb The number of the line where the value should be recovered. * @param element_idx The index of the element that should be recovered in the line. * @@ -672,16 +786,30 @@ int obi_set_char_with_elt_idx_and_col_name_in_view(Obiview_p view, const char* c obichar_t obi_get_char_with_elt_idx_and_col_p_in_view(Obiview_p view, OBIDMS_column_p column_p, index_t line_nb, index_t element_idx); -// TODO +/** + * @brief Recovers a value in an OBIDMS column containing data with the type OBI_CHAR, + * using the index of the element in the line, and the column name, in the context of a view. + * + * @param view A pointer on the opened view. + * @param column_name The alias of the column in the view. + * @param line_nb The number of the line where the value should be recovered. + * @param element_idx The index of the element that should be recovered in the line. + * + * @returns The recovered value. + * @retval OBIChar_NA the NA value of the type if an error occurred and obi_errno is set. + * + * @since August 2016 + * @author Celine Mercier (celine.mercier@metabarcoding.org) + */ obichar_t obi_get_char_with_elt_idx_and_col_name_in_view(Obiview_p view, const char* column_name, index_t line_nb, index_t element_idx); /** * @brief Sets a value in an OBIDMS column containing data with the type OBI_CHAR, - * using the name of the element in the line, in the context of a view. + * using the name of the element in the line, and the column pointer, in the context of a view. * * @param view A pointer on the opened writable view. - * @param column A pointer on the column. + * @param column_p A pointer on the column. * @param line_nb The number of the line where the value should be set. * @param element_name The name of the element that should be set in the line. * @param value The value that should be set. @@ -696,16 +824,32 @@ obichar_t obi_get_char_with_elt_idx_and_col_name_in_view(Obiview_p view, const c int obi_set_char_with_elt_name_and_col_p_in_view(Obiview_p view, OBIDMS_column_p column_p, index_t line_nb, const char* element_name, obichar_t value); -// TODO +/** + * @brief Sets a value in an OBIDMS column containing data with the type OBI_CHAR, + * using the name of the element in the line, and the column name, in the context of a view. + * + * @param view A pointer on the opened writable view. + * @param column_name The alias of the column in the view. + * @param line_nb The number of the line where the value should be set. + * @param element_name The name of the element that should be set in the line. + * @param value The value that should be set. + * + * @returns An integer value indicating the success of the operation. + * @retval 0 on success. + * @retval -1 if an error occurred. + * + * @since August 2016 + * @author Celine Mercier (celine.mercier@metabarcoding.org) + */ int obi_set_char_with_elt_name_and_col_name_in_view(Obiview_p view, const char* column_name, index_t line_nb, const char* element_name, obichar_t value); /** * @brief Recovers a value in an OBIDMS column containing data with the type OBI_CHAR, - * using the name of the element in the line, in the context of a view. + * using the name of the element in the line, and the column pointer, in the context of a view. * * @param view A pointer on the opened view. - * @param column A pointer on the column. + * @param column_p A pointer on the column. * @param line_nb The number of the line where the value should be recovered. * @param element_name The name of the element that should be recovered in the line. * @@ -718,18 +862,32 @@ int obi_set_char_with_elt_name_and_col_name_in_view(Obiview_p view, const char* obichar_t obi_get_char_with_elt_name_and_col_p_in_view(Obiview_p view, OBIDMS_column_p column_p, index_t line_nb, const char* element_name); -// TODO +/** + * @brief Recovers a value in an OBIDMS column containing data with the type OBI_CHAR, + * using the name of the element in the line, and the column name, in the context of a view. + * + * @param view A pointer on the opened view. + * @param column_name The alias of the column in the view. + * @param line_nb The number of the line where the value should be recovered. + * @param element_name The name of the element that should be recovered in the line. + * + * @returns The recovered value. + * @retval OBIChar_NA the NA value of the type if an error occurred and obi_errno is set. + * + * @since August 2016 + * @author Celine Mercier (celine.mercier@metabarcoding.org) + */ obichar_t obi_get_char_with_elt_name_and_col_name_in_view(Obiview_p view, const char* column_name, index_t line_nb, const char* element_name); /** - * @brief Sets a value in an OBIDMS column containing data with the type OBI_FLOAT, using the index of the element in the line, - * in the context of a view. + * @brief Sets a value in an OBIDMS column containing data with the type OBI_FLOAT, + * using the index of the element in the line, and the column pointer, 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 column_p A pointer on the column. * @param line_nb The number of the line where the value should be set. * @param element_idx The index of the element that should be set in the line. * @param value The value that should be set. @@ -744,15 +902,34 @@ obichar_t obi_get_char_with_elt_name_and_col_name_in_view(Obiview_p view, const int obi_set_float_with_elt_idx_and_col_p_in_view(Obiview_p view, OBIDMS_column_p column_p, index_t line_nb, index_t element_idx, obifloat_t value); -// TODO +/** + * @brief Sets a value in an OBIDMS column containing data with the type OBI_FLOAT, + * using the index of the element in the line, and the column name, 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_name The alias of the column in the view. + * @param line_nb The number of the line where the value should be set. + * @param element_idx The index of the element that should be set in the line. + * @param value The value that should be set. + * + * @returns An integer value indicating the success of the operation. + * @retval 0 on success. + * @retval -1 if an error occurred. + * + * @since August 2016 + * @author Celine Mercier (celine.mercier@metabarcoding.org) + */ int obi_set_float_with_elt_idx_and_col_name_in_view(Obiview_p view, const char* column_name, index_t line_nb, index_t element_idx, obifloat_t value); /** - * @brief Recovers a value in an OBIDMS column containing data with the type OBI_FLOAT, in the context of a view. + * @brief Recovers a value in an OBIDMS column containing data with the type OBI_FLOAT, + * using the index of the element in the line, and the column pointer, in the context of a view. * * @param view A pointer on the opened view. - * @param column A pointer on the column. + * @param column_p A pointer on the column. * @param line_nb The number of the line where the value should be recovered. * @param element_idx The index of the element that should be recovered in the line. * @@ -765,16 +942,30 @@ int obi_set_float_with_elt_idx_and_col_name_in_view(Obiview_p view, const char* obifloat_t obi_get_float_with_elt_idx_and_col_p_in_view(Obiview_p view, OBIDMS_column_p column_p, index_t line_nb, index_t element_idx); -// TODO +/** + * @brief Recovers a value in an OBIDMS column containing data with the type OBI_FLOAT, + * using the index of the element in the line, and the column name, in the context of a view. + * + * @param view A pointer on the opened view. + * @param column_name The alias of the column in the view. + * @param line_nb The number of the line where the value should be recovered. + * @param element_idx The index of the element that should be recovered in the line. + * + * @returns The recovered value. + * @retval OBIFloat_NA the NA value of the type if an error occurred and obi_errno is set. + * + * @since August 2016 + * @author Celine Mercier (celine.mercier@metabarcoding.org) + */ obifloat_t obi_get_float_with_elt_idx_and_col_name_in_view(Obiview_p view, const char* column_name, index_t line_nb, index_t element_idx); /** * @brief Sets a value in an OBIDMS column containing data with the type OBI_FLOAT, - * using the name of the element in the line, in the context of a view. + * using the name of the element in the line, and the column pointer, in the context of a view. * * @param view A pointer on the opened writable view. - * @param column A pointer on the column. + * @param column_p A pointer on the column. * @param line_nb The number of the line where the value should be set. * @param element_name The name of the element that should be set in the line. * @param value The value that should be set. @@ -789,16 +980,32 @@ obifloat_t obi_get_float_with_elt_idx_and_col_name_in_view(Obiview_p view, const int obi_set_float_with_elt_name_and_col_p_in_view(Obiview_p view, OBIDMS_column_p column_p, index_t line_nb, const char* element_name, obifloat_t value); -// TODO +/** + * @brief Sets a value in an OBIDMS column containing data with the type OBI_FLOAT, + * using the name of the element in the line, and the column name, in the context of a view. + * + * @param view A pointer on the opened writable view. + * @param column_name The alias of the column in the view. + * @param line_nb The number of the line where the value should be set. + * @param element_name The name of the element that should be set in the line. + * @param value The value that should be set. + * + * @returns An integer value indicating the success of the operation. + * @retval 0 on success. + * @retval -1 if an error occurred. + * + * @since August 2016 + * @author Celine Mercier (celine.mercier@metabarcoding.org) + */ int obi_set_float_with_elt_name_and_col_name_in_view(Obiview_p view, const char* column_name, index_t line_nb, const char* element_name, obifloat_t value); /** * @brief Recovers a value in an OBIDMS column containing data with the type OBI_FLOAT, - * using the name of the element in the line, in the context of a view. + * using the name of the element in the line, and the column pointer, in the context of a view. * * @param view A pointer on the opened view. - * @param column A pointer on the column. + * @param column_p A pointer on the column. * @param line_nb The number of the line where the value should be recovered. * @param element_name The name of the element that should be recovered in the line. * @@ -811,18 +1018,32 @@ int obi_set_float_with_elt_name_and_col_name_in_view(Obiview_p view, const char* obifloat_t obi_get_float_with_elt_name_and_col_p_in_view(Obiview_p view, OBIDMS_column_p column_p, index_t line_nb, const char* element_name); -// TODO +/** + * @brief Recovers a value in an OBIDMS column containing data with the type OBI_FLOAT, + * using the name of the element in the line, and the column name, in the context of a view. + * + * @param view A pointer on the opened view. + * @param column_name The alias of the column in the view. + * @param line_nb The number of the line where the value should be recovered. + * @param element_name The name of the element that should be recovered in the line. + * + * @returns The recovered value. + * @retval OBIFloat_NA the NA value of the type if an error occurred and obi_errno is set. + * + * @since August 2016 + * @author Celine Mercier (celine.mercier@metabarcoding.org) + */ obifloat_t obi_get_float_with_elt_name_and_col_name_in_view(Obiview_p view, const char* column_name, index_t line_nb, const char* element_name); /** - * @brief Sets a value in an OBIDMS column containing data with the type OBI_INT, using the index of the element in the line, - * in the context of a view. + * @brief Sets a value in an OBIDMS column containing data with the type OBI_INT, + * using the index of the element in the line, and the column pointer, 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 column_p A pointer on the column. * @param line_nb The number of the line where the value should be set. * @param element_idx The index of the element that should be set in the line. * @param value The value that should be set. @@ -837,15 +1058,34 @@ obifloat_t obi_get_float_with_elt_name_and_col_name_in_view(Obiview_p view, cons int obi_set_int_with_elt_idx_and_col_p_in_view(Obiview_p view, OBIDMS_column_p column_p, index_t line_nb, index_t element_idx, obiint_t value); -// TODO +/** + * @brief Sets a value in an OBIDMS column containing data with the type OBI_INT, + * using the index of the element in the line, and the column name, 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_name The alias of the column in the view. + * @param line_nb The number of the line where the value should be set. + * @param element_idx The index of the element that should be set in the line. + * @param value The value that should be set. + * + * @returns An integer value indicating the success of the operation. + * @retval 0 on success. + * @retval -1 if an error occurred. + * + * @since August 2016 + * @author Celine Mercier (celine.mercier@metabarcoding.org) + */ int obi_set_int_with_elt_idx_and_col_name_in_view(Obiview_p view, const char* column_name, index_t line_nb, index_t element_idx, obiint_t value); /** - * @brief Recovers a value in an OBIDMS column containing data with the type OBI_INT, in the context of a view. + * @brief Recovers a value in an OBIDMS column containing data with the type OBI_INT, + * using the index of the element in the line, and the column pointer, in the context of a view. * * @param view A pointer on the opened view. - * @param column A pointer on the column. + * @param column_p A pointer on the column. * @param line_nb The number of the line where the value should be recovered. * @param element_idx The index of the element that should be recovered in the line. * @@ -858,16 +1098,30 @@ int obi_set_int_with_elt_idx_and_col_name_in_view(Obiview_p view, const char* co obiint_t obi_get_int_with_elt_idx_and_col_p_in_view(Obiview_p view, OBIDMS_column_p column_p, index_t line_nb, index_t element_idx); -// TODO +/** + * @brief Recovers a value in an OBIDMS column containing data with the type OBI_INT, + * using the index of the element in the line, and the column name, in the context of a view. + * + * @param view A pointer on the opened view. + * @param column_name The alias of the column in the view. + * @param line_nb The number of the line where the value should be recovered. + * @param element_idx The index of the element that should be recovered in the line. + * + * @returns The recovered value. + * @retval OBIInt_NA the NA value of the type if an error occurred and obi_errno is set. + * + * @since August 2016 + * @author Celine Mercier (celine.mercier@metabarcoding.org) + */ obiint_t obi_get_int_with_elt_idx_and_col_name_in_view(Obiview_p view, const char* column_name, index_t line_nb, index_t element_idx); /** * @brief Sets a value in an OBIDMS column containing data with the type OBI_INT, - * using the name of the element in the line, in the context of a view. + * using the index of the element in the line, and the column pointer, in the context of a view. * * @param view A pointer on the opened writable view. - * @param column A pointer on the column. + * @param column_p A pointer on the column. * @param line_nb The number of the line where the value should be set. * @param element_name The name of the element that should be set in the line. * @param value The value that should be set. @@ -882,16 +1136,32 @@ obiint_t obi_get_int_with_elt_idx_and_col_name_in_view(Obiview_p view, const cha int obi_set_int_with_elt_name_and_col_p_in_view(Obiview_p view, OBIDMS_column_p column_p, index_t line_nb, const char* element_name, obiint_t value); -// TODO +/** + * @brief Sets a value in an OBIDMS column containing data with the type OBI_INT, + * using the index of the element in the line, and the column name, in the context of a view. + * + * @param view A pointer on the opened writable view. + * @param column_name The alias of the column in the view. + * @param line_nb The number of the line where the value should be set. + * @param element_name The name of the element that should be set in the line. + * @param value The value that should be set. + * + * @returns An integer value indicating the success of the operation. + * @retval 0 on success. + * @retval -1 if an error occurred. + * + * @since August 2016 + * @author Celine Mercier (celine.mercier@metabarcoding.org) + */ int obi_set_int_with_elt_name_and_col_name_in_view(Obiview_p view, const char* column_name, index_t line_nb, const char* element_name, obiint_t value); /** * @brief Recovers a value in an OBIDMS column containing data with the type OBI_INT, - * using the name of the element in the line, in the context of a view. + * using the name of the element in the line, and the column pointer, in the context of a view. * * @param view A pointer on the opened view. - * @param column A pointer on the column. + * @param column_p A pointer on the column. * @param line_nb The number of the line where the value should be recovered. * @param element_name The name of the element that should be recovered in the line. * @@ -904,21 +1174,35 @@ int obi_set_int_with_elt_name_and_col_name_in_view(Obiview_p view, const char* c obiint_t obi_get_int_with_elt_name_and_col_p_in_view(Obiview_p view, OBIDMS_column_p column_p, index_t line_nb, const char* element_name); -// TODO +/** + * @brief Recovers a value in an OBIDMS column containing data with the type OBI_INT, + * using the name of the element in the line, and the column name, in the context of a view. + * + * @param view A pointer on the opened view. + * @param column_name The alias of the column in the view. + * @param line_nb The number of the line where the value should be recovered. + * @param element_name The name of the element that should be recovered in the line. + * + * @returns The recovered value. + * @retval OBIInt_NA the NA value of the type if an error occurred and obi_errno is set. + * + * @since August 2016 + * @author Celine Mercier (celine.mercier@metabarcoding.org) + */ obiint_t obi_get_int_with_elt_name_and_col_name_in_view(Obiview_p view, const char* column_name, index_t line_nb, const char* element_name); /** * @brief Sets a value in an OBIDMS column containing data in the form of indices referring - * to sequence qualities handled by an indexer, and using the index of the element in the column's line, - * in the context of a view. + * to sequence qualities handled by an indexer (OBI_QUAL data type), + * using the index of the element in the line, and the column pointer, in the context of a view. * * This function is for qualities in the character string format. * * @warning Pointers returned by obi_open_column() don't allow writing. * * @param view A pointer on the opened view. - * @param column A pointer as returned by obi_create_column() or obi_clone_column(). + * @param column_p A pointer as returned by obi_create_column() or obi_clone_column(). * @param line_nb The number of the line where the value should be set. * @param element_idx The index of the element that should be set in the line. * @param value The value that should be set, in the character string format. @@ -933,21 +1217,42 @@ obiint_t obi_get_int_with_elt_name_and_col_name_in_view(Obiview_p view, const ch int obi_set_qual_char_with_elt_idx_and_col_p_in_view(Obiview_p view, OBIDMS_column_p column_p, index_t line_nb, index_t element_idx, const char* value); -// TODO +/** + * @brief Sets a value in an OBIDMS column containing data in the form of indices referring + * to sequence qualities handled by an indexer (OBI_QUAL data type), + * using the index of the element in the line, and the column name, in the context of a view. + * + * This function is for qualities in the character string format. + * + * @warning Pointers returned by obi_open_column() don't allow writing. + * + * @param view A pointer on the opened view. + * @param column_name The alias of the column in the view. + * @param line_nb The number of the line where the value should be set. + * @param element_idx The index of the element that should be set in the line. + * @param value The value that should be set, in the character string format. + * + * @returns An integer value indicating the success of the operation. + * @retval 0 on success. + * @retval -1 if an error occurred. + * + * @since August 2016 + * @author Celine Mercier (celine.mercier@metabarcoding.org) + */ int obi_set_qual_char_with_elt_idx_and_col_name_in_view(Obiview_p view, const char* column_name, index_t line_nb, index_t element_idx, const char* value); /** * @brief Sets a value in an OBIDMS column containing data in the form of indices referring - * to sequence qualities handled by an indexer, and using the index of the element in the column's line, - * in the context of a view. + * to sequence qualities handled by an indexer (OBI_QUAL data type), + * using the index of the element in the line, and the column pointer, in the context of a view. * - * This function is for qualities in the integer format. + * This function is for qualities in the integer array format. * * @warning Pointers returned by obi_open_column() don't allow writing. * * @param view A pointer on the opened view. - * @param column A pointer as returned by obi_create_column() or obi_clone_column(). + * @param column_p A pointer as returned by obi_create_column() or obi_clone_column(). * @param line_nb The number of the line where the value should be set. * @param element_idx The index of the element that should be set in the line. * @param value The value that should be set, in the integer array format. @@ -963,19 +1268,41 @@ int obi_set_qual_char_with_elt_idx_and_col_name_in_view(Obiview_p view, const ch int obi_set_qual_int_with_elt_idx_and_col_p_in_view(Obiview_p view, OBIDMS_column_p column_p, index_t line_nb, index_t element_idx, const uint8_t* value, int value_length); -// TODO +/** + * @brief Sets a value in an OBIDMS column containing data in the form of indices referring + * to sequence qualities handled by an indexer (OBI_QUAL data type), + * using the index of the element in the line, and the column name, in the context of a view. + * + * This function is for qualities in the integer array format. + * + * @warning Pointers returned by obi_open_column() don't allow writing. + * + * @param view A pointer on the opened view. + * @param column_name The alias of the column in the view. + * @param line_nb The number of the line where the value should be set. + * @param element_idx The index of the element that should be set in the line. + * @param value The value that should be set, in the integer array format. + * @param value_length The length of the integer array. + * + * @returns An integer value indicating the success of the operation. + * @retval 0 on success. + * @retval -1 if an error occurred. + * + * @since August 2016 + * @author Celine Mercier (celine.mercier@metabarcoding.org) + */ int obi_set_qual_int_with_elt_idx_and_col_name_in_view(Obiview_p view, const char* column_name, index_t line_nb, index_t element_idx, const uint8_t* value, int value_length); /** * @brief Recovers a value in an OBIDMS column containing data in the form of indices referring - * to sequence qualities handled by an indexer, and using the index of the element in the column's line, - * in the context of a view. + * to sequence qualities handled by an indexer (OBI_QUAL data type), + * using the index of the element in the line, and the column pointer, in the context of a view. * * This function returns quality scores in the character string format. * * @param view A pointer on the opened view. - * @param column A pointer as returned by obi_create_column(). + * @param column_p A pointer as returned by obi_create_column(). * @param line_nb The number of the line where the value should be recovered. * @param element_idx The index of the element that should be recovered in the line. * @@ -988,19 +1315,36 @@ int obi_set_qual_int_with_elt_idx_and_col_name_in_view(Obiview_p view, const cha char* obi_get_qual_char_with_elt_idx_and_col_p_in_view(Obiview_p view, OBIDMS_column_p column_p, index_t line_nb, index_t element_idx); -// TODO +/** + * @brief Recovers a value in an OBIDMS column containing data in the form of indices referring + * to sequence qualities handled by an indexer (OBI_QUAL data type), + * using the index of the element in the line, and the column name, in the context of a view. + * + * This function returns quality scores in the character string format. + * + * @param view A pointer on the opened view. + * @param column_name The alias of the column in the view. + * @param line_nb The number of the line where the value should be recovered. + * @param element_idx The index of the element that should be recovered in the line. + * + * @returns The recovered value, in the character string format. + * @retval OBIQual_char_NA the NA value of the type if an error occurred and obi_errno is set. + * + * @since August 2016 + * @author Celine Mercier (celine.mercier@metabarcoding.org) + */ char* obi_get_qual_char_with_elt_idx_and_col_name_in_view(Obiview_p view, const char* column_name, index_t line_nb, index_t element_idx); /** * @brief Recovers a value in an OBIDMS column containing data in the form of indices referring - * to sequence qualities handled by an indexer, and using the index of the element in the column's line, - * in the context of a view. + * to sequence qualities handled by an indexer (OBI_QUAL data type), + * using the index of the element in the line, and the column pointer, in the context of a view. * - * This function returns quality scores in the integer format. + * This function returns quality scores in the integer array format. * * @param view A pointer on the opened view. - * @param column A pointer as returned by obi_create_column(). + * @param column_p A pointer as returned by obi_create_column(). * @param line_nb The number of the line where the value should be recovered. * @param element_idx The index of the element that should be recovered in the line. * @param value_length A pointer on an integer to store the length of the integer array recovered. @@ -1014,21 +1358,39 @@ char* obi_get_qual_char_with_elt_idx_and_col_name_in_view(Obiview_p view, const const uint8_t* obi_get_qual_int_with_elt_idx_and_col_p_in_view(Obiview_p view, OBIDMS_column_p column_p, index_t line_nb, index_t element_idx, int* value_length); -// TODO +/** + * @brief Recovers a value in an OBIDMS column containing data in the form of indices referring + * to sequence qualities handled by an indexer (OBI_QUAL data type), + * using the index of the element in the line, and the column name, in the context of a view. + * + * This function returns quality scores in the integer array format. + * + * @param view A pointer on the opened view. + * @param column_name The alias of the column in the view. + * @param line_nb The number of the line where the value should be recovered. + * @param element_idx The index of the element that should be recovered in the line. + * @param value_length A pointer on an integer to store the length of the integer array recovered. + * + * @returns The recovered value, in the integer array format. + * @retval OBIQual_int_NA the NA value of the type if an error occurred and obi_errno is set. + * + * @since August 2016 + * @author Celine Mercier (celine.mercier@metabarcoding.org) + */ const uint8_t* obi_get_qual_int_with_elt_idx_and_col_name_in_view(Obiview_p view, const char* column_name, index_t line_nb, index_t element_idx, int* value_length); /** * @brief Sets a value in an OBIDMS column containing data in the form of indices referring - * to sequence qualities handled by an indexer, and using the index of the element in the column's line, - * in the context of a view. + * to sequence qualities handled by an indexer (OBI_QUAL data type), + * using the name of the element in the line, and the column pointer, in the context of a view. * * This function is for quality scores in the character string format. * * @warning Pointers returned by obi_open_column() don't allow writing. * * @param view A pointer on the opened view. - * @param column A pointer as returned by obi_create_column() or obi_clone_column(). + * @param column_p A pointer as returned by obi_create_column() or obi_clone_column(). * @param line_nb The number of the line where the value should be set. * @param element_name The name of the element that should be set in the line. * @param value The value that should be set, in the character string format. @@ -1043,21 +1405,42 @@ const uint8_t* obi_get_qual_int_with_elt_idx_and_col_name_in_view(Obiview_p view int obi_set_qual_char_with_elt_name_and_col_p_in_view(Obiview_p view, OBIDMS_column_p column_p, index_t line_nb, const char* element_name, const char* value); -// TODO +/** + * @brief Sets a value in an OBIDMS column containing data in the form of indices referring + * to sequence qualities handled by an indexer (OBI_QUAL data type), + * using the name of the element in the line, and the column name, in the context of a view. + * + * This function is for quality scores in the character string format. + * + * @warning Pointers returned by obi_open_column() don't allow writing. + * + * @param view A pointer on the opened view. + * @param column_name The alias of the column in the view. + * @param line_nb The number of the line where the value should be set. + * @param element_name The name of the element that should be set in the line. + * @param value The value that should be set, in the character string format. + * + * @returns An integer value indicating the success of the operation. + * @retval 0 on success. + * @retval -1 if an error occurred. + * + * @since August 2016 + * @author Celine Mercier (celine.mercier@metabarcoding.org) + */ int obi_set_qual_char_with_elt_name_and_col_name_in_view(Obiview_p view, const char* column_name, index_t line_nb, const char* element_name, const char* value); /** * @brief Sets a value in an OBIDMS column containing data in the form of indices referring - * to sequence qualities handled by an indexer, and using the index of the element in the column's line, - * in the context of a view. + * to sequence qualities handled by an indexer (OBI_QUAL data type), + * using the name of the element in the line, and the column pointer, in the context of a view. * * This function is for quality scores in the integer array format. * * @warning Pointers returned by obi_open_column() don't allow writing. * * @param view A pointer on the opened view. - * @param column A pointer as returned by obi_create_column() or obi_clone_column(). + * @param column_p A pointer as returned by obi_create_column() or obi_clone_column(). * @param line_nb The number of the line where the value should be set. * @param element_name The name of the element that should be set in the line. * @param value The value that should be set, in the integer format. @@ -1073,19 +1456,41 @@ int obi_set_qual_char_with_elt_name_and_col_name_in_view(Obiview_p view, const c int obi_set_qual_int_with_elt_name_and_col_p_in_view(Obiview_p view, OBIDMS_column_p column_p, index_t line_nb, const char* element_name, const uint8_t* value, int value_length); -// TODO +/** + * @brief Sets a value in an OBIDMS column containing data in the form of indices referring + * to sequence qualities handled by an indexer (OBI_QUAL data type), + * using the name of the element in the line, and the column name, in the context of a view. + * + * This function is for quality scores in the integer array format. + * + * @warning Pointers returned by obi_open_column() don't allow writing. + * + * @param view A pointer on the opened view. + * @param column_name The alias of the column in the view. + * @param line_nb The number of the line where the value should be set. + * @param element_name The name of the element that should be set in the line. + * @param value The value that should be set, in the integer format. + * @param value_length The length of the integer array. + * + * @returns An integer value indicating the success of the operation. + * @retval 0 on success. + * @retval -1 if an error occurred. + * + * @since August 2016 + * @author Celine Mercier (celine.mercier@metabarcoding.org) + */ int obi_set_qual_int_with_elt_name_and_col_name_in_view(Obiview_p view, const char* column_name, index_t line_nb, const char* element_name, const uint8_t* value, int value_length); /** * @brief Recovers a value in an OBIDMS column containing data in the form of indices referring - * to sequence qualities handled by an indexer, and using the index of the element in the column's line, - * in the context of a view. + * to sequence qualities handled by an indexer (OBI_QUAL data type), + * using the name of the element in the line, and the column pointer, in the context of a view. * * This function returns quality scores in the character string format. * * @param view A pointer on the opened view. - * @param column A pointer as returned by obi_create_column() or obi_clone_column(). + * @param column_p A pointer as returned by obi_create_column() or obi_clone_column(). * @param line_nb The number of the line where the value should be recovered. * @param element_name The name of the element that should be recovered in the line. * @@ -1098,19 +1503,36 @@ int obi_set_qual_int_with_elt_name_and_col_name_in_view(Obiview_p view, const ch char* obi_get_qual_char_with_elt_name_and_col_p_in_view(Obiview_p view, OBIDMS_column_p column_p, index_t line_nb, const char* element_name); -// TODO +/** + * @brief Recovers a value in an OBIDMS column containing data in the form of indices referring + * to sequence qualities handled by an indexer (OBI_QUAL data type), + * using the name of the element in the line, and the column name, in the context of a view. + * + * This function returns quality scores in the character string format. + * + * @param view A pointer on the opened view. + * @param column_name The alias of the column in the view. + * @param line_nb The number of the line where the value should be recovered. + * @param element_name The name of the element that should be recovered in the line. + * + * @returns The recovered value, in the character string format. + * @retval OBIQual_char_NA the NA value of the type if an error occurred and obi_errno is set. + * + * @since August 2016 + * @author Celine Mercier (celine.mercier@metabarcoding.org) + */ char* obi_get_qual_char_with_elt_name_and_col_name_in_view(Obiview_p view, const char* column_name, index_t line_nb, const char* element_name); /** * @brief Recovers a value in an OBIDMS column containing data in the form of indices referring - * to sequence qualities handled by an indexer, and using the index of the element in the column's line, - * in the context of a view. + * to sequence qualities handled by an indexer (OBI_QUAL data type), + * using the name of the element in the line, and the column pointer, in the context of a view. * * This function returns quality scores in the integer array format. * * @param view A pointer on the opened view. - * @param column A pointer as returned by obi_create_column() or obi_clone_column(). + * @param column_p A pointer as returned by obi_create_column() or obi_clone_column(). * @param line_nb The number of the line where the value should be recovered. * @param element_name The name of the element that should be recovered in the line. * @param value_length A pointer on an integer to store the length of the integer array recovered. @@ -1124,18 +1546,36 @@ char* obi_get_qual_char_with_elt_name_and_col_name_in_view(Obiview_p view, const const uint8_t* obi_get_qual_int_with_elt_name_and_col_p_in_view(Obiview_p view, OBIDMS_column_p column_p, index_t line_nb, const char* element_name, int* value_length); -// TODO +/** + * @brief Recovers a value in an OBIDMS column containing data in the form of indices referring + * to sequence qualities handled by an indexer (OBI_QUAL data type), + * using the name of the element in the line, and the column name, in the context of a view. + * + * This function returns quality scores in the integer array format. + * + * @param view A pointer on the opened view. + * @param column_name The alias of the column in the view. + * @param line_nb The number of the line where the value should be recovered. + * @param element_name The name of the element that should be recovered in the line. + * @param value_length A pointer on an integer to store the length of the integer array recovered. + * + * @returns The recovered value, in the integer format. + * @retval OBIQual_int_NA the NA value of the type if an error occurred and obi_errno is set. + * + * @since August 2016 + * @author Celine Mercier (celine.mercier@metabarcoding.org) + */ const uint8_t* obi_get_qual_int_with_elt_name_and_col_name_in_view(Obiview_p view, const char* column_name, index_t line_nb, const char* element_name, int* value_length); /** - * @brief Sets a value in an OBIDMS column containing data with the type OBI_SEQ, using the index of the element in the line, - * in the context of a view. + * @brief Sets a value in an OBIDMS column containing data with the type OBI_SEQ, + * using the index of the element in the line, and the column pointer, 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 column_p A pointer on the column. * @param line_nb The number of the line where the value should be set. * @param element_idx The index of the element that should be set in the line. * @param value The value that should be set. @@ -1150,15 +1590,34 @@ const uint8_t* obi_get_qual_int_with_elt_name_and_col_name_in_view(Obiview_p vie int obi_set_seq_with_elt_idx_and_col_p_in_view(Obiview_p view, OBIDMS_column_p column_p, index_t line_nb, index_t element_idx, const char* value); -// TODO +/** + * @brief Sets a value in an OBIDMS column containing data with the type OBI_SEQ, + * using the index of the element in the line, and the column name, 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_name The alias of the column in the view. + * @param line_nb The number of the line where the value should be set. + * @param element_idx The index of the element that should be set in the line. + * @param value The value that should be set. + * + * @returns An integer value indicating the success of the operation. + * @retval 0 on success. + * @retval -1 if an error occurred. + * + * @since August 2016 + * @author Celine Mercier (celine.mercier@metabarcoding.org) + */ int obi_set_seq_with_elt_idx_and_col_name_in_view(Obiview_p view, const char* column_name, index_t line_nb, index_t element_idx, const char* value); /** - * @brief Recovers a value in an OBIDMS column containing data with the type OBI_SEQ, in the context of a view. + * @brief Recovers a value in an OBIDMS column containing data with the type OBI_SEQ, + * using the index of the element in the line, and the column pointer, in the context of a view. * * @param view A pointer on the opened view. - * @param column A pointer on the column. + * @param column_p A pointer on the column. * @param line_nb The number of the line where the value should be recovered. * @param element_idx The index of the element that should be recovered in the line. * @@ -1171,16 +1630,30 @@ int obi_set_seq_with_elt_idx_and_col_name_in_view(Obiview_p view, const char* co char* obi_get_seq_with_elt_idx_and_col_p_in_view(Obiview_p view, OBIDMS_column_p column_p, index_t line_nb, index_t element_idx); -// TODO +/** + * @brief Recovers a value in an OBIDMS column containing data with the type OBI_SEQ, + * using the index of the element in the line, and the column name, in the context of a view. + * + * @param view A pointer on the opened view. + * @param column_name The alias of the column in the view. + * @param line_nb The number of the line where the value should be recovered. + * @param element_idx The index of the element that should be recovered in the line. + * + * @returns The recovered value. + * @retval OBISeq_NA the NA value of the type if an error occurred and obi_errno is set. + * + * @since August 2016 + * @author Celine Mercier (celine.mercier@metabarcoding.org) + */ char* obi_get_seq_with_elt_idx_and_col_name_in_view(Obiview_p view, const char* column_name, index_t line_nb, index_t element_idx); /** * @brief Sets a value in an OBIDMS column containing data with the type OBI_SEQ, - * using the name of the element in the line, in the context of a view. + * using the name of the element in the line, and the column pointer, in the context of a view. * * @param view A pointer on the opened writable view. - * @param column A pointer on the column. + * @param column_p A pointer on the column. * @param line_nb The number of the line where the value should be set. * @param element_name The name of the element that should be set in the line. * @param value The value that should be set. @@ -1195,16 +1668,32 @@ char* obi_get_seq_with_elt_idx_and_col_name_in_view(Obiview_p view, const char* int obi_set_seq_with_elt_name_and_col_p_in_view(Obiview_p view, OBIDMS_column_p column_p, index_t line_nb, const char* element_name, const char* value); -// TODO +/** + * @brief Sets a value in an OBIDMS column containing data with the type OBI_SEQ, + * using the name of the element in the line, and the column name, in the context of a view. + * + * @param view A pointer on the opened writable view. + * @param column_name The alias of the column in the view. + * @param line_nb The number of the line where the value should be set. + * @param element_name The name of the element that should be set in the line. + * @param value The value that should be set. + * + * @returns An integer value indicating the success of the operation. + * @retval 0 on success. + * @retval -1 if an error occurred. + * + * @since August 2016 + * @author Celine Mercier (celine.mercier@metabarcoding.org) + */ int obi_set_seq_with_elt_name_and_col_name_in_view(Obiview_p view, const char* column_name, index_t line_nb, const char* element_name, const char* value); /** * @brief Recovers a value in an OBIDMS column containing data with the type OBI_SEQ, - * using the name of the element in the line, in the context of a view. + * using the name of the element in the line, and the column pointer, in the context of a view. * * @param view A pointer on the opened view. - * @param column A pointer on the column. + * @param column_p A pointer on the column. * @param line_nb The number of the line where the value should be recovered. * @param element_name The name of the element that should be recovered in the line. * @@ -1217,18 +1706,32 @@ int obi_set_seq_with_elt_name_and_col_name_in_view(Obiview_p view, const char* c char* obi_get_seq_with_elt_name_and_col_p_in_view(Obiview_p view, OBIDMS_column_p column_p, index_t line_nb, const char* element_name); -// TODO +/** + * @brief Recovers a value in an OBIDMS column containing data with the type OBI_SEQ, + * using the name of the element in the line, and the column name, in the context of a view. + * + * @param view A pointer on the opened view. + * @param column_name The alias of the column in the view. + * @param line_nb The number of the line where the value should be recovered. + * @param element_name The name of the element that should be recovered in the line. + * + * @returns The recovered value. + * @retval OBISeq_NA the NA value of the type if an error occurred and obi_errno is set. + * + * @since August 2016 + * @author Celine Mercier (celine.mercier@metabarcoding.org) + */ char* obi_get_seq_with_elt_name_and_col_name_in_view(Obiview_p view, const char* column_name, index_t line_nb, const char* element_name); /** - * @brief Sets a value in an OBIDMS column containing data with the type OBI_STR, using the index of the element in the line, - * in the context of a view. + * @brief Sets a value in an OBIDMS column containing data with the type OBI_STR, + * using the index of the element in the line, and the column pointer, 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 column_p A pointer on the column. * @param line_nb The number of the line where the value should be set. * @param element_idx The index of the element that should be set in the line. * @param value The value that should be set. @@ -1243,15 +1746,34 @@ char* obi_get_seq_with_elt_name_and_col_name_in_view(Obiview_p view, const char* int obi_set_str_with_elt_idx_and_col_p_in_view(Obiview_p view, OBIDMS_column_p column_p, index_t line_nb, index_t element_idx, const char* value); -// TODO +/** + * @brief Sets a value in an OBIDMS column containing data with the type OBI_STR, + * using the index of the element in the line, and the column name, 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_name The alias of the column in the view. + * @param line_nb The number of the line where the value should be set. + * @param element_idx The index of the element that should be set in the line. + * @param value The value that should be set. + * + * @returns An integer value indicating the success of the operation. + * @retval 0 on success. + * @retval -1 if an error occurred. + * + * @since August 2016 + * @author Celine Mercier (celine.mercier@metabarcoding.org) + */ int obi_set_str_with_elt_idx_and_col_name_in_view(Obiview_p view, const char* column_name, index_t line_nb, index_t element_idx, const char* value); /** - * @brief Recovers a value in an OBIDMS column containing data with the type OBI_STR, in the context of a view. + * @brief Recovers a value in an OBIDMS column containing data with the type OBI_STR, + * using the index of the element in the line, and the column pointer, in the context of a view. * * @param view A pointer on the opened view. - * @param column A pointer on the column. + * @param column_p A pointer on the column. * @param line_nb The number of the line where the value should be recovered. * @param element_idx The index of the element that should be recovered in the line. * @@ -1264,16 +1786,30 @@ int obi_set_str_with_elt_idx_and_col_name_in_view(Obiview_p view, const char* co const char* obi_get_str_with_elt_idx_and_col_p_in_view(Obiview_p view, OBIDMS_column_p column_p, index_t line_nb, index_t element_idx); -// TODO +/** + * @brief Recovers a value in an OBIDMS column containing data with the type OBI_STR, + * using the index of the element in the line, and the column name, in the context of a view. + * + * @param view A pointer on the opened view. + * @param column_name The alias of the column in the view. + * @param line_nb The number of the line where the value should be recovered. + * @param element_idx The index of the element that should be recovered in the line. + * + * @returns The recovered value. + * @retval OBIStr_NA the NA value of the type if an error occurred and obi_errno is set. + * + * @since August 2016 + * @author Celine Mercier (celine.mercier@metabarcoding.org) + */ const char* obi_get_str_with_elt_idx_and_col_name_in_view(Obiview_p view, const char* column_name, index_t line_nb, index_t element_idx); /** * @brief Sets a value in an OBIDMS column containing data with the type OBI_STR, - * using the name of the element in the line, in the context of a view. + * using the name of the element in the line, and the column pointer, in the context of a view. * * @param view A pointer on the opened writable view. - * @param column A pointer on the column. + * @param column_p A pointer on the column. * @param line_nb The number of the line where the value should be set. * @param element_name The name of the element that should be set in the line. * @param value The value that should be set. @@ -1288,16 +1824,32 @@ const char* obi_get_str_with_elt_idx_and_col_name_in_view(Obiview_p view, const int obi_set_str_with_elt_name_and_col_p_in_view(Obiview_p view, OBIDMS_column_p column_p, index_t line_nb, const char* element_name, const char* value); -// TODO +/** + * @brief Sets a value in an OBIDMS column containing data with the type OBI_STR, + * using the name of the element in the line, and the column name, in the context of a view. + * + * @param view A pointer on the opened writable view. + * @param column_name The alias of the column in the view. + * @param line_nb The number of the line where the value should be set. + * @param element_name The name of the element that should be set in the line. + * @param value The value that should be set. + * + * @returns An integer value indicating the success of the operation. + * @retval 0 on success. + * @retval -1 if an error occurred. + * + * @since August 2016 + * @author Celine Mercier (celine.mercier@metabarcoding.org) + */ int obi_set_str_with_elt_name_and_col_name_in_view(Obiview_p view, const char* column_name, index_t line_nb, const char* element_name, const char* value); /** * @brief Recovers a value in an OBIDMS column containing data with the type OBI_STR, - * using the name of the element in the line, in the context of a view. + * using the name of the element in the line, and the column pointer, in the context of a view. * * @param view A pointer on the opened view. - * @param column A pointer on the column. + * @param column_p A pointer on the column. * @param line_nb The number of the line where the value should be recovered. * @param element_name The name of the element that should be recovered in the line. * @@ -1310,13 +1862,27 @@ int obi_set_str_with_elt_name_and_col_name_in_view(Obiview_p view, const char* c const char* obi_get_str_with_elt_name_and_col_p_in_view(Obiview_p view, OBIDMS_column_p column_p, index_t line_nb, const char* element_name); -// TODO +/** + * @brief Recovers a value in an OBIDMS column containing data with the type OBI_STR, + * using the name of the element in the line, and the column name, in the context of a view. + * + * @param view A pointer on the opened view. + * @param column_name The alias of the column in the view. + * @param line_nb The number of the line where the value should be recovered. + * @param element_name The name of the element that should be recovered in the line. + * + * @returns The recovered value. + * @retval OBIStr_NA the NA value of the type if an error occurred and obi_errno is set. + * + * @since August 2016 + * @author Celine Mercier (celine.mercier@metabarcoding.org) + */ const char* obi_get_str_with_elt_name_and_col_name_in_view(Obiview_p view, const char* column_name, index_t line_nb, const char* element_name); /** - * @brief Sets a value in an OBIDMS column containing indices, using the index of the element in the line, - * in the context of a view. + * @brief Sets a value in an OBIDMS column containing indices (stored data type: OBI_IDX), + * using the index of the element in the line, and the column pointer, 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. * @@ -1327,7 +1893,7 @@ const char* obi_get_str_with_elt_name_and_col_name_in_view(Obiview_p view, const * indices without going through the time-consuming step of indexing the value. * * @param view A pointer on the opened writable view. - * @param column A pointer on the column. + * @param column_p A pointer on the column. * @param line_nb The number of the line where the value should be set. * @param element_idx The index of the element that should be set in the line. * @param value The value that should be set. @@ -1342,18 +1908,43 @@ const char* obi_get_str_with_elt_name_and_col_name_in_view(Obiview_p view, const int obi_set_index_with_elt_idx_and_col_p_in_view(Obiview_p view, OBIDMS_column_p column_p, index_t line_nb, index_t element_idx, index_t value); -// TODO +/** + * @brief Sets a value in an OBIDMS column containing indices (stored data type: OBI_IDX), + * using the index of the element in the line, and the column name, in the context of a view. + * + * Note: If the column is read-only or if there is a line selection associated with the view (making columns non-writable), it is cloned. + * + * Note: Columns containing indices refer to data stored elsewhere, for example lines in other columns, + * or data stored in indexers. + * + * In the case of columns referring to values stored in indexers, this allows to directly set already-known + * indices without going through the time-consuming step of indexing the value. + * + * @param view A pointer on the opened writable view. + * @param column_name The alias of the column in the view. + * @param line_nb The number of the line where the value should be set. + * @param element_idx The index of the element that should be set in the line. + * @param value The value that should be set. + * + * @returns An integer value indicating the success of the operation. + * @retval 0 on success. + * @retval -1 if an error occurred. + * + * @since November 2016 + * @author Celine Mercier (celine.mercier@metabarcoding.org) + */ int obi_set_index_with_elt_idx_and_col_name_in_view(Obiview_p view, const char* column_name, index_t line_nb, index_t element_idx, index_t value); /** - * @brief Recovers a value in an OBIDMS column containing indexes, in the context of a view. + * @brief Recovers a value in an OBIDMS column containing indices (stored data type: OBI_IDX), + * using the index of the element in the line, and the column pointer, in the context of a view. * * This enables to recover the indexes in columns containing any type of indexed data (OBI_SEQ, OBI_STR...), for example to quickly test if * the values are identical (same index in the same indexer). * * @param view A pointer on the opened view. - * @param column A pointer on the column. + * @param column_p A pointer on the column. * @param line_nb The number of the line where the value should be recovered. * @param element_idx The index of the element that should be recovered in the line. * @@ -1366,13 +1957,30 @@ int obi_set_index_with_elt_idx_and_col_name_in_view(Obiview_p view, const char* index_t obi_get_index_with_elt_idx_and_col_p_in_view(Obiview_p view, OBIDMS_column_p column_p, index_t line_nb, index_t element_idx); -// TODO +/** + * @brief Recovers a value in an OBIDMS column containing indices (stored data type: OBI_IDX), + * using the index of the element in the line, and the column name, in the context of a view. + * + * This enables to recover the indexes in columns containing any type of indexed data (OBI_SEQ, OBI_STR...), for example to quickly test if + * the values are identical (same index in the same indexer). + * + * @param view A pointer on the opened view. + * @param column_name The alias of the column in the view. + * @param line_nb The number of the line where the value should be recovered. + * @param element_idx The index of the element that should be recovered in the line. + * + * @returns The recovered value. + * @retval OBIIdx_NA the NA value of the type if an error occurred and obi_errno is set. + * + * @since November 2016 + * @author Celine Mercier (celine.mercier@metabarcoding.org) + */ index_t obi_get_index_with_elt_idx_and_col_name_in_view(Obiview_p view, const char* column_name, index_t line_nb, index_t element_idx); /** - * @brief Sets a value in an OBIDMS column containing indices, using the index of the element in the line, - * in the context of a view. + * @brief Sets a value in an OBIDMS column containing indices (stored data type: OBI_IDX), + * using the name of the element in the line, and the column pointer, 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. * @@ -1383,7 +1991,7 @@ index_t obi_get_index_with_elt_idx_and_col_name_in_view(Obiview_p view, const ch * indices without going through the time-consuming step of indexing the value. * * @param view A pointer on the opened writable view. - * @param column A pointer on the column. + * @param column_p A pointer on the column. * @param line_nb The number of the line where the value should be set. * @param element_name The name of the element that should be recovered in the line. * @param value The value that should be set. @@ -1398,19 +2006,43 @@ index_t obi_get_index_with_elt_idx_and_col_name_in_view(Obiview_p view, const ch int obi_set_index_with_elt_name_and_col_p_in_view(Obiview_p view, OBIDMS_column_p column_p, index_t line_nb, const char* element_name, index_t value); -// TODO +/** + * @brief Sets a value in an OBIDMS column containing indices (stored data type: OBI_IDX), + * using the name of the element in the line, and the column name, in the context of a view. + * + * Note: If the column is read-only or if there is a line selection associated with the view (making columns non-writable), it is cloned. + * + * Note: Columns containing indices refer to data stored elsewhere, for example lines in other columns, + * or data stored in indexers. + * + * In the case of columns referring to values stored in indexers, this allows to directly set already-known + * indices without going through the time-consuming step of indexing the value. + * + * @param view A pointer on the opened writable view. + * @param column_name The alias of the column in the view. + * @param line_nb The number of the line where the value should be set. + * @param element_name The name of the element that should be recovered in the line. + * @param value The value that should be set. + * + * @returns An integer value indicating the success of the operation. + * @retval 0 on success. + * @retval -1 if an error occurred. + * + * @since November 2016 + * @author Celine Mercier (celine.mercier@metabarcoding.org) + */ int obi_set_index_with_elt_name_and_col_name_in_view(Obiview_p view, const char* column_name, index_t line_nb, const char* element_name, index_t value); /** - * @brief Recovers a value in an OBIDMS column containing indexes, - * using the name of the element in the line, in the context of a view. + * @brief Recovers a value in an OBIDMS column containing indices (stored data type: OBI_IDX), + * using the name of the element in the line, and the column pointer, in the context of a view. * * This enables to recover the indexes in columns containing any type of indexed data (OBI_SEQ, OBI_STR...), for example to quickly test if * the values are identical (same index in the same indexer). * * @param view A pointer on the opened view. - * @param column A pointer on the column. + * @param column_p A pointer on the column. * @param line_nb The number of the line where the value should be recovered. * @param element_name The name of the element that should be recovered in the line. * @@ -1423,7 +2055,24 @@ int obi_set_index_with_elt_name_and_col_name_in_view(Obiview_p view, const char* index_t obi_get_index_with_elt_name_and_col_p_in_view(Obiview_p view, OBIDMS_column_p column_p, index_t line_nb, const char* element_name); -// TODO +/** + * @brief Recovers a value in an OBIDMS column containing indices (stored data type: OBI_IDX), + * using the name of the element in the line, and the column name, in the context of a view. + * + * This enables to recover the indexes in columns containing any type of indexed data (OBI_SEQ, OBI_STR...), for example to quickly test if + * the values are identical (same index in the same indexer). + * + * @param view A pointer on the opened view. + * @param column_name The alias of the column in the view. + * @param line_nb The number of the line where the value should be recovered. + * @param element_name The name of the element that should be recovered in the line. + * + * @returns The recovered value. + * @retval OBIIdx_NA the NA value of the type if an error occurred and obi_errno is set. + * + * @since November 2016 + * @author Celine Mercier (celine.mercier@metabarcoding.org) + */ index_t obi_get_index_with_elt_name_and_col_name_in_view(Obiview_p view, const char* column_name, index_t line_nb, const char* element_name);