3 * This source code is part of
7 * GROningen MAchine for Chemical Simulations
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.
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.
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.
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.
29 * For more info, check our website at http://www.gromacs.org
31 /*! \libinternal \file
33 * Declares ::gmx::MessageStringCollector.
35 * \author Teemu Murtola <teemu.murtola@cbr.su.se>
37 * \ingroup module_utility
39 #ifndef GMX_UTILITY_MESSAGESTRINGCOLLECTOR_H
40 #define GMX_UTILITY_MESSAGESTRINGCOLLECTOR_H
44 #include "../utility/common.h"
49 /*! \libinternal \brief
50 * Helper class for collecting message strings, optionally with context.
52 * After strings have been collected, they can be formatted into one long
53 * string for, e.g., printing out or for including in an exception.
56 * \ingroup module_utility
58 class MessageStringCollector
61 MessageStringCollector();
62 ~MessageStringCollector();
65 * Starts a context for messages.
67 * \param[in] name Short description of the context.
69 * \see finishContext()
70 * \see MessageStringContext
72 void startContext(const char *name);
74 * Convenience wrapper for startContext(const char *).
76 void startContext(const std::string &name)
77 { startContext(name.c_str()); }
81 void append(const char *message)
82 { append(std::string(message)); }
86 void append(const std::string &message);
88 * Ends a context started with startContext().
90 * \see MessageStringContext
94 * Clears all collected messages.
99 * Returns true if any messages have been added.
101 * \returns true if append() has been called at least once.
103 * The return value is identical to \c toString().empty().
104 * Calls to startContext()/finishContext() only do not cause this
105 * function to return true.
107 bool isEmpty() const;
109 * Returns all collected messages as one string.
111 std::string toString() const;
116 PrivateImplPointer<Impl> impl_;
119 /*! \libinternal \brief
120 * Convenience class for creating a message context.
122 * This class provides a RAII-style interface to the
123 * MessageStringCollector::startContext() and
124 * MessageStringCollector::finishContext() methods: finishContext() is called
125 * upon destruction of the object. This avoids the need to call
126 * MessageStringCollector::finishContext() on every possible exit point.
130 bool function(::gmx::MessageStringCollector *errors)
132 ::gmx::MessageStringContext errcontext(errors, "In function()");
133 bool bOk = function2(errors);
134 bOk = function3(errors) && bOk;
140 * \see MessageStringCollector
142 * \ingroup module_utility
144 class MessageStringContext
148 * Adds a context for the given object.
150 MessageStringContext(MessageStringCollector *collector, const char *name)
151 : collector_(*collector)
153 collector_.startContext(name);
156 * Adds a context for the given object.
158 MessageStringContext(MessageStringCollector *collector,
159 const std::string &name)
160 : collector_(*collector)
162 collector_.startContext(name);
165 * Calls MessageStringCollector::finishContext() on the wrapped object.
167 ~MessageStringContext()
169 collector_.finishContext();
173 //! The wrapped object.
174 MessageStringCollector &collector_;
176 GMX_DISALLOW_COPY_AND_ASSIGN(MessageStringContext);