src/gromacs/utility/file.h

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