new fortune
[feisty_meow.git] / nucleus / library / basis / outcome.h
1 #ifndef OUTCOME_CLASS
2 #define OUTCOME_CLASS
3
4 /*****************************************************************************\
5 *                                                                             *
6 *  Name   : outcome                                                           *
7 *  Author : Chris Koeritz                                                     *
8 *                                                                             *
9 *******************************************************************************
10 * Copyright (c) 1990-$now By Author.  This program is free software; you can  *
11 * redistribute it and/or modify it under the terms of the GNU General Public  *
12 * License as published by the Free Software Foundation; either version 2 of   *
13 * the License or (at your option) any later version.  This is online at:      *
14 *     http://www.fsf.org/copyleft/gpl.html                                    *
15 * Please send any updates to: fred@gruntose.com                               *
16 \*****************************************************************************/
17
18 #include "definitions.h"
19
20 namespace basis {
21
22 //! Outcomes describe the state of completion for an operation.
23 /*!
24   These are an extremely simple representation of a non-exceptional exit
25   value as an integer.  The range of expression is from 0 to MAXINT.
26   Outcomes are meant to represent the category of 'how' the operation
27   completed; they do not carry along any results of 'what' was produced.
28 */
29
30 class outcome
31 {
32 public:
33   outcome(int value = 0) : c_outcome_value(value) {}
34     //!< Represents the completion of an operation as a particular "value".
35     /*!< The outcomes partition the input space of the operation and represent
36     the different conclusions possible during processing.  Values for outcomes
37     must be maintained on a system-wide basis as unique identifiers for them
38     to be meaningful.  Note that zero is reserved as a default outcome value.
39     This usually translates to an outcome of OKAY. */
40
41   ~outcome() { c_outcome_value = 0; }  //!< destructor resets outcome value.
42
43   bool equal_to(const outcome &to_compare) const
44       { return c_outcome_value == to_compare.c_outcome_value; }
45     //!< Returns true if this outcome is equal to "to_compare".
46     /*!< comparisons between outcomes will operate properly provided that
47     all system-wide outcome values are unique. */
48
49   bool operator == (int to_compare) const
50       { return c_outcome_value == to_compare; }
51     //!< Returns true if this outcome is equal to the integer "to_compare".
52
53   int value() const { return c_outcome_value; }
54     //<! returns the numerical value for the outcome.
55
56   int packed_size() const { return 4; }
57     //!< a convenience function for those packing outcomes.
58     /*!< this is inconveniently hard-coded, since packing is only available in the structures
59     library and not at the base. */
60
61 private:
62   int c_outcome_value;  //<! the numerical id for the outcome.
63 };
64
65 //////////////
66
67 //! checks if the outcome indicates non-okay completion and returns it if so.
68 #define PROMOTE_OUTCOME(outc) \
69   if (outc != common::OKAY) return outc
70
71 //////////////
72
73 //! Provides a way to define auto-generated outcome values.
74 /*! This macro provides a way to mark our outcome values so that parsers
75 can find all of them when needed.
76 NOTE: do not use the macro in CPP files; it's only for headers.  if you
77 define outcomes in CPP files, they will not be added to the build
78 manifest, nor will they be guaranteed to be unique or auto-generated. */
79
80 #define DEFINE_OUTCOME(NAME, CURRENT_VALUE, INFO_STRING) \
81   NAME = CURRENT_VALUE
82
83 //! Similar to standard outcomes (above), but these cannot be auto-incremented.
84 /*! This macro specifies an outcome definition where the value is constant,
85 because it must participate in a network API.  Standard outcomes are just
86 return values from method calls signifying completion, but the API style
87 outcomes can be used to describe remote procedural invocations.  Thus, once
88 they are established with unique values, those values cannot change. */
89
90 #define DEFINE_API_OUTCOME(NAME, CURRENT_VALUE, INFO_STRING) \
91   NAME = CURRENT_VALUE
92
93 //////////////
94
95 } //namespace.
96
97 #endif
98