Array

template<typename ElemType, DataLocation Location>
class Array

A plain contiguous array allocated in either the Host or Device according to the Location parameter. The memory allocated for the Array will be aligned to the SIMD width of the target system (e.g., 256-bit when using AVX2 instruction set).

Similar to the std::vector, the Array has an allocation capacity and a size. The capacity stores the size of the current memory allocation, while the size stores the number of elements in the container. In this way, it can be resized at will without altering the memory allocation as long as the new size is not greater than the current capacity(). Otherwise, HighFM will allocate a new block in memory and move the content of the container to this new block. To avoid constant reallocations when modifying the size of the container, its allocation capacity is always a multiple of the HIGHFM_MEMORY_BLOCK (default: 1024 elements).

Template Parameters:

• ElemType – Type of the elements in the container.

• Location – Where the array will be allocated. Options: Host or Device.

Constructor

Array()

Creates an empty Array.

Array(index_t n)

Creates an Array with size n. The elements in the container will be initialized to its default value.

Parameters:

n – [in] container size.

Throws:

LengthError – if `n < 0`.

Array(index_t n, ElemType val)

Creates an Array and then fills the container with val.

Parameters:

• n – [in] container size.

• val – [in] value to initialize the Array with.

Throws:

LengthError – if `size < 0`.

template<DataLocation OtherLoc>
Array(const DataMap<ElemType, OtherLoc> &data_map)

Creates an Array and then copies the content from a data_map. The data_map can be located in another memory space (e.g., in the GPU).

Parameters:

data_map – [in] a DataMap to use as the data source.

Array(ElemType *ptr, index_t n)

Creates an Array and then copies the data from the container pointed by ptr. The container must be stored contiguously in memory and be in the same memory space.

Parameters:

• ptr – [in] pointer to the beginning of a container.

• n – [in] container size.

Array(const Array &other)

Creates an Array and then copies the content from an other Array.

Parameters:

other – [in] another Array to use as the data source.

template<DataLocation OtherLoc>
Array(const Array<ElemType, OtherLoc> &other)

Creates an Array and then copies the content from an other Array. The other array can be located in another memory space (e.g., in the GPU).

Parameters:

other – [in] another Array to use as the data source.

Array(Array &&other) noexcept

Creates an Array and then moves the content from an other Array, following the move semantics. The other array is left in an unspecified state afterwards.

Parameters:

other – [in] another Array to use as the data source.

Destructor

virtual ~Array()

Deallocates the container and set its size to zero.

Assignment

Array &operator=(const Array &other)

Copies the content from an other Array to this container. This routine will automatically reallocate the Array if needed.

Parameters:

other – [in] another Array to use as the data source.

Returns:

*this.

template<DataLocation OtherLoc>
Array &operator=(const Array<ElemType, OtherLoc> &other)

Copies the content from an other Array to this container. The other array can be located in another memory space (e.g., in the GPU). This routine will automatically reallocate the Array if needed.

Parameters:

other – [in] another Array to use as the data source.

Returns:

*this.

template<DataLocation OtherLoc>
Array &operator=(const DataMap<ElemType, OtherLoc> &data_map)

Copies the content from a DataMap to this container. The data_map can be located in another memory space (e.g., in the GPU). This routine will automatically reallocate the Array if needed.

Parameters:

data_map – [in] a DataMap to use as the data source.

Returns:

*this.

Array &operator=(Array &&other) noexcept

Replaces the container’s content with the contents of an other Array, following the move semantics. The other array is left in an unspecified state afterwards.

Parameters:

other – [in] another Array to use as the data source.

Returns:

*this.

void fill(index_t n, ElemType val)

Fills the Array with n copies of val. This routine will automatically reallocate the Array if needed.

Parameters:

• n – [in] number of copies.

• val – [in] value to replace the Array content with.

void fill(ElemType val)

Sets all elements in the Array to val.

Parameters:

val – [in] value to replace the Array content with.

Iterators

iterator begin() noexcept

Returns:

an iterator to the beginning of the container.

iterator end() noexcept

Returns:

an iterator to past-the-end element of the container.

const_iterator cbegin() const noexcept

Returns:

a const_iterator to the beginning of the container.

const_iterator cend() const noexcept

Returns:

a const_iterator to the past-the-end element of the container.

Element Access

ElemType *data() noexcept

Note

If empty() = true, data() returns a nullptr.

Returns:

A raw pointer to the beginning of the container.

ElemType *data() const noexcept

Note

If empty() = true, data() returns a nullptr.

Returns:

A raw pointer to the beginning of the container.

ElemType &operator[](index_t idx)

Accesses element at idx position.

Parameters:

idx – [in] position of the element to return.

Returns:

A reference to the requested element.

ElemType operator[](index_t idx) const

Accesses element at idx position.

Parameters:

idx – [in] position of the element to return.

Returns:

A const reference to the requested element.

Capacity

bool is_empty() const noexcept

Returns:

true if the container is empty, false otherwise.

index_t size() const noexcept

Returns:

The number of elements in the container.

index_t capacity() const noexcept

Returns:

The capacity of the currently allocated storage.

void reserve(index_t new_cap)

Reallocates the container to new_cap if new_cap > capacity(). Otherwise, this routine does nothing.

Warning

During the reallocation, this routine will allocate additional memory equal to size() to preserve the array’s content. If this behaviour is undesirable, use clear() before calling this routine.

Parameters:

new_cap – [in] new capacity.

void shrink_to_fit()

Reallocates the container based on the number of elements within. This routine will reduce the capacity() accordingly.

Warning

During the reallocation, this routine will allocate additional memory equal to size() to preserve the array’s content.

Modifiers

void deallocate() noexcept

Deallocates the container from memory.

void clear() noexcept

Clears the content of the Array and sets its size to 0.

void resize(index_t new_size)

Resizes the container to new_size. If new_size > capacity(), this routine automatically reallocates the object to contain the additional elements.

Note

See reserve() in case of reallocation.

Parameters:

new_size – [in] new size of the container.

Throws:

LengthError – if `new_size < 0`.

void push_back(ElemType value)

Inserts value at the end of the Array. If the resulting size is greater than the current capacity(), this routine automatically reallocates the container.

Note

See reserve() in case of reallocation.

Parameters:

value – [in] value to be inserted at the end of the Array.

ElemType pop_back()

Removes the last element of the container, decreasing the Array size by 1.

Returns:

the removed element.

void swap(Array &other) noexcept

Swaps the Array content with other, including any memory allocation.

Parameters:

other – [inout] another Array to exchange content with.