Sort all includes in src/gromacs

[alexxy/gromacs.git] / src / gromacs / utility / file.h

diff --git a/src/gromacs/utility/file.h b/src/gromacs/utility/file.h
index b91ac51f342241463bf7a1e739a66725086668d9..ef837b4a842b5357bc6f38c68c0a56aff5a984e8 100644 (file)
--- a/src/gromacs/utility/file.h
+++ b/src/gromacs/utility/file.h
@@ -1,10 +1,10 @@
 /*
  * This file is part of the GROMACS molecular simulation package.
  *
- * Copyright (c) 2012, by the GROMACS development team, led by
- * David van der Spoel, Berk Hess, Erik Lindahl, and including many
- * others, as listed in the AUTHORS file in the top-level source
- * directory and at http://www.gromacs.org.
+ * Copyright (c) 2012,2013,2014, by the GROMACS development team, led by
+ * Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl,
+ * and including many others, as listed in the AUTHORS file in the
+ * top-level source directory and at http://www.gromacs.org.
  *
  * GROMACS is free software; you can redistribute it and/or
  * modify it under the terms of the GNU Lesser General Public License
@@ -34,7 +34,7 @@
  */
 /*! \file
  * \brief
- * Declares functions for file handling.
+ * Declares gmx::File.
  *
  * \author Teemu Murtola <teemu.murtola@gmail.com>
  * \inpublicapi
@@ -47,7 +47,7 @@
 
 #include <string>
 
-#include "common.h"
+#include "gromacs/utility/common.h"
 
 namespace gmx
 {
@@ -106,6 +106,17 @@ class File
          */
         void close();
 
+        /*! \brief
+         * Returns whether the file is an interactive terminal.
+         *
+         * Only works on Unix, otherwise always returns true.
+         * It only makes sense to call this for File::standardInput() and
+         * friends.
+         *
+         * Thie file must be open.
+         * Does not throw.
+         */
+        bool isInteractive() const;
         /*! \brief
          * Returns a file handle for interfacing with C functions.
          *
@@ -133,8 +144,7 @@ class File
          * \throws     FileIOError on any I/O error.
          *
          * On error or when false is returned, \p line will be empty.
-         * Terminating newline will be present in \p line if it was present in
-         * the file.
+         * Trailing space will be removed from the line.
          * To loop over all lines in the file, use:
          * \code
            std::string line;
@@ -142,9 +152,24 @@ class File
            {
                // ...
            }
-         * \endcode
+           \endcode
          */
         bool readLine(std::string *line);
+        /*! \brief
+         * Reads a single line from the file.
+         *
+         * \param[out] line    String to receive the line.
+         * \returns    false if nothing was read because the file ended.
+         * \throws     std::bad_alloc if out of memory.
+         * \throws     FileIOError on any I/O error.
+         *
+         * On error or when false is returned, \p line will be empty.
+         * Works as readLine(), except that terminating newline will be present
+         * in \p line if it was present in the file.
+         *
+         * \see readLine()
+         */
+        bool readLineWithTrailingSpace(std::string *line);
 
         /*! \brief
          * Writes a string to the file.
@@ -179,7 +204,7 @@ class File
         void writeLine();
 
         /*! \brief
-         * Checks whether a file exists.
+         * Checks whether a file exists and is a regular file.
          *
          * \param[in] filename  Path to the file to check.
          * \returns   true if \p filename exists and is accessible.
@@ -212,7 +237,7 @@ class File
         /*! \brief
          * Reads contents of a file to a std::string.
          *
-         * \param[in] filename  File to read.
+         * \param[in] filename  Name of the file to read.
          * \returns   The contents of \p filename.
          * \throws    std::bad_alloc if out of memory.
          * \throws    FileIOError on any I/O error.
@@ -223,7 +248,7 @@ class File
         /*! \brief
          * Convenience method for writing a file from a string in a single call.
          *
-         * \param[in] filename  File to read.
+         * \param[in] filename  Name of the file to read.
          * \param[in] text      String to write to \p filename.
          * \throws    FileIOError on any I/O error.
          *
@@ -236,11 +261,11 @@ class File
         /*! \brief
          * Initialize file object from an existing file handle.
          *
-         * \param[in]  fp     File handle to use (may be NULL).
+         * \param[in]  fp     %File handle to use (may be NULL).
          * \param[in]  bClose Whether this object should close its file handle.
          * \throws     std::bad_alloc if out of memory.
          *
-         * Used internally to implement standardError().
+         * Used internally to implement standardOutput() and standardError().
          */
         File(FILE *fp, bool bClose);