--- name: "rheostream" section: "7rheolef" platform: "linux" package: "librheolef-dev" version: "7.2-4" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/rheostream/7rheolef" --- # rheostream(7rheolef) i/o utilities (rheolef-7.2) ## 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 { public: irheostream() : boost::iostreams::filtering_stream(), _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 { public: orheostream() : boost::iostreams::filtering_stream(), _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 \ ## COPYRIGHT Copyright (C) 2000-2018 Pierre Saramito \ GPLv3+: GNU GPL version 3 or later \. This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.