src/gromacs/utility/file.h

   1 /*
   2  * This file is part of the GROMACS molecular simulation package.
   3  *
   4  * Copyright (c) 2012,2013, by the GROMACS development team, led by
   5  * Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl,
   6  * and including many others, as listed in the AUTHORS file in the
   7  * top-level source directory and at http://www.gromacs.org.
   8  *
   9  * GROMACS is free software; you can redistribute it and/or
  10  * modify it under the terms of the GNU Lesser General Public License
  11  * as published by the Free Software Foundation; either version 2.1
  12  * of the License, or (at your option) any later version.
  13  *
  14  * GROMACS is distributed in the hope that it will be useful,
  15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  17  * Lesser General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU Lesser General Public
  20  * License along with GROMACS; if not, see
  21  * http://www.gnu.org/licenses, or write to the Free Software Foundation,
  22  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA.
  23  *
  24  * If you want to redistribute modifications to GROMACS, please
  25  * consider that scientific software is very special. Version
  26  * control is crucial - bugs must be traceable. We will be happy to
  27  * consider code for inclusion in the official distribution, but
  28  * derived work must not be called official GROMACS. Details are found
  29  * in the README & COPYING files - if they are missing, get the
  30  * official version at http://www.gromacs.org.
  31  *
  32  * To help us fund GROMACS development, we humbly ask that you cite
  33  * the research papers on the package. Check out http://www.gromacs.org.
  34  */
  35 /*! \file
  36  * \brief
  37  * Declares gmx::File.
  38  *
  39  * \author Teemu Murtola <teemu.murtola@gmail.com>
  40  * \inpublicapi
  41  * \ingroup module_utility
  42  */
  43 #ifndef GMX_UTILITY_FILE_H
  44 #define GMX_UTILITY_FILE_H
  45
  46 #include <cstdio>
  47
  48 #include <string>
  49
  50 #include "common.h"
  51
  52 namespace gmx
  53 {
  54
  55 /*! \brief
  56  * Basic file object.
  57  *
  58  * This class provides basic file I/O functionality and uses exceptions
  59  * (FileIOError) for error reporting.
  60  *
  61  * \inpublicapi
  62  * \ingroup module_utility
  63  */
  64 class File
  65 {
  66     public:
  67         /*! \brief
  68          * Creates a file object and opens a file.
  69          *
  70          * \param[in] filename  Path of the file to open.
  71          * \param[in] mode      Mode to open the file in (for fopen()).
  72          * \throws    std::bad_alloc if out of memory.
  73          * \throws    FileIOError on any I/O error.
  74          *
  75          * \see open(const char *, const char *)
  76          */
  77         File(const char *filename, const char *mode);
  78         //! \copydoc File(const char *, const char *)
  79         File(const std::string &filename, const char *mode);
  80         /*! \brief
  81          * Destroys the file object.
  82          *
  83          * If the file is still open, it is closed.
  84          * Any error conditions will be ignored.
  85          */
  86         ~File();
  87
  88         /*! \brief
  89          * Opens a file.
  90          *
  91          * \param[in] filename  Path of the file to open.
  92          * \param[in] mode      Mode to open the file in (for fopen()).
  93          * \throws    FileIOError on any I/O error.
  94          *
  95          * The file object must not be open.
  96          */
  97         void open(const char *filename, const char *mode);
  98         //! \copydoc open(const char *, const char *)
  99         void open(const std::string &filename, const char *mode);
 100         /*! \brief
 101          * Closes the file object.
 102          *
 103          * \throws  FileIOError on any I/O error.
 104          *
 105          * The file must be open.
 106          */
 107         void close();
 108
 109         /*! \brief
 110          * Returns a file handle for interfacing with C functions.
 111          *
 112          * The file must be open.
 113          * Does not throw.
 114          */
 115         FILE *handle();
 116
 117         /*! \brief
 118          * Reads given number of bytes from the file.
 119          *
 120          * \param[out] buffer  Pointer to buffer that receives the bytes.
 121          * \param[in]  bytes   Number of bytes to read.
 122          * \throws     FileIOError on any I/O error.
 123          *
 124          * The file must be open.
 125          */
 126         void readBytes(void *buffer, size_t bytes);
 127         /*! \brief
 128          * Reads a single line from the file.
 129          *
 130          * \param[out] line    String to receive the line.
 131          * \returns    false if nothing was read because the file ended.
 132          * \throws     std::bad_alloc if out of memory.
 133          * \throws     FileIOError on any I/O error.
 134          *
 135          * On error or when false is returned, \p line will be empty.
 136          * Trailing space will be removed from the line.
 137          * To loop over all lines in the file, use:
 138          * \code
 139            std::string line;
 140            while (file.readLine(&line))
 141            {
 142                // ...
 143            }
 144            \endcode
 145          */
 146         bool readLine(std::string *line);
 147         /*! \brief
 148          * Reads a single line from the file.
 149          *
 150          * \param[out] line    String to receive the line.
 151          * \returns    false if nothing was read because the file ended.
 152          * \throws     std::bad_alloc if out of memory.
 153          * \throws     FileIOError on any I/O error.
 154          *
 155          * On error or when false is returned, \p line will be empty.
 156          * Works as readLine(), except that terminating newline will be present
 157          * in \p line if it was present in the file.
 158          *
 159          * \see readLine()
 160          */
 161         bool readLineWithTrailingSpace(std::string *line);
 162
 163         /*! \brief
 164          * Writes a string to the file.
 165          *
 166          * \param[in]  str  String to write.
 167          * \throws     FileIOError on any I/O error.
 168          *
 169          * The file must be open.
 170          */
 171         void writeString(const char *str);
 172         //! \copydoc writeString(const char *)
 173         void writeString(const std::string &str) { writeString(str.c_str()); }
 174         /*! \brief
 175          * Writes a line to the file.
 176          *
 177          * \param[in]  line  Line to write.
 178          * \throws     FileIOError on any I/O error.
 179          *
 180          * If \p line does not end in a newline, one newline is appended.
 181          * Otherwise, works as writeString().
 182          *
 183          * The file must be open.
 184          */
 185         void writeLine(const char *line);
 186         //! \copydoc writeLine(const char *)
 187         void writeLine(const std::string &line) { writeLine(line.c_str()); }
 188         /*! \brief
 189          * Writes a newline to the file.
 190          *
 191          * \throws     FileIOError on any I/O error.
 192          */
 193         void writeLine();
 194
 195         /*! \brief
 196          * Checks whether a file exists and is a regular file.
 197          *
 198          * \param[in] filename  Path to the file to check.
 199          * \returns   true if \p filename exists and is accessible.
 200          *
 201          * Does not throw.
 202          */
 203         static bool exists(const char *filename);
 204         //! \copydoc exists(const char *)
 205         static bool exists(const std::string &filename);
 206
 207         /*! \brief
 208          * Returns a File object for accessing stdin.
 209          *
 210          * \throws    std::bad_alloc if out of memory (only on first call).
 211          */
 212         static File &standardInput();
 213         /*! \brief
 214          * Returns a File object for accessing stdout.
 215          *
 216          * \throws    std::bad_alloc if out of memory (only on first call).
 217          */
 218         static File &standardOutput();
 219         /*! \brief
 220          * Returns a File object for accessing stderr.
 221          *
 222          * \throws    std::bad_alloc if out of memory (only on first call).
 223          */
 224         static File &standardError();
 225
 226         /*! \brief
 227          * Reads contents of a file to a std::string.
 228          *
 229          * \param[in] filename  Name of the file to read.
 230          * \returns   The contents of \p filename.
 231          * \throws    std::bad_alloc if out of memory.
 232          * \throws    FileIOError on any I/O error.
 233          */
 234         static std::string readToString(const char *filename);
 235         //! \copydoc readToString(const char *)
 236         static std::string readToString(const std::string &filename);
 237         /*! \brief
 238          * Convenience method for writing a file from a string in a single call.
 239          *
 240          * \param[in] filename  Name of the file to read.
 241          * \param[in] text      String to write to \p filename.
 242          * \throws    FileIOError on any I/O error.
 243          *
 244          * If \p filename exists, it is overwritten.
 245          */
 246         static void writeFileFromString(const std::string &filename,
 247                                         const std::string &text);
 248
 249     private:
 250         /*! \brief
 251          * Initialize file object from an existing file handle.
 252          *
 253          * \param[in]  fp     %File handle to use (may be NULL).
 254          * \param[in]  bClose Whether this object should close its file handle.
 255          * \throws     std::bad_alloc if out of memory.
 256          *
 257          * Used internally to implement standardOutput() and standardError().
 258          */
 259         File(FILE *fp, bool bClose);
 260
 261         class Impl;
 262
 263         PrivateImplPointer<Impl> impl_;
 264 };
 265
 266 } // namespace gmx
 267
 268 #endif