obiview.h 39.5 KB
Newer Older
Celine Mercier's avatar
Celine Mercier committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28
/********************************************************************
 * Obiview header file                                              *
 ********************************************************************/

/**
 * @file obiview.h
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 * @date 16 December 2015
 * @brief Header file for the OBIDMS view functions and structures.
 */


#ifndef OBIVIEW_H_
#define OBIVIEW_H_


#include <stdlib.h>
#include <errno.h>
#include <stdio.h>
#include <stdbool.h>
#include <time.h>
#include <math.h>

#include "obidms.h"
#include "obidmscolumn.h"
#include "obierrno.h"


29 30 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
#define OBIVIEW_NAME_MAX_LENGTH (1000)   		/**< The maximum length of an OBIDMS view name.
                                	 	  	  	 */
#define OBIVIEW_COMMENTS_MAX_LENGTH (10000)		/**< The maximum length of the comments associated
												 *   with a view.
                                	 	  	  	 */
#define VIEW_TYPE_MAX_LENGTH (1024)   			/**< The maximum length of the type name of a view.
                                	 	  	  	 */
#define OBIVIEW_FILE_NAME "obiviews"   			/**< The default name of a view file.
                                	 	  	  	 */
#define LINES_COLUMN_NAME "LINES"				/**< The name of the column containing the line selections
 	 	 	 	 	 	 	 	 	 	 	 	 *   in all views.
                                	 	  	  	 */
#define VIEW_TYPE_NUC_SEQS "NUC_SEQS_VIEW"   	/**< The type name of views based on nucleotide sequences
												 *   and their metadata.
                                	 	  	  	 */
#define NUC_SEQUENCE_COLUMN "NUC_SEQ"			/**< The name of the column containing the nucleotide sequences
 	 	 	 	 	 	 	 	 	 	 	 	 *   in NUC_SEQS_VIEW views.
                                	 	  	  	 */
#define NUC_SEQUENCE_INDEXER "NUC_SEQ_INDEXER"	/**< The name of the indexer containing the nucleotide sequences
 	 	 	 	 	 	 	 	 	 	 	 	 *   in NUC_SEQS_VIEW views.
                                	 	  	  	 */
#define ID_COLUMN "ID"							/**< The name of the column containing the sequence identifiers
 	 	 	 	 	 	 	 	 	 	 	 	 *   in NUC_SEQS_VIEW views.
                                	 	  	  	 */
#define ID_INDEXER "ID_INDEXER"					/**< The name of the indexer containing the sequence identifiers
 	 	 	 	 	 	 	 	 	 	 	 	 *   in NUC_SEQS_VIEW views.
                                	 	  	  	 */
#define DEFINITION_COLUMN "DEFINITION"			/**< The name of the column containing the sequence definitions
 	 	 	 	 	 	 	 	 	 	 	 	 *   in NUC_SEQS_VIEW views.
                                	 	  	  	 */
#define DEFINITION_INDEXER "DEFINITION_INDEXER"	/**< The name of the indexer containing the sequence definitions
 	 	 	 	 	 	 	 	 	 	 	 	 *   in NUC_SEQS_VIEW views.
                                	 	  	  	 */
Celine Mercier's avatar
Celine Mercier committed
62

Celine Mercier's avatar
Celine Mercier committed
63

64 65 66 67
/**
 * @brief Structure for an opened view.
 */
typedef struct Obiview {
68

69 70 71 72 73 74
	OBIDMS_p         	dms;    									/**< A pointer on the DMS to which the view belongs.
	 	 	    													 */
	char   				name[OBIVIEW_NAME_MAX_LENGTH+1];    		/**< Name of the view.
	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 */
	char				created_from[OBIVIEW_NAME_MAX_LENGTH+1];    /**< Name of the view from which that view was cloned if the view was cloned.
 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 */
75
	char				view_type[VIEW_TYPE_MAX_LENGTH+1];			/**< Type of the view if there is one.
76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100
																	 *   Types existing: NUC_SEQS_VIEW.
 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 */
	bool             	read_only;    								/**< Whether the view is read-only or can be modified.
																	 */
	OBIDMS_column_p  	line_selection;    							/**< A pointer on the column containing the line selection
																	 *   associated with the view if there is one.
																	 *   This line selection is read-only, and when a line from the view is read,
																	 *   it is this line selection that is used.
	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 */
	OBIDMS_column_p  	new_line_selection;    						/**< A pointer on the column containing the new line selection being built
	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 *   to associate with the view, if there is one.
	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 *   When a line is selected with obi_select_line() or obi_select_lines(),
	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 *   it is recorded in this line selection.
	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 */
	index_t			 	line_count;    								/**< The number of lines in the view. Refers to the number of lines in each
	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 *   column of the view if line_selection is NULL, or to the line count of
	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 *   line_selection if it is not NULL.
 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 */
	int    			 	column_count;    							/**< The number of columns in the view.
 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 */
	OBIDMS_column_p  	columns[MAX_NB_OPENED_COLUMNS];    			/**< Array of pointers on all the columns of the view.
	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 */
	char 				comments[OBIVIEW_COMMENTS_MAX_LENGTH+1];	/**< Comments, additional informations on the view.
	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 */
} Obiview_t, *Obiview_p;
Celine Mercier's avatar
Celine Mercier committed
101 102 103


/**
104
 * @brief Structure referencing a column by its name and its version.
Celine Mercier's avatar
Celine Mercier committed
105 106 107 108 109 110 111 112 113 114
 */
typedef struct Column_reference {
	char 	   	 column_name[OBIDMS_COLUMN_MAX_NAME+1];    /**< Name of the column.
	 	 	 	 	 	 	 	 	 	 	 	 	 	    */
	obiversion_t version;				   		    	   /**< Version of the column.
	 	 	 	 	 	 	 	 	 	 	 	 	 	    */
} Column_reference_t, *Column_reference_p;


/**
115 116 117
 * @brief Structure for a closed view stored in the view file.
 * 		  Views are identified by their name.
 * 		  Once a view has been written in the view file, it can not be modified and can only be read.
Celine Mercier's avatar
Celine Mercier committed
118
 */
119 120 121 122 123 124 125 126 127
typedef struct Obiview_infos {
	int					view_number;    							/**< Number of the view in the view file.
	 	 	    													 */
	time_t 		 		creation_date;    							/**< Time at which the view was written in the view file.
		 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 */
	char   				name[OBIVIEW_NAME_MAX_LENGTH+1];    		/**< Name of the view, used to identify it.
	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 */
	char				created_from[OBIVIEW_NAME_MAX_LENGTH+1];    /**< Name of the view from which that view was cloned, if it was cloned.
	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 */
128
	char				view_type[VIEW_TYPE_MAX_LENGTH+1];			/**< Type of the view if there is one.
129 130 131 132 133 134 135 136 137 138 139 140 141 142 143
	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 *   Types existing: NUC_SEQS_VIEW.
	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 */
	bool				all_lines;									/**< Whether there is a line selection associated with the view.
	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 */
	Column_reference_t	line_selection;								/**< Whether there is a line selection associated with the view.
 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 */
	index_t             line_count;    								/**< The number of lines in the view.
																	 */
	int 				column_count;    							/**< The number of columns in the view.
	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 */
	Column_reference_t	column_references[MAX_NB_OPENED_COLUMNS];   /**< References (name and version) for all the columns in the view.
 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 */
	char 				comments[OBIVIEW_COMMENTS_MAX_LENGTH+1];	/**< Comments, additional informations on the view.
 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 */
} Obiview_infos_t, *Obiview_infos_p;
144

Celine Mercier's avatar
Celine Mercier committed
145

146
// TODO : Combine the common elements of the Obiview_infos and Obiview structures in one structure used by both?
Celine Mercier's avatar
Celine Mercier committed
147 148 149


/**
150
 * @brief Structure for the header of view files.
Celine Mercier's avatar
Celine Mercier committed
151
 */
152 153 154 155 156 157 158 159
typedef struct Obiviews_header {
	size_t header_size;   /**< Size of the header in bytes.
	 	 	 	 	 	   */
	size_t views_size;    /**< Size of the views in bytes.
	 	   	   	   	   	   */
	int    view_count;    /**< Number of views saved.
	   	   	   	   	   	   */
} Obiviews_header_t, *Obiviews_header_p;
Celine Mercier's avatar
Celine Mercier committed
160 161


162 163 164 165 166 167 168 169 170
/**
 * @brief Structure for the information stored in view files.
 */
typedef struct Obiviews_infos_all {
	Obiviews_header_p	header;   		/**< Pointer on the header of the view file.
	 	   	   	   	   	   	   	   	     */
	Obiview_infos_p 	view_infos;     /**< Pointer on the beginning (first view) of the informations on views.
	   	   	   	     	 	 	 	 	 */
} Obiviews_infos_all_t, *Obiviews_infos_all_p;
171

Celine Mercier's avatar
Celine Mercier committed
172

173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191
/**
 * @brief Creates a new view.
 *
 * Fails if a view with the same name already exists.
 *
 * @param dms A pointer on the OBIDMS.
 * @param view_name The unique name of the view.
 * @param view_to_clone Eventually a pointer on the opened view to clone to create the new one, if there is one. NULL if not.
 * @param line_selection Eventually a pointer on a list of indexes corresponding to a line selection to use with the view to clone
 * 						 if there is one. NULL if there is no line selection or no view to clone.
 * @param comments Eventually, comments to associate with the view. NULL if not.
 *
 * @returns A pointer to the newly created view structure.
 * @retval NULL if an error occurred.
 *
 * @since December 2015
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
Obiview_p obi_new_view(OBIDMS_p dms, const char* view_name, Obiview_p view_to_clone, index_t* line_selection, const char* comments);
Celine Mercier's avatar
Celine Mercier committed
192 193 194


/**
195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213
 * @brief Creates a new view by cloning another view written in the view file and identified by its name.
 *
 * Note : obi_new_view can clone from a pointer on an opened view, while this function will read the view to clone
 * 		  from the view file.
 *
 * Fails if a view with the same name already exists.
 *
 * @param dms A pointer on the OBIDMS.
 * @param view_name The unique name of the new view.
 * @param view_to_clone_name The name of the view to clone stored in the view file of the OBIDMS.
 * @param line_selection Eventually a pointer on a list of indexes corresponding to a line selection to use with the view to clone
 * 						 if there is one. NULL if there is no line selection or no view to clone.
 * @param comments Eventually, comments to associate with the view. NULL if not.
 *
 * @returns A pointer to the newly created view structure.
 * @retval NULL if an error occurred.
 *
 * @since December 2015
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
Celine Mercier's avatar
Celine Mercier committed
214
 */
215
Obiview_p obi_new_view_cloned_from_name(OBIDMS_p dms, const char* view_name, const char* view_to_clone_name, index_t* line_selection, const char* comments);
Celine Mercier's avatar
Celine Mercier committed
216 217 218


/**
219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239
 * @brief Creates a new view with the type NUC_SEQ_VIEW, based on nucleotide sequences and their metadata.
 *
 * Fails if a view with the same name already exists.
 *
 * The obligatory columns specific to the view type are created too and opened:
 * 	- NUC_SEQUENCE_COLUMN where nucleotide sequences are stored
 * 	- ID_COLUMN			  where sequence identifiers are stored
 * 	- DEFINITION_COLUMN   where sequence definitions are stored
 *
 * @param dms A pointer on the OBIDMS.
 * @param view_name The unique name of the view.
 * @param view_to_clone Eventually a pointer on the opened view to clone to create the new one, if there is one. NULL if not.
 * @param line_selection Eventually a pointer on a list of indexes corresponding to a line selection to use with the view to clone
 * 						 if there is one. NULL if there is no line selection or no view to clone.
 * @param comments Eventually, comments to associate with the view. NULL if not.
 *
 * @returns A pointer to the newly created view structure.
 * @retval NULL if an error occurred.
 *
 * @since February 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
Celine Mercier's avatar
Celine Mercier committed
240
 */
241
Obiview_p obi_new_view_nuc_seqs(OBIDMS_p dms, const char* view_name, Obiview_p view_to_clone, index_t* line_selection, const char* comments);
242

Celine Mercier's avatar
Celine Mercier committed
243

244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272
/**
 * @brief Creates a new view with the type NUC_SEQ_VIEW, based on nucleotide sequences and their metadata,
 *        by cloning another NUC_SEQ_VIEW view written in the view file and identified by its name.
 *
 * Note : obi_new_view_nuc_seqs can clone from a pointer on an opened view, while this function will read the view to clone
 * 		  from the view file.
 *
 * Fails if a view with the same name already exists.
 * Fails if the view to clone doesn't have the type NUC_SEQ_VIEW.
 *
 * The obligatory columns specific to the view type are created too and opened:
 * 	- NUC_SEQUENCE_COLUMN where nucleotide sequences are stored
 * 	- ID_COLUMN			  where sequence identifiers are stored
 * 	- DEFINITION_COLUMN   where sequence definitions are stored
 *
 * @param dms A pointer on the OBIDMS.
 * @param view_name The unique name of the new view.
 * @param view_to_clone_name The name of the view to clone stored in the view file of the OBIDMS.
 * @param line_selection Eventually a pointer on a list of indexes corresponding to a line selection to use with the view to clone
 * 						 if there is one. NULL if there is no line selection or no view to clone.
 * @param comments Eventually, comments to associate with the view. NULL if not.
 *
 * @returns A pointer to the newly created view structure.
 * @retval NULL if an error occurred.
 *
 * @since February 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
Obiview_p obi_new_view_nuc_seqs_cloned_from_name(OBIDMS_p dms, const char* view_name, const char* view_to_clone_name, index_t* line_selection, const char* comments);
Celine Mercier's avatar
Celine Mercier committed
273 274


275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291
/**
 * @brief Opens a view identified by its name stored in the view file.
 *
 * When opening a view, all the columns and eventually the line selection belonging to it are opened with it.
 *
 * @warning The opened view is read-only.
 *
 * @param dms A pointer on the OBIDMS.
 * @param view_name The unique name identifying the view.
 *
 * @returns A pointer on the opened view structure.
 * @retval NULL if an error occurred.
 *
 * @since December 2015
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
Obiview_p obi_open_view(OBIDMS_p dms, const char* view_name);
Celine Mercier's avatar
Celine Mercier committed
292 293


294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316
/**
 * @brief Adds a column to a view.
 *
 * @warning The view must be writable.
 *
 * @param view A pointer on the view.
 * @param column_name The name of the column.
 * @param version_number The version of the column if it should be opened and not created (if -1, the latest version is retrieved).
 * @param data_type The OBIType code of the data.
 * @param nb_lines The number of lines to be stored.
 * @param nb_elements_per_line The number of elements per line.
 * @param elements_names The names of the elements with ';' as separator.
 * @param indexer_name The name of the indexer if there is one associated with the column.
 * @param comments Optional comments associated with the column.
 * @param create Whether the column should be created (create == true) or opened (create == false).
 *
 * @returns A value indicating the success of the operation.
 * @retval 0 if the operation was successfully completed.
 * @retval -1 if an error occurred.
 *
 * @since February 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
Celine Mercier's avatar
Celine Mercier committed
317 318 319 320 321 322 323
int obi_view_add_column(Obiview_p view,
						const char* column_name,
						obiversion_t version_number,
						OBIType_t data_type,
						index_t nb_lines,
						index_t nb_elements_per_line,
						const char* elements_names,
Celine Mercier's avatar
Celine Mercier committed
324
						const char* indexer_name,
Celine Mercier's avatar
Celine Mercier committed
325 326 327
						const char* comments,
						bool create);

328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343

/**
 * @brief Deletes a column from a view.
 *
 * @warning The view must be writable.
 *
 * @param view A pointer on the view.
 * @param column_name The name of the column that should be deleted from the view.
 *
 * @returns A value indicating the success of the operation.
 * @retval 0 if the operation was successfully completed.
 * @retval -1 if an error occurred.
 *
 * @since February 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
Celine Mercier's avatar
Celine Mercier committed
344 345
int obi_view_delete_column(Obiview_p view, const char* column_name);

346

347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378
/**
 * @brief Gets the pointer on a column from its name in a view.
 *
 * @param view A pointer on the view.
 * @param column_name The name of the column in the view.
 *
 * @returns A pointer on the column.
 * @retval NULL if an error occurred.
 *
 * @since February 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
OBIDMS_column_p obi_view_get_column(Obiview_p view, const char* column_name);


/**
 * @brief Gets the pointer on the pointer on a column from its name in a view.
 *
 * Note: This is used to replace old cloned columns with new ones in views in layers above the C layer.
 *
 * @param view A pointer on the view.
 * @param column_name The name of the column in the view.
 *
 * @returns A pointer on the pointer on the column.
 * @retval NULL if an error occurred.
 *
 * @since February 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
OBIDMS_column_p* obi_view_get_pointer_on_column_in_view(Obiview_p view, const char* column_name);


379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397
/**
 * @brief Selects a line in the context of a view.
 *
 * If no line selection exists for the view, it will be created.
 *
 * @warning The view must be writable.
 * @warning The new line index will be simply added at the end of the current
 *          new line selection.
 *
 * @param view A pointer on the view.
 * @param line_nb The index of the line that should be added in the selection.
 *
 * @returns A value indicating the success of the operation.
 * @retval 0 if the operation was successfully completed.
 * @retval -1 if an error occurred.
 *
 * @since February 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
Celine Mercier's avatar
Celine Mercier committed
398 399
int obi_select_line(Obiview_p view, index_t line_nb);

400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420

/**
 * @brief Selects a list of line in the context of a view.
 *
 * If no line selection exists for the view, it will be created.
 *
 * @warning The view must be writable.
 * @warning The new line indexes will be simply added at the end of the current
 *          new line selection.
 *
 * @param view A pointer on the view.
 * @param line_nbs A pointer on an array of indexes corresponding to the lines that
 *                 should be added in the selection.
 *
 * @returns A value indicating the success of the operation.
 * @retval 0 if the operation was successfully completed.
 * @retval -1 if an error occurred.
 *
 * @since February 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
Celine Mercier's avatar
Celine Mercier committed
421 422
int obi_select_lines(Obiview_p view, index_t* line_nbs);

423 424

/**
425
 * @brief Saves a view, writing it in the view file.
426
 *
427
 * The view is written at the end of the view file, following the latest written view.
428
 *
429
 * @warning The view must be writable.
430 431 432
 *
 * @param view A pointer on the view.
 *
433 434 435
 * @returns A value indicating the success of the operation.
 * @retval 0 if the operation was successfully completed.
 * @retval -1 if an error occurred.
436 437 438 439
 *
 * @since February 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
440
int obi_save_view(Obiview_p view);
Celine Mercier's avatar
Celine Mercier committed
441

442 443

/**
444
 * @brief Closes an opened view.
445
 *
446
 * @warning Use obi_save_and_close_view() to automatically save the view if it's not already saved in the view file.
447 448 449
 *
 * @param view A pointer on the view.
 *
450 451 452
 * @returns A value indicating the success of the operation.
 * @retval 0 if the operation was successfully completed.
 * @retval -1 if an error occurred.
453 454 455 456
 *
 * @since February 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
457
int obi_close_view(Obiview_p view);
Celine Mercier's avatar
Celine Mercier committed
458

459 460

/**
461
 * @brief Closes an opened view, and saves it if it is not read-only (meaning it is not already saved in the view file).
462 463 464 465 466 467 468 469 470 471
 *
 * @param view A pointer on the view.
 *
 * @returns A value indicating the success of the operation.
 * @retval 0 if the operation was successfully completed.
 * @retval -1 if an error occurred.
 *
 * @since February 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
472
int obi_save_and_close_view(Obiview_p view);
Celine Mercier's avatar
Celine Mercier committed
473

474 475

/**
476
 * @brief Opens the structure containing all the informations written in the view file.
477
 *
478
 * @param dms A pointer on the OBIDMS to which the view file belongs.
479
 *
480 481
 * @returns A pointer on the view informations structure.
 * @retval NULL if an error occurred.
482 483 484 485
 *
 * @since February 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
486
Obiviews_infos_all_p obi_read_view_infos(OBIDMS_p dms);
Celine Mercier's avatar
Celine Mercier committed
487

488 489

/**
490
 * @brief Closes the structure containing all the informations written in the view file.
491
 *
492
 * @param views A pointer on the view informations structure.
493 494 495 496 497 498 499 500
 *
 * @returns A value indicating the success of the operation.
 * @retval 0 if the operation was successfully completed.
 * @retval -1 if an error occurred.
 *
 * @since February 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
501
int obi_close_view_infos(Obiviews_infos_all_p views);
Celine Mercier's avatar
Celine Mercier committed
502

503

504 505
// TODO in following functions would it be better to use column names instead of column pointers?
//		check if it would be a gain or loss of time
506 507

/**
508 509
 * @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.
510
 *
511
 *  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.
512
 *
513 514
 * @param view A pointer on the opened writable view.
 * @param column A pointer on the column.
515 516 517 518 519 520 521 522 523 524 525 526 527 528 529
 * @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 February 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
int obi_column_set_obibool_with_elt_idx_in_view(Obiview_p view, OBIDMS_column_p column, index_t line_nb, index_t element_idx, obibool_t value);


/**
530
 * @brief Recovers a value in an OBIDMS column containing data with the type OBI_BOOL, in the context of a view.
531
 *
532 533
 * @param view A pointer on the opened view.
 * @param column A pointer on the column.
534 535 536 537 538 539 540 541 542 543 544 545 546 547
 * @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 February 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
obibool_t obi_column_get_obibool_with_elt_idx_in_view(Obiview_p view, OBIDMS_column_p column, index_t line_nb, index_t element_idx);


/**
 * @brief Sets a value in an OBIDMS column containing data with the type OBI_BOOL,
548
 *        using the name of the element in the line, in the context of a view.
549
 *
550 551
 * @param view A pointer on the opened writable view.
 * @param column A pointer on the column.
552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567
 * @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 February 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
int obi_column_set_obibool_with_elt_name_in_view(Obiview_p view, OBIDMS_column_p column, 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,
568
 *        using the name of the element in the line, in the context of a view.
569
 *
570 571
 * @param view A pointer on the opened view.
 * @param column A pointer on the column.
572 573 574 575 576 577 578 579 580 581 582 583 584
 * @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 February 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
obibool_t obi_column_get_obibool_with_elt_name_in_view(Obiview_p view, OBIDMS_column_p column, index_t line_nb, const char* element_name);


/**
585 586
 * @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.
587
 *
588
 *  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.
589
 *
590 591
 * @param view A pointer on the opened writable view.
 * @param column A pointer on the column.
592 593 594 595 596 597 598 599 600 601 602 603 604 605 606
 * @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 February 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
int obi_column_set_obichar_with_elt_idx_in_view(Obiview_p view, OBIDMS_column_p column, index_t line_nb, index_t element_idx, obichar_t value);


/**
607
 * @brief Recovers a value in an OBIDMS column containing data with the type OBI_CHAR, in the context of a view.
608
 *
609 610
 * @param view A pointer on the opened view.
 * @param column A pointer on the column.
611 612 613 614 615 616 617 618 619 620 621 622 623 624
 * @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 February 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
obichar_t obi_column_get_obichar_with_elt_idx_in_view(Obiview_p view, OBIDMS_column_p column, index_t line_nb, index_t element_idx);


/**
 * @brief Sets a value in an OBIDMS column containing data with the type OBI_CHAR,
625
 *        using the name of the element in the line, in the context of a view.
626
 *
627 628
 * @param view A pointer on the opened writable view.
 * @param column A pointer on the column.
629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644
 * @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 February 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
int obi_column_set_obichar_with_elt_name_in_view(Obiview_p view, OBIDMS_column_p column, 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,
645
 *        using the name of the element in the line, in the context of a view.
646
 *
647 648
 * @param view A pointer on the opened view.
 * @param column A pointer on the column.
649 650 651 652 653 654 655 656 657 658 659 660 661
 * @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 February 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
obichar_t obi_column_get_obichar_with_elt_name_in_view(Obiview_p view, OBIDMS_column_p column, index_t line_nb, const char* element_name);


/**
662 663
 * @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.
664
 *
665
 *  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.
666
 *
667 668
 * @param view A pointer on the opened writable view.
 * @param column A pointer on the column.
669 670 671 672 673 674 675 676 677 678 679 680 681 682 683
 * @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 February 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
int obi_column_set_obifloat_with_elt_idx_in_view(Obiview_p view, OBIDMS_column_p column, index_t line_nb, index_t element_idx, obifloat_t value);


/**
684
 * @brief Recovers a value in an OBIDMS column containing data with the type OBI_FLOAT, in the context of a view.
685
 *
686 687
 * @param view A pointer on the opened view.
 * @param column A pointer on the column.
688 689 690 691 692 693 694 695 696 697 698 699 700 701
 * @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 February 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
obifloat_t obi_column_get_obifloat_with_elt_idx_in_view(Obiview_p view, OBIDMS_column_p column, index_t line_nb, index_t element_idx);


/**
 * @brief Sets a value in an OBIDMS column containing data with the type OBI_FLOAT,
702
 *        using the name of the element in the line, in the context of a view.
703
 *
704 705
 * @param view A pointer on the opened writable view.
 * @param column A pointer on the column.
706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721
 * @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 February 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
int obi_column_set_obifloat_with_elt_name_in_view(Obiview_p view, OBIDMS_column_p column, 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,
722
 *        using the name of the element in the line, in the context of a view.
723
 *
724 725
 * @param view A pointer on the opened view.
 * @param column A pointer on the column.
726 727 728 729 730 731 732 733 734 735 736 737 738
 * @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 February 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
obifloat_t obi_column_get_obifloat_with_elt_name_in_view(Obiview_p view, OBIDMS_column_p column, index_t line_nb, const char* element_name);


/**
739 740
 * @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.
741
 *
742
 *  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.
743
 *
744 745
 * @param view A pointer on the opened writable view.
 * @param column A pointer on the column.
746 747 748 749 750 751 752 753 754 755 756 757 758 759 760
 * @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 February 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
int obi_column_set_obiint_with_elt_idx_in_view(Obiview_p view, OBIDMS_column_p column, index_t line_nb, index_t element_idx, obiint_t value);


/**
761
 * @brief Recovers a value in an OBIDMS column containing data with the type OBI_INT, in the context of a view.
762
 *
763 764
 * @param view A pointer on the opened view.
 * @param column A pointer on the column.
765 766 767 768
 * @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.
769
 * @retval OBIInt_NA the NA value of the type if an error occurred and obi_errno is set.
770 771 772 773 774 775 776 777 778
 *
 * @since February 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
obiint_t obi_column_get_obiint_with_elt_idx_in_view(Obiview_p view, OBIDMS_column_p column, index_t line_nb, index_t element_idx);


/**
 * @brief Sets a value in an OBIDMS column containing data with the type OBI_INT,
779
 *        using the name of the element in the line, in the context of a view.
780
 *
781 782
 * @param view A pointer on the opened writable view.
 * @param column A pointer on the column.
783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798
 * @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 February 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
int obi_column_set_obiint_with_elt_name_in_view(Obiview_p view, OBIDMS_column_p column, 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,
799
 *        using the name of the element in the line, in the context of a view.
800
 *
801 802
 * @param view A pointer on the opened view.
 * @param column A pointer on the column.
803 804 805 806
 * @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.
807
 * @retval OBIInt_NA the NA value of the type if an error occurred and obi_errno is set.
808 809 810 811 812 813 814 815
 *
 * @since February 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
obiint_t obi_column_get_obiint_with_elt_name_in_view(Obiview_p view, OBIDMS_column_p column, index_t line_nb, const char* element_name);


/**
816 817
 * @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.
818
 *
819
 *  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.
820
 *
821 822
 * @param view A pointer on the opened writable view.
 * @param column A pointer on the column.
823 824 825 826 827 828 829 830 831 832 833 834 835 836 837
 * @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 February 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
int obi_column_set_obiseq_with_elt_idx_in_view(Obiview_p view, OBIDMS_column_p column, index_t line_nb, index_t element_idx, const char* value);


/**
838
 * @brief Recovers a value in an OBIDMS column containing data with the type OBI_SEQ, in the context of a view.
839
 *
840 841
 * @param view A pointer on the opened view.
 * @param column A pointer on the column.
842 843 844 845
 * @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.
846
 * @retval OBISeq_NA the NA value of the type if an error occurred and obi_errno is set.
847 848 849 850 851 852 853 854
 *
 * @since February 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
char* obi_column_get_obiseq_with_elt_idx_in_view(Obiview_p view, OBIDMS_column_p column, index_t line_nb, index_t element_idx);


/**
855 856
 * @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.
857
 *
858 859
 * @param view A pointer on the opened writable view.
 * @param column A pointer on the column.
860 861 862 863 864 865 866 867 868 869 870 871 872 873 874
 * @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 February 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
int obi_column_set_obiseq_with_elt_name_in_view(Obiview_p view, OBIDMS_column_p column, index_t line_nb, const char* element_name, const char* value);


/**
875 876
 * @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.
877
 *
878 879
 * @param view A pointer on the opened view.
 * @param column A pointer on the column.
880 881 882 883
 * @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.
884
 * @retval OBISeq_NA the NA value of the type if an error occurred and obi_errno is set.
885 886 887 888 889 890 891 892
 *
 * @since February 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
char* obi_column_get_obiseq_with_elt_name_in_view(Obiview_p view, OBIDMS_column_p column, index_t line_nb, const char* element_name);


/**
893 894
 * @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.
895
 *
896
 *  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.
897
 *
898 899
 * @param view A pointer on the opened writable view.
 * @param column A pointer on the column.
900 901 902 903 904 905 906 907 908 909 910 911 912 913 914
 * @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 February 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
int obi_column_set_obistr_with_elt_idx_in_view(Obiview_p view, OBIDMS_column_p column, index_t line_nb, index_t element_idx, const char* value);


/**
915
 * @brief Recovers a value in an OBIDMS column containing data with the type OBI_STR, in the context of a view.
916
 *
917 918
 * @param view A pointer on the opened view.
 * @param column A pointer on the column.
919 920 921 922
 * @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.
923
 * @retval OBIStr_NA the NA value of the type if an error occurred and obi_errno is set.
924 925 926 927 928 929 930 931
 *
 * @since February 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
const char* obi_column_get_obistr_with_elt_idx_in_view(Obiview_p view, OBIDMS_column_p column, index_t line_nb, index_t element_idx);


/**
932 933
 * @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.
934
 *
935 936
 * @param view A pointer on the opened writable view.
 * @param column A pointer on the column.
937 938 939 940 941 942 943 944 945 946 947 948 949 950 951
 * @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 February 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
int obi_column_set_obistr_with_elt_name_in_view(Obiview_p view, OBIDMS_column_p column, index_t line_nb, const char* element_name, const char* value);


/**
952 953
 * @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.
954
 *
955 956
 * @param view A pointer on the opened view.
 * @param column A pointer on the column.
957 958 959 960
 * @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.
961
 * @retval OBIStr_NA the NA value of the type if an error occurred and obi_errno is set.
962 963 964 965 966 967 968
 *
 * @since February 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
const char* obi_column_get_obistr_with_elt_name_in_view(Obiview_p view, OBIDMS_column_p column, index_t line_nb, const char* element_name);


Celine Mercier's avatar
Celine Mercier committed
969
#endif /* OBIVIEW_H_ */