obidmscolumn_qual.h 9.42 KB
Newer Older
1 2 3 4 5 6 7 8
/****************************************************************************
 * OBIDMS_column_qual header file                                           *
 ****************************************************************************/

/**
 * @file obidsmcolumn_qual.h
 * @author Celine Mercier
 * @date May 4th 2016
9
 * @brief Header file for the functions handling OBIColumns containing data in the form of indices referring to sequence qualities.
10 11 12 13 14 15 16 17 18 19 20 21 22 23 24
 */


#ifndef OBIDMSCOLUMN_QUAL_H_
#define OBIDMSCOLUMN_QUAL_H_


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

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


25
#define QUALITY_ASCII_BASE (33)   		/**< The default ASCII base of sequence quality.
26 27 28 29 30
										 *   Used to convert sequence qualities from characters to integers
										 *   and the other way around.
                                	 	 */


31 32 33 34 35 36 37 38 39 40 41 42
/**
 * @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.
 *
 * This function is for qualities in the character string format.
 *
 * @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_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.
43 44
 * @param offset The ASCII base of sequence quality, used to convert sequence qualities from characters to integers
 *				 and the other way around. If -1, the default base is used.
45 46 47 48 49 50 51 52
 *
 * @returns An integer value indicating the success of the operation.
 * @retval 0 on success.
 * @retval -1 if an error occurred.
 *
 * @since May 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
53
int obi_column_set_obiqual_char_with_elt_idx(OBIDMS_column_p column, index_t line_nb, index_t element_idx, const char* value, int offset);
54 55 56 57 58 59 60 61 62 63 64 65 66


/**
 * @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.
 *
 * This function is for qualities in the integer format.
 *
 * @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_idx The index of the element that should be set in the line.
67 68
 * @param value The value that should be set, in the integer array format.
 * @param value_length The length of the integer array.
69 70 71 72 73 74 75 76
 *
 * @returns An integer value indicating the success of the operation.
 * @retval 0 on success.
 * @retval -1 if an error occurred.
 *
 * @since May 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
77
int obi_column_set_obiqual_int_with_elt_idx(OBIDMS_column_p column, index_t line_nb, index_t element_idx, const uint8_t* value, int value_length);
78 79 80 81 82 83 84 85 86 87 88


/**
 * @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.
 *
 * This function returns quality scores in the character string format.
 *
 * @param column A pointer as returned by obi_create_column().
 * @param line_nb The number of the line where the value should be recovered.
 * @param element_idx The index of the element that should be recovered in the line.
89 90
 * @param offset The ASCII base of sequence quality, used to convert sequence qualities from characters to integers
 *				 and the other way around. If -1, the default base is used.
91 92
 *
 * @returns The recovered value, in the character string format.
93
 * @retval OBIQual_char_NA the NA value of the type if an error occurred and obi_errno is set.
94 95 96 97
 *
 * @since May 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
98
char* obi_column_get_obiqual_char_with_elt_idx(OBIDMS_column_p column, index_t line_nb, index_t element_idx, int offset);
99 100 101 102 103 104 105 106 107 108 109


/**
 * @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.
 *
 * This function returns quality scores in the integer format.
 *
 * @param column A pointer as returned by obi_create_column().
 * @param line_nb The number of the line where the value should be recovered.
 * @param element_idx The index of the element that should be recovered in the line.
110
 * @param value_length A pointer on an integer to store the length of the integer array recovered.
111
 *
112 113
 * @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.
114 115 116 117
 *
 * @since May 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
118
const uint8_t* obi_column_get_obiqual_int_with_elt_idx(OBIDMS_column_p column, index_t line_nb, index_t element_idx, int* value_length);
119 120 121 122 123 124 125 126 127 128 129 130 131 132


/**
 * @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.
 *
 * This function is for quality scores in the character string format.
 *
 * @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 value that should be set, in the character string format.
133 134
 * @param offset The ASCII base of sequence quality, used to convert sequence qualities from characters to integers
 *				 and the other way around. If -1, the default base is used.
135 136 137 138 139 140 141 142
 *
 * @returns An integer value indicating the success of the operation.
 * @retval 0 on success.
 * @retval -1 if an error occurred.
 *
 * @since May 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
143
int obi_column_set_obiqual_char_with_elt_name(OBIDMS_column_p column, index_t line_nb, const char* element_name, const char* value, int offset);
144 145 146 147 148 149


/**
 * @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.
 *
150
 * This function is for quality scores in the integer array format.
151 152 153 154 155 156 157
 *
 * @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 value that should be set, in the integer format.
158
 * @param value_length The length of the integer array.
159 160 161 162 163 164 165 166
 *
 * @returns An integer value indicating the success of the operation.
 * @retval 0 on success.
 * @retval -1 if an error occurred.
 *
 * @since May 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
167
int obi_column_set_obiqual_int_with_elt_name(OBIDMS_column_p column, index_t line_nb, const char* element_name, const uint8_t* value, int value_length);
168 169 170 171 172 173 174 175 176 177 178


/**
 * @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.
 *
 * This function returns quality scores in the character string format.
 *
 * @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.
179 180
 * @param offset The ASCII base of sequence quality, used to convert sequence qualities from characters to integers
 *				 and the other way around. If -1, the default base is used.
181 182
 *
 * @returns The recovered value, in the character string format.
183
 * @retval OBIQual_char_NA the NA value of the type if an error occurred and obi_errno is set.
184 185 186 187
 *
 * @since May 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
188
char* obi_column_get_obiqual_char_with_elt_name(OBIDMS_column_p column, index_t line_nb, const char* element_name, int offset);
189 190 191 192 193 194


/**
 * @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.
 *
195
 * This function returns quality scores in the integer array format.
196 197 198 199
 *
 * @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.
200
 * @param value_length A pointer on an integer to store the length of the integer array recovered.
201 202
 *
 * @returns The recovered value, in the integer format.
203
 * @retval OBIQual_int_NA the NA value of the type if an error occurred and obi_errno is set.
204 205 206 207
 *
 * @since May 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
208
const uint8_t* obi_column_get_obiqual_int_with_elt_name(OBIDMS_column_p column, index_t line_nb, const char* element_name, int* value_length);
209 210 211 212


#endif /* OBIDMSCOLUMN_QUAL_H_ */