Template Numerical Library: TNL::Containers::Array< Value, Device, Index, Allocator > Class Template Reference

Template Numerical Library version\ main:0b2c40fb1

Loading...
Searching...
No Matches
Public Types | Public Member Functions | Static Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
TNL::Containers::Array< Value, Device, Index, Allocator > Class Template Reference

Array is responsible for memory management, access to array elements, and general array operations. More...

`#include <TNL/Containers/Array.h>`

Inheritance diagram for TNL::Containers::Array< Value, Device, Index, Allocator >:
[legend]
Collaboration diagram for TNL::Containers::Array< Value, Device, Index, Allocator >:
[legend]

## Public Types
using | AllocatorType = Allocator
| Allocator type used for allocating this array.
using | ConstViewType = ArrayView< std::add_const_t< Value >, Device, Index >
| Compatible constant ArrayView type.
using | DeviceType = Device
| Device used to run operations on the array.
using | IndexType = Index
| Type being used for the array elements indexing.
template<typename _Value, typename _Device = Device, typename _Index = Index, typename _Allocator = typename Allocators::Default< _Device >::template Allocator< _Value >>
using | Self = Array< _Value, _Device, _Index, _Allocator >
| A template which allows to quickly obtain an Array type with changed template parameters.
using | ValueType = Value
| Type of elements stored in this array.
using | ViewType = ArrayView< Value, Device, Index >
| Compatible ArrayView type.

## Public Member Functions
| Array ()=default
| Constructs an empty array with zero size.
| Array (Array &&array) noexcept
| Move constructor for initialization from rvalues.
| Array (const AllocatorType &allocator)
| Constructs an empty array and sets the provided allocator.
| Array (const Array &array)
| Copy constructor (makes a deep copy).
| Array (const Array &array, const AllocatorType &allocator)
| Copy constructor with a specific allocator (makes a deep copy).
| Array (const Array &array, IndexType begin, IndexType size=0, const AllocatorType &allocator=AllocatorType())
| Copy constructor (makes a deep copy).
template<typename Value_, typename Device_, typename Index_, typename Allocator_>
| Array (const Array< Value_, Device_, Index_, Allocator_ > &a)
| Copy constructor from array with different template parameters.
template<typename InValue, std::enable_if_t< std::is_convertible_v< InValue, ValueType >, bool > = true>
| Array (const std::initializer_list< InValue > &list, const AllocatorType &allocator=AllocatorType())
| Constructor which initializes the array by copying elements from std::initializer_list, e.g. {...}.
template<typename InValue>
| Array (const std::list< InValue > &list, const AllocatorType &allocator=AllocatorType())
| Constructor which initializes the array by copying elements from std::list.
template<typename InValue>
| Array (const std::vector< InValue > &vector, const AllocatorType &allocator=AllocatorType())
| Constructor which initializes the array by copying elements from std::vector.
| Array (IndexType size, const AllocatorType &allocator=AllocatorType())
| Constructs an array with given size.
| Array (IndexType size, ValueType value, const AllocatorType &allocator=AllocatorType())
| Constructs an array with given size and value.
| Array (ValueType *data, IndexType size, const AllocatorType &allocator=AllocatorType())
| Constructs an array with given size and copies data from given pointer.
virtual | ~Array ()
| Destructor.
__cuda_callable__ bool | empty () const
| Returns true if the current array size is zero.
template<typename Function>
void | forAllElements (Function &&f)
| Process the lambda function f for each array element.
template<typename Function>
void | forAllElements (Function &&f) const
| Process the lambda function f for each array element for constant instances.
template<typename Function>
void | forElements (IndexType begin, IndexType end, Function &&f)
| Process the lambda function f for each array element in interval [ begin, end).
template<typename Function>
void | forElements (IndexType begin, IndexType end, Function &&f) const
| Process the lambda function f for each array element in interval [ begin, end) for constant instances of the array.
AllocatorType | getAllocator () const
| Returns the allocator associated with the array.
__cuda_callable__ Value * | getArrayData ()
| Returns a raw pointer to the data.
__cuda_callable__ const Value * | getArrayData () const
| Returns a const-qualified raw pointer to the data.
ConstViewType | getConstView (IndexType begin=0, IndexType end=0) const
| Returns a non-modifiable view of the array.
__cuda_callable__ Value * | getData ()
| Returns a raw pointer to the data.
__cuda_callable__ const Value * | getData () const
| Returns a const-qualified raw pointer to the data.
__cuda_callable__ ValueType | getElement (IndexType i) const
| Returns the value of the i-th element.
__cuda_callable__ IndexType | getSize () const
| Returns the current array size.
ViewType | getView (IndexType begin=0, IndexType end=0)
| Returns a modifiable view of the array.
void | load (const String &fileName)
| Method for loading the array from a binary file fileName.
| operator ConstViewType () const
| Conversion operator to a non-modifiable view of the array.
| operator ViewType ()
| Conversion operator to a modifiable view of the array.
template<typename ArrayT>
bool | operator!= (const ArrayT &array) const
| Compares the array with another array-like container.
__cuda_callable__ Value & | operator() (IndexType i)
| Accesses the i-th element of the array.
__cuda_callable__ const Value & | operator() (IndexType i) const
| Accesses the i-th element of the array.
Array & | operator= (Array &&array) noexcept(false)
| Move-assignment operator for acquiring data from rvalues.
Array & | operator= (const Array &array)
| Copy-assignment operator for copying data from another array.
template<typename InValue>
Array & | operator= (const std::list< InValue > &list)
| Copies elements from std::list to this array.
template<typename InValue>
Array & | operator= (const std::vector< InValue > &vector)
| Copies elements from std::vector to this array.
template<typename T, typename..., typename = std::enable_if_t< std::is_convertible_v< T, ValueType > || IsArrayType< T >::value >>
Array & | operator= (const T &data)
| Assigns either array-like container or a single value.
template<typename ArrayT>
bool | operator== (const ArrayT &array) const
| Compares the array with another array-like container.
__cuda_callable__ Value & | operator[] (IndexType i)
| Accesses the i-th element of the array.
__cuda_callable__ const Value & | operator[] (IndexType i) const
| Accesses the i-th element of the array.
void | reset ()
| Resets the array to the empty state.
void | resize (IndexType size)
| Method for resizing the array.
void | resize (IndexType size, ValueType value)
| Method for resizing the array with an initial value.
void | save (const String &fileName) const
| Method for saving the array to a binary file fileName.
__cuda_callable__ void | setElement (IndexType i, ValueType value)
| Sets the value of the i-th element to v.
template<typename ArrayT>
void | setLike (const ArrayT &array)
| Sets the same size as the size of an existing array.
void | setSize (IndexType size)
| Method for setting the array size.
void | setValue (ValueType value, IndexType begin=0, IndexType end=0)
| Sets elements of the array to given value.
void | swap (Array &array) noexcept
| Swaps this array with another.

## Static Public Member Functions
static std::string | getSerializationType ()
| Returns a string representation of the array type in C++ style, with a placeholder in place of Device and Allocator.

## Protected Member Functions
void | reallocate (IndexType size)
| Internal method for reallocating array elements. Used only from the two overloads of resize.
void | releaseData ()
| Internal method for releasing (deallocating) array data.

## Protected Attributes
Allocator | allocator
| The internal allocator instance.
Value * | data = nullptr
| Pointer to the data.
IndexType | size = 0
| Number of elements in the array.

## Detailed Description

template<typename Value, typename Device = Devices::Host, typename Index = int, typename Allocator = typename Allocators::Default< Device >::template Allocator< Value >>
class TNL::Containers::Array< Value, Device, Index, Allocator >

Array is responsible for memory management, access to array elements, and general array operations.

Template Parameters

  Value | The type of array elements.
  Device | The device to be used for the execution of array operations. It can be any class defined in the TNL::Devices namespace.
  Index | The indexing type.
  Allocator | The type of the allocator used for the allocation and deallocation of memory used by the array. By default, an appropriate allocator for the specified Device is selected with TNL::Allocators::Default.

Memory management handled by constructors and destructors according to the RAII principle and by methods resize setSize, setLike, swap, and reset. You can also use methods getSize and empty to check the current array size and getData to access the raw pointer.

Methods annotated as __cuda_callable__ can be called either from host or from kernels executing on a device according to the Device parameter. One of these methods is the operator[] which provides direct access to the array elements. However, it cannot be called from the host if the array was allocated in a memory space which is not directly accessible by the host. If the host needs access to individual array elements which are allocated in a different memory space, they have to be accessed by the setElement or getElement method. However, these methods imply an explicit data transfer which is not buffered, so it can be very slow.

Other methods, such as operator=, operator==, operator!=, and setValue, provide various operations on whole arrays.

See also ArrayView, Vector, VectorView.

Example
  #include <iostream>
  #include <list>
  #include <vector>
  #include <TNL/Containers/Array.h>
  using namespace TNL;
  using namespace std;
  /***
  * The following works for any device (CPU, GPU ...).
  */
  template< typename Device >
  void
  arrayExample()
  {
  const int size = 10;
  using ArrayType = Containers::Array< int, Device >;
  ArrayType a1( size );
  ArrayType a2( size );
  /***
  * You may initiate the array using setElement
  */
  for( int i = 0; i < size; i++ )
  a1.setElement( i, i );
  std::cout << "a1 = " << a1 << '\n';
  /***
  * You may also assign value to all array elements ...
  */
  a2 = 0;
  std::cout << "a2 = " << a2 << '\n';
  /***
  * ... or assign STL list and vector.
  */
  std::list< float > l = { 1.0, 2.0, 3.0 };
  std::vector< float > v = { 5.0, 6.0, 7.0 };
  a1 = l;
  std::cout << "a1 = " << a1 << '\n';
  a1 = v;
  std::cout << "a1 = " << a1 << '\n';
  /***
  * You may swap array data with the swap method.
  */
  a1.swap( a2 );
  /***
  * You may save it to file and load again
  */
  File( "a1.tnl", std::ios_base::out ) << a1;
  File( "a1.tnl", std::ios_base::in ) >> a2;
  std::remove( "a1.tnl" );
  if( a2 != a1 )
  std::cerr << "Something is wrong!!!\n";
  std::cout << "a2 = " << a2 << '\n';
  }
  int
  main()
  {
  std::cout << "The first test runs on CPU ...\n";
  arrayExample< Devices::Host >();
  #ifdef __CUDACC__
  std::cout << "The second test runs on GPU ...\n";
  arrayExample< Devices::Cuda >();
  #endif
  }
  std::cout
  TNL::Containers::Array
  Array is responsible for memory management, access to array elements, and general array operations.
  Definition Array.h:65
  TNL::Containers::Array::size
  IndexType size
  Number of elements in the array.
  Definition Array.h:777
  TNL::File
  This class serves for binary IO. It allows to do IO even for data allocated on GPU together with on-t...
  Definition File.h:25
  std::list
  TNL
  The main TNL namespace.
  Definition AtomicOperations.h:15
  std
  STL namespace.
  std::remove
  T remove(T... args)
  std::vector

Output
  The first test runs on CPU ...
  a1 = [ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 ]
  a2 = [ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 ]
  a1 = [ 1, 2, 3 ]
  a1 = [ 5, 6, 7 ]
  a2 = [ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 ]

## Member Typedef Documentation

## ◆ AllocatorType

template<typename Value, typename Device = Devices::Host, typename Index = int, typename Allocator = typename Allocators::Default< Device >::template Allocator< Value >>

using TNL::Containers::Array< Value, Device, Index, Allocator >::AllocatorType = Allocator

Allocator type used for allocating this array.

See TNL::Allocators.

## ◆ DeviceType

template<typename Value, typename Device = Devices::Host, typename Index = int, typename Allocator = typename Allocators::Default< Device >::template Allocator< Value >>

using TNL::Containers::Array< Value, Device, Index, Allocator >::DeviceType = Device

Device used to run operations on the array.

See TNL::Devices for the available options.

## Constructor & Destructor Documentation

## ◆ Array() [1/12]

template<typename Value, typename Device = Devices::Host, typename Index = int, typename Allocator = typename Allocators::Default< Device >::template Allocator< Value >>

TNL::Containers::Array< Value, Device, Index, Allocator >::Array | ( | const AllocatorType & | allocator | ) |
| explicit

Constructs an empty array and sets the provided allocator.

Parameters

  allocator | The allocator to be associated with this array.

## ◆ Array() [2/12]

template<typename Value, typename Device = Devices::Host, typename Index = int, typename Allocator = typename Allocators::Default< Device >::template Allocator< Value >>

TNL::Containers::Array< Value, Device, Index, Allocator >::Array | ( | IndexType | size,
|  | const AllocatorType & | allocator = AllocatorType() )
| explicit

Constructs an array with given size.

Parameters

  size | The number of array elements to be allocated.
  allocator | The allocator to be associated with this array.

## ◆ Array() [3/12]

template<typename Value, typename Device = Devices::Host, typename Index = int, typename Allocator = typename Allocators::Default< Device >::template Allocator< Value >>

TNL::Containers::Array< Value, Device, Index, Allocator >::Array | ( | IndexType | size,
|  | ValueType | value,
|  | const AllocatorType & | allocator = AllocatorType() )
| explicit

Constructs an array with given size and value.

Parameters

  size | The number of array elements to be allocated.
  value | The value all elements will be set to.
  allocator | The allocator to be associated with this array.

## ◆ Array() [4/12]

template<typename Value, typename Device = Devices::Host, typename Index = int, typename Allocator = typename Allocators::Default< Device >::template Allocator< Value >>

TNL::Containers::Array< Value, Device, Index, Allocator >::Array | ( | ValueType * | data,
|  | IndexType | size,
|  | const AllocatorType & | allocator = AllocatorType() )

Constructs an array with given size and copies data from given pointer.

Parameters

  data | The pointer to the data to be copied to the array.
  size | The number of array elements to be copied to the array.
  allocator | The allocator to be associated with this array.

## ◆ Array() [5/12]

template<typename Value, typename Device = Devices::Host, typename Index = int, typename Allocator = typename Allocators::Default< Device >::template Allocator< Value >>

TNL::Containers::Array< Value, Device, Index, Allocator >::Array | ( | const Array< Value, Device, Index, Allocator > & | array | ) |
| explicit

Copy constructor (makes a deep copy).

Parameters

  array | The array to be copied.

## ◆ Array() [6/12]

template<typename Value, typename Device = Devices::Host, typename Index = int, typename Allocator = typename Allocators::Default< Device >::template Allocator< Value >>

TNL::Containers::Array< Value, Device, Index, Allocator >::Array | ( | const Array< Value, Device, Index, Allocator > & | array,
|  | const AllocatorType & | allocator )
| explicit

Copy constructor with a specific allocator (makes a deep copy).

Parameters

  array | The array to be copied.
  allocator | The allocator to be associated with this array.

## ◆ Array() [7/12]

template<typename Value, typename Device = Devices::Host, typename Index = int, typename Allocator = typename Allocators::Default< Device >::template Allocator< Value >>

TNL::Containers::Array< Value, Device, Index, Allocator >::Array | ( | const Array< Value, Device, Index, Allocator > & | array,
|  | IndexType | begin,
|  | IndexType | size = 0,
|  | const AllocatorType & | allocator = AllocatorType() )

Copy constructor (makes a deep copy).

Parameters

  array | The array to be copied.
  begin | The first index which should be copied.
  size | The number of elements that should be copied.
  allocator | The allocator to be associated with this array.

## ◆ Array() [8/12]

template<typename Value, typename Device = Devices::Host, typename Index = int, typename Allocator = typename Allocators::Default< Device >::template Allocator< Value >>

TNL::Containers::Array< Value, Device, Index, Allocator >::Array | ( | Array< Value, Device, Index, Allocator > && | array | ) |
| noexcept

Move constructor for initialization from rvalues.

Parameters

  array | The array to be moved.

## ◆ Array() [9/12]

template<typename Value, typename Device = Devices::Host, typename Index = int, typename Allocator = typename Allocators::Default< Device >::template Allocator< Value >>
template<typename Value_, typename Device_, typename Index_, typename Allocator_>

TNL::Containers::Array< Value, Device, Index, Allocator >::Array | ( | const Array< Value_, Device_, Index_, Allocator_ > & | a | ) |
| explicit

Copy constructor from array with different template parameters.

Template Parameters

  Value_ | Value type of the input array.
  Device_ | Device type of the input array.
  Index_ | Index type of the input array.
  Allocator_ | Allocator type of the input array.

Parameters

  a | the input array.

## ◆ Array() [10/12]

template<typename Value, typename Device = Devices::Host, typename Index = int, typename Allocator = typename Allocators::Default< Device >::template Allocator< Value >>
template<typename InValue, std::enable_if_t< std::is_convertible_v< InValue, ValueType >, bool > = true>

TNL::Containers::Array< Value, Device, Index, Allocator >::Array | ( | const std::initializer_list< InValue > & | list,
|  | const AllocatorType & | allocator = AllocatorType() )

Constructor which initializes the array by copying elements from std::initializer_list, e.g. {...}.

Parameters

  list | The initializer list containing elements to be copied.
  allocator | The allocator to be associated with this array.

## ◆ Array() [11/12]

template<typename Value, typename Device = Devices::Host, typename Index = int, typename Allocator = typename Allocators::Default< Device >::template Allocator< Value >>
template<typename InValue>

TNL::Containers::Array< Value, Device, Index, Allocator >::Array | ( | const std::list< InValue > & | list,
|  | const AllocatorType & | allocator = AllocatorType() )

Constructor which initializes the array by copying elements from std::list.

Parameters

  list | The STL list containing elements to be copied.
  allocator | The allocator to be associated with this array.

## ◆ Array() [12/12]

template<typename Value, typename Device = Devices::Host, typename Index = int, typename Allocator = typename Allocators::Default< Device >::template Allocator< Value >>
template<typename InValue>

TNL::Containers::Array< Value, Device, Index, Allocator >::Array | ( | const std::vector< InValue > & | vector,
|  | const AllocatorType & | allocator = AllocatorType() )

Constructor which initializes the array by copying elements from std::vector.

Parameters

  vector | The STL vector containing elements to be copied.
  allocator | The allocator to be associated with this array.

## Member Function Documentation

## ◆ empty()

template<typename Value, typename Device = Devices::Host, typename Index = int, typename Allocator = typename Allocators::Default< Device >::template Allocator< Value >>

__cuda_callable__ bool TNL::Containers::Array< Value, Device, Index, Allocator >::empty | ( |  | ) | const
| nodiscard

Returns true if the current array size is zero.

This method can be called from device kernels.

## ◆ forAllElements() [1/2]

template<typename Value, typename Device = Devices::Host, typename Index = int, typename Allocator = typename Allocators::Default< Device >::template Allocator< Value >>
template<typename Function>

void TNL::Containers::Array< Value, Device, Index, Allocator >::forAllElements | ( | Function && | f | ) |

Process the lambda function f for each array element.

The lambda function is supposed to be declared as

f( IndexType elementIdx, ValueType& elementValue )
TNL::Containers::Array::ValueType
Value ValueType
Type of elements stored in this array.
Definition Array.h:74
TNL::Containers::Array::IndexType
Index IndexType
Type being used for the array elements indexing.
Definition Array.h:86

where

- elementIdx is an index of the array element being currently processed
- elementValue is a value of the array element being currently processed

This is performed at the same place where the array is allocated, i.e. it is efficient even on GPU.

Parameters

  f | The lambda function to be processed.

Example
  #include <iostream>
  #include <TNL/Containers/Array.h>
  #include <TNL/Containers/ArrayView.h>
  using namespace TNL;
  template< typename Device >
  void
  forElementsExample()
  {
  /****
  * Create new arrays
  */
  const int size = 10;
  Containers::Array< float, Device > a( size );
  Containers::Array< float, Device > b( size );
  b = 0;
  /****
  * Initiate the elements of array `a`
  */
  a.forAllElements(
  [] __cuda_callable__( int i, float& value )
  {
  value = i;
  } );
  /****
  * Initiate elements of array `b` with indexes 0-4 using `a_view`
  */
  auto a_view = a.getView();
  b.forElements(
  0,
  5,
  [ = ] __cuda_callable__( int i, float& value )
  {
  value = a_view[ i ] + 4.0;
  } );
  /****
  * Print the results
  */
  std::cout << " a = " << a << '\n';
  std::cout << " b = " << b << '\n';
  }
  int
  main( int argc, char* argv[] )
  {
  std::cout << "Running example on the host system:\n";
  forElementsExample< Devices::Host >();
  #ifdef __CUDACC__
  std::cout << "Running example on the CUDA device:\n";
  forElementsExample< Devices::Cuda >();
  #endif
  }
  __cuda_callable__
  #define __cuda_callable__
  Definition Macros.h:49

Output
  Running example on the host system:
  a = [ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 ]
  b = [ 4, 5, 6, 7, 8, 0, 0, 0, 0, 0 ]

## ◆ forAllElements() [2/2]

template<typename Value, typename Device = Devices::Host, typename Index = int, typename Allocator = typename Allocators::Default< Device >::template Allocator< Value >>
template<typename Function>

void TNL::Containers::Array< Value, Device, Index, Allocator >::forAllElements | ( | Function && | f | ) | const

Process the lambda function f for each array element for constant instances.

The lambda function is supposed to be declared as

f( IndexType elementIdx, const ValueType& elementValue )

where

- elementIdx is an index of the array element being currently processed
- elementValue is a value of the array element being currently processed

This is performed at the same place where the array is allocated, i.e. it is efficient even on GPU.

Parameters

  f | The lambda function to be processed.

Example
  #include <iostream>
  #include <TNL/Containers/Array.h>
  #include <TNL/Containers/ArrayView.h>
  using namespace TNL;
  template< typename Device >
  void
  forElementsExample()
  {
  /****
  * Create new arrays
  */
  const int size = 10;
  Containers::Array< float, Device > a( size );
  Containers::Array< float, Device > b( size );
  b = 0;
  /****
  * Initiate the elements of array `a`
  */
  a.forAllElements(
  [] __cuda_callable__( int i, float& value )
  {
  value = i;
  } );
  /****
  * Initiate elements of array `b` with indexes 0-4 using `a_view`
  */
  auto a_view = a.getView();
  b.forElements(
  0,
  5,
  [ = ] __cuda_callable__( int i, float& value )
  {
  value = a_view[ i ] + 4.0;
  } );
  /****
  * Print the results
  */
  std::cout << " a = " << a << '\n';
  std::cout << " b = " << b << '\n';
  }
  int
  main( int argc, char* argv[] )
  {
  std::cout << "Running example on the host system:\n";
  forElementsExample< Devices::Host >();
  #ifdef __CUDACC__
  std::cout << "Running example on the CUDA device:\n";
  forElementsExample< Devices::Cuda >();
  #endif
  }

Output
  Running example on the host system:
  a = [ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 ]
  b = [ 4, 5, 6, 7, 8, 0, 0, 0, 0, 0 ]

## ◆ forElements() [1/2]

template<typename Value, typename Device = Devices::Host, typename Index = int, typename Allocator = typename Allocators::Default< Device >::template Allocator< Value >>
template<typename Function>

void TNL::Containers::Array< Value, Device, Index, Allocator >::forElements | ( | IndexType | begin,
|  | IndexType | end,
|  | Function && | f )

Process the lambda function f for each array element in interval [ begin, end).

The lambda function is supposed to be declared as

f( IndexType elementIdx, ValueType& elementValue )

where

- elementIdx is an index of the array element being currently processed
- elementValue is a value of the array element being currently processed

This is performed at the same place where the array is allocated, i.e. it is efficient even on GPU.

Parameters

  begin | The beginning of the array elements interval.
  end | The end of the array elements interval.
  f | The lambda function to be processed.

Example
  #include <iostream>
  #include <TNL/Containers/Array.h>
  #include <TNL/Containers/ArrayView.h>
  using namespace TNL;
  template< typename Device >
  void
  forElementsExample()
  {
  /****
  * Create new arrays
  */
  const int size = 10;
  Containers::Array< float, Device > a( size );
  Containers::Array< float, Device > b( size );
  b = 0;
  /****
  * Initiate the elements of array `a`
  */
  a.forAllElements(
  [] __cuda_callable__( int i, float& value )
  {
  value = i;
  } );
  /****
  * Initiate elements of array `b` with indexes 0-4 using `a_view`
  */
  auto a_view = a.getView();
  b.forElements(
  0,
  5,
  [ = ] __cuda_callable__( int i, float& value )
  {
  value = a_view[ i ] + 4.0;
  } );
  /****
  * Print the results
  */
  std::cout << " a = " << a << '\n';
  std::cout << " b = " << b << '\n';
  }
  int
  main( int argc, char* argv[] )
  {
  std::cout << "Running example on the host system:\n";
  forElementsExample< Devices::Host >();
  #ifdef __CUDACC__
  std::cout << "Running example on the CUDA device:\n";
  forElementsExample< Devices::Cuda >();
  #endif
  }

Output
  Running example on the host system:
  a = [ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 ]
  b = [ 4, 5, 6, 7, 8, 0, 0, 0, 0, 0 ]

## ◆ forElements() [2/2]

template<typename Value, typename Device = Devices::Host, typename Index = int, typename Allocator = typename Allocators::Default< Device >::template Allocator< Value >>
template<typename Function>

void TNL::Containers::Array< Value, Device, Index, Allocator >::forElements | ( | IndexType | begin,
|  | IndexType | end,
|  | Function && | f ) const

Process the lambda function f for each array element in interval [ begin, end) for constant instances of the array.

The lambda function is supposed to be declared as

f( IndexType elementIdx, const ValueType& elementValue )

where

- elementIdx is an index of the array element being currently processed
- elementValue is a value of the array element being currently processed

This is performed at the same place where the array is allocated, i.e. it is efficient even on GPU.

Parameters

  begin | The beginning of the array elements interval.
  end | The end of the array elements interval.
  f | The lambda function to be processed.

Example
  #include <iostream>
  #include <TNL/Containers/Array.h>
  #include <TNL/Containers/ArrayView.h>
  using namespace TNL;
  template< typename Device >
  void
  forElementsExample()
  {
  /****
  * Create new arrays
  */
  const int size = 10;
  Containers::Array< float, Device > a( size );
  Containers::Array< float, Device > b( size );
  b = 0;
  /****
  * Initiate the elements of array `a`
  */
  a.forAllElements(
  [] __cuda_callable__( int i, float& value )
  {
  value = i;
  } );
  /****
  * Initiate elements of array `b` with indexes 0-4 using `a_view`
  */
  auto a_view = a.getView();
  b.forElements(
  0,
  5,
  [ = ] __cuda_callable__( int i, float& value )
  {
  value = a_view[ i ] + 4.0;
  } );
  /****
  * Print the results
  */
  std::cout << " a = " << a << '\n';
  std::cout << " b = " << b << '\n';
  }
  int
  main( int argc, char* argv[] )
  {
  std::cout << "Running example on the host system:\n";
  forElementsExample< Devices::Host >();
  #ifdef __CUDACC__
  std::cout << "Running example on the CUDA device:\n";
  forElementsExample< Devices::Cuda >();
  #endif
  }

Output
  Running example on the host system:
  a = [ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 ]
  b = [ 4, 5, 6, 7, 8, 0, 0, 0, 0, 0 ]

## ◆ getArrayData() [1/2]

template<typename Value, typename Device = Devices::Host, typename Index = int, typename Allocator = typename Allocators::Default< Device >::template Allocator< Value >>

__cuda_callable__ Value * TNL::Containers::Array< Value, Device, Index, Allocator >::getArrayData | ( |  | ) |
| nodiscard

Returns a raw pointer to the data.

Use this method in algorithms where you want to emphasize that C-style array pointer is required.

This method can be called from device kernels.

## ◆ getArrayData() [2/2]

template<typename Value, typename Device = Devices::Host, typename Index = int, typename Allocator = typename Allocators::Default< Device >::template Allocator< Value >>

__cuda_callable__ const Value * TNL::Containers::Array< Value, Device, Index, Allocator >::getArrayData | ( |  | ) | const
| nodiscard

Returns a const-qualified raw pointer to the data.

Use this method in algorithms where you want to emphasize that C-style array pointer is required.

This method can be called from device kernels.

## ◆ getConstView()

template<typename Value, typename Device = Devices::Host, typename Index = int, typename Allocator = typename Allocators::Default< Device >::template Allocator< Value >>

ConstViewType TNL::Containers::Array< Value, Device, Index, Allocator >::getConstView | ( | IndexType | begin = 0,
|  | IndexType | end = 0 ) const
| nodiscard

Returns a non-modifiable view of the array.

By default, a view for the whole array is returned. If begin or end is set to a non-zero value, a view only for the sub-interval [begin, end) is returned.

Parameters

  begin | The beginning of the array sub-interval. It is 0 by default.
  end | The end of the array sub-interval. The default value is 0 which is, however, replaced with the array size.

## ◆ getData() [1/2]

template<typename Value, typename Device = Devices::Host, typename Index = int, typename Allocator = typename Allocators::Default< Device >::template Allocator< Value >>

__cuda_callable__ Value * TNL::Containers::Array< Value, Device, Index, Allocator >::getData | ( |  | ) |
| nodiscard

Returns a raw pointer to the data.

This method can be called from device kernels.

## ◆ getData() [2/2]

template<typename Value, typename Device = Devices::Host, typename Index = int, typename Allocator = typename Allocators::Default< Device >::template Allocator< Value >>

__cuda_callable__ const Value * TNL::Containers::Array< Value, Device, Index, Allocator >::getData | ( |  | ) | const
| nodiscard

Returns a const-qualified raw pointer to the data.

This method can be called from device kernels.

## ◆ getElement()

template<typename Value, typename Device = Devices::Host, typename Index = int, typename Allocator = typename Allocators::Default< Device >::template Allocator< Value >>

__cuda_callable__ ValueType TNL::Containers::Array< Value, Device, Index, Allocator >::getElement | ( | IndexType | i | ) | const
| nodiscard

Returns the value of the i-th element.

This method can be called from both the host system and the device where the array is allocated.

Parameters

  i | The index of the element to be returned.

## ◆ getSize()

template<typename Value, typename Device = Devices::Host, typename Index = int, typename Allocator = typename Allocators::Default< Device >::template Allocator< Value >>

__cuda_callable__ IndexType TNL::Containers::Array< Value, Device, Index, Allocator >::getSize | ( |  | ) | const
| nodiscard

Returns the current array size.

This method can be called from device kernels.

## ◆ getView()

template<typename Value, typename Device = Devices::Host, typename Index = int, typename Allocator = typename Allocators::Default< Device >::template Allocator< Value >>

ViewType TNL::Containers::Array< Value, Device, Index, Allocator >::getView | ( | IndexType | begin = 0,
|  | IndexType | end = 0 )
| nodiscard

Returns a modifiable view of the array.

By default, a view for the whole array is returned. If begin or end is set to a non-zero value, a view only for the sub-interval [begin, end) is returned.

Parameters

  begin | The beginning of the array sub-interval. It is 0 by default.
  end | The end of the array sub-interval. The default value is 0 which is, however, replaced with the array size.

## ◆ load()

template<typename Value, typename Device = Devices::Host, typename Index = int, typename Allocator = typename Allocators::Default< Device >::template Allocator< Value >>

void TNL::Containers::Array< Value, Device, Index, Allocator >::load | ( | const String & | fileName | ) |

Method for loading the array from a binary file fileName.

Parameters

  fileName | The input file name.

## ◆ operator!=()

template<typename Value, typename Device = Devices::Host, typename Index = int, typename Allocator = typename Allocators::Default< Device >::template Allocator< Value >>
template<typename ArrayT>

bool TNL::Containers::Array< Value, Device, Index, Allocator >::operator!= | ( | const ArrayT & | array | ) | const
| nodiscard

Compares the array with another array-like container.

Template Parameters

  ArrayT | The type of the parameter can be any array-like container, e.g. Array, ArrayView, Vector, VectorView, etc.

Parameters

  array | Reference to the array-like container.

Returns
  The negated result of operator==.

## ◆ operator()() [1/2]

template<typename Value, typename Device = Devices::Host, typename Index = int, typename Allocator = typename Allocators::Default< Device >::template Allocator< Value >>

__cuda_callable__ Value & TNL::Containers::Array< Value, Device, Index, Allocator >::operator() | ( | IndexType | i | ) |
| nodiscard

Accesses the i-th element of the array.

Equivalent to operator[], with the same notes and caveats.

## ◆ operator()() [2/2]

template<typename Value, typename Device = Devices::Host, typename Index = int, typename Allocator = typename Allocators::Default< Device >::template Allocator< Value >>

__cuda_callable__ const Value & TNL::Containers::Array< Value, Device, Index, Allocator >::operator() | ( | IndexType | i | ) | const
| nodiscard

Accesses the i-th element of the array.

Equivalent to operator[], with the same notes and caveats.

## ◆ operator=() [1/5]

template<typename Value, typename Device = Devices::Host, typename Index = int, typename Allocator = typename Allocators::Default< Device >::template Allocator< Value >>

Array & TNL::Containers::Array< Value, Device, Index, Allocator >::operator= | ( | Array< Value, Device, Index, Allocator > && | array | ) |

Move-assignment operator for acquiring data from rvalues.

Parameters

  array | Reference to the source array.

Returns
  Reference to this array.

## ◆ operator=() [2/5]

template<typename Value, typename Device = Devices::Host, typename Index = int, typename Allocator = typename Allocators::Default< Device >::template Allocator< Value >>

Array & TNL::Containers::Array< Value, Device, Index, Allocator >::operator= | ( | const Array< Value, Device, Index, Allocator > & | array | ) |

Copy-assignment operator for copying data from another array.

Parameters

  array | Reference to the source array.

Returns
  Reference to this array.

## ◆ operator=() [3/5]

template<typename Value, typename Device = Devices::Host, typename Index = int, typename Allocator = typename Allocators::Default< Device >::template Allocator< Value >>
template<typename InValue>

Array & TNL::Containers::Array< Value, Device, Index, Allocator >::operator= | ( | const std::list< InValue > & | list | ) |

Copies elements from std::list to this array.

Parameters

  list | The STL list containing elements to be copied.

Returns
  Reference to this array.

## ◆ operator=() [4/5]

template<typename Value, typename Device = Devices::Host, typename Index = int, typename Allocator = typename Allocators::Default< Device >::template Allocator< Value >>
template<typename InValue>

Array & TNL::Containers::Array< Value, Device, Index, Allocator >::operator= | ( | const std::vector< InValue > & | vector | ) |

Copies elements from std::vector to this array.

Parameters

  vector | The STL vector containing elements to be copied.

Returns
  Reference to this array.

## ◆ operator=() [5/5]

template<typename Value, typename Device = Devices::Host, typename Index = int, typename Allocator = typename Allocators::Default< Device >::template Allocator< Value >>
template<typename T, typename..., typename = std::enable_if_t< std::is_convertible_v< T, ValueType > || IsArrayType< T >::value >>

Array & TNL::Containers::Array< Value, Device, Index, Allocator >::operator= | ( | const T & | data | ) |

Assigns either array-like container or a single value.

If T is an array type, e.g. Array, ArrayView, StaticArray, Vector, VectorView, or StaticVector, the elements from data are copied into this array. Otherwise, if it is a type convertible to ValueType, all array elements are set to the value data.

Template Parameters

  T | The type of the source array or value.

Parameters

  data | Reference to the source array or value.

Returns
  Reference to this array.

## ◆ operator==()

template<typename Value, typename Device = Devices::Host, typename Index = int, typename Allocator = typename Allocators::Default< Device >::template Allocator< Value >>
template<typename ArrayT>

bool TNL::Containers::Array< Value, Device, Index, Allocator >::operator== | ( | const ArrayT & | array | ) | const
| nodiscard

Compares the array with another array-like container.

Template Parameters

  ArrayT | The type of the parameter can be any array-like container, e.g. Array, ArrayView, Vector, VectorView, etc.

Parameters

  array | Reference to the array-like container.

Returns
  true if both arrays are element-wise equal and false otherwise.

## ◆ operator[]() [1/2]

template<typename Value, typename Device = Devices::Host, typename Index = int, typename Allocator = typename Allocators::Default< Device >::template Allocator< Value >>

__cuda_callable__ Value & TNL::Containers::Array< Value, Device, Index, Allocator >::operator[] | ( | IndexType | i | ) |
| nodiscard

Accesses the i-th element of the array.

This method can be called only from the device which has direct access to the memory space where the array was allocated. For example, if the array was allocated in the host memory, it can be called only from host, and if the array was allocated in the device memory, it can be called only from device kernels. If NDEBUG is not defined, assertions inside this methods performs runtime checks for cross-device memory accesses which lead to segmentation fault. If you need to do just a pointer arithmetics use getData instead.

Parameters

  i | The index of the element to be accessed.

Returns
  Reference to the i-th element.

## ◆ operator[]() [2/2]

template<typename Value, typename Device = Devices::Host, typename Index = int, typename Allocator = typename Allocators::Default< Device >::template Allocator< Value >>

__cuda_callable__ const Value & TNL::Containers::Array< Value, Device, Index, Allocator >::operator[] | ( | IndexType | i | ) | const
| nodiscard

Accesses the i-th element of the array.

This method can be called only from the device which has direct access to the memory space where the array was allocated. For example, if the array was allocated in the host memory, it can be called only from host, and if the array was allocated in the device memory, it can be called only from device kernels. If NDEBUG is not defined, assertions inside this methods performs runtime checks for cross-device memory accesses which lead to segmentation fault. If you need to do just a pointer arithmetics use getData instead.

Parameters

  i | The index of the element to be accessed.

Returns
  Constant reference to the i-th element.

## ◆ reset()

template<typename Value, typename Device = Devices::Host, typename Index = int, typename Allocator = typename Allocators::Default< Device >::template Allocator< Value >>

void TNL::Containers::Array< Value, Device, Index, Allocator >::reset | ( |  | ) |

Resets the array to the empty state.

The current data will be deallocated, thus all pointers and views to the array elements will become invalid.

## ◆ resize() [1/2]

template<typename Value, typename Device = Devices::Host, typename Index = int, typename Allocator = typename Allocators::Default< Device >::template Allocator< Value >>

void TNL::Containers::Array< Value, Device, Index, Allocator >::resize | ( | IndexType | size | ) |

Method for resizing the array.

The method resizes the array to the given size:

- If the current size is greater than count, the array is reduced to its first size elements.
- If the current size is less than size, additional elements are appended (see the note below on initialization).
- If the current size is equal to size, nothing happens.

If the array size changes, the current data will be deallocated, thus all pointers and views to the array elements will become invalid.

Note that this method differs from std::vector::resize with respect to the initialization of array elements:

- if ValueType is a fundamental type, the elements are default-initialized (i.e., the elements are initialized to indeterminate values).
- otherwise, the elements are value-initialized (like in std::vector::resize).

Parameters

  size | The new size of the array.

## ◆ resize() [2/2]

template<typename Value, typename Device = Devices::Host, typename Index = int, typename Allocator = typename Allocators::Default< Device >::template Allocator< Value >>

void TNL::Containers::Array< Value, Device, Index, Allocator >::resize | ( | IndexType | size,
|  | ValueType | value )

Method for resizing the array with an initial value.

The method resizes the array to the given size:

- If the current size is greater than count, the array is reduced to its first size elements.
- If the current size is less than size, additional copies of value are appended.
- If the current size is equal to size, nothing happens.

If the array size changes, the current data will be deallocated, thus all pointers and views to the array elements will become invalid.

Parameters

  size | The new size of the array.
  value | The value to initialize new elements with.

## ◆ save()

template<typename Value, typename Device = Devices::Host, typename Index = int, typename Allocator = typename Allocators::Default< Device >::template Allocator< Value >>

void TNL::Containers::Array< Value, Device, Index, Allocator >::save | ( | const String & | fileName | ) | const

Method for saving the array to a binary file fileName.

Parameters

  fileName | The output file name.

## ◆ setElement()

template<typename Value, typename Device = Devices::Host, typename Index = int, typename Allocator = typename Allocators::Default< Device >::template Allocator< Value >>

__cuda_callable__ void TNL::Containers::Array< Value, Device, Index, Allocator >::setElement | ( | IndexType | i,
|  | ValueType | value )

Sets the value of the i-th element to v.

This method can be called from both the host system and the device where the array is allocated.

Parameters

  i | The index of the element to be set.
  value | The new value of the element.

## ◆ setLike()

template<typename Value, typename Device = Devices::Host, typename Index = int, typename Allocator = typename Allocators::Default< Device >::template Allocator< Value >>
template<typename ArrayT>

void TNL::Containers::Array< Value, Device, Index, Allocator >::setLike | ( | const ArrayT & | array | ) |

Sets the same size as the size of an existing array.

If the array size changes, the current data will be deallocated, thus all pointers and views to the array elements will become invalid.

Note that this method uses setSize rather than resize.

Template Parameters

  ArrayT | The type of the parameter can be any type which provides the method getSize() with the same signature as Array.

Parameters

  array | The array whose size is to be taken.

## ◆ setSize()

template<typename Value, typename Device = Devices::Host, typename Index = int, typename Allocator = typename Allocators::Default< Device >::template Allocator< Value >>

void TNL::Containers::Array< Value, Device, Index, Allocator >::setSize | ( | IndexType | size | ) |

Method for setting the array size.

This method behaves almost like resize, but when the array size is changed, old elements are not copied to the new memory location. Hence, this is a shortcut for deallocating the array with resize(0) followed by setting the new size with resize(size)

Parameters

  size | The new size of the array.

## ◆ setValue()

template<typename Value, typename Device = Devices::Host, typename Index = int, typename Allocator = typename Allocators::Default< Device >::template Allocator< Value >>

void TNL::Containers::Array< Value, Device, Index, Allocator >::setValue | ( | ValueType | value,
|  | IndexType | begin = 0,
|  | IndexType | end = 0 )

Sets elements of the array to given value.

By default, all array elements are set to the given value. If begin or end is set to a non-zero value, only elements in the sub-interval [begin, end) are set.

Parameters

  value | The new value for the array elements.
  begin | The beginning of the array sub-interval. It is 0 by default.
  end | The end of the array sub-interval. The default value is 0 which is, however, replaced with the array size.

## ◆ swap()

template<typename Value, typename Device = Devices::Host, typename Index = int, typename Allocator = typename Allocators::Default< Device >::template Allocator< Value >>

void TNL::Containers::Array< Value, Device, Index, Allocator >::swap | ( | Array< Value, Device, Index, Allocator > & | array | ) |
| noexcept

Swaps this array with another.

Swapping is done in a shallow way, i.e. only pointers and sizes are swapped.

Parameters

  array | The array to be swapped with this array.

The documentation for this class was generated from the following file:

- src/TNL/Containers/Array.h