--- /dev/null
+#ifndef __VIENNA_RNA_PACKAGE_UTILS_H__
+#define __VIENNA_RNA_PACKAGE_UTILS_H__
+
+/**
+ * \file utils.h
+ * \brief Various utility- and helper-functions used throughout the Vienna RNA package
+ */
+
+/**
+ * Output flag of \ref get_input_line(): "An ERROR has occured, maybe EOF"
+ */
+#define VRNA_INPUT_ERROR 1U
+/**
+ * Output flag of \ref get_input_line(): "the user requested quitting the program"
+ */
+#define VRNA_INPUT_QUIT 2U
+/**
+ * Output flag of \ref get_input_line(): "something was read"
+ */
+#define VRNA_INPUT_MISC 4U
+
+/** Input/Output flag of \ref get_input_line():\n
+ * if used as input option this tells get_input_line() that the data to be read should comply
+ * with the FASTA format
+ *
+ * the function will return this flag if a fasta header was read
+ */
+#define VRNA_INPUT_FASTA_HEADER 8U
+
+/** Input flag for get_input_line():\n
+ * Tell get_input_line() that we assume to read a nucleotide sequence
+ *
+ */
+#define VRNA_INPUT_SEQUENCE 16U
+
+/** Input flag for get_input_line():\n
+ * Tell get_input_line() that we assume to read a structure constraint
+ *
+ */
+#define VRNA_INPUT_CONSTRAINT 32U
+
+/**
+ * Input switch for \ref get_input_line():
+ * "do not trunkate the line by eliminating white spaces at end of line"
+ */
+#define VRNA_INPUT_NO_TRUNCATION 256U
+
+/**
+ * Input switch for read_record(): "do fill rest array"
+ */
+#define VRNA_INPUT_NO_REST 512U
+
+/**
+ * Input switch for read_record(): "never allow data to span more than one line"
+ */
+#define VRNA_INPUT_NO_SPAN 1024U
+
+/**
+ * Input switch for read_record(): "do not skip empty lines"
+ */
+#define VRNA_INPUT_NOSKIP_BLANK_LINES 2048U
+
+/**
+ * Output flag for read_record(): "read an empty line"
+ */
+#define VRNA_INPUT_BLANK_LINE 4096U
+
+/**
+ * Input switch for \ref get_input_line(): "do not skip comment lines"
+ */
+#define VRNA_INPUT_NOSKIP_COMMENTS 128U
+
+/**
+ * Output flag for read_record(): "read a comment"
+ */
+#define VRNA_INPUT_COMMENT 8192U
+
+
+
+
+/**
+ * pipe sign '|' switch for structure constraints (paired with another base)
+ */
+#define VRNA_CONSTRAINT_PIPE 1U
+/**
+ * dot '.' switch for structure constraints (no constraint at all)
+ */
+#define VRNA_CONSTRAINT_DOT 2U
+/**
+ * 'x' switch for structure constraint (base must not pair)
+ */
+#define VRNA_CONSTRAINT_X 4U
+/**
+ * angle brackets '<', '>' switch for structure constraint (paired downstream/upstream)
+ */
+#define VRNA_CONSTRAINT_ANG_BRACK 8U
+/**
+ * round brackets '(',')' switch for structure constraint (base i pairs base j)
+ */
+#define VRNA_CONSTRAINT_RND_BRACK 16U
+/**
+ * constraint may span over several lines
+ */
+#define VRNA_CONSTRAINT_MULTILINE 32U
+/**
+ * do not print the header information line
+ */
+#define VRNA_CONSTRAINT_NO_HEADER 64U
+/**
+ * placeholder for all constraining characters
+ */
+#define VRNA_CONSTRAINT_ALL 128U
+/**
+ * '+' switch for structure constraint (base is involved in a gquad)
+ */
+#define VRNA_CONSTRAINT_G 256U
+
+
+
+/**
+ * Tell a function that an input is assumed to span several lines if used as input-option
+ * A function might also be returning this state telling that it has read data from
+ * multiple lines.
+ *
+ * \see extract_record_rest_structure(), read_record(), getConstraint()
+ *
+ */
+#define VRNA_OPTION_MULTILINE 32U
+
+
+/**
+ * Get the minimum of two comparable values
+ */
+#define MIN2(A, B) ((A) < (B) ? (A) : (B))
+/**
+ * Get the maximum of two comparable values
+ */
+#define MAX2(A, B) ((A) > (B) ? (A) : (B))
+/**
+ * Get the minimum of three comparable values
+ */
+#define MIN3(A, B, C) (MIN2( (MIN2((A),(B))) ,(C)))
+/**
+ * Get the maximum of three comparable values
+ */
+#define MAX3(A, B, C) (MAX2( (MAX2((A),(B))) ,(C)))
+
+
+/**
+ * Stringify a macro after expansion
+ */
+#define XSTR(s) STR(s)
+/**
+ * Stringify a macro argument
+ */
+#define STR(s) #s
+
+#ifndef FILENAME_MAX_LENGTH
+/**
+ * \brief Maximum length of filenames that are generated by our programs
+ *
+ * This definition should be used throughout the complete ViennaRNA package
+ * wherever a static array holding filenames of output files is declared.
+ */
+#define FILENAME_MAX_LENGTH 80
+/**
+ * \brief Maximum length of id taken from fasta header for filename generation
+ *
+ * this has to be smaller than FILENAME_MAX_LENGTH since in most cases,
+ * some suffix will be appended to the ID
+ */
+#define FILENAME_ID_LENGTH 42
+#endif
+
+
+#ifdef HAVE_CONFIG_H
+#include <config.h>
+#ifndef HAVE_STRDUP
+char *strdup(const char *s);
+#endif
+#endif
+#ifdef WITH_DMALLOC
+/* use dmalloc library to check for memory management bugs */
+#include "dmalloc.h"
+#define space(S) calloc(1,(S))
+#else
+
+/**
+ * \brief Allocate space safely
+ *
+ * \param size The size of the memory to be allocated in bytes
+ * \return A pointer to the allocated memory
+ */
+/*@only@*/ /*@notnull@*/
+void *space(unsigned size) /*@ensures MaxSet(result) == (size-1);@*/;
+
+/**
+ * \brief Reallocate space safely
+ *
+ * \param p A pointer to the memory region to be reallocated
+ * \param size The size of the memory to be allocated in bytes
+ * \return A pointer to the newly allocated memory
+ */
+/*@only@*/ /*@notnull@*/
+void *xrealloc(/*@null@*/ /*@only@*/ /*@out@*/ /*@returned@*/ void *p,
+ unsigned size) /*@modifies *p @*/ /*@ensures MaxSet(result) == (size-1) @*/;
+#endif
+
+/**
+ * \brief Die with an error message
+ *
+ * \see warn_user()
+ * \param message The error message to be printed before exiting with 'FAILURE'
+ */
+/*@exits@*/
+void nrerror(const char message[]);
+
+/**
+ * \brief Print a warning message
+ *
+ * Print a warning message to \e stderr
+ *
+ * \param message The warning message
+ */
+void warn_user(const char message[]);
+
+/**
+ * \brief Make random number seeds
+ */
+void init_rand(void);
+
+/**
+ * \brief Current 48 bit random number
+ *
+ * This variable is used by urn(). These should be set to some
+ * random number seeds before the first call to urn().
+ *
+ * \see urn()
+ */
+extern unsigned short xsubi[3];
+
+/**
+ * \brief get a random number from [0..1]
+ *
+ * \note Usually implemented by calling \e erand48().
+ * \return A random number in range [0..1]
+ */
+double urn(void);
+
+/**
+ * \brief Generates a pseudo random integer in a specified range
+ *
+ * \param from The first number in range
+ * \param to The last number in range
+ * \return A pseudo random number in range [from, to]
+ */
+int int_urn(int from, int to);
+
+void filecopy(FILE *from, FILE *to); /* inefficient `cp' */
+
+/**
+ * \brief Get a timestamp
+ *
+ * Returns a string containing the current date in the format
+ * \verbatim Fri Mar 19 21:10:57 1993\endverbatim
+ *
+ * \return A string containing the timestamp
+ */
+/*@observer@*/
+char *time_stamp(void);
+
+/**
+ * \brief Create a random string using characters from a specified symbol set
+ *
+ * \param l The length of the sequence
+ * \param symbols The symbol set
+ * \return A random string of length 'l' containing characters from the symbolset
+ */
+/*@only@*/ /*@notnull@*/
+char *random_string(int l, const char symbols[]);
+
+/**
+ * \brief Calculate hamming distance between two sequences
+ *
+ * Calculate the number of positions in which
+ * \param s1 The first sequence
+ * \param s2 The second sequence
+ * \return The hamming distance between s1 and s2
+ */
+int hamming(const char *s1, const char *s2);
+
+/**
+ * \brief Calculate hamming distance between two sequences up to a specified length
+ *
+ * This function is similar to hamming() but instead of comparing both sequences
+ * up to their actual length only the first 'n' characters are taken into account
+ * \param s1 The first sequence
+ * \param s2 The second sequence
+ * \return The hamming distance between s1 and s2
+ */
+int hamming_bound(const char *s1, const char *s2, int n);
+
+/**
+ * \brief Read a line of arbitrary length from a stream
+ *
+ * Returns a pointer to the resulting string. The necessary memory is
+ * allocated and should be released using \e free() when the string is
+ * no longer needed.
+ *
+ * \param fp A file pointer to the stream where the function should read from
+ * \return A pointer to the resulting string
+ */
+/*@only@*/ /*@null@*/
+char *get_line(FILE *fp);
+
+int skip_comment_lines(char **line);
+
+/**
+ * Retrieve a line from 'stdin' savely while skipping comment characters and
+ * other features
+ * This function returns the type of input it has read if recognized.
+ * An option argument allows to switch between different reading modes.\n
+ * Currently available options are:\n
+ * #VRNA_INPUT_NOPRINT_COMMENTS, #VRNA_INPUT_NOSKIP_COMMENTS, #VRNA_INPUT_NOELIM_WS_SUFFIX
+ *
+ * pass a collection of options as one value like this:
+ * \verbatim get_input_line(string, option_1 | option_2 | option_n) \endverbatim
+ *
+ * If the function recognizes the type of input, it will report it in the return
+ * value. It also reports if a user defined 'quit' command (@-sign on 'stdin')
+ * was given. Possible return values are:\n
+ * #VRNA_INPUT_FASTA_HEADER, #VRNA_INPUT_ERROR, #VRNA_INPUT_MISC, #VRNA_INPUT_QUIT
+ *
+ * \param string A pointer to the character array that contains the line read
+ * \param options A collection of options for switching the functions behavior
+ * \return A flag with information about what has been read
+ */
+unsigned int get_input_line(char **string,
+ unsigned int options);
+
+unsigned int get_multi_input_line(char **string,
+ unsigned int options);
+
+/**
+ * \brief Get a data record from stdin
+ *
+ * This function may be used to obtain complete datasets from stdin. A dataset is always
+ * defined to contain at least a sequence. If data on stdin starts with a fasta header,
+ * i.e. a line like
+ * \verbatim >some header info \endverbatim
+ * then read_record() will assume that the sequence that follows the header may span
+ * over several lines. To disable this behavior and to assign a single line to the argument
+ * 'sequence' one can pass VRNA_INPUT_NO_SPAN in the 'options' argument.
+ * If no fasta header is read in the beginning of a data block, a sequence must not span over
+ * multiple lines!\n
+ * Unless the options #VRNA_INPUT_NOSKIP_COMMENTS or #VRNA_INPUT_NOSKIP_BLANK_LINES are passed,
+ * a sequence may be interrupted by lines starting with a comment character or empty lines.\n
+ * A sequence is regarded as completely read if it was either assumed to not span over multiple
+ * lines, a secondary structure or structure constraint follows the sequence on the next line
+ * or a new header marks the beginning of a new sequence...\n
+ * All lines following the sequence (this includes comments) and not initiating a new dataset are
+ * available through the line-array 'rest'. Here one can usually find the structure constraint or
+ * other information belonging to the current dataset. Filling of 'rest' may be prevented by
+ * passing #VRNA_INPUT_NO_REST to the options argument.\n
+ *
+ * \note This function will exit any program with an error message if no sequence could be read!
+ *
+ * The main purpose of this function is to be able to easily parse blocks of data from stdin
+ * in the header of a loop where all calculations for the appropriate data is done inside the
+ * loop. The loop may be then left on certain return values, e.g.:
+ * \verbatim
+char *id, *seq, **rest;
+int i;
+while(!(read_record(&id, &seq, &rest, 0) & (VRNA_INPUT_ERROR | VRNA_INPUT_QUIT))){
+ if(id) printf("%s\n", id);
+ printf("%s\n", seq);
+ if(rest)
+ for(i=0;rest[i];i++)
+ printf("%s\n", rest[i]);
+} \endverbatim
+ *
+ * In the example above, the while loop will be terminated when read_record() returns either an
+ * error or a user initiated quit request.\n
+ * As long as data is read from stdin, the id is printed if it is available for the current block
+ * of data. The sequence will be printed in any case and if some more lines belong to the current
+ * block of data each line will be printed as well.
+ *
+ * \note Do not forget to free the memory occupied by header, sequence and rest!
+ *
+ * \param header A pointer which will be set such that it points to the header of the record
+ * \param sequence A pointer which will be set such that it points to the sequence of the record
+ * \param rest A pointer which will be set such that it points to an array of lines which also belong to the record
+ * \param options Some options which may be passed to alter the behavior of the function, use 0 for no options
+ * \return A flag with information about what the function actually did read
+ */
+unsigned int read_record( char **header,
+ char **sequence,
+ char ***rest,
+ unsigned int options);
+
+
+/* \brief Extract a dot-bracket structure string from (multiline)character array
+ *
+ * This function extracts a dot-bracket structure string from the 'rest' array as
+ * returned by read_record() and returns it. All occurences of comments within the
+ * 'lines' array will be skipped as long as they do not break the structure string.
+ * If no structure could be read, this function returns NULL.
+ *
+ * \see read_record()
+ *
+ * \param lines The (multiline) character array to be parsed
+ * \param length The assumed length of the dot-bracket string (passing a value < 1 results in no length limit)
+ * \param option Some options which may be passed to alter the behavior of the function, use 0 for no options
+ * \return The dot-bracket string read from lines or NULL
+ */
+char *extract_record_rest_structure(const char **lines,
+ unsigned int length,
+ unsigned int option);
+
+/**
+ * \brief Pack secondary secondary structure, 5:1 compression using base 3 encoding
+ *
+ * Returns a binary string encoding of the secondary structure using
+ * a 5:1 compression scheme. The string is NULL terminated and can
+ * therefore be used with standard string functions such as strcmp().
+ * Useful for programs that need to keep many structures in memory.
+ *
+ * \param struc The secondary structure in dot-bracket notation
+ * \return The binary encoded structure
+ */
+char *pack_structure(const char *struc);
+
+/**
+ * \brief Unpack secondary structure previously packed with pack_structure()
+ *
+ * Translate a compressed binary string produced by pack_structure() back into
+ * the familiar dot-bracket notation.
+ *
+ * \param packed The binary encoded packed secondary structure
+ * \return The unpacked secondary structure in dot-bracket notation
+ */
+char *unpack_structure(const char *packed);
+
+/**
+ * \brief Create a pair table of a secondary structure
+ *
+ * Returns a newly allocated table, such that table[i]=j if (i.j) pair
+ * or 0 if i is unpaired, table[0] contains the length of the structure.
+ *
+ * \param structure The secondary structure in dot-bracket notation
+ * \return A pointer to the created pair_table
+ */
+short *make_pair_table(const char *structure);
+
+short *make_pair_table_pk(const char *structure);
+
+/**
+ * \brief Get an exact copy of a pair table
+ *
+ * \param pt The pair table to be copied
+ * \return A pointer to the copy of 'pt'
+ */
+short *copy_pair_table(const short *pt);
+
+/**
+***Pair table for snoop align
+***
+***
+**/
+short *alimake_pair_table(const char *structure);
+
+/**
+*** returns a newly allocated table, such that: table[i]=j if (i.j) pair or
+*** 0 if i is unpaired, table[0] contains the length of the structure.
+*** The special pseudoknotted H/ACA-mRNA structure is taken into account.
+**/
+short *make_pair_table_snoop(const char *structure);
+
+/**
+ * \brief Compute the "base pair" distance between two secondary structures s1 and s2.
+ *
+ * The sequences should have the same length.
+ * dist = number of base pairs in one structure but not in the other
+ * same as edit distance with open-pair close-pair as move-set
+ *
+ * \param str1 First structure in dot-bracket notation
+ * \param str2 Second structure in dot-bracket notation
+ * \return The base pair distance between str1 and str2
+ */
+
+int *make_loop_index_pt(short *pt);
+
+
+int bp_distance(const char *str1,
+ const char *str2);
+
+/**
+ * \brief Print a line to \e stdout that asks for an input sequence
+ *
+ * There will also be a ruler (scale line) printed that helps orientation of the sequence positions
+ */
+void print_tty_input_seq(void);
+
+/**
+ * \brief Print a line with a user defined string and a ruler to stdout.
+ *
+ * (usually this is used to ask for user input)
+ * There will also be a ruler (scale line) printed that helps orientation of the sequence positions
+ *
+ * \param s A user defined string that will be printed to stdout
+ */
+void print_tty_input_seq_str(const char *s);
+
+/**
+ * \brief Print structure constraint characters to stdout
+ * (full constraint support)
+ *
+ */
+void print_tty_constraint_full(void);
+
+/**
+ * \brief Print structure constraint characters to stdout.
+ * (constraint support is specified by option parameter)
+ *
+ * Currently available options are:\n
+ * #VRNA_CONSTRAINT_PIPE (paired with another base)\n
+ * #VRNA_CONSTRAINT_DOT (no constraint at all)\n
+ * #VRNA_CONSTRAINT_X (base must not pair)\n
+ * #VRNA_CONSTRAINT_ANG_BRACK (paired downstream/upstream)\n
+ * #VRNA_CONSTRAINT_RND_BRACK (base i pairs base j)\n
+ *
+ * pass a collection of options as one value like this:
+ * \verbatim print_tty_constraint(option_1 | option_2 | option_n) \endverbatim
+ *
+ * \param option Option switch that tells which constraint help will be printed
+ */
+void print_tty_constraint(unsigned int option);
+
+/**
+ * \brief Convert a DNA input sequence to RNA alphabet
+ *
+ * This function substitudes <i>T</i> and <i>t</i> with <i>U</i> and <i>u</i>, respectively
+ *
+ * \param sequence The sequence to be converted
+ */
+void str_DNA2RNA(char *sequence);
+
+/**
+ * \brief Convert an input sequence to uppercase
+ *
+ * \param sequence The sequence to be converted
+ */
+void str_uppercase(char *sequence);
+
+/**
+ * \brief Get an index mapper array (iindx) for accessing the energy matrices, e.g. in partition function related functions.
+ *
+ * Access of a position "(i,j)" is then accomplished by using \verbatim (i,j) ~ iindx[i]-j \endverbatim
+ * This function is necessary as most of the two-dimensional energy matrices are actually one-dimensional arrays throughout
+ * the ViennaRNAPackage
+ *
+ * Consult the implemented code to find out about the mapping formula ;)
+ *
+ * \see get_indx()
+ * \param length The length of the RNA sequence
+ * \return The mapper array
+ */
+int *get_iindx(unsigned int length);
+
+/**
+ * \brief Get an index mapper array (indx) for accessing the energy matrices, e.g. in MFE related functions.
+ *
+ * Access of a position "(i,j)" is then accomplished by using \verbatim (i,j) ~ indx[j]+i \endverbatim
+ * This function is necessary as most of the two-dimensional energy matrices are actually one-dimensional arrays throughout
+ * the ViennaRNAPackage
+ *
+ * Consult the implemented code to find out about the mapping formula ;)
+ *
+ * \see get_iindx()
+ * \param length The length of the RNA sequence
+ * \return The mapper array
+ *
+ */
+int *get_indx(unsigned int length);
+
+void getConstraint( char **cstruc,
+ const char **lines,
+ unsigned int option);
+
+/**
+ * \brief Insert constraining pair types according to constraint structure string
+ *
+ * \see get_indx(), get_iindx()
+ *
+ * \param constraint The structure constraint string
+ * \param length The actual length of the sequence (constraint may be shorter)
+ * \param ptype A pointer to the basepair type array
+ * \param min_loop_size The minimal loop size (usually \ref TURN )
+ * \param idx_type Define the access type for base pair type array (0 = indx, 1 = iindx)
+ */
+void constrain_ptypes(const char *constraint,
+ unsigned int length,
+ char *ptype,
+ int *BP,
+ int min_loop_size,
+ unsigned int idx_type);
+
+unsigned int *make_referenceBP_array(short *reference_pt,
+ unsigned int turn);
+
+unsigned int *compute_BPdifferences( short *pt1,
+ short *pt2,
+ unsigned int turn);
+
+#endif
git://source.jalview.org / jabaws.git / blobdiff