obidmscolumn_qual.h 8.65 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 26 27 28 29 30
#define QUALITY_ASCII_BASE (33)   		/**< The ASCII base of sequence quality.
										 *   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 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64
/**
 * @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.
 *
 * @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)
 */
int obi_column_set_obiqual_char_with_elt_idx(OBIDMS_column_p column, 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.
 *
 * 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.
65 66
 * @param value The value that should be set, in the integer array format.
 * @param value_length The length of the integer array.
67 68 69 70 71 72 73 74
 *
 * @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)
 */
75
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);
76 77 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.
 *
 * @returns The recovered value, in the character string format.
89
 * @retval OBIQual_str_NA the NA value of the type if an error occurred and obi_errno is set.
90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105
 *
 * @since May 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
char* obi_column_get_obiqual_char_with_elt_idx(OBIDMS_column_p column, 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.
 *
 * 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.
106
 * @param value_length A pointer on an integer to store the length of the integer array recovered.
107
 *
108 109
 * @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.
110 111 112 113
 *
 * @since May 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
114
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);
115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143


/**
 * @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.
 *
 * @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)
 */
int obi_column_set_obiqual_char_with_elt_name(OBIDMS_column_p column, 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.
 *
144
 * This function is for quality scores in the integer array format.
145 146 147 148 149 150 151
 *
 * @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.
152
 * @param value_length The length of the integer array.
153 154 155 156 157 158 159 160
 *
 * @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)
 */
161
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);
162 163 164 165 166 167 168 169 170 171 172 173 174


/**
 * @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.
 *
 * @returns The recovered value, in the character string format.
175
 * @retval OBIQual_str_NA the NA value of the type if an error occurred and obi_errno is set.
176 177 178 179 180 181 182 183 184 185 186
 *
 * @since May 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
char* obi_column_get_obiqual_char_with_elt_name(OBIDMS_column_p column, 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.
 *
187
 * This function returns quality scores in the integer array format.
188 189 190 191
 *
 * @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.
192
 * @param value_length A pointer on an integer to store the length of the integer array recovered.
193 194
 *
 * @returns The recovered value, in the integer format.
195
 * @retval OBIQual_int_NA the NA value of the type if an error occurred and obi_errno is set.
196 197 198 199
 *
 * @since May 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
200
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);
201 202 203 204


#endif /* OBIDMSCOLUMN_QUAL_H_ */