[Loki-lib-cvs] SF.net SVN: loki-lib:[955] trunk/include/loki/CheckReturn.h

[<ric...@us...>]

Revision: 955
          http://loki-lib.svn.sourceforge.net/loki-lib/?rev=955&view=rev
Author:   rich_sposato
Date:     2009-01-29 08:24:30 +0000 (Thu, 29 Jan 2009)

Log Message:
-----------
Added documentation comments.  Added a policy.

Modified Paths:
--------------
    trunk/include/loki/CheckReturn.h

Modified: trunk/include/loki/CheckReturn.h
===================================================================
--- trunk/include/loki/CheckReturn.h	2009-01-28 18:12:10 UTC (rev 954)
+++ trunk/include/loki/CheckReturn.h	2009-01-29 08:24:30 UTC (rev 955)
@@ -45,18 +45,20 @@
 ///  primitive (bool, int, etc...) a pointer, or an enum (such as an error
 ///  condition enum).  It can work with other types that have cheap copy
 ///  operations.
-///
-///  \par OnError Policy
 ///  - OnError is a policy class indicating how to handle the situation when a
 ///  caller does not check or copy the returned value.  Loki provides some
 ///  policy classs and you may also write your own.  For example, you can write
-///  a policy to throw an exception or create a message box when the function
-///  ignores the return value.  If your write your own, you only need to provide
-///  a function named "run".
+///  a policy to create a message box when the function ignores the return value.
+///  That would quickly tell you places where code ignores the function call.
+///  If your write your own, you only need a templated class or struct with a
+///  public function named "run" that accepts a reference to a const value.
 ///
+/// @par Provided Policy Classes
 ///  - IgnoreReturnValue Deliberately ignores when the caller ignores the return value.
 ///  - TriggerAssert Asserts in debug builds if the caller ignores the return value.
 ///  - FprintfStderr Prints out an error message if the caller ignores the return value.
+///  - ThrowTheValue Throws the ignored value as an exception.
+///  - ThrowLogicError Throws a logic_error exception to indicate a programming error.
 ////////////////////////////////////////////////////////////////////////////////
 
 
@@ -65,16 +67,34 @@
 {
 	static void run(const T&)
 	{
-	    /// Do nothing at all.
+		/// Do nothing at all.
 	}
 };
 
 template<class T>
+struct ThrowTheValue
+{
+	static void run(const T & value )
+	{
+		throw value;
+	}
+};
+
+template<class T>
+struct ThrowLogicError
+{
+	static void run( const T & )
+	{
+		throw ::std::logic_error( "CheckReturn: return value was not checked.\n" );
+	}
+};
+
+template<class T>
 struct TriggerAssert
 {
 	static void run(const T&)
 	{
-        assert( 0 );
+		assert( 0 );
 	}
 };
 
@@ -83,7 +103,7 @@
 {
 	static void run(const T&)
 	{
-		fprintf(stderr, "CheckReturn: return value was not checked\n");
+		fprintf(stderr, "CheckReturn: return value was not checked.\n");
 	}
 };
 
@@ -94,45 +114,45 @@
 {
 public:
 
-    /// Conversion constructor changes Value type to CheckReturn type.
-    inline CheckReturn( const Value & value ) :
-        m_value( value ), m_checked( false ) {}
+	/// Conversion constructor changes Value type to CheckReturn type.
+	inline CheckReturn( const Value & value ) :
+		m_value( value ), m_checked( false ) {}
 
-    /// Copy-constructor allows functions to call another function within the
-    /// return statement.  The other CheckReturn's m_checked flag is set since
-    /// its duty has been passed to the m_checked flag in this one.
-    inline CheckReturn( const CheckReturn & that ) :
-        m_value( that.m_value ), m_checked( false )
-    { that.m_checked = true; }
+	/// Copy-constructor allows functions to call another function within the
+	/// return statement.  The other CheckReturn's m_checked flag is set since
+	/// its duty has been passed to the m_checked flag in this one.
+	inline CheckReturn( const CheckReturn & that ) :
+		m_value( that.m_value ), m_checked( false )
+	{ that.m_checked = true; }
 
-    /// Destructor checks if return value was used.
-    inline ~CheckReturn( void )
-    {
+	/// Destructor checks if return value was used.
+	inline ~CheckReturn( void )
+	{
 		// If m_checked is false, then a function failed to check the
-        // return value from a function call.
+		// return value from a function call.
 		if (!m_checked)
 			OnError<Value>::run(m_value);
-    }
+	}
 
-    /// Conversion operator changes CheckReturn back to Value type.
-    inline operator Value ( void )
-    {
-        m_checked = true;
-        return m_value;
-    }
+	/// Conversion operator changes CheckReturn back to Value type.
+	inline operator Value ( void )
+	{
+		m_checked = true;
+		return m_value;
+	}
 
 private:
-    /// Default constructor not implemented.
-    CheckReturn( void );
+	/// Default constructor not implemented.
+	CheckReturn( void );
 
-    /// Copy-assignment operator not implemented.
-    CheckReturn & operator = ( const CheckReturn & that );
+	/// Copy-assignment operator not implemented.
+	CheckReturn & operator = ( const CheckReturn & that );
 
-    /// Copy of returned value.
-    Value m_value;
+	/// Copy of returned value.
+	Value m_value;
 
-    /// Flag for whether calling function checked return value yet.
-    mutable bool m_checked;
+	/// Flag for whether calling function checked return value yet.
+	mutable bool m_checked;
 };
 
 // ----------------------------------------------------------------------------


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.