Merge pull request #525 from quotient-im/kitsune/query-current-state

Move out current room state to its own class

1 files changed, 223 insertions, 0 deletions

diff --git a/lib/omittable.h b/lib/omittable.h
new file mode 100644
index 00000000..b5efecf5
--- /dev/null
+++ b/lib/omittable.h
@@ -0,0 +1,223 @@
+// 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