src/gromacs/utility/file.h

   1 /*
   2  * This file is part of the GROMACS molecular simulation package.
   3  *
   4  * Copyright (c) 2012,2013,2014,2015, 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 "gromacs/utility/classhelpers.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          * Opens a file and returns a `FILE` handle.
  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    FileIOError on any I/O error.
  73          *
  74          * Instead of returning `NULL` on errors, throws an exception with
  75          * additional details (including the file name and `errno`).
  76          */
  77         static FILE *openRawHandle(const char *filename, const char *mode);
  78         //! \copydoc openRawHandle(const char *, const char *)
  79         static FILE *openRawHandle(const std::string &filename, const char *mode);
  80         /*! \brief
  81          * Creates a file object and opens a file.
  82          *
  83          * \param[in] filename  Path of the file to open.
  84          * \param[in] mode      Mode to open the file in (for fopen()).
  85          * \throws    std::bad_alloc if out of memory.
  86          * \throws    FileIOError on any I/O error.
  87          *
  88          * \see open(const char *, const char *)
  89          */
  90         File(const char *filename, const char *mode);
  91         //! \copydoc File(const char *, const char *)
  92         File(const std::string &filename, const char *mode);
  93         /*! \brief
  94          * Destroys the file object.
  95          *
  96          * If the file is still open, it is closed.
  97          * Any error conditions will be ignored.
  98          */
  99         ~File();
 100
 101         /*! \brief
 102          * Opens a file.
 103          *
 104          * \param[in] filename  Path of the file to open.
 105          * \param[in] mode      Mode to open the file in (for fopen()).
 106          * \throws    FileIOError on any I/O error.
 107          *
 108          * The file object must not be open.
 109          */
 110         void open(const char *filename, const char *mode);
 111         //! \copydoc open(const char *, const char *)
 112         void open(const std::string &filename, const char *mode);
 113         /*! \brief
 114          * Closes the file object.
 115          *
 116          * \throws  FileIOError on any I/O error.
 117          *
 118          * The file must be open.
 119          */
 120         void close();
 121
 122         /*! \brief
 123          * Returns a file handle for interfacing with C functions.
 124          *
 125          * The file must be open.
 126          * Does not throw.
 127          */
 128         FILE *handle();
 129
 130         /*! \brief
 131          * Reads given number of bytes from the file.
 132          *
 133          * \param[out] buffer  Pointer to buffer that receives the bytes.
 134          * \param[in]  bytes   Number of bytes to read.
 135          * \throws     FileIOError on any I/O error.
 136          *
 137          * The file must be open.
 138          */
 139         void readBytes(void *buffer, size_t bytes);
 140
 141         /*! \brief
 142          * Writes a string to the file.
 143          *
 144          * \param[in]  str  String to write.
 145          * \throws     FileIOError on any I/O error.
 146          *
 147          * The file must be open.
 148          */
 149         void writeString(const char *str);
 150         //! \copydoc writeString(const char *)
 151         void writeString(const std::string &str) { writeString(str.c_str()); }
 152
 153         /*! \brief
 154          * Checks whether a file exists and is a regular file.
 155          *
 156          * \param[in] filename  Path to the file to check.
 157          * \returns   true if \p filename exists and is accessible.
 158          *
 159          * Does not throw.
 160          */
 161         static bool exists(const char *filename);
 162         //! \copydoc exists(const char *)
 163         static bool exists(const std::string &filename);
 164
 165         /*! \brief
 166          * Reads contents of a file to a std::string.
 167          *
 168          * \param[in] filename  Name of the file to read.
 169          * \returns   The contents of \p filename.
 170          * \throws    std::bad_alloc if out of memory.
 171          * \throws    FileIOError on any I/O error.
 172          */
 173         static std::string readToString(const char *filename);
 174         //! \copydoc readToString(const char *)
 175         static std::string readToString(const std::string &filename);
 176         /*! \brief
 177          * Convenience method for writing a file from a string in a single call.
 178          *
 179          * \param[in] filename  Name of the file to read.
 180          * \param[in] text      String to write to \p filename.
 181          * \throws    FileIOError on any I/O error.
 182          *
 183          * If \p filename exists, it is overwritten.
 184          */
 185         static void writeFileFromString(const std::string &filename,
 186                                         const std::string &text);
 187
 188     private:
 189         class Impl;
 190
 191         PrivateImplPointer<Impl> impl_;
 192 };
 193
 194 } // namespace gmx
 195
 196 #endif