qevercloud::Optional< T > Class Template Reference

Supports optional values. More...

Public Member Functions
	Optional ()
	Default constructor. More...
	Optional (const Optional &o)
	Copy constructor.
template<typename X >
	Optional (const Optional< X > &o)
	Template copy constructor. More...
	Optional (const T &value)
	Initialization with a value of the type T. More...
template<typename X >
	Optional (const X &value)
	Template initialization with a value of any compatible type.
void	clear ()
	Clears an Optional. More...
Optional &	init ()
	Fast way to initialize an Optional with a default value. More...
bool	isEqual (const Optional< T > &other) const
	Two optionals are equal if they are both not set or have equal values. More...
bool	isSet () const
	Checks if value is set. More...
	operator const T & () const
	Implicit conversion of Optional<T> to T. More...
	operator T & ()
	Implicit conversion of Optional<T> to T. More...
T *	operator-> ()
	Two syntatic constructs come to mind to use for implementation of access to a struct's/class's field directly from Optional. More...
const T *	operator-> () const
	const version.
Optional &	operator= (const Optional &o)
	Assignment.
template<typename X >
Optional &	operator= (const Optional< X > &o)
	Template assignment with an Optional of any compatible value.
Optional &	operator= (const T &value)
	Assignment with a value of the type T.
template<typename X >
Optional &	operator= (const X &value)
	Template assignment with a value of any compatible type.
const T &	ref () const
	Returs a reference to the holded value. More...
T &	ref ()
	Returs reference to the holded value. More...
T	value (T defaultValue=T()) const
	The function is sometimes useful to simplify checking for the value being set. More...

Friends
void	swap (Optional &first, Optional &second)

Detailed Description

template<typename T>
class qevercloud::Optional< T >

Supports optional values.

Most of the fields in the Evernote API structs are optional. But С++ does not support this notion directly.

To implement the concept of optional values conventional Thrift C++ wrapper uses a special field of a struct type where each field is of type bool with the same name as a field in the struct. This bool flag indicated was the field with the same name in the outer struct assigned or not.

While this method have its advantages (obviousness and simplicity) I found it very inconvenient to work with. You have to check by hand that both values (value itself and its __isset flag) are in sync. There is no checks whatsoever against an error and such an error is too easy to make.

So for my library I created a special class that supports the optional value notion explicitly. Basically Optional class just holds a bool value that tracks the fact that a value was assigned. But this tracking is done automatically and attempts to use unissigned values throw exceptions. In this way errors are much harder to make and it's harder for them to slip through testing unnoticed too.

Constructor & Destructor Documentation

template<typename T>

qevercloud::Optional< T >::Optional ( )

inline

Default constructor.

Default Optional is not set.

template<typename T>

template<typename X >

qevercloud::Optional< T >::Optional ( const Optional< X > &  o )

inline

Template copy constructor.

Allows to be initialized with Optional of any compatible type.

template<typename T>

qevercloud::Optional< T >::Optional ( const T &  value )

inline

Initialization with a value of the type T.

Note: it's implicit.

Member Function Documentation

template<typename T>

void qevercloud::Optional< T >::clear ( )

inline

Clears an Optional.

Optional<int> o(1);
o.clear();
cout << o; // exception

template<typename T>

Optional& qevercloud::Optional< T >::init ( )

inline

Fast way to initialize an Optional with a default value.

It's very useful for structs.

struct S2 {int f;};
struct S {int f1; Optional<S2> f2};
Optional<S> o; // o.isSet() != ture

// without init() it's cumbersome to access struct fields
// it's especially true for nested Optionals
o = S(); // now o is set
o->f2 = S2(); // and o.f2 is set
o->f2->f = 1; // so at last it can be used

// with init() it's simpler
o.init()->f2.init()->f = 1;

Returns

reference to itself

template<typename T>

bool qevercloud::Optional< T >::isEqual ( const Optional< T > &  other ) const

inline

Two optionals are equal if they are both not set or have equal values.

I do not define operator== due to not easily resolvable conflicts with operator T&.

Note that optional == other_optional may throw but optional.isEqual(other_optional) will not.

template<typename T>

bool qevercloud::Optional< T >::isSet ( ) const

inline

Checks if value is set.

Returns

true if Optional have been assigned a value and false otherwise.

Access to an unassigned ("not set") Optional lead to an exception.

template<typename T>

qevercloud::Optional< T >::operator const T & ( ) const

inline

Implicit conversion of Optional<T> to T.

const version.

template<typename T>

qevercloud::Optional< T >::operator T & ( )

inline

Implicit conversion of Optional<T> to T.

Note: a reference is returned, not a copy.

template<typename T>

T* qevercloud::Optional< T >::operator-> ( )

inline

Two syntatic constructs come to mind to use for implementation of access to a struct's/class's field directly from Optional.

One is the dereference operator. This is what boost::optional uses. While it's conceptually nice I found it to be not a very convenient way to refer to structs, especially nested ones. So I overloaded the operator-> and use smart pointer semantics.

struct S1 {int f1;};
struct S2 {Optional<S1> f2;};
Optional<S2> o;

*((*o).f2).f1; // boost way, not implemented

o->f2->f1;     // QEverCloud way

I admit, boost::optional is much more elegant overall. It uses pointer semantics quite clearly and in an instantly understandable way. It's universal (* works for any type and not just structs). There is no need for implicit type concersions and so there is no subtleties because of it. And so on.

But then referring to struct fields is a chore. And this is the most common use case of Optionals in QEverCloud.

So I decided to use non-obvious-on-the-first-sight semantics for my Optional. IMO it's much more convenient when gotten used to.

template<typename T>

const T& qevercloud::Optional< T >::ref ( ) const

inline

Returs a reference to the holded value.

const version.

template<typename T>

T& qevercloud::Optional< T >::ref ( )

inline

Returs reference to the holded value.

There are contexts in C++ where impicit type conversions can't help. For example:

Optional<QStringList> l;
for(auto s : l); // you will hear from your compiler

Explicit type conversion can be used...

Optional<QStringList> l;
for(auto s : static_cast<QStringList&>(l)); // ugh...

... but this is indeed ugly as hell.

So I implemented ref() function that returns a reference to the holded value.

Optional<QStringList> l;
for(auto s : l.ref()); // not ideal but OK

template<typename T>

T qevercloud::Optional< T >::value ( T  defaultValue = T() ) const

inline

The function is sometimes useful to simplify checking for the value being set.

Parameters

defaultValue

The value to return if Optional is not set.

Returns

Optional value if set and defaultValue otherwise.