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.