#include <Magnum/Ui/NumericStorage.h>
template<class T>
Magnum::Ui::NumericStorage class new in Git master

Multi-dimensional storage for numeric types.

Owns or references typed numeric data for use with DataLayer, providing also a way to update them along with customizable default value, value range and steps for incrementing and decrementing.

The template is explicitly instantiated for UnsignedByte, Byte, UnsignedShort, Short, UnsignedInt, Int, UnsignedLong, Long, Float, Double, Half, Deg, Rad, Seconds and Nanoseconds. To reduce the amount of used StorageQuery types, types smaller than 32 bits are implicitly expanded to a corresponding 32-bit type in returned StorageQuery instances. Other types are currently not supported.

Base classes

class AbstractStorage new in Git master
Base for DataLayer storage implementations.

Public types

using StorageType = T
Storage type.
using Type = Implementation::NumericStorageQueryTraits<T>::Type
Query type.

Constructors, destructors, conversion operators

template<class Owner>
NumericStorage(Owner& owner, ValueInitT, StorageFlags flags = {}) explicit
Construct a value-initialized single-item storage.
template<class Owner>
NumericStorage(Owner& owner, ValueInitT, std::size_t size, StorageFlags flags = {}) explicit
Construct a value-initialized 1D storage.
template<class Owner>
NumericStorage(Owner& owner, ValueInitT, const Containers::Size2D& size, StorageFlags flags = {}) explicit
Construct a value-initialized 2D storage.
template<class Owner>
NumericStorage(Owner& owner, ValueInitT, const Containers::Size3D& size, StorageFlags flags = {}) explicit
Construct a value-initialized 3D storage.
template<class Owner>
NumericStorage(Owner& owner, NoInitT, StorageFlags flags = {}) explicit
Construct a single-item storage without initializing its contents.
template<class Owner>
NumericStorage(Owner& owner, NoInitT, std::size_t size, StorageFlags flags = {}) explicit
Construct a 1D storage without initializing its contents.
template<class Owner>
NumericStorage(Owner& owner, NoInitT, const Containers::Size2D& size, StorageFlags flags = {}) explicit
Construct a 2D storage without initializing its contents.
template<class Owner>
NumericStorage(Owner& owner, NoInitT, const Containers::Size3D& size, StorageFlags flags = {}) explicit
Construct a 3D storage without initializing its contents.
template<class Owner>
NumericStorage(Owner& owner, DirectInitT, const T& value, StorageFlags flags = {}) explicit
Construct a direct-initialized single-item storage.
template<class Owner>
NumericStorage(Owner& owner, DirectInitT, std::size_t size, const T& value, StorageFlags flags = {}) explicit
Construct a direct-initialized 1D storage.
template<class Owner>
NumericStorage(Owner& owner, DirectInitT, const Containers::Size2D& size, const T& value, StorageFlags flags = {}) explicit
Construct a direct-initialized 2D storage.
template<class Owner>
NumericStorage(Owner& owner, DirectInitT, const Containers::Size3D& size, const T& value, StorageFlags flags = {}) explicit
Construct a direct-initialized 3D storage.
template<class Owner>
NumericStorage(Owner& owner, NonOwnedT, T& value, StorageFlags flags = {}) explicit
Construct a non-owned single-item storage.
template<class Owner>
NumericStorage(Owner& owner, NonOwnedT, const T& value, StorageFlags flags = {}) explicit
template<class Owner>
NumericStorage(Owner& owner, NonOwnedT, T&& value, StorageFlags flags = {}) deleted explicit
Constructing a non-owned storage from a r-value reference is not allowed.
template<class Owner>
NumericStorage(Owner& owner, NonOwnedT, const T&& value, StorageFlags flags = {}) deleted explicit
Constructing a non-owned storage from a r-value reference is not allowed.
template<class Owner>
NumericStorage(Owner& owner, NonOwnedT, const Containers::StridedArrayView1D<T>& values, StorageFlags flags = {}) explicit
Construct a non-owned 1D storage.
template<class Owner>
NumericStorage(Owner& owner, NonOwnedT, const Containers::StridedArrayView1D<const T>& values, StorageFlags flags = {}) explicit
template<class Owner>
NumericStorage(Owner& owner, NonOwnedT, const Containers::StridedArrayView2D<T>& values, StorageFlags flags = {}) explicit
Construct a non-owned 2D storage.
template<class Owner>
NumericStorage(Owner& owner, NonOwnedT, const Containers::StridedArrayView2D<const T>& values, StorageFlags flags = {}) explicit
template<class Owner>
NumericStorage(Owner& owner, NonOwnedT, const Containers::StridedArrayView3D<T>& values, StorageFlags flags = {}) explicit
Construct a non-owned 3D storage.
template<class Owner>
NumericStorage(Owner& owner, NonOwnedT, const Containers::StridedArrayView3D<const T>& values, StorageFlags flags = {}) explicit
template<class Owner, typename std::enable_if<std::is_convertible<Owner&, DataLayer&>::value||std::is_convertible<Owner&, AbstractUserInterface&>::value, int>::type = 0>
NumericStorage(Owner& owner, StorageFlags flags = {}) explicit
Construct a value-initialized single-item storage.
template<class Owner>
NumericStorage(Owner& owner, std::size_t size, StorageFlags flags = {}) explicit
Construct a value-initialized 1D storage.
template<class Owner>
NumericStorage(Owner& owner, const Containers::Size2D& size, StorageFlags flags = {}) explicit
Construct a value-initialized 2D storage.
template<class Owner>
NumericStorage(Owner& owner, const Containers::Size3D& size, StorageFlags flags = {}) explicit
Construct a value-initialized 3D storage.
operator StorageQuery<Type>() const
Single-item storage value.

Public functions

auto isMutable() const -> bool
Whether the storage is mutable.
auto range() const -> Containers::Pair<T, T>
Accepted value range.
auto setRange(T min, T max) const -> const NumericStorage<T>&
Set accepted value range.
auto step() const -> T
Step for increment and decrement.
auto setStep(T step) const -> const NumericStorage<T>&
Set step for increment and decrement.
auto defaultValue() const -> T
Default value.
auto setDefaultValue(T value) const -> const NumericStorage<T>&
Set default value.
auto value() const -> StorageQuery<Type>
Single-item storage value.
auto operator->() const -> StorageQuery<Type>
Single-item storage value.
auto operator[](std::size_t index) const -> StorageQuery<Type>
1D storage value at given index
auto operator[](const Containers::Size2D& index) const -> StorageQuery<Type>
2D storage value at given index
auto operator[](const Containers::Size3D& index) const -> StorageQuery<Type>
3D storage value at given index
auto data() const -> Containers::StridedArrayView3D<const T>
Raw storage data.
auto mutableData() const -> Containers::StridedArrayView3D<T>
Raw mutable storage data.

Typedef documentation

template<class T>
typedef T Magnum::Ui::NumericStorage<T>::StorageType

Storage type.

Note that to reduce combinatorial explosion, the types retured by queries don't always match the actual storage type. See Type for details.

template<class T>
typedef Implementation::NumericStorageQueryTraits<T>::Type Magnum::Ui::NumericStorage<T>::Type

Query type.

To reduce the amount of used StorageQuery types, types smaller than 32 bits are implicitly expanded to a corresponding 32-bit type in returned StorageQuery instances, in particular for StorageType being UnsignedByte and UnsignedShort the StorageQuery type returned by value() expands to UnsignedInt, Byte and Short expands to Int, and Half expands to Float. Otherwise the storage and query type is the same.

Function documentation

template<class T> template<class Owner>
Magnum::Ui::NumericStorage<T>::NumericStorage(Owner& owner, ValueInitT, StorageFlags flags = {}) explicit

Construct a value-initialized single-item storage.

Equivalent to calling NumericStorage(Owner&, ValueInitT, const Containers::Size3D&, StorageFlags) with size being {1, 1, 1}.

template<class T> template<class Owner>
Magnum::Ui::NumericStorage<T>::NumericStorage(Owner& owner, ValueInitT, const Containers::Size3D& size, StorageFlags flags = {}) explicit

Construct a value-initialized 3D storage.

Parameters
owner DataLayer to create the storage in or a UserInterface instance to take a UserInterface::dataLayer() from
size Storage size
flags Storage flags

Delegates to NumericStorage(Owner&, NoInitT, const Containers::Size3D&, StorageFlags) and then initializes the storage, trivial types set to zero and default constructor called otherwise. See the documentation of NumericStorage(Owner&, NoInitT, const Containers::Size3D&, StorageFlags) for more information.

template<class T> template<class Owner>
Magnum::Ui::NumericStorage<T>::NumericStorage(Owner& owner, NoInitT, StorageFlags flags = {}) explicit

Construct a single-item storage without initializing its contents.

Equivalent to calling NumericStorage(Owner&, NoInitT, const Containers::Size3D&, StorageFlags) with size being {1, 1, 1}.

template<class T> template<class Owner>
Magnum::Ui::NumericStorage<T>::NumericStorage(Owner& owner, NoInitT, std::size_t size, StorageFlags flags = {}) explicit

Construct a 1D storage without initializing its contents.

Equivalent to calling NumericStorage(Owner&, ValueInitT, const Containers::Size3D&, StorageFlags) with size being {1, 1, size}.

template<class T> template<class Owner>
Magnum::Ui::NumericStorage<T>::NumericStorage(Owner& owner, NoInitT, const Containers::Size2D& size, StorageFlags flags = {}) explicit

Construct a 2D storage without initializing its contents.

Equivalent to calling NumericStorage(Owner&, ValueInitT, const Containers::Size3D&, StorageFlags) with size being {1, size[0], size[1]}.

template<class T> template<class Owner>
Magnum::Ui::NumericStorage<T>::NumericStorage(Owner& owner, NoInitT, const Containers::Size3D& size, StorageFlags flags = {}) explicit

Construct a 3D storage without initializing its contents.

Parameters
owner DataLayer to create the storage in or a UserInterface instance to take a UserInterface::dataLayer() from
size Storage size
flags Storage flags

Expects that the size is non-empty. If owner is a user interface reference, expects that it contains a DataLayer instance. While the stored values are not initialized in any way, the range() is set to min and max representable values of given type, step() is set to T(1) and defaultValue() to T{}. You can use mutableData() to fill the storage upon creation.

Delegates to either AbstractStorage::AbstractStorage(DataLayer&, const Containers::Size3D&, StorageFlags) or AbstractStorage::AbstractStorage(UserInterface&, const Containers::Size3D&, StorageFlags), see their documentation for detailed description of all constraints.

template<class T> template<class Owner>
Magnum::Ui::NumericStorage<T>::NumericStorage(Owner& owner, DirectInitT, const T& value, StorageFlags flags = {}) explicit

Construct a direct-initialized single-item storage.

Equivalent to calling NumericStorage(Owner&, DirectInitT, const Containers::Size3D&, const T&, StorageFlags) with size being {1, 1, 1}.

template<class T> template<class Owner>
Magnum::Ui::NumericStorage<T>::NumericStorage(Owner& owner, DirectInitT, std::size_t size, const T& value, StorageFlags flags = {}) explicit

Construct a direct-initialized 1D storage.

Equivalent to calling NumericStorage(Owner&, DirectInitT, const Containers::Size3D&, const T&, StorageFlags) with size being {1, 1, size}.

template<class T> template<class Owner>
Magnum::Ui::NumericStorage<T>::NumericStorage(Owner& owner, DirectInitT, const Containers::Size2D& size, const T& value, StorageFlags flags = {}) explicit

Construct a direct-initialized 2D storage.

Equivalent to calling NumericStorage(Owner&, DirectInitT, const Containers::Size3D&, const T&, StorageFlags) with size being {1, size[0], size[1]}.

template<class T> template<class Owner>
Magnum::Ui::NumericStorage<T>::NumericStorage(Owner& owner, DirectInitT, const Containers::Size3D& size, const T& value, StorageFlags flags = {}) explicit

Construct a direct-initialized 3D storage.

Parameters
owner DataLayer to create the storage in or a UserInterface instance to take a UserInterface::dataLayer() from
size Storage size
value Value to initialize the storage with
flags Storage flags

Delegates to NumericStorage(Owner&, NoInitT, const Containers::Size3D&, StorageFlags) and then initializes the storage using value. The value is subsequently also used as the default value instead of 0. See the documentation of NumericStorage(Owner&, NoInitT, const Containers::Size3D&, StorageFlags) for more information.

template<class T> template<class Owner>
Magnum::Ui::NumericStorage<T>::NumericStorage(Owner& owner, NonOwnedT, T& value, StorageFlags flags = {}) explicit

Construct a non-owned single-item storage.

Behaves like calling NumericStorage(Owner&, NonOwnedT, const Containers::StridedArrayView3D<T>&, StorageFlags) with value turned into a view of size {1, 1, 1} but results in a more compact internal representation.

template<class T> template<class Owner>
Magnum::Ui::NumericStorage<T>::NumericStorage(Owner& owner, NonOwnedT, const T& value, StorageFlags flags = {}) explicit

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

template<class T> template<class Owner>
Magnum::Ui::NumericStorage<T>::NumericStorage(Owner& owner, NonOwnedT, T&& value, StorageFlags flags = {}) explicit deleted

Constructing a non-owned storage from a r-value reference is not allowed.

This prevents the storage to be accidentally constructed from a temporary value.

template<class T> template<class Owner>
Magnum::Ui::NumericStorage<T>::NumericStorage(Owner& owner, NonOwnedT, const T&& value, StorageFlags flags = {}) explicit deleted

Constructing a non-owned storage from a r-value reference is not allowed.

This prevents the storage to be accidentally constructed from a temporary value.

template<class T> template<class Owner>
Magnum::Ui::NumericStorage<T>::NumericStorage(Owner& owner, NonOwnedT, const Containers::StridedArrayView1D<T>& values, StorageFlags flags = {}) explicit

Construct a non-owned 1D storage.

Behaves like calling NumericStorage(Owner&, NonOwnedT, const Containers::StridedArrayView3D<T>&, StorageFlags) with values turned into a view of size {1, 1, values.size()} but results in a more compact internal representation.

template<class T> template<class Owner>
Magnum::Ui::NumericStorage<T>::NumericStorage(Owner& owner, NonOwnedT, const Containers::StridedArrayView1D<const T>& values, StorageFlags flags = {}) explicit

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

template<class T> template<class Owner>
Magnum::Ui::NumericStorage<T>::NumericStorage(Owner& owner, NonOwnedT, const Containers::StridedArrayView2D<T>& values, StorageFlags flags = {}) explicit

Construct a non-owned 2D storage.

Behaves like calling NumericStorage(Owner&, NonOwnedT, const Containers::StridedArrayView2D<T>&, StorageFlags) with values turned into a view of size {1, values.size()[0], values.size()[1]} but results in a more compact internal representation.

template<class T> template<class Owner>
Magnum::Ui::NumericStorage<T>::NumericStorage(Owner& owner, NonOwnedT, const Containers::StridedArrayView2D<const T>& values, StorageFlags flags = {}) explicit

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

template<class T> template<class Owner>
Magnum::Ui::NumericStorage<T>::NumericStorage(Owner& owner, NonOwnedT, const Containers::StridedArrayView3D<T>& values, StorageFlags flags = {}) explicit

Construct a non-owned 3D storage.

Parameters
owner DataLayer to create the storage in or a UserInterface instance to take a UserInterface::dataLayer() from
values Value view
flags Storage flags

Uses the values view as the storage instead of allocating it. If owner is a user interface reference, expects that it contains a DataLayer instance. The values view is expected to be non-empty with its contents staying in scope for the whole storage lifetime. If the values are a const view, data updates through the storage are not possible. The range() is set to min and max representable values of given type, and step() is set to T(1).

It's expected that setDirty() is called whenever the values are modified externally. Also note that external modifications don't get clamped against the range() and as such the query values may fall outside of it.

Delegates to either AbstractStorage::AbstractStorage(DataLayer&, const Containers::Size3D&, StorageFlags) or AbstractStorage::AbstractStorage(UserInterface&, const Containers::Size3D&, StorageFlags), see their documentation for detailed description of all constraints.

template<class T> template<class Owner>
Magnum::Ui::NumericStorage<T>::NumericStorage(Owner& owner, NonOwnedT, const Containers::StridedArrayView3D<const T>& values, StorageFlags flags = {}) explicit

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

template<class T> template<class Owner, typename std::enable_if<std::is_convertible<Owner&, DataLayer&>::value||std::is_convertible<Owner&, AbstractUserInterface&>::value, int>::type = 0>
Magnum::Ui::NumericStorage<T>::NumericStorage(Owner& owner, StorageFlags flags = {}) explicit

Construct a value-initialized single-item storage.

Alias to NumericStorage(Owner&, ValueInitT, StorageFlags).

template<class T>
Magnum::Ui::NumericStorage<T>::operator StorageQuery<Type>() const

Single-item storage value.

Equivalent to value(), see its documentation for more information.

template<class T>
bool Magnum::Ui::NumericStorage<T>::isMutable() const

Whether the storage is mutable.

Returns true if the storage is owned (i.e., created using the ValueInit, NoInit or DirectInit constructor) or if it's created using the NonOwned constructor from a mutable view or value reference, false otherwise.

Immutable storages return immutable queries from value() and operator[]() and don't allow accessing mutableData().

template<class T>
const NumericStorage<T>& Magnum::Ui::NumericStorage<T>::setRange(T min, T max) const

Set accepted value range.

Returns Reference to self (for method chaining)

Expects that min isn't larger than max. The range is used to clamp the value when setting, incrementing and decrementing it through StorageQuery APIs, as well as setting it to a min or max. Note that setting the range doesn't clamp existing values in the storage, it only affects future updates. Similarly it also doesn't affect external updates in a non-owned storage.

For integer types the default is the min and max representable value, e.g. -32768 and 32768 for Short, for floating-point types it's negative and positive infinity.

If the range is different from the previously used range, calling this function causes the storage to be marked as dirty.

template<class T>
const NumericStorage<T>& Magnum::Ui::NumericStorage<T>::setStep(T step) const

Set step for increment and decrement.

Returns Reference to self (for method chaining)

Expects that step is not 0. The step is used just for incrementing and decrementing the value (for as long as the range() allows), the values can still be set to any value between individual steps without getting rounded.

The default step is 1 for both integer and floating-point types. Setting a negative step value will cause the effect of StorageQuery::increment() and decrement() to reverse.

Unlike setRange(), calling this function does not cause the storage to be marked as dirty, as it doesn't have any effect on the values.

template<class T>
const NumericStorage<T>& Magnum::Ui::NumericStorage<T>::setDefaultValue(T value) const

Set default value.

Returns Reference to self (for method chaining)

The default value is used when calling StorageQuery::reset(). Initially is set to either 0 or the value that was passed to the NumericStorage(Owner&, DirectInitT, const Containers::Size3D&, const T&, StorageFlags) constructor. Note that the default value isn't restricted in regards to the range or step specified by setRange() and setStep() in any way.

Unlike setRange(), calling this function does not cause the storage to be marked as dirty, as it doesn't have any effect on existing values.

template<class T>
StorageQuery<Type> Magnum::Ui::NumericStorage<T>::value() const

Single-item storage value.

Expects that size() is {1, 1, 1}. If it's not, use one of the operator[]() overloads.

See documentation of operator[](const Containers::Size3D&) const for details about what is all supported by the returned query.

template<class T>
StorageQuery<Type> Magnum::Ui::NumericStorage<T>::operator->() const

Single-item storage value.

Equivalent to value(), see its documentation for more information.

template<class T>
StorageQuery<Type> Magnum::Ui::NumericStorage<T>::operator[](std::size_t index) const

1D storage value at given index

Expects that size() is {1, 1, size} and index is less than size. Use operator[](const Containers::Size2D&) const for indexing a 2D storage and operator[](const Containers::Size3D&) const for indexing a 3D storage.

See documentation of operator[](const Containers::Size3D&) const for details about what is all supported by the returned query.

template<class T>
StorageQuery<Type> Magnum::Ui::NumericStorage<T>::operator[](const Containers::Size2D& index) const

2D storage value at given index

Expects that size() is {1, size[0], size[1]} and index is less than size. Use operator[](const Containers::Size3D&) const for indexing a 3D storage.

See documentation of operator[](const Containers::Size3D&) const for details about what is all supported by the returned query.

template<class T>
StorageQuery<Type> Magnum::Ui::NumericStorage<T>::operator[](const Containers::Size3D& index) const

3D storage value at given index

Expects that index is less than size().

The returned query supports StorageOperation::Min and Max for querying the value range. Unless the storage is non-owned and immutable, the query implements also an updater accepting StorageOperation::Set, Reset, Increment and Decrement.

Note that to reduce combinatorial type explosion, the query uses a Type which is always at least 32-bit. All value updates ultimately result in the original StorageType being used to store the value however.

template<class T>
Containers::StridedArrayView3D<const T> Magnum::Ui::NumericStorage<T>::data() const

Raw storage data.

For mutable access use either mutableData() or the StorageQuery instances returned by value() and operator[]().

In case of an owned storage (created using the ValueInit, NoInit or DirectInit constructor variants) the returned view is tightly packed with a size of size(), and the view is only guaranteed to be valid for as long as no new storages are created in the underlying DataLayer. In case of a non-owned storage (created using the NonOwned constructor) the returned view matches the one passed to the constructor, possibly with extra dimensions added at the front.

template<class T>
Containers::StridedArrayView3D<T> Magnum::Ui::NumericStorage<T>::mutableData() const

Raw mutable storage data.

Like data() const, but returns a mutable view. Expects that the storage is either owned or non-owned and mutable. Meant to be used mainly for filling a storage created using the NoInit constructor variant, or for batch updates. Note that the user is responsible for calling setDirty() upon a modification in order to correctly trigger updates on associated data bindings.