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    FileIOError on any I/O error.
  69          *
  70          * \see open(const char *, const char *)
  71          */
  72         File(const char *filename, const char *mode);
  73         //! \copydoc File(const char *, const char *)
  74         File(const std::string &filename, const char *mode);
  75         /*! \brief
  76          * Destroys the file object.
  77          *
  78          * If the file is still open, it is closed.
  79          * Any error conditions will be ignored.
  80          */
  81         ~File();
  82
  83         /*! \brief
  84          * Opens a file.
  85          *
  86          * \param[in] filename  Path of the file to open.
  87          * \param[in] mode      Mode to open the file in (for fopen()).
  88          * \throws    FileIOError on any I/O error.
  89          *
  90          * The file object must not be open.
  91          */
  92         void open(const char *filename, const char *mode);
  93         //! \copydoc open(const char *, const char *)
  94         void open(const std::string &filename, const char *mode);
  95         /*! \brief
  96          * Closes the file object.
  97          *
  98          * \throws  FileIOError on any I/O error.
  99          *
 100          * The file must be open.
 101          */
 102         void close();
 103
 104         /*! \brief
 105          * Returns a file handle for interfacing with C functions.
 106          *
 107          * The file must be open.
 108          * Does not throw.
 109          */
 110         FILE *handle();
 111
 112         /*! \brief
 113          * Reads given number of bytes from the file.
 114          *
 115          * \param[out] buffer  Pointer to buffer that receives the bytes.
 116          * \param[in]  bytes   Number of bytes to read.
 117          * \throws     FileIOError on any I/O error.
 118          *
 119          * The file must be open.
 120          */
 121         void readBytes(void *buffer, size_t bytes);
 122
 123         /*! \brief
 124          * Reads contents of a file to a std::string.
 125          *
 126          * \param[in] filename  File to read.
 127          * \returns   The contents of \p filename.
 128          * \throws    std::bad_alloc if out of memory.
 129          * \throws    FileIOError on any I/O error.
 130          */
 131         static std::string readToString(const char *filename);
 132         //! \copydoc readToString(const char *)
 133         static std::string readToString(const std::string &filename);
 134
 135     private:
 136         FILE                   *fp_;
 137
 138         GMX_DISALLOW_COPY_AND_ASSIGN(File);
 139 };
 140
 141 } // namespace gmx
 142
 143 #endif