casacore
Fallible.h
Go to the documentation of this file.
1 //# Fallible.h: Identifies a value as valid or invalid
2 //# Copyright (C) 1994,1995,1999
3 //# Associated Universities, Inc. Washington DC, USA.
4 //#
5 //# This library is free software; you can redistribute it and/or modify it
6 //# under the terms of the GNU Library General Public License as published by
7 //# the Free Software Foundation; either version 2 of the License, or (at your
8 //# option) any later version.
9 //#
10 //# This library is distributed in the hope that it will be useful, but WITHOUT
11 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12 //# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
13 //# License for more details.
14 //#
15 //# You should have received a copy of the GNU Library General Public License
16 //# along with this library; if not, write to the Free Software Foundation,
17 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
18 //#
19 //# Correspondence concerning AIPS++ should be addressed as follows:
20 //# Internet email: aips2-request@nrao.edu.
21 //# Postal address: AIPS++ Project Office
22 //# National Radio Astronomy Observatory
23 //# 520 Edgemont Road
24 //# Charlottesville, VA 22903-2475 USA
25 //#
26 //# $Id$
27 
28 #ifndef CASA_FALLIBLE_H
29 #define CASA_FALLIBLE_H
30 
31 #include <casacore/casa/aips.h>
32 
33 namespace casacore { //# NAMESPACE CASACORE - BEGIN
34 
35 //# The following function is to be found in Fallible2.cc not Fallible.cc
36 //# because it's a non-templated function and template instantiators normally
37 //# do not like them in the same .cc file with templated functions.
38 //
39 // <summary> throw exception on access of an invalid object </summary>
40 //
41 // This function gets called when an invalid object is accessed. It
42 // just throws an exception. Since we have inline functions, let's keep
43 // the throw out of them to keep them from moving out of line.
44 // <thrown>
45 // <li> AipsError
46 // </thrown>
47 //
48 // <group name=invalid_access>
49 void AccessInvalidFallibleObject();
50 // </group>
51 
52 // <summary> Mark a value as valid or invalid. </summary>
53 // <use visibility=export>
54 // <reviewed reviewer="Gareth Hunt" date="1994/09/14" tests="tFallible,TestCenter" demos="">
55 // </reviewed>
56 
57 // <etymology>
58 // This is to be used for values which might be fallible, i.e. might not
59 // be valid.
60 // </etymology>
61 
62 // <synopsis>
63 // This class resembles the one in <em>Scientific and Engineering C++</em>
64 // by Barton and Nackman. While it was written with that book closed, the
65 // class is simple enough that resemblances likely remain.
66 //
67 // This class essentially just holds a value (with automatic conversion)
68 // and allows inquiry as to whether the value is valid. If the value is
69 // used and is indeed invalid an exception will be thrown.
70 //
71 // A copy of the value is stored in the <src>Fallible<T></src> object, so
72 // making copies shouldn't be too expensive. It is anticipated that this
73 // class will most often be used with built in, or other small, types.
74 // </synopsis>
75 
76 // <example>
77 // Suppose we write some code that turns a day/month/year into a day
78 // of the week:
79 // <srcblock>
80 // enum DayName {Sunday, Monday, Tuesday, Wednesday, Thursday, Friday,
81 // Saturday};
82 // Fallible<DayName> dayFromDate(uInt day, uInt month, uInt year); // a func.
83 // </srcblock>
84 // And we also have some other function that needs a day name, for example
85 // just prints it:
86 // <srcblock>
87 // ostream &operator<<(ostream &os, DayName day); // Print name as string
88 // </srcblock>
89 //
90 // Since the automatic conversions are defined, if we are certain that the
91 // dates are valid, we can just go ahead and use the value:
92 // <srcblock>
93 // cout << dayFromData(2, 1, 1962) << endl; // A valid date
94 // </srcblock>
95 // If, by some chance, you are wrong and a date fails, then an exception will
96 // be thrown and a run-time error will occur.
97 //
98 // If, as is more likely the case, you don't know a priori whether a test will
99 // succeed, you can check it:
100 // <srcblock>
101 // Fallible<DayName> result = dayFromDate(d,m,y); // who knows if valid?
102 // if (result.isValid()) {
103 // cout << result << endl;
104 // } else {
105 // // some corrective action
106 // }
107 // </srcblock>
108 // </example>
109 
110 // <motivation>
111 // The alternatives are to have "special values" (e.g. have an "undefined
112 // day" in the enumeration) or return a Boolean, or change a Boolean. While
113 // those solutions are often adequate, <src>Fallible<T></src> can often be
114 // more natural.
115 // </motivation>
116 
117 // <templating arg=T>
118 // <LI> default constructor
119 // <LI> copy constructor
120 // </templating>
121 
122 template<class T> class Fallible
123 {
124 public:
125  // The default constructor creates an invalid object.
127 
128  // Create a valid object
130 
131  //# Actually, the default copy ctor and assignment operator would work
132  Fallible(const Fallible<T> &other) : value_p(other.value_p),
133  isValid_p(other.isValid_p) {}
134 
136  {value_p = other.value_p; isValid_p = other.isValid_p;
137  return *this;}
138 
140 
141  // Automatically convert a <src>Fallible<T></src> to a <src>T</src>.
142  operator T() const { if (! isValid_p) AccessInvalidFallibleObject();
143  return value_p; }
144 
145  // Sometimes it's more convenient to not rely on a compiler supplied
146  // conversion, especially when the compiler is confused.
147  T value() const { if (! isValid_p) AccessInvalidFallibleObject();
148  return value_p; }
149 
150  Bool isValid() const {return isValid_p;}
151 private:
154 };
155 
156 
157 } //# NAMESPACE CASACORE - END
158 
159 #endif
160 
Mark a value as valid or invalid.
Definition: Fallible.h:123
Bool isValid() const
Definition: Fallible.h:150
T value() const
Sometimes it's more convenient to not rely on a compiler supplied conversion, especially when the com...
Definition: Fallible.h:147
Fallible(const Fallible< T > &other)
Definition: Fallible.h:132
Fallible< T > & operator=(const Fallible< T > &other)
Definition: Fallible.h:135
Fallible()
The default constructor creates an invalid object.
Definition: Fallible.h:126
Fallible(const T &value)
Create a valid object.
Definition: Fallible.h:129
this file contains all the compiler specific defines
Definition: mainpage.dox:28
const Bool False
Definition: aipstype.h:44
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
const Bool True
Definition: aipstype.h:43