// SPDX-FileCopyrightText: 2018 Kitsune Ral <kitsune-ral@users.sf.net>
// SPDX-License-Identifier: LGPL-2.1-or-later
#pragma once
#include <optional>
#include <functional>
namespace Quotient {
template <typename T>
class Omittable;
constexpr auto none = std::nullopt;
//! \brief Lift an operation into dereferenceable types (Omittables or pointers)
//!
//! This is a more generic version of Omittable::then() that extends to
//! an arbitrary number of arguments of any type that is dereferenceable (unary
//! operator*() can be applied to it) and (explicitly or implicitly) convertible
//! to bool. This allows to streamline checking for nullptr/none before applying
//! the operation on the underlying types. \p fn is only invoked if all \p args
//! are "truthy" (i.e. <tt>(... && bool(args)) == true</tt>).
//! \param fn A callable that should accept the types stored inside
//! Omittables/pointers passed in \p args
//! \return Always an Omittable: if \p fn returns another type, lift() wraps
//! it in an Omittable; if \p fn returns an Omittable, that return value
//! (or none) is returned as is.
template <typename FnT, typename... MaybeTs>
inline auto lift(FnT&& fn, MaybeTs&&... args)
{
return (... && bool(args))
? Omittable(std::invoke(std::forward<FnT>(fn), *args...))
: none;
}
/** `std::optional` with tweaks
*
* The tweaks are:
* - streamlined assignment (operator=)/emplace()ment of values that can be
* used to implicitly construct the underlying type, including
* direct-list-initialisation, e.g.:
* \code
* struct S { int a; char b; }
* Omittable<S> o;
* o = { 1, 'a' }; // std::optional would require o = S { 1, 'a' }
* \endcode
* - entirely deleted value(). The technical reason is that Xcode 10 doesn't
* have it; but besides that, value_or() or (after explicit checking)
* `operator*()`/`operator->()` are better alternatives within Quotient
* that doesn't practice throwing exceptions (as doesn't most of Qt).
* - disabled non-const lvalue operator*() and operator->(), as it's too easy
* to inadvertently cause a value change through them.
* - ensure() to provide a safe and explicit lvalue accessor instead of
* those above. Allows chained initialisation of nested Omittables:
* \code
* struct Inner { int member = 10; Omittable<int> innermost; };
* struct Outer { int anotherMember = 10; Omittable<Inner> inner; };
* Omittable<Outer> o; // = { 10, std::nullopt };
* o.ensure().inner.ensure().innermost.emplace(42);
* \endcode
* - merge() - a soft version of operator= that only overwrites its first
* operand with the second one if the second one is not empty.
* - then() and then_or() to streamline read-only interrogation in a "monadic"
* interface.
*/
template <typename T>
class Omittable : public std::optional<T> {
public:
using base_type = std::optional<T>;
using value_type = std::decay_t<T>;
using std::optional<T>::optional;
// Overload emplace() and operator=() to allow passing braced-init-lists
// (the standard emplace() does direct-initialisation but
// not direct-list-initialisation).
using base_type::operator=;
Omittable& operator=(const value_type& v)
{
base_type::operator=(v);
return *this;
}
Omittable& operator=(value_type&& v)
{
base_type::operator=(std::move(v));
return *this;
}
using base_type::emplace;
T& emplace(const T& val) { return base_type::emplace(val); }
T& emplace(T&& val) { return base_type::emplace(std::move(val)); }
// Use value_or() or check (with operator! or has_value) before accessing
// with operator-> or operator*
// The technical reason is that Xcode 10 has incomplete std::optional
// that has no value(); but using value() may also mean that you rely
// on the optional throwing an exception (which is not assumed practice
// throughout Quotient) or that you spend unnecessary CPU cycles on
// an extraneous has_value() check.
auto& value() = delete;
const auto& value() const = delete;
template <typename U>
value_type& ensure(U&& defaultValue = value_type {})
{
return this->has_value() ? this->operator*()
: this->emplace(std::forward<U>(defaultValue));
}
value_type& ensure(const value_type& defaultValue)
{
return ensure<>(defaultValue);
}
value_type& ensure(value_type&& defaultValue)
{
return ensure<>(std::move(defaultValue));
}
//! Merge the value from another Omittable
//! \return true if \p other is not omitted and the value of
//! the current Omittable was different (or omitted),
//! in other words, if the current Omittable has changed;
//! false otherwise
template <typename T1>
auto merge(const std::optional<T1>& other)
-> std::enable_if_t<std::is_convertible_v<T1, T>, bool>
{
if (!other || (this->has_value() && **this == *other))
return false;
this->emplace(*other);
return true;
}
// Hide non-const lvalue operator-> and operator* as these are
// a bit too surprising: value() & doesn't lazy-create an object;
// and it's too easy to inadvertently change the underlying value.
const value_type* operator->() const& { return base_type::operator->(); }
value_type* operator->() && { return base_type::operator->(); }
const value_type& operator*() const& { return base_type::operator*(); }
value_type& operator*() && { return base_type::operator*(); }
// The below is inspired by the proposed std::optional monadic operations
// (http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2021/p0798r6.html).
//! \brief Lift a callable into the Omittable
//!
//! 'Lifting', as used in functional programming, means here invoking
//! a callable (e.g., a function) on the contents of the Omittable if it has
//! any and wrapping the returned value (that may be of a different type T2)
//! into a new Omittable\<T2>. If the current Omittable is empty,
//! the invocation is skipped altogether and Omittable\<T2>{none} is
//! returned instead.
//! \note if \p fn already returns an Omittable (i.e., it is a 'functor',
//! in functional programming terms), then() will not wrap another
//! Omittable around but will just return what \p fn returns. The
//! same doesn't hold for the parameter: if \p fn accepts an Omittable
//! you have to wrap it in another Omittable before calling then().
//! \return `none` if the current Omittable has `none`;
//! otherwise, the Omittable returned from a call to \p fn
//! \tparam FnT a callable with \p T (or <tt>const T&</tt>)
//! returning Omittable<T2>, T2 is any supported type
//! \sa then_or, transform
template <typename FnT>
auto then(FnT&& fn) const&
{
return lift(std::forward<FnT>(fn), *this);
}
//! \brief Lift a callable into the rvalue Omittable
//!
//! This is an rvalue overload for then().
template <typename FnT>
auto then(FnT&& fn) &&
{
return lift(std::forward<FnT>(fn), *this);
}
//! \brief Lift a callable into the const lvalue Omittable, with a fallback
//!
//! This effectively does the same what then() does, except that it returns
//! a value of type returned by the callable, or the provided fallback value
//! if the current Omittable is empty. This is a typesafe version to apply
//! an operation on an Omittable without having to deal with another
//! Omittable afterwards.
template <typename FnT, typename FallbackT>
auto then_or(FnT&& fn, FallbackT&& fallback) const&
{
return then(std::forward<FnT>(fn))
.value_or(std::forward<FallbackT>(fallback));
}
//! \brief Lift a callable into the rvalue Omittable, with a fallback
//!
//! This is an overload for functions that accept rvalue
template <typename FnT, typename FallbackT>
auto then_or(FnT&& fn, FallbackT&& fallback) &&
{
return then(std::forward<FnT>(fn))
.value_or(std::forward<FallbackT>(fallback));
}
};
template <typename T>
Omittable(T&&) -> Omittable<T>;
//! \brief Merge the value from an optional
//! This is an adaptation of Omittable::merge() to the case when the value
//! on the left hand side is not an Omittable.
//! \return true if \p rhs is not omitted and the \p lhs value was different,
//! in other words, if \p lhs has changed;
//! false otherwise
template <typename T1, typename T2>
inline auto merge(T1& lhs, const std::optional<T2>& rhs)
-> std::enable_if_t<std::is_assignable_v<T1&, const T2&>, bool>
{
if (!rhs || lhs == *rhs)
return false;
lhs = *rhs;
return true;
}
} // namespace Quotient