utils.h 6.44 KB
Newer Older
1
/****************************************************************************
2
 * Header file for utility functions                                        *
3 4
 ****************************************************************************/

5
/**
6
 * @file utils.h
7
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
8 9
 * @date 29 March 2016
 * @brief Header file for utility functions.
10 11
 */

12

13 14
#ifndef UTILS_H_
#define UTILS_H_
15

16
#include <stdio.h>
17 18
#include <sys/stat.h>

Celine Mercier's avatar
Celine Mercier committed
19
#include "obidms.h"
20
#include "obitypes.h"
21

22

23 24 25 26 27 28 29 30 31 32
#define FORMATTED_TIME_LENGTH (1024)    					/**< The length allocated for the character string containing a formatted date.
 	 	 	 	 	 	 	 	 	     	 	 	 	 	 */
#define ONE_IF_ZERO(x) (((x)==0)?1:(x))						/**< If x is equal to 0, x takes the value 1.
                                	   	 	 	 	 	 	 */
#define DNA_ALPHA   "acgtbdefhijklmnopqrsuvwxyz#![]"	    /**< DNA alphabet (IUPAC).
 	 	 	 	  //"ABCDEFGHIJKLMNOPQRSTUVWXYZ#![]" 	 	 */
#define CDNA_ALPHA  "tgcavhefdijmlknopqysabwxrz#!]["		/**< Complementary DNA alphabet (IUPAC).
 	 	 	 	  //"TVGHEFCDIJMLKNOPQYSAABWXRZ#!][" 	 	 */


33

34 35 36 37 38 39 40 41 42 43 44 45 46 47
/**
 * @brief Copy the content of a file into another file.
 *
 * @param src_file_path The path to the source file to copy.
 * @param dest_file_path The path to the destination file.
 *
 * @retval 0 if the operation was successfully completed.
 * @retval -1 if an error occurred.
 *
 * @since July 2017
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
int copy_file(const char* src_file_path, const char* dest_file_path);

48

49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77
/**
 * @brief Counts the number of digits of a number.
 *
 * @param i The number.
 *
 * @returns The number of digits of the number.
 *
 * @since July 2017
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
int digit_count(index_t i);


/**
 * @brief Builds a word from a prefix and an index, with the form prefix_index.
 *
 * @warning The returned pointer has to be freed by the caller.
 *
 * @param prefix The prefix for the word.
 * @param idx The index to use as suffix.
 *
 * @returns The built word.
 *
 * @since July 2017
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
char* build_word_with_idx(const char* prefix, index_t idx);


78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101
/**
 * @brief Counts the number of files and directories in a directory.
 *
 * @param dir_path The absolute path of the directory.
 *
 * @returns The number of files and directories in the directory.
 *
 * @since April 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
int count_dir(char* dir_path);


/**
 * @brief Formats a date in a way that is easy to read.
 *
 * @warning The pointer returned must be freed by the caller.
 *
 * @param date A date.
 *
 * @returns The date formatted in a way that is easy to read.
 *
 * @since October 2015
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
102
 */
103
char* obi_format_date(time_t date);
104 105


106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126
/**
 * @brief Allocates a chunk of memory aligned on 16 bytes boundary.
 *
 * @warning The pointer returned must be freed by the caller.
 * @warning The memory chunk pointed at by the returned pointer can be
 *          smaller than the size asked for, since the address is shifted
 *          to be aligned.
 *
 * @param size The size in bytes of the memory chunk to be allocated.
 * 			   Ideally the closest multiple of 16 greater than the wanted size.
 * @param shift A pointer on an integer corresponding to the shift made to align
 * 				the address. Used to free the memory chunk.
 *
 * @returns The pointer on the aligned memory.
 *
 * @since May 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
void* obi_get_memory_aligned_on_16(int size, int* shift);


127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163
/**
 * @brief Version of quick sort modified to allow the user to provide an
 *        additional pointer sent to the comparison function.
 *
 * @param key This is the pointer to the object that serves as key for the search, type-casted as a void*.
 * @param base This is the pointer to the first object of the array where the search is performed, type-casted as a void*.
 * @param num This is the number of elements in the array pointed by base.
 * @param size This is the size in bytes of each element in the array.
 * @param user_data This is an additional pointer passed to the comparison function.
 * @param cmp This is the function that compares two elements, eventually with an additional pointer.
 *
 * @returns A pointer to an entry in the array that matches the search key.
 * @retval NULL if key is not found.
 *
 * @since January 2017
 * @author original code modified by Celine Mercier (celine.mercier@metabarcoding.org)
 */
void* bsearch_user_data(const void* key, const void* base, size_t num, size_t size, const void* user_data,
              	  	  	int (*cmp)(const void *key, const void *elt, const void* user_data));


/**
 * @brief Version of quick sort modified to allow the user to provide an
 *        additional pointer sent to the comparison function.
 *
 * @param aa This is the pointer to the first element of the array to be sorted.
 * @param n This is the number of elements in the array pointed by base.
 * @param es This is the size in bytes of each element in the array.
 * @param user_data This is an additional pointer passed to the comparison function.
 * @param cmp This is the function that compares two elements, eventually with an additional pointer.
 *
 * @since January 2017
 * @author original code modified by Celine Mercier (celine.mercier@metabarcoding.org)
 */
void qsort_user_data(void *aa, size_t n, size_t es, const void *user_data, int (*cmp)(const void *, const void *, const void *));


164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197
/**
 * Function returning the reverse complement of a nucleotide sequence.
 *
 * @warning The sequence must be in lower case.
 * @warning The sequence will be replaced by its reverse complement without being copied.
 *
 * @param nucAcSeq The nucleotide sequence.
 *
 * @returns The reverse complemented sequence.
 *
 * @since December 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 * @note Copied from ecoPCR source code
 */
char* reverse_complement_sequence(char* nucAcSeq);


/**
 * Function returning the reverse complement of a pattern.
 *
 * @warning The pattern must be in lower case.
 * @warning The pattern will be replaced by its reverse complement without being copied.
 *
 * @param nucAcSeq The pattern.
 *
 * @returns The reverse complemented pattern.
 *
 * @since December 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 * @note Copied from ecoPCR source code
 */
char* reverse_complement_pattern(char* nucAcSeq);


198
#endif /* UTILS_H_ */