NAME

       rheostream - i/o utilities (rheolef-7.2)

DESCRIPTION

       Here, utilities for stream input and output are suitable are reviewed. Two classes are provided, together
       with a set of useful functions.

OUTPUT STREAM

       The irheostream is suitable for a sequential memory envinement: for a distributed memory and parallel
       computation case, see the diststream(2) class. Indeed, the irheostream is used as a base class for the
       idiststream one.

       File decompresion is assumed using gzip and a recursive search in a directory list is provided for input.

           orheostream foo('NAME', 'suffix');

        is like

           ofstream foo('NAME.suffix').

        However, if NAME does not end with .suffix, then .suffix is automatically added. By default, compression
       is performed on the fly with gzip, adding an additional .gz suffix. The flush action is nicely handled in
       compression mode:

           foo.flush();

        This feature allows intermediate results to be available during long computations. The compression can
       be deactivated while opening a file by an optional argument:

           orheostream foo('NAME', 'suffix', io::nogz);

        An existing compressed file can be reopen in append mode: new results will be appended at the end of an
       existing file:

           orheostream foo('NAME', 'suffix', io::app);

INPUT STREAM

       Conversely,

           irheostream foo('NAME','suffix');

        is like

           ifstream foo('NAME.suffix').

        However, we look at a search path environment variable RHEOPATH in order to find NAME while suffix is
       assumed. Moreover, gzip compressed files, ending with the .gz suffix is assumed, and decompression is
       done.

OPTIONS

       The following code:

       irheostream is('results', 'data');

        will recursively look for a results[.data[.gz]] file in the rectory mentioned by the RHEOPATH
       environment variable.

       For instance, if you insert in our '.cshrc' something like:

           setenv RHEOPATH '.:/home/dupont:/usr/local/math/demo'

        the process will study the current directory ., then, if neither square.data.gz nor square.data exits,
       it scan all subdirectory of the current directory. Then, if file is not founded, it start recusively in
       /home/dupond and then in /usr/local/math/demo.

       File decompression is performed by using the gzip command, and data are pipe-lined directly in memory.

       If the file start with . as ./square or with a / as /home/oscar/square, no search occurs and RHEOPATH
       environment variable is not used.

       Also, if the environment variable RHEOPATH is not set, the default value is the current directory ..

       For output stream:

           orheostream os('newresults', 'data');

        file compression is assumed, and 'newresults.data.gz' will be created.

       File loading and storing are mentioned by a message, either:

           ! load './results.data.gz'

        or:

           ! file './newresults.data.gz' created.

        on the clog stream. By adding the following:

           clog << noverbose;

        you turn off these messages.

USEFULL FUNCTIONS

       // float-to-string conversion
       std::string ftos (const Float& x);

       // catch first occurrence of string in file
       bool scatch (std::istream& in, const std::string& ch, bool full_match = true);

       // has_suffix("toto.suffix", "suffix") -> true
       bool has_suffix (const std::string& name, const std::string& suffix);

       // "toto.suffix" --> "toto"
       std::string delete_suffix (const std::string& name, const std::string& suffix);

       // has_any_suffix("toto.any_suffix") -> true
       bool has_any_suffix (const std::string& name);

       // delete_any_suffix("toto.any_suffix") --> "toto"
       std::string delete_any_suffix (const std::string& name);

       // "/usr/local/dir/toto.suffix" --> "toto.suffix"
       std::string get_basename (const std::string& name);

       // "/usr/local/dir/toto.suffix" --> "/usr/local/dir"
       std::string get_dirname (const std::string& name);

       // "toto" --> "/usr/local/math/data/toto.suffix"
       std::string get_full_name_from_rheo_path (const std::string& rootname, const std::string& suffix);

       // "." + "../geodir" --> ".:../geodir"
       void append_dir_to_rheo_path (const std::string& dir);

       // "../geodir" + "." --> "../geodir:."
       void prepend_dir_to_rheo_path (const std::string& dir);

       // predicate when a file exists
       bool file_exists (const std::string& filename);

       // is_float("3.14") -> true
       bool is_float (const std::string&);

       // string-to-float conversion
       Float to_float (const std::string&);

       // in TMPDIR environment variable or "/tmp" by default
       std::string get_tmpdir();

IMPLEMENTATION

       This documentation has been generated from file util/lib/rheostream.h

       class irheostream : public boost::iostreams::filtering_stream<boost::iostreams::input> {
       public:
           irheostream() : boost::iostreams::filtering_stream<boost::iostreams::input>(), _ifs() {}
           irheostream(const std::string& name, const std::string& suffix = std::string());
           virtual ~irheostream();
           void open  (const std::string& name, const std::string& suffix = std::string());
           void close();

       };

       class orheostream : public boost::iostreams::filtering_stream<boost::iostreams::output> {
       public:
           orheostream() : boost::iostreams::filtering_stream<boost::iostreams::output>(), _mode(), _full_name() {}
           orheostream(const std::string& name, const std::string& suffix = std::string(),
               io::mode_type mode = io::out);
           virtual ~orheostream();
           void open  (const std::string& name, const std::string& suffix = std::string(),
               io::mode_type mode = io::out);
           void flush();
           void close();
           const std::string& filename() const { return _full_name; }

       };

AUTHOR

       Pierre  Saramito  <Pierre.Saramito@imag.fr>

COPYRIGHT

       Copyright   (C)  2000-2018  Pierre  Saramito  <Pierre.Saramito@imag.fr> GPLv3+: GNU GPL version 3 or
       later  <http://gnu.org/licenses/gpl.html>.  This  is  free  software:  you  are free to change and
       redistribute it.  There is NO WARRANTY, to the extent permitted by law.

rheolef                                            Version 7.2                              rheostream(7rheolef)