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
 124         /*! \brief
 125          * Writes a string to the file.
 126          *
 127          * \param[in]  str  String to write.
 128          * \throws     FileIOError on any I/O error.
 129          *
 130          * The file must be open.
 131          */
 132         void writeString(const char *str);
 133         //! \copydoc writeString(const char *)
 134         void writeString(const std::string &str) { writeString(str.c_str()); }
 135         /*! \brief
 136          * Writes a line to the file.
 137          *
 138          * \param[in]  line  Line to write.
 139          * \throws     FileIOError on any I/O error.
 140          *
 141          * If \p line does not end in a newline, one newline is appended.
 142          * Otherwise, works as writeString().
 143          *
 144          * The file must be open.
 145          */
 146         void writeLine(const char *line);
 147         //! \copydoc writeLine(const char *)
 148         void writeLine(const std::string &line) { writeLine(line.c_str()); }
 149         /*! \brief
 150          * Writes a newline to the file.
 151          *
 152          * \throws     FileIOError on any I/O error.
 153          */
 154         void writeLine();
 155
 156         /*! \brief
 157          * Returns a File object for accessing stdout.
 158          *
 159          * \throws    std::bad_alloc if out of memory (only on first call).
 160          */
 161         static File &standardOutput();
 162         /*! \brief
 163          * Returns a File object for accessing stderr.
 164          *
 165          * \throws    std::bad_alloc if out of memory (only on first call).
 166          */
 167         static File &standardError();
 168
 169         /*! \brief
 170          * Reads contents of a file to a std::string.
 171          *
 172          * \param[in] filename  File to read.
 173          * \returns   The contents of \p filename.
 174          * \throws    std::bad_alloc if out of memory.
 175          * \throws    FileIOError on any I/O error.
 176          */
 177         static std::string readToString(const char *filename);
 178         //! \copydoc readToString(const char *)
 179         static std::string readToString(const std::string &filename);
 180
 181     private:
 182         /*! \brief
 183          * Initialize file object from an existing file handle.
 184          *
 185          * \param[in]  fp     File handle to use (may be NULL).
 186          * \param[in]  bClose Whether this object should close its file handle.
 187          * \throws     std::bad_alloc if out of memory.
 188          *
 189          * Used internally to implement standardError().
 190          */
 191         File(FILE *fp, bool bClose);
 192
 193         class Impl;
 194
 195         PrivateImplPointer<Impl> impl_;
 196 };
 197
 198 } // namespace gmx
 199
 200 #endif