1 #ifndef VIENNA_RNA_PACKAGE_UTILS_H 2 #define VIENNA_RNA_PACKAGE_UTILS_H 3 4 #ifdef VRNA_WARN_DEPRECATED 5 # if defined(__clang__) 6 # define DEPRECATED(func, msg) func __attribute__ ((deprecated("", msg))) 7 # elif defined(__GNUC__) 8 # define DEPRECATED(func, msg) func __attribute__ ((deprecated(msg))) 9 # else 10 # define DEPRECATED(func, msg) func 11 # endif 12 #else 13 # define DEPRECATED(func, msg) func 14 #endif 15 16 /** 17 * @file ViennaRNA/utils/basic.h 18 * @ingroup utils 19 * @brief General utility- and helper-functions used throughout the @em ViennaRNA @em Package 20 */ 21 22 /** 23 * @addtogroup utils 24 * @{ 25 */ 26 27 /* two helper macros to indicate whether a function should be exported in 28 * the library or stays hidden */ 29 #define PUBLIC 30 #define PRIVATE static 31 32 /** 33 * @brief Output flag of get_input_line(): @e "An ERROR has occured, maybe EOF" 34 */ 35 #define VRNA_INPUT_ERROR 1U 36 /** 37 * @brief @brief Output flag of get_input_line(): @e "the user requested quitting the program" 38 */ 39 #define VRNA_INPUT_QUIT 2U 40 /** 41 * @brief Output flag of get_input_line(): @e "something was read" 42 */ 43 #define VRNA_INPUT_MISC 4U 44 45 /** 46 * @brief Input/Output flag of get_input_line():\n 47 * if used as input option this tells get_input_line() that the data to be read should comply 48 * with the FASTA format 49 * 50 * the function will return this flag if a fasta header was read 51 */ 52 #define VRNA_INPUT_FASTA_HEADER 8U 53 54 /* 55 * @brief Input flag for get_input_line():\n 56 * Tell get_input_line() that we assume to read a nucleotide sequence 57 * 58 */ 59 #define VRNA_INPUT_SEQUENCE 16U 60 61 /** @brief Input flag for get_input_line():\n 62 * Tell get_input_line() that we assume to read a structure constraint 63 * 64 */ 65 #define VRNA_INPUT_CONSTRAINT 32U 66 67 /** 68 * @brief Input switch for get_input_line(): 69 * @e "do not trunkate the line by eliminating white spaces at end of line" 70 */ 71 #define VRNA_INPUT_NO_TRUNCATION 256U 72 73 /** 74 * @brief Input switch for vrna_file_fasta_read_record(): @e "do fill rest array" 75 */ 76 #define VRNA_INPUT_NO_REST 512U 77 78 /** 79 * @brief Input switch for vrna_file_fasta_read_record(): @e "never allow data to span more than one line" 80 */ 81 #define VRNA_INPUT_NO_SPAN 1024U 82 83 /** 84 * @brief Input switch for vrna_file_fasta_read_record(): @e "do not skip empty lines" 85 */ 86 #define VRNA_INPUT_NOSKIP_BLANK_LINES 2048U 87 88 /** 89 * @brief Output flag for vrna_file_fasta_read_record(): @e "read an empty line" 90 */ 91 #define VRNA_INPUT_BLANK_LINE 4096U 92 93 /** 94 * @brief Input switch for get_input_line(): @e "do not skip comment lines" 95 */ 96 #define VRNA_INPUT_NOSKIP_COMMENTS 128U 97 98 /** 99 * @brief Output flag for vrna_file_fasta_read_record(): @e "read a comment" 100 */ 101 #define VRNA_INPUT_COMMENT 8192U 102 103 /** 104 * @brief Get the minimum of two comparable values 105 */ 106 #define MIN2(A, B) ((A) < (B) ? (A) : (B)) 107 108 /** 109 * @brief Get the maximum of two comparable values 110 */ 111 #define MAX2(A, B) ((A) > (B) ? (A) : (B)) 112 113 /** 114 * @brief Get the minimum of three comparable values 115 */ 116 #define MIN3(A, B, C) (MIN2((MIN2((A), (B))), (C))) 117 118 /** 119 * @brief Get the maximum of three comparable values 120 */ 121 #define MAX3(A, B, C) (MAX2((MAX2((A), (B))), (C))) 122 123 #include <stdio.h> 124 #include <stdarg.h> 125 126 #include <ViennaRNA/datastructures/basic.h> 127 128 129 #ifdef WITH_DMALLOC 130 /* use dmalloc library to check for memory management bugs */ 131 #include "dmalloc.h" 132 #define vrna_alloc(S) calloc(1, (S)) 133 #define vrna_realloc(p, S) xrealloc(p, S) 134 #else 135 136 /** 137 * @brief Allocate space safely 138 * 139 * @param size The size of the memory to be allocated in bytes 140 * @return A pointer to the allocated memory 141 */ 142 void * 143 vrna_alloc(unsigned size); 144 145 146 /** 147 * @brief Reallocate space safely 148 * 149 * @param p A pointer to the memory region to be reallocated 150 * @param size The size of the memory to be allocated in bytes 151 * @return A pointer to the newly allocated memory 152 */ 153 void * 154 vrna_realloc(void *p, 155 unsigned size); 156 157 158 #endif 159 160 /** 161 * @brief Initialize seed for random number generator 162 */ 163 void 164 vrna_init_rand(void); 165 166 167 /** 168 * @brief Current 48 bit random number 169 * 170 * This variable is used by vrna_urn(). These should be set to some 171 * random number seeds before the first call to vrna_urn(). 172 * 173 * @see vrna_urn() 174 */ 175 extern unsigned short xsubi[3]; 176 177 /** 178 * @brief get a random number from [0..1] 179 * 180 * @see vrna_int_urn(), vrna_init_rand() 181 * @note Usually implemented by calling @e erand48(). 182 * @return A random number in range [0..1] 183 */ 184 double 185 vrna_urn(void); 186 187 188 /** 189 * @brief Generates a pseudo random integer in a specified range 190 * 191 * @see vrna_urn(), vrna_init_rand() 192 * @param from The first number in range 193 * @param to The last number in range 194 * @return A pseudo random number in range [from, to] 195 */ 196 int 197 vrna_int_urn(int from, 198 int to); 199 200 201 /** 202 * @brief Get a timestamp 203 * 204 * Returns a string containing the current date in the format 205 * @verbatim Fri Mar 19 21:10:57 1993 @endverbatim 206 * 207 * @return A string containing the timestamp 208 */ 209 char * 210 vrna_time_stamp(void); 211 212 213 /** 214 * Retrieve a line from 'stdin' savely while skipping comment characters and 215 * other features 216 * This function returns the type of input it has read if recognized. 217 * An option argument allows one to switch between different reading modes.\n 218 * Currently available options are:\n 219 * #VRNA_INPUT_COMMENT, #VRNA_INPUT_NOSKIP_COMMENTS, #VRNA_INPUT_NO_TRUNCATION 220 * 221 * pass a collection of options as one value like this: 222 * @verbatim get_input_line(string, option_1 | option_2 | option_n) @endverbatim 223 * 224 * If the function recognizes the type of input, it will report it in the return 225 * value. It also reports if a user defined 'quit' command (@-sign on 'stdin') 226 * was given. Possible return values are:\n 227 * #VRNA_INPUT_FASTA_HEADER, #VRNA_INPUT_ERROR, #VRNA_INPUT_MISC, #VRNA_INPUT_QUIT 228 * 229 * @param string A pointer to the character array that contains the line read 230 * @param options A collection of options for switching the functions behavior 231 * @return A flag with information about what has been read 232 */ 233 unsigned int 234 get_input_line(char **string, 235 unsigned int options); 236 237 238 /** 239 * @brief Get an index mapper array (iindx) for accessing the energy matrices, e.g. in partition function related functions. 240 * 241 * Access of a position "(i,j)" is then accomplished by using @verbatim (i,j) ~ iindx[i]-j @endverbatim 242 * This function is necessary as most of the two-dimensional energy matrices are actually one-dimensional arrays throughout 243 * the ViennaRNA Package 244 * 245 * Consult the implemented code to find out about the mapping formula ;) 246 * 247 * @see vrna_idx_col_wise() 248 * @param length The length of the RNA sequence 249 * @return The mapper array 250 */ 251 int * 252 vrna_idx_row_wise(unsigned int length); 253 254 255 /** 256 * @brief Get an index mapper array (indx) for accessing the energy matrices, e.g. in MFE related functions. 257 * 258 * Access of a position "(i,j)" is then accomplished by using @verbatim (i,j) ~ indx[j]+i @endverbatim 259 * This function is necessary as most of the two-dimensional energy matrices are actually one-dimensional arrays throughout 260 * the ViennaRNAPackage 261 * 262 * Consult the implemented code to find out about the mapping formula ;) 263 * 264 * @see vrna_idx_row_wise() 265 * @param length The length of the RNA sequence 266 * @return The mapper array 267 * 268 */ 269 int * 270 vrna_idx_col_wise(unsigned int length); 271 272 273 /** 274 * @} 275 */ 276 277 /** 278 * @addtogroup message_utils 279 * @{ 280 * @brief Functions to print various kind of messages 281 */ 282 283 /** 284 * @brief Print an error message and die 285 * 286 * This function is a wrapper to @em fprintf(stderr, ...) that 287 * puts a capital <b>ERROR:</b> in front of the message and then exits 288 * the calling program. 289 * 290 * @see vrna_message_verror(), vrna_message_warning(), vrna_message_info() 291 * 292 * @param format The error message to be printed 293 * @param ... Optional arguments for the formatted message string 294 */ 295 void 296 vrna_message_error(const char *format, 297 ...); 298 299 300 /** 301 * @brief Print an error message and die 302 * 303 * This function is a wrapper to @em vfprintf(stderr, ...) that 304 * puts a capital <b>ERROR:</b> in front of the message and then exits 305 * the calling program. 306 * 307 * @see vrna_message_error(), vrna_message_warning(), vrna_message_info() 308 * 309 * @param format The error message to be printed 310 * @param args The argument list for the formatted message string 311 */ 312 void 313 vrna_message_verror(const char *format, 314 va_list args); 315 316 317 /** 318 * @brief Print a warning message 319 * 320 * This function is a wrapper to @em fprintf(stderr, ...) that 321 * puts a capital <b>WARNING:</b> in front of the message. 322 * 323 * @see vrna_message_vwarning(), vrna_message_error(), vrna_message_info() 324 * 325 * @param format The warning message to be printed 326 * @param ... Optional arguments for the formatted message string 327 */ 328 void 329 vrna_message_warning(const char *format, 330 ...); 331 332 333 /** 334 * @brief Print a warning message 335 * 336 * This function is a wrapper to @em fprintf(stderr, ...) that 337 * puts a capital <b>WARNING:</b> in front of the message. 338 * 339 * @see vrna_message_vwarning(), vrna_message_error(), vrna_message_info() 340 * 341 * @param format The warning message to be printed 342 * @param args The argument list for the formatted message string 343 */ 344 void 345 vrna_message_vwarning(const char *format, 346 va_list args); 347 348 349 /** 350 * @brief Print an info message 351 * 352 * This function is a wrapper to @em fprintf(...). 353 * 354 * @see vrna_message_vinfo(), vrna_message_error(), vrna_message_warning() 355 * 356 * @param fp The file pointer where the message is printed to 357 * @param format The warning message to be printed 358 * @param ... Optional arguments for the formatted message string 359 */ 360 void 361 vrna_message_info(FILE *fp, 362 const char *format, 363 ...); 364 365 366 /** 367 * @brief Print an info message 368 * 369 * This function is a wrapper to @em fprintf(...). 370 * 371 * @see vrna_message_vinfo(), vrna_message_error(), vrna_message_warning() 372 * 373 * @param fp The file pointer where the message is printed to 374 * @param format The info message to be printed 375 * @param args The argument list for the formatted message string 376 */ 377 void 378 vrna_message_vinfo(FILE *fp, 379 const char *format, 380 va_list args); 381 382 383 /** 384 * @brief Print a line to @e stdout that asks for an input sequence 385 * 386 * There will also be a ruler (scale line) printed that helps orientation of the sequence positions 387 */ 388 void 389 vrna_message_input_seq_simple(void); 390 391 392 /** 393 * @brief Print a line with a user defined string and a ruler to stdout. 394 * 395 * (usually this is used to ask for user input) 396 * There will also be a ruler (scale line) printed that helps orientation of the sequence positions 397 * 398 * @param s A user defined string that will be printed to stdout 399 */ 400 void 401 vrna_message_input_seq(const char *s); 402 403 404 void 405 vrna_message_input_msa(const char *s); 406 407 408 /** 409 * @} 410 */ 411 412 #ifndef VRNA_DISABLE_BACKWARD_COMPATIBILITY 413 414 DEPRECATED(int *get_indx(unsigned int length), "Use vrna_idx_col_wise() instead"); 415 416 DEPRECATED(int *get_iindx(unsigned int length), "Use vrna_idx_row_wise() instead"); 417 418 /** 419 * @brief Read a line of arbitrary length from a stream 420 * 421 * Returns a pointer to the resulting string. The necessary memory is 422 * allocated and should be released using @e free() when the string is 423 * no longer needed. 424 * 425 * @deprecated Use vrna_read_line() as a substitute! 426 * 427 * @param fp A file pointer to the stream where the function should read from 428 * @return A pointer to the resulting string 429 */ 430 DEPRECATED(char *get_line(FILE *fp), "Use vrna_read_line() instead"); 431 432 /** 433 * @brief Print a line to @e stdout that asks for an input sequence 434 * 435 * There will also be a ruler (scale line) printed that helps orientation of the sequence positions 436 * @deprecated Use vrna_message_input_seq_simple() instead! 437 */ 438 DEPRECATED(void print_tty_input_seq(void), "Use vrna_message_input_seq_simple() instead"); 439 440 /** 441 * @brief Print a line with a user defined string and a ruler to stdout. 442 * 443 * (usually this is used to ask for user input) 444 * There will also be a ruler (scale line) printed that helps orientation of the sequence positions 445 * 446 * @deprecated Use vrna_message_input_seq() instead! 447 */ 448 DEPRECATED(void print_tty_input_seq_str(const char *s), "Use vrna_message_input_seq() instead"); 449 450 /** 451 * @brief Print a warning message 452 * 453 * Print a warning message to @e stderr 454 * 455 * @deprecated Use vrna_message_warning() instead! 456 */ 457 DEPRECATED(void warn_user(const char message[]), "Use vrna_message_warning() instead"); 458 459 /** 460 * @brief Die with an error message 461 * 462 * @deprecated Use vrna_message_error() instead! 463 */ 464 DEPRECATED(void nrerror(const char message[]), "Use vrna_message_error() instead()"); 465 466 /** 467 * @brief Allocate space safely 468 * 469 * @deprecated Use vrna_alloc() instead! 470 */ 471 DEPRECATED(void *space(unsigned size), "Use vrna_alloc() instead"); 472 473 /** 474 * @brief Reallocate space safely 475 * 476 * @deprecated Use vrna_realloc() instead! 477 */ 478 DEPRECATED(void *xrealloc(void *p, 479 unsigned size), "Use vrna_realloc() instead"); 480 481 /** 482 * @brief Make random number seeds 483 * @deprecated Use vrna_init_rand() instead! 484 */ 485 DEPRECATED(void init_rand(void), "Use vrna_init_rand() instead"); 486 487 /** 488 * @brief get a random number from [0..1] 489 * 490 * @deprecated Use vrna_urn() instead! 491 */ 492 DEPRECATED(double urn(void), "Use vrna_urn() instead"); 493 494 /** 495 * @brief Generates a pseudo random integer in a specified range 496 * 497 * @deprecated Use vrna_int_urn() instead! 498 */ 499 DEPRECATED(int int_urn(int from, 500 int to), "Use vrna_int_urn() instead()"); 501 502 /** 503 * @brief Inefficient `cp` 504 * 505 * @deprecated Use vrna_file_copy() instead! 506 */ 507 DEPRECATED(void filecopy(FILE *from, 508 FILE *to), "Use vrna_file_copy() instead"); 509 510 /** 511 * @brief Get a timestamp 512 * 513 * @deprecated Use vrna_time_stamp() instead! 514 */ 515 DEPRECATED(char *time_stamp(void), "Use vrna_time_stamp() instead"); 516 517 #endif 518 519 #endif 520