namespace utils

Overview

Various utility methods used by all other modules. More…

// namespaces

namespace utils::exceptions
namespace utils::options

// enums

enum LogLevel

// classes

class LogManager
class Logger
class Profiler
class ProfilingManager
class ThreadPool
class UnitTests

// global variables

static const char dir_separator
const std::string letters

// global functions

std::string basename (const std::string& str)

template <char Remove>
bool BothAre (
    char first,
    char second
    )

template <char Remove>
std::string& combine_same_chars (std::string& str)

std::string download_pdb (const std::string& code)

std::string download_pdb (
    const std::string& code,
    const std::string& local_path
    )

bool ends_with (
    const std::string& str,
    const std::string& ending
    )

void exit_OK_with_message (const std::string& message)

void exit_with_error (
    const std::string& fname,
    const int line,
    const std::string& message
    )

bool find_file (
    const std::string& fname,
    std::string& result,
    const std::string& path
    )

__attribute__ ( (used)) std std::string format_paragraph (
    const std::vector <std::string>& words,
    const std::string& paragraph_pad,
    const std::string& line_pad,
    const int max_line_width,
    const int max_first_line_width
    )

std::string from_base64 (const std::string& in)

template <class T>
T from_string (const std::string& token)

template <class T>
std::vector <T> from_string (
    const std::string& token,
    const core::index2 n_tokens
    )

template <class T>
std::vector <T>& from_string (
    const std::string& token,
    const core::index2 n_tokens,
    std::vector <T>& destination
    )

template <class T>
T from_string (
    std::string& token,
    const T default_value
    )

template <class T>
std::vector <T>& from_string (
    const std::vector <std::string>& tokens,
    std::vector <T>& destination,
    const T default_value
    )

template <class T>
T from_string (
    const std::string& line,
    const int start,
    const int stop,
    const T default_value
    )

std::vector <std::string> glob (const std::string& mask)

bool has_prefix (
    const std::string& str,
    const std::string& prefix
    )

bool has_suffix (
    const std::string& str,
    const std::string& suffix
    )

bool if_file_exists (const std::string& fname)

void in_stream (
    const std::string& fname,
    std::ifstream& in_stream,
    std::ios_base::openmode mode = std::ios_base::in
    )

bool is_integer (const std::string& s)

std::string join_paths (
    const std::string& p1,
    const std::string& p2
    )

std::string& load_binary_file (
    const std::string& filename,
    std::string& buffer
    )

std::string load_text_file (const std::string& fname)

void load_text_file (
    const std::string& fname,
    std::string& sink
    )

const LogLevel& log_level_by_name (const std::string& level)
const std::string& log_level_name (const LogLevel& level)
const std::string& log_level_name_colored (const LogLevel& level)

std::pair <size_t, size_t> matching_bracket (
    const std::string& text,
    const size_t starting_pos,
    const std::string& bracket_type,
    const bool eat_brackets
    )

std::shared_ptr <std::ostream> out_stream (const std::string& fname)
std::string pathname (const std::string& str)
void random_alphanumeric (std::string& result)
std::vector <std::string> read_listfile (const std::string& fname)

void read_listfile (
    const std::string& fname,
    std::vector <std::string>& destination
    )

std::map <std::string, std::vector <std::string>> read_properties_file (
    const std::string& fname,
    const bool replace_underscores_with_spaces = false
    )

std::map <std::string, std::vector <std::string>>& read_properties_file (
    const std::string& fname,
    std::map <std::string, std::vector <std::string>>& storage_map,
    const bool replace_undersores_with_spaces
    )

std::string& replace_substring (
    std::string& subject,
    const std::string& search,
    const std::string& replace
    )

std::pair <std::string, std::string> root_extension (const std::string& str)

std::vector <std::string> split (
    const std::string& str,
    const char delim,
    const bool if_trim_tokens = true
    )

void split (
    const std::string& input_str,
    const std::string& separator,
    const int max,
    std::vector <std::string>& results
    )

template <typename T>
std::vector <T>& split (
    const std::string& s,
    std::vector <T>& tokens,
    const char delim = ' ',
    const bool if_trim_tokens = true
    )

std::vector <std::string>& split (
    const std::string& s,
    std::vector <std::string>& tokens,
    const core::index2 chunk_length
    )

std::vector <std::string>& split_into_strings (
    const std::string& s,
    std::vector <std::string>& tokens,
    const char delim = ' ',
    const bool if_trim_tokens = true
    )

template <typename ... Args>
std::string string_format (
    const std::string& format,
    Args ... args
    )

template <typename ... Args>
std::string string_format (
    const char* format,
    Args ... args
    )

std::string string_format (
    const char* fmt_str,
    const std::vector <float>& data
    )

std::string string_format (
    const char* fmt_str,
    const std::vector <double>& data
    )

double swap_double (const double d)
std::string time_stamp ()
std::string to_base64 (const std::string& in)
double to_double (const char* p)
int to_int (const char* p)
void to_lower (std::string& s)

template <class T>
const std::string to_string (const T& data)

template <class T>
const std::string to_string (
    const std::vector <T>& data,
    const std::string& separator
    )

void to_upper (std::string& s)
std::string& trim (std::string& str)

void trim_extensions (
    std::string& fname,
    std::vector <std::string> extensions = {".pdb.gz",".pdb",".gz",".fasta",".pir"}
    )

std::string& ungzip_string (
    const std::string& str,
    std::string& dest
    )

std::stringstream& ungzip_string (
    const std::string& str,
    std::stringstream& dest
    )

void UnitTests::assert_equals< std::string > (
    const std::string expected,
    const std::string actual
    )

std::string& unzip_string (
    const std::string& str,
    std::string& dest
    )

std::stringstream& unzip_string (
    const std::string& str,
    std::stringstream& dest
    )

std::string& zip_string (
    const std::string& str,
    std::string& dest,
    int compressionlevel = Z_BEST_COMPRESSION
    )

Detailed Documentation

Various utility methods used by all other modules.

Global Variables

static const char dir_separator

Character used to separate sub-directories in a file path.

Global Functions

std::string basename (const std::string& str)

Returns a file name extracted from a path.

template <char Remove>
bool BothAre (
    char first,
    char second
    )

Predicate that returns true if the two given chars are identical and equal to the template parameter.

The predicate is used by combine_same_chars() method.

Parameters:

Remove
  • the character to be recognized by this method
first
  • the first of the two compared characters
second
  • the second of the two compared characters
template <char Remove>
std::string& combine_same_chars (std::string& str)

Substitute multiple subsequent occurrences of a given character with a single char.

In the following examples, each stretch of spaces is substituted with a single space

std::string str = "Crazy     dog";
std::cout << combine_same_chars<' '>(str);

Parameters:

Remove
  • the character to be recognized by this method
str
  • the string to be modified

Returns:

the modified string

std::string download_pdb (const std::string& code)

Download a PDB file from RCSB website.

Example application calls that function to actually bring you a PDB file from the web!


Parameters:

code
  • four letter code of the protein

Returns:

PDB data as a string

std::string download_pdb (
    const std::string& code,
    const std::string& local_path
    )

Tries to find PDB in a local directory, when fails - downloads it from RCSB website.

Parameters:

code
  • four letter code of the protein
local_path
  • local path where the file may be located

Returns:

PDB data as a string

bool ends_with (
    const std::string& str,
    const std::string& ending
    )

Returns true if a given string has a specified ending.

Parameters:

str
  • the input string
ending
  • string that may be found at the end of the str string

Returns:

true if the given ending was found at the end of the given string

bool find_file (
    const std::string& fname,
    std::string& result,
    const std::string& path
    )

Tries to find a file in certain locations and returns true when succeeded.

This method tests:

  • the given file name in a local directory
  • the given file name in the given directory
  • basename of the given file name in the given directory The actual name of the file that has been found will be stored in the result variable

Parameters:

fname
  • name of the file to look for
result
  • if found, resulting file name (possibly with the correct path) will be stored at this reference
path
  • database path to check

Returns:

true if the requested file exists

__attribute__ ( (used)) std std::string format_paragraph (
    const std::vector <std::string>& words,
    const std::string& paragraph_pad,
    const std::string& line_pad,
    const int max_line_width,
    const int max_first_line_width
    )

Converts long strings into nice paragraphs.

The method removes all existing tabs an new line characters and create a single line string that in turn is nicely formatted to fit a given width. If you need to manually break the text or introduce a tab, use the N (new line) or T (tab) special command.

This is a variant of format_paragraph(std::vector<std::string> & , const std::string &, const std::string &, const int) method where the first line might have different length than all the other lines.

Parameters:

words
  • a given line of text
max_line_width
  • length of a paragraph
paragraph_pad
  • string that is used as a prefix for the very first line in each paragraph
line_pad
  • string that is used as a prefix for every line, except the very first line in a paragraph
words
  • a given line of text
max_line_width
  • length of a paragraph
max_first_line_width
  • length of the very first line in a paragraph
paragraph_pad
  • string that is used as a prefix for the very first line in each paragraph
line_pad
  • string that is used as a prefix for every line, except the very first line in a paragraph

Returns:

a string with newline characters that breaks the string into a paragraph.Converts long strings into nice paragraphs.

a string with newline characters that breaks the string into a paragraph.

std::string from_base64 (const std::string& in)

Decodes Base64 string into binary data.

Parameters:

in
  • Base64 string that encodes binary data

Returns:

char* binary bytes wrapped into a string

template <class T>
T from_string (const std::string& token)

Generic method to convert a string into other types.

Parameters:

T
  • the generic type of data to be created
token
  • the element to be converted

Returns:

output value extracetd from the given string

template <class T>
std::vector <T> from_string (
    const std::string& token,
    const core::index2 n_tokens
    )

Extracts a vector of tokens from a string.

Tokens must be separated by spaces or tabs

Parameters:

T
  • type of the data to cast
token
  • input string e.g. “12.3 178.0 13 26.67”
n_tokens
  • the number of tokens to extract

Returns:

a newly created vector of tokens

template <class T>
std::vector <T>& from_string (
    const std::string& token,
    const core::index2 n_tokens,
    std::vector <T>& destination
    )

Extracts a vector of tokens from a string.

Tokens must be separated by spaces or tabs

Parameters:

T
  • type of the data to cast
token
  • input string e.g. “12.3 178.0 13 26.67”
n_tokens
  • the number of tokens to extract
destination
  • vector where the data will be inserted

Returns:

a reference to destination vector

template <class T>
T from_string (
    std::string& token,
    const T default_value
    )

Extracts a data token (double, int, etc) from a string.

Parameters:

T
  • type of the data to cast
token
  • input string
default_value
  • value to be used when an input string is empty

Returns:

a parsed value

template <class T>
std::vector <T>& from_string (
    const std::vector <std::string>& tokens,
    std::vector <T>& destination,
    const T default_value
    )

Extracts a vector of tokens from a vector of strings.

Parameters:

T
  • type of the data to cast
tokens
  • input strings
destination
  • vector where the data will be inserted
default_value
  • value to be used when an input string is empty

Returns:

a reference to destination vector

template <class T>
T from_string (
    const std::string& line,
    const int start,
    const int stop,
    const T default_value
    )

Extracts a data token (double, int, etc) from a substring of a given string.

Parameters:

T
  • type of the data to cast
line
  • input string
start
  • position where the data item starts
stop
  • position where the data item ends (inclusive!)
default_value
  • value to be used when an input string is empty

Returns:

a parsed value

std::vector <std::string> glob (const std::string& mask)

Lists the contents of a directory.

This method actually wraps the glob() function from glibc

Parameters:

mask
  • a relative path with a file mask, e.g. ./some/dir/1*.pdb

Returns:

a vector holding file names

See also:

glibc site http://www.gnu.org/software/libc/manual/html_node/Globbing.html

bool has_prefix (
    const std::string& str,
    const std::string& prefix
    )

Tests is a string begins with a particular substring.

Parameters:

str
  • query string
prefix
  • desired prefix

Returns:

true if the string begins with the given substring

bool has_suffix (
    const std::string& str,
    const std::string& suffix
    )

Tests is a string ends with a particular suffix.

Parameters:

str
  • query string
suffix
  • desired suffix

Returns:

true if the string ends with the given substring

bool if_file_exists (const std::string& fname)

Tests if a given file exists.

Parameters:

fname
  • name of the input file

Returns:

true if the requested file exists

void in_stream (
    const std::string& fname,
    std::ifstream& in_stream,
    std::ios_base::openmode mode = std::ios_base::in
    )

Associates a disk file with a given input stream if the file exists.

Otherwise, an exception is thrown. This method should be used as follows: std::ifstream in; in_stream(fname,in); // throws an exception if anything goes wrong


Parameters:

fname
  • name of the input file
in_stream
  • the stream the file will be associated with
mode
  • flags describing the requested i/o mode for the file.
bool is_integer (const std::string& s)

Returns true if a string represents an integer number.

Parameters:

s
  • an input string

Returns:

true when the string is an integer

std::string join_paths (
    const std::string& p1,
    const std::string& p2
    )

Joins two parts of a path into a single one using the separator appropriate to the OS.

Parameters:

p1
  • the first part of the path, e.g. a directory
p2
  • the second part of the path, e.g. a file name

Returns:

a full path

std::string& load_binary_file (
    const std::string& filename,
    std::string& buffer
    )

Loads a binary file into a buffer.

Parameters:

filename
  • name of the input file
buffer
  • data buffer (as a string)

Returns:

reference to the buffer

std::string load_text_file (const std::string& fname)

Loads the whole content of a text file into a string.

Parameters:

fname
  • name of the input file

Returns:

a string containing all the characters from the given file

void load_text_file (
    const std::string& fname,
    std::string& sink
    )

Loads the whole content of a text file into the given string.

Parameters:

fname
  • name of the input file
sink
  • where the data should go; the previous content of this string is lost

Returns:

a string containing all the characters from the given file

const LogLevel& log_level_by_name (const std::string& level)

Return the log level corresponding to a given name.

Parameters:

level
  • name of a level

Returns:

a log level

const std::string& log_level_name (const LogLevel& level)

Return the name of a given log level.

Parameters:

level
  • the level enum

Returns:

name of this log level

const std::string& log_level_name_colored (const LogLevel& level)

Return the name of a given log level as a string colored by terminal controlling characters.

Parameters:

level
  • the level enum

Returns:

name of this log level

std::pair <size_t, size_t> matching_bracket (
    const std::string& text,
    const size_t starting_pos,
    const std::string& bracket_type,
    const bool eat_brackets
    )

Finds a pair of matching brackets. This function reports the outer-most pair of brackets starting from a given position in the input string. Inner brackets may be found by calling this function accordingly.

Parameters:

text
  • the source string with brackets
starting_pos
  • starting position
bracket_type
  • a string holding two haracters used as the pair of brackets, e.g. “()” or “{}”. Of course other options are also possible, e.g. “><” or “<>”. Note that the last two example strings are different: only the first character of this string may be used as the opening bracket and the second character as the closing bracket
eat_brackets
  • if true, the returned positions d not include the brackets
std::shared_ptr <std::ostream> out_stream (const std::string& fname)

Returns a smart pointer to an output stream.

If the given file name is an empty string, simply a pointer to std::cout is returned. Otherwise the method returns a pointer to a newly opened file. Alternatively, user may explicitly ask to write to std::cout or to std::cerr by passing “stdout” or “stderr” as a file name.

Parameters:

fname
  • name of the output file

Returns:

an output stream

std::string pathname (const std::string& str)

Returns a directory name extracted from a path.

void random_alphanumeric (std::string& result)

Fills a given string with random alphanumerc contents.

Parameters:

result
  • random alphanumeric token will be stored in this string
std::vector <std::string> read_listfile (const std::string& fname)

Reads a file with strings and returns all of them as a vector instance.

This method is intended to read a listfile i.e. a file providing a list of files

Parameters:

fname
  • an input file name

Returns:

a vector holding file names

void read_listfile (
    const std::string& fname,
    std::vector <std::string>& destination
    )

Reads a file with strings and places the strings in a given vector.

This method is intended to read a listfile i.e. a file providing a list of files

Parameters:

fname
  • an input file name
destination
  • where to store strings read from a list-file
std::map <std::string, std::vector <std::string>> read_properties_file (
    const std::string& fname,
    const bool replace_underscores_with_spaces = false
    )

Loads properties file (the standard JAVA file format)

Parameters:

fname
  • name of the input file
replace_underscores_with_spaces
  • if true, any ‘_’ character will be replaced with ‘ ‘

Returns:

a map that binds each string key to a vector of string tokens

std::map <std::string, std::vector <std::string>>& read_properties_file (
    const std::string& fname,
    std::map <std::string, std::vector <std::string>>& storage_map,
    const bool replace_undersores_with_spaces
    )

Loads properties file (the standard JAVA file format).

This method creates a new map and fills it with the data found in a given file. The simple example loads a file and prints its content on a screen:


Parameters:

fname
  • name of the input file
storage_map
  • container where the data will be stored
replace_undersores_with_spaces
  • if true, any ‘_’ character will be replaced with ‘ ‘

Returns:

a map that binds each string key to a vector of string tokens

std::string& replace_substring (
    std::string& subject,
    const std::string& search,
    const std::string& replace
    )

Replaces all occurrences of a substring with another string.

Parameters:

subject
  • the string to be modified
search
  • the substring to be found and replaced
replace
  • the replacement string

Returns:

the modified string

std::pair <std::string, std::string> root_extension (const std::string& str)

Returns a file name root and extension (just the last extension is extracted from the root name)

std::vector <std::string> split (
    const std::string& str,
    const char delim,
    const bool if_trim_tokens = true
    )

Splits a string into tokens based on a given delimiter.

Parameters:

str
  • the input string with tokens to be converted
delim
  • character to be trimmed off (a space by default)
if_trim_tokens
  • if true, tokens will be trimmed of white space characters

Returns:

the newly created vector that holds the tokens extracted from the given string

void split (
    const std::string& input_str,
    const std::string& separator,
    const int max,
    std::vector <std::string>& results
    )

Splits a string into a vector of tokens based on a given delimiter.

Parameters:

input_str
  • input string
separator
  • separator (delimiter)
max
  • maximum number of tokens to be extracted
results
  • vector to insert the resulting tokens
template <typename T>
std::vector <T>& split (
    const std::string& s,
    std::vector <T>& tokens,
    const char delim = ' ',
    const bool if_trim_tokens = true
    )

Splits a string into tokens based on a given delimiter and converts them into a generic type T.

Parameters:

T
  • the final type of the data that will be converted from string
s
  • the input string with tokens to be converted
tokens
  • the resulting (converted) tokens will be stored here
delim
  • character to be trimmed off (a space by default)
if_trim_tokens
  • if true, tokens will be trimmed of white space characters

Returns:

the reference to the vector of converted data

std::vector <std::string>& split (
    const std::string& s,
    std::vector <std::string>& tokens,
    const core::index2 chunk_length
    )

Cuts a string into pieces of a given length.

Parameters:

s
  • a string to be fragmented
tokens
  • the resulting string parts will be stored here
chunk_length
  • the length of the fragments

Returns:

the reference to the vector of tokens

std::vector <std::string>& split_into_strings (
    const std::string& s,
    std::vector <std::string>& tokens,
    const char delim = ' ',
    const bool if_trim_tokens = true
    )

Splits a string into string tokens based on a given delimiter.

This method works exactly as split<std::string>() speciation; it was introduced because gcc didn’t dispatch templates properly.

Parameters:

s
  • the input string with tokens to be converted
tokens
  • the resulting words will be stored here
delim
  • delimiter character
if_trim_tokens
  • if true, tokens will be trimmed of white space characters

Returns:

the reference to the vector of converted data

template <typename ... Args>
std::string string_format (
    const std::string& format,
    Args ... args
    )

Formatted print to a string.

This method is simply a wrapper for vsnprintf()

Parameters:

format
  • the format string (old school printf() style)
  • data to be printed

Returns:

the newly created output string

template <typename ... Args>
std::string string_format (
    const char* format,
    Args ... args
    )

Formatted print to a string.

This method is simply a wrapper for vsnprintf()

Parameters:

format
  • the format string (old school printf() style)
  • data to be printed

Returns:

the newly created output string

std::string string_format (
    const char* fmt_str,
    const std::vector <float>& data
    )

Prints a number of double values into a string.

Parameters:

fmt_str
  • the format string (old school printf() style)
data
  • vector holding the data

Returns:

the newly created output string

std::string string_format (
    const char* fmt_str,
    const std::vector <double>& data
    )

Prints a number of float values into a string.

Parameters:

fmt_str
  • the format string (old school printf() style)
data
  • vector holding the data

Returns:

the newly created output string

double swap_double (const double d)

Simple function that reverses bytes in a double variable.

std::string time_stamp ()

Creates a nicely looking timestamp.

Returns a string with a timestamp, e.g. “26-11-2014,0:6:17”

std::string to_base64 (const std::string& in)

Encodes a binary string with Base64 encoding.

Parameters:

in
  • input string (actually char* binary bytes wrapped into a string for convenience)

Returns:

encoded string

double to_double (const char* p)

Fast method to convert a char buffer to a double value.

Parameters:

p
  • the char* buffer

Returns:

double value

int to_int (const char* p)

Fast method to convert a char buffer to an integer value.

Parameters:

p
  • the char* buffer

Returns:

int value

void to_lower (std::string& s)

Makes a given strint lowercase.

Parameters:

s
  • input string
template <class T>
const std::string to_string (const T& data)

Converts any data to a string.

Parameters:

T
  • the generic type of the input data to be converted
data
  • the element to be converted

Returns:

the string representing the input data

template <class T>
const std::string to_string (
    const std::vector <T>& data,
    const std::string& separator
    )

Converts all the data from the given vector to a string.

Parameters:

T
  • the generic type of the input data to be converted
data
  • the element to be converted
separator
  • a string used to separate words in an output string

Returns:

the string representing the input data

void to_upper (std::string& s)

Makes a given strint uppercase.

Parameters:

s
  • input string
std::string& trim (std::string& str)

Removes spaces (or other characters, if desired) from both ends of a given string.

Parameters:

str
  • the string to be modified
delim
  • characters to be trimmed off (by default = ” ntr”)

Returns:

the string representing the input data

void trim_extensions (
    std::string& fname,
    std::vector <std::string> extensions = {".pdb.gz",".pdb",".gz",".fasta",".pir"}
    )

Removes extension from a file name.

Parameters:

fname
  • a file name to work on
extensions
  • a vector of extensions to be removed from the file name. Each of the extensions is tested in the order as they appear in the vector.
std::string& ungzip_string (
    const std::string& str,
    std::string& dest
    )

un-gzips data compressed with gzip algorithm

Parameters:

str
  • compressed (input) string
dest
  • uncompressed (output) string

Returns:

reference to the output buffer

std::stringstream& ungzip_string (
    const std::string& str,
    std::stringstream& dest
    )

un-gzips data compressed with gzip algorithm

Parameters:

str
  • compressed (input) string
dest
  • output stream

Returns:

reference to the output stream

std::string& unzip_string (
    const std::string& str,
    std::string& dest
    )

un-zips data compressed with zip algorithm

Parameters:

str
  • compressed (input) string
dest
  • uncompressed (output) string

Returns:

reference to the output buffer

std::stringstream& unzip_string (
    const std::string& str,
    std::stringstream& dest
    )

un-zips data compressed with zip algorithm

Parameters:

str
  • compressed (input) string
dest
  • output stream

Returns:

reference to the output stream

std::string& zip_string (
    const std::string& str,
    std::string& dest,
    int compressionlevel = Z_BEST_COMPRESSION
    )

Compress data with zip algorithm.

Parameters:

str
  • uncompressed (input) string
dest
  • output buffer
compressionlevel
  • compression level

Returns:

reference to the output string