Support types module
#include "diplib.h"
template<typename T>
dip::DimensionArray class

A dynamic array type optimized for few elements.

dip::DimensionArray is similar to std::vector but optimized for one particular use within the DIPlib library: hold one element per image dimension. Most images have only two or three dimensions, and for internal processing we might add the tensor dimension to the mix, yielding up to four dimensions for most applications. However, DIPlib does not limit image dimensionality, and we need to be able to hold more than four dimensions if the user needs to do so. We want the array holding the image dimensions to be as efficient in use as a static array of size 4, but without the limitation of a static array. So this version of std::vector has a static array of size 4, which is used if that is sufficient, and also a pointer we can use if we need to allocate space on the heap.

It also differs from std::vector in that it doesn’t grow or shrink efficiently, don’t use this type when repeatedly using push_back() or similar functionality. The DIPlib codebase uses dip::DimensionArray only where the array holds one value per image dimension, or when more often than not the array will have very few elements, and std::vector everywhere else.

The interface tries to copy that of the STL containers, but only partially. We do not include some of the std::vector functionality, and do include some custom functionality useful for the specific application of the container. We also have some custom algorithms such as dip::DimensionArray::sort() that assumes the array is short.

This container can only be used with trivially copyable types (this means that the destructor performs no action, and the object can be copied by copying its bit pattern).

An array of size 0 has space for writing four values in it, data() won’t return a nullptr, and nothing will break if you call front(). But don’t do any of these things! The implementation could change. Plus, you’re just being silly and making unreadable code.

Constructors, destructors, assignment and conversion operators

DimensionArray()
The default-initialized array has zero size.
DimensionArray(dip::DimensionArray::size_type sz, T newval = T()) explicit
Like std::vector, you can initialize with a size and a default value.
DimensionArray(std::initializer_list<T> const init)
Like std::vector, you can initialize with a set of values in braces.
DimensionArray(DimensionArray<T> const& other)
Copy constructor, initializes with a copy of other.
DimensionArray(DimensionArray<T>&& other) noexcept
Move constructor, initializes by stealing the contents of other.
auto operator=(DimensionArray<T> const& other) -> DimensionArray<T>&
Copy assignment, copies over data from other.
auto operator=(DimensionArray<T>&& other) -> DimensionArray<T>& noexcept
Move assignment, steals the contents of other.

Aliases

using value_type = T
Type of values stored in container
using iterator = T*
Type of container’s iterator
using const_iterator = T const*
Type of container’s const iterator
using reverse_iterator = std::reverse_iterator<iterator>
Type of container’s reverse iterator
using const_reverse_iterator = std::reverse_iterator<const_iterator>
Type of container’s const reverse iterator
using size_type = std::size_t
Type of index into container

Functions

template<typename O>
void DimensionArray(DimensionArray<O> const& other)
Cast constructor, initializes with a copy of other. Casting done as default in C++, not through dip::clamp_cast.
void swap(DimensionArray<T>& other) noexcept
Swaps the contents of two arrays.
void resize(dip::DimensionArray::size_type newsz, T newval = T())
Resizes the array, making it either larger or smaller. Initializes new elements with newval.
void clear() noexcept
Clears the contents of the array, set its length to 0.
auto empty() const -> bool noexcept
Checks whether the array is empty (size is 0).
auto size() const -> dip::DimensionArray::size_type noexcept
Returns the size of the array.
auto front() -> T&
Accesses the first element of the array
auto front() const -> T const&
Accesses the first element of the array
auto back() -> T&
Accesses the last element of the array
auto back() const -> T const&
Accesses the last element of the array
auto data() -> T*
Returns a pointer to the underlying data
auto data() const -> T const*
Returns a pointer to the underlying data
auto begin() -> dip::DimensionArray::iterator
Returns an iterator to the beginning
auto begin() const -> dip::DimensionArray::const_iterator
Returns an iterator to the beginning
auto end() -> dip::DimensionArray::iterator
Returns an iterator to the end
auto end() const -> dip::DimensionArray::const_iterator
Returns an iterator to the end
auto rbegin() -> dip::DimensionArray::reverse_iterator
Returns a reverse iterator to the beginning
auto rbegin() const -> dip::DimensionArray::const_reverse_iterator
Returns a reverse iterator to the beginning
auto rend() -> dip::DimensionArray::reverse_iterator
Returns a reverse iterator to the end
auto rend() const -> dip::DimensionArray::const_reverse_iterator
Returns a reverse iterator to the end
void insert(dip::DimensionArray::size_type index, T const& value)
Adds a value at the given location, moving the current value at that location and subsequent values forward by one.
void push_back(T const& value)
Adds a value to the back. Not efficient – prefer std::vector if you need to use this repeatedly.
void append(DimensionArray<T> const& values)
Adds all values in source array to the back.
void erase(dip::DimensionArray::size_type index)
Removes the value at the given location, moving subsequent values forward by one.
void pop_back()
Removes the value at the back.
void sort()
Sort the contents of the array from smallest to largest.
template<typename S>
void sort(DimensionArray<S>& other)
Sort the contents of the array from smallest to largest, and keeping other in the same order.
auto sorted_indices() const -> DimensionArray<dip::DimensionArray::size_type>
Returns an array with indices into the array, sorted from smallest value to largest.
auto permute(DimensionArray<dip::DimensionArray::size_type> const& order) const -> DimensionArray<T>
Order the elements in the array according to the order array, such as returned by sorted_indices.
auto inverse_permute(DimensionArray<dip::DimensionArray::size_type> const& order) const -> DimensionArray<T>
Inverse orders the elements in the array according to the order array, such as returned by sorted_indices.
auto find(T value) -> dip::DimensionArray::size_type
Finds the first occurrence of value in the array, returns the index or size() if it is not present.
auto sum() const -> T
Compute the sum of the elements in the array.
auto product() const -> T
Compute the product of the elements in the array.
auto norm_square() const -> double
Compute the sum of the squares of the elements in the array.
auto minimum() const -> dip::DimensionArray::size_type
Find the minimum element in the array, returns the index or 0 if the array is empty.
auto maximum() const -> dip::DimensionArray::size_type
Find the maximum element in the array, returns the index or 0 if the array is empty.
auto minimum_value() const -> T
Find the minimum element in the array, returns the value. The array must not be empty.
auto minimum_value() -> T&
Find the minimum element in the array, returns the value. The array must not be empty.
auto maximum_value() const -> T
Find the maximum element in the array, returns the value. The array must not be empty.
auto maximum_value() -> T&
Find the maximum element in the array, returns the value. The array must not be empty.
auto all() const -> bool
True if all elements are non-zero.
auto any() const -> bool
True if one element is non-zero.
auto count() const -> dip::DimensionArray::size_type
Count of number of elements that are non-zero.
void fill(T const& value)
Assigns one same value to each element in the array

Operators

auto operator[](dip::DimensionArray::size_type index) -> T&
Accesses an element of the array
auto operator[](dip::DimensionArray::size_type index) const -> T const&
Accesses an element of the array
auto operator+=(T const& v) -> DimensionArray<T>&
Adds a constant to each element in the array.
template<typename S>
auto operator+=(DimensionArray<S> const& other) -> DimensionArray<T>&
Adds an array to this, element-wise. other must have the same number of elements.
auto operator-=(T const& v) -> DimensionArray<T>&
Subtracts a constant from each element in the array.
template<typename S>
auto operator-=(DimensionArray<S> const& other) -> DimensionArray<T>&
Subtracts an array from this, element-wise. other must have the same number of elements.
auto operator*=(T const& v) -> DimensionArray<T>&
Multiplies each element in the array by a constant.
auto operator/=(T const& v) -> DimensionArray<T>&
Divides each element in the array by a constant.

Function documentation

template<typename T>
DimensionArray<T> permute(DimensionArray<dip::DimensionArray::size_type> const& order) const

Order the elements in the array according to the order array, such as returned by sorted_indices.

Postcondition:

out[ ii ] = (*this)[ order[ ii ] ];

template<typename T>
DimensionArray<T> inverse_permute(DimensionArray<dip::DimensionArray::size_type> const& order) const

Inverse orders the elements in the array according to the order array, such as returned by sorted_indices.

Postcondition:

out[ order[ ii ]] = (*this)[ ii ];

Elements not indexed by order will be default-initialized.