Support types module
#include "diplib.h"

template<typename T>
dip::DimensionArray class

A dynamic array type optimized for few elements.

Reference

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(dip::DimensionArray const& other): Copy constructor, initializes with a copy of other.
DimensionArray(dip::DimensionArray&& other) noexcept: Move constructor, initializes by stealing the contents of other.
auto operator=(dip::DimensionArray const& other) -> dip::DimensionArray&: Copy assignment, copies over data from other.
auto operator=(dip::DimensionArray&& other) -> dip::DimensionArray& 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(dip::DimensionArray const& other): Cast constructor, initializes with a copy of other. Casting done as default in C++, not through dip::clamp_cast.
void swap(dip::DimensionArray& 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(dip::DimensionArray 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(dip::DimensionArray& other): Sort the contents of the array from smallest to largest, and keeping other in the same order.
void reverse(): Reverses the elements in the array, putting the first element at the end.
auto sorted_indices() const -> dip::DimensionArray: Returns an array with indices into the array, sorted from smallest value to largest.
auto permute(dip::DimensionArray const& order) const -> dip::DimensionArray: Order the elements in the array according to the order array, such as returned by sorted_indices.
auto inverse_permute(dip::DimensionArray const& order) const -> dip::DimensionArray: Inverse orders the elements in the array according to the order array, such as returned by sorted_indices.
auto find(T value) const -> 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. Returns 1 for an empty 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) -> dip::DimensionArray&: Adds a constant to each element in the array.
template<typename S> auto operator+=(dip::DimensionArray const& other) -> dip::DimensionArray&: Adds an array to this, element-wise. other must have the same number of elements.
auto operator-=(T const& v) -> dip::DimensionArray&: Subtracts a constant from each element in the array.
template<typename S> auto operator-=(dip::DimensionArray const& other) -> dip::DimensionArray&: Subtracts an array from this, element-wise. other must have the same number of elements.
auto operator*=(T const& v) -> dip::DimensionArray&: Multiplies each element in the array by a constant.
auto operator/=(T const& v) -> dip::DimensionArray&: Divides each element in the array by a constant.

Function documentation

template<typename T>
dip::DimensionArray permute(dip::DimensionArray 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>
dip::DimensionArray inverse_permute(dip::DimensionArray 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.

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

Contents