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
33namespace 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>
49void 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
122template<class T> class Fallible
123{
124public:
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;}
151private:
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()
The default constructor creates an invalid object.
Definition: Fallible.h:126
Fallible< T > & operator=(const Fallible< T > &other)
Definition: Fallible.h:135
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