Fallible.h

Go to the documentation of this file.

// # Fallible.h: Identifies a value as valid or invalid
// # Copyright (C) 1994,1995,1999
// # Associated Universities, Inc. Washington DC, USA.
// #
// # This library is free software; you can redistribute it and/or modify it
// # under the terms of the GNU Library General Public License as published by
// # the Free Software Foundation; either version 2 of the License, or (at your
// # option) any later version.
// #
// # This library is distributed in the hope that it will be useful, but WITHOUT
// # ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
// # FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
// # License for more details.
// #
// # You should have received a copy of the GNU Library General Public License
// # along with this library; if not, write to the Free Software Foundation,
// # Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
// #
// # Correspondence concerning AIPS++ should be addressed as follows:
// #        Internet email: casa-feedback@nrao.edu.
// #        Postal address: AIPS++ Project Office
// #                        National Radio Astronomy Observatory
// #                        520 Edgemont Road
// #                        Charlottesville, VA 22903-2475 USA
 
#ifndef CASA_FALLIBLE_H
#define CASA_FALLIBLE_H
 
#include <casacore/casa/aips.h>
#include <casacore/casa/Exceptions/Error.h>
 
namespace casacore {  // # NAMESPACE CASACORE - BEGIN
 
// <summary> throw exception on access of an invalid object </summary>
//
// This function gets called when an invalid object is accessed. It
// just throws an exception.
// <thrown>
//  <li> AipsError
// </thrown>
//
// <group name=invalid_access>
[[deprecated("Fallible is replaced by std::optional")]]
inline void AccessInvalidFallibleObject() {
  throw(
      AipsError("Fallible<T>:: invalid object accessed. Sorry I don't know"
                " from where"));
}
// </group>
 
// <summary> Mark a value as valid or invalid. </summary>
// <use visibility=export>
// <reviewed reviewer="Gareth Hunt" date="1994/09/14" tests="tFallible,TestCenter" demos="">
// </reviewed>
 
// <etymology>
// This is to be used for values which might be fallible, i.e. might not
// be valid.
// </etymology>
 
// <synopsis>
// This class resembles the one in <em>Scientific and Engineering C++</em>
// by Barton and Nackman. While it was written with that book closed, the
// class is simple enough that resemblances likely remain.
//
// This class essentially just holds a value (with automatic conversion)
// and allows inquiry as to whether the value is valid. If the value is
// used and is indeed invalid an exception will be thrown.
//
// A copy of the value is stored in the <src>Fallible<T></src> object, so
// making copies shouldn't be too expensive. It is anticipated that this
// class will most often be used with built in, or other small, types.
// </synopsis>
 
// <example>
// Suppose we write some code that turns a day/month/year into a day
// of the week:
// <srcblock>
//    enum DayName {Sunday, Monday, Tuesday, Wednesday, Thursday, Friday,
//                  Saturday};
//    Fallible<DayName> dayFromDate(uInt day, uInt month, uInt year); // a func.
// </srcblock>
// And we also have some other function that needs a day name, for example
// just prints it:
// <srcblock>
//    ostream &operator<<(ostream &os, DayName day); // Print name as string
// </srcblock>
//
// Since the automatic conversions are defined, if we are certain that the
// dates are valid, we can just go ahead and use the value:
// <srcblock>
//    cout << dayFromData(2, 1, 1962) << endl; // A valid date
// </srcblock>
// If, by some chance, you are wrong and a date fails, then an exception will
// be thrown and a run-time error will occur.
//
// If, as is more likely the case, you don't know a priori whether a test will
// succeed, you can check it:
// <srcblock>
//    Fallible<DayName> result = dayFromDate(d,m,y); // who knows if valid?
//    if (result.isValid()) {
//       cout << result << endl;
//    } else {
//      // some corrective action
//    }
// </srcblock>
// </example>
 
// <motivation>
// The alternatives are to have "special values" (e.g. have an "undefined
// day" in the enumeration) or return a Boolean, or change a Boolean. While
// those solutions are often adequate, <src>Fallible<T></src> can often be
// more natural.
// </motivation>
 
// <templating arg=T>
//   <LI>  default constructor
//   <LI>  copy constructor
// </templating>
 
template <class T>
class [[deprecated("Use std::optional")]] Fallible {
 public:
  // The default constructor creates an invalid object.
  Fallible() : value_p(T()), isValid_p(False) {}
 
  // Create a valid object
  Fallible(const T &value) : value_p(value), isValid_p(True) {}
 
  // # Actually, the default copy ctor and assignment operator would work
  Fallible(const Fallible<T> &other) : value_p(other.value_p), isValid_p(other.isValid_p) {}
 
  Fallible<T> &operator=(const Fallible<T> &other) {
    value_p = other.value_p;
    isValid_p = other.isValid_p;
    return *this;
  }
 
  ~Fallible() {}
 
  // Automatically convert a <src>Fallible<T></src> to a <src>T</src>.
  operator T() const {
    if (!isValid_p) AccessInvalidFallibleObject();
    return value_p;
  }
 
  // Sometimes it's more convenient to not rely on a compiler supplied
  // conversion, especially when the compiler is confused.
  T value() const {
    if (!isValid_p) AccessInvalidFallibleObject();
    return value_p;
  }
 
  Bool isValid() const { return isValid_p; }
 
 private:
  T value_p;
  Bool isValid_p;
};
 
}  // namespace casacore
 
#endif