obidmscolumn_idx.h 4.91 KB
Newer Older
Celine Mercier's avatar
Celine Mercier committed
1 2 3 4 5 6 7 8
/****************************************************************************
 * OBIDMS_column_idx header file                                            *
 ****************************************************************************/

/**
 * @file obidsmcolumn_idx.h
 * @author Celine Mercier
 * @date February 14th 2016
9
 * @brief Header file for the functions handling OBIColumns containing indices (stored data type: OBI_IDX).
10
 *
11 12
 * Note: Columns containing indices refer to data stored elsewhere, for example lines in other columns,
 *	     or data stored in indexers.
Celine Mercier's avatar
Celine Mercier committed
13 14 15 16 17 18 19 20 21 22 23 24 25 26
 */


#ifndef OBIDMSCOLUMN_IDX_H_
#define OBIDMSCOLUMN_IDX_H_


#include <stdlib.h>
#include <stdio.h>

#include "obidmscolumn.h"
#include "obitypes.h"


27
/**
28 29
 * @brief Sets a value in an OBIDMS column containing indices (stored data type: OBI_IDX),
 *        using the index of the element in the line.
30
 *
31 32 33 34 35
 *	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.
36 37 38 39 40
 *
 * @warning Pointers returned by obi_open_column() don't allow writing.
 *
 * @param column A pointer as returned by obi_create_column() or obi_clone_column().
 * @param line_nb The number of the line where the value should be set.
41 42
 * @param element_idx The index of the element that should be set in the line.
 * @param value The index that should be set.
43 44 45 46 47
 *
 * @returns An integer value indicating the success of the operation.
 * @retval 0 on success.
 * @retval -1 if an error occurred.
 *
48
 * @since November 2016
49 50
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
51
int obi_column_set_index_with_elt_idx(OBIDMS_column_p column, index_t line_nb, index_t element_idx, index_t value);
Celine Mercier's avatar
Celine Mercier committed
52

53 54

/**
55 56
 * @brief Recovers a value in an OBIDMS column containing indices (stored data type: OBI_IDX),
 *        using the index of the element in the line.
57
 *
58 59
 *	Note: Columns containing indices refer to data stored elsewhere, for example lines in other columns,
 *	      or data stored in indexers.
60
 *
61 62 63
 * The value recovered is the index itself and not the data it is referring to.
 *
 * @param column A pointer as returned by obi_create_column().
64
 * @param line_nb The number of the line where the value should be recovered.
65
 * @param element_idx The index of the element that should be recovered in the line.
66 67 68 69
 *
 * @returns The recovered value.
 * @retval OBIIdx_NA the NA value of the type if an error occurred and obi_errno is set.
 *
70
 * @since November 2016
71 72
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
73
index_t obi_column_get_index_with_elt_idx(OBIDMS_column_p column, index_t line_nb, index_t element_idx);
Celine Mercier's avatar
Celine Mercier committed
74 75


76
/**
77 78
 * @brief Sets a value in an OBIDMS column containing indices (stored data type: OBI_IDX),
 *        using the index of the element in the line.
79
 *
80 81
 *	Note: Columns containing indices refer to data stored elsewhere, for example lines in other columns,
 *	      or data stored in indexers.
82
 *
83 84 85 86 87 88 89 90 91 92 93 94 95
 * 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.
 *
 * @warning Pointers returned by obi_open_column() don't allow writing.
 *
 * @param column A pointer as returned by obi_create_column() or obi_clone_column().
 * @param 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 index that should be set.
 *
 * @returns An integer value indicating the success of the operation.
 * @retval 0 on success.
 * @retval -1 if an error occurred.
96 97 98 99
 *
 * @since November 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
100
int obi_column_set_index_with_elt_name(OBIDMS_column_p column, index_t line_nb, index_t element_idx, index_t value);
101 102 103


/**
104
 * @brief Recovers a value in an OBIDMS column containing indices (stored data type: OBI_IDX),
105 106
 *        using the name of the element in the line.
 *
107 108 109 110 111
 *	Note: Columns containing indices refer to data stored elsewhere, for example lines in other columns,
 *	      or data stored in indexers.
 *
 * The value recovered is the index itself and not the data it is referring to.
 *
112 113 114 115 116 117 118 119 120 121 122 123 124
 * @param column A pointer as returned by obi_create_column() or obi_clone_column().
 * @param line_nb The number of the line where the value should be recovered.
 * @param element_name The name of the element that should be recovered in the line.
 *
 * @returns The recovered value.
 * @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_column_get_index_with_elt_name(OBIDMS_column_p column, index_t line_nb, const char* element_name);


Celine Mercier's avatar
Celine Mercier committed
125 126
#endif /* OBIDMSCOLUMN_IDX_H_ */