xtd::array< type_t, rank_, allocator_t > Class Template Reference

Inheritance diagram for xtd::array< type_t, rank_, allocator_t >:

Definition

template<typename type_t, xtd::usize rank_, typename allocator_t>
class xtd::array< type_t, rank_, allocator_t >

Provides methods for creating, manipulating, searching, and sorting arrays, thereby serving as the base class for all arrays.

Definition

template<typename type_t, xtd::usize rank_, typename allocator_t>
class array : public xtd::basic_array<type_t, allocator_t>;

Header

#include <xtd/array>

Namespace

xtd

Library

xtd.core

Remarks

The xtd::array class is not part of the xtd::collections namespaces. However, it is still considered a collection because it is based on the xtd::collections::generic::ilist interface.

An element is a value in an xtd::array. The length of an xtd::array is the total number of elements it can contain. The lower bound of an v is the index of its first element. An xtd::array can have any lower bound, but it has a lower bound of zero by default. A different lower bound can be defined when creating an instance of the xtd::array class using xtd::array::create_instance. A multidimensional xtd::array can have different bounds for each dimension. An array can have a maximum of 32 dimensions.

Unlike the classes in the xtd::collections namespaces, xtd::array has a fixed capacity. To increase the capacity, you must create a new xtd::array object with the required capacity, copy the elements from the old xtd::array object to the new one, and delete the old xtd::array.

The xtd::array class implements the xtd::collections::generic::ilist, xtd::collections::generic::icollection, and xtd::collections::generic::ienumerable generic interfaces. The implementations are provided to arrays at run time, and as a result, the generic interfaces do not appear in the declaration syntax for the xtd::array class. In addition, there are no reference topics for interface members that are accessible only by casting an array to the generic interface type (explicit interface implementations). The key thing to be aware of when you cast an array to one of these interfaces is that members which add, insert, or remove elements throw xtd::not_supported_exception.

The xtd::array::copy method copies elements not only between arrays of the same type but also between standard arrays of different types; it handles type casting automatically.

Some methods, such as xtd::array::create_instance, xtd::array::copy, xtd::array::copy_to, xtd::array::get_value, and xtd::array::set_value, provide overloads that accept 64-bit integers as parameters to accommodate large capacity arrays. xtd::array::long_length and xtd::array::get_long_length return 64-bit integers indicating the length of the array.

The xtd::array is not guaranteed to be sorted. You must sort the xtd::array prior to performing operations (such as xtd::array::binary_search) that require the xtd::array to be sorted.

Examples

The following code example demonstrates different methods to create an array.

Examples

The following code example creates and initializes an Array and displays its properties and its elements.

#include <xtd/xtd>
 
auto print_values(const array<int>& my_arr) {
  for (auto i : my_arr)
    console::write("\t{}", i);
  console::write_line();
}
 
auto print_values(const array<any_object>& my_arr) {
  for (auto o : my_arr)
    console::write("\t{}", o);
  console::write_line();
}
 
auto main() -> int {
  // Creates and initializes a new integer array and a new Object array.
  auto my_int_array = array<int> {1, 2, 3, 4, 5};
  auto my_obj_array = array<any_object> {26, 27, 28, 29, 30};
  
  // Prints the initial values of both arrays.
  console::write_line("Initially,");
  console::write("integer array:");
  print_values(my_int_array);
  console::write("Object array: ");
  print_values(my_obj_array);
  
  // Copies the first two elements from the integer array to the Object array.
  array<>::copy(my_int_array, my_obj_array, 2);
  
  // Prints the values of the modified arrays.
  console::write_line("\nAfter copying the first two elements of the integer array to the Object array,");
  console::write("integer array:");
  print_values(my_int_array);
  console::write("Object array: ");
  print_values(my_obj_array);
  
  // Copies the last two elements from the object array to the integer array.
  xtd::array<>::copy(my_obj_array, my_obj_array.get_upper_bound(0) - 1, my_int_array, my_int_array.get_upper_bound(0) - 1, 2);
  
  // Prints the values of the modified arrays.
  console::write_line("\nAfter copying the last two elements of the Object array to the integer array,");
  console::write("integer array:");
  print_values(my_int_array);
  console::write("Object array: ");
  print_values(my_obj_array);
}
 
// This code produces the following output :
//
// Initially,
// integer array:  1  2  3  4  5
// Object array:   26  27  28  29  30
//
// After copying the first two elements of the integer array to the Object array,
// integer array:  1  2  3  4  5
// Object array:   1  2  28  29  30
//
// After copying the last two elements of the Object array to the integer array,
// integer array:  1  2  3  29  30
// Object array:   1  2  28  29  30

Examples

date_time_format_info.cpp, date_time_now.cpp, form_paint.cpp, graphics.cpp, and ienumerable.cpp.

Public Aliases
using	value_type
	Represents the array value type.
using	allocator_type
	Represents the array allocator type.
using	base_type
	Represents the array base type.
using	size_type
	Represents the array size type (usually xtd::usize).
using	difference_type
	Represents the array difference type (usually xtd::ptrdiff).
using	reference
	Represents the reference of array value type.
using	const_reference
	Represents the const reference of array value type.
using	pointer
	Represents the pointer of array value type.
using	const_pointer
	Represents the const pointer of array value type.
using	iterator
	Represents the iterator of array value type.
using	const_iterator
	Represents the const iterator of array value type.
using	reverse_iterator
	Represents the reverse iterator of array value type.
using	const_reverse_iterator
	Represents the const reverse iterator of array value type.

Public Constructors
	array ()=default
	Initializes a new instance of the array class that is empty.
	array (const array &array)
	Copy constructor with specified array.
	array (array &&array)
	Move constructor with specified array.
	array (const array< xtd::usize, 1 > &lengths)
	Initializes a new instance of the array class with lengths for each rank specified.
	array (const array< xtd::usize, 1 > &lengths, const type_t &value)
	Initializes a new instance of the array class with lengths for each rank specified.
	array (const xtd::collections::generic::ienumerable< type_t > &enumerable)
	Initializes a new instance of the array and copy array array specified.
	array (const xtd::collections::generic::ilist< type_t > &listlist)
	Initializes a new instance of the array and copy array array specified.
template<typename input_iterator_t>
	array (input_iterator_t first, input_iterator_t last)
	Constructs the container with the contents of the range [first, last).
	array (std::initializer_list< type_t > items)
	Constructs the container with the contents of the specified initializer list.

Public Properties
xtd::usize	rank () const noexcept override
	Gets the rank (number of dimensions) of the array.

Public Methods
xtd::string	to_string () const noexcept override
	Returns a xtd::string that represents the current object.

Public Operators
array &	operator= (const array &)=default
	Copy assignment operator. Replaces the contents with a copy of the contents of other.
array &	operator= (array &&)=default
	Move assignment operator. Replaces the contents with those of other using move semantics (i.e. the data in other is moved from other into this container). other is in a valid but unspecified state afterwards.

Additional Inherited Members
using	value_type
	Represents the array value type.
using	allocator_type
	Represents the array allocator type.
using	base_type
	Represents the array base type.
using	size_type
	Represents the array size type (usually xtd::usize).
using	difference_type
	Represents the array difference type (usually xtd::ptrdiff).
using	reference
	Represents the reference of array value type.
using	const_reference
	Represents the const reference of array value type.
using	pointer
	Represents the pointer of array value type.
using	const_pointer
	Represents the const pointer of array value type.
using	iterator
	Represents the iterator of array value type.
using	const_iterator
	Represents the const iterator of array value type.
using	reverse_iterator
	Represents the reverse iterator of array value type.
using	const_reverse_iterator
	Represents the const reverse iterator of array value type.
using	value_type
	Represents the xtd::collections::generic::icollection value type.
using	value_type
	Represents the xtd::collections::generic::ienumerable value type.
using	iterator
	Represents the iterator of xtd::collections::generic::ienumerable value type.
using	const_iterator
	Represents the const iterator of xtd::collections::generic::ienumerable value type.
using	iterator
	Represents the iterator of enumerable value type.
using	const_iterator
	Represents the const iterator of enumerable value type.
using	enumerable_type
	Represents the ienumerable enumerable type.
using	source_type
	Represents the ienumerable source type.
using	ienumerable
	Represents the ienumerable value type.
using	list
	Represents the list value type.
static constexpr xtd::usize	npos
	Represents a value that is not a valid position in a collection.
static constexpr xtd::usize	bpos
	Represents the index of the first valid element in a collection.
static constexpr xtd::usize	epos
	Represents the index of the last valid element in a collection.
auto	count () const noexcept -> size_type override
	Gets the number of elements contained in the xtd::array <type_t>.
virtual auto	data () noexcept -> pointer
	Returns pointer to the underlying array serving as element storage.
auto	is_fixed_size () const noexcept -> bool override
	Gets a value indicating whether the xtd::collections::generic::ilist <type_t> has a fixed size.
auto	is_read_only () const noexcept -> bool override
	Gets a value indicating whether the xtd::collections::generic::icollection <type_t> is read-only.
auto	is_synchronized () const noexcept -> bool override
	Gets a value indicating whether access to the xtd::collections::generic::icollection <type_t> is synchronized (thread safe).
virtual auto	items () const noexcept -> const base_type &
	Returns the underlying base type items.
virtual auto	length () const noexcept -> size_type
	Gets a size that represents the total number of elements in all the dimensions of the array.
virtual auto	long_length () -> xtd::int64
	Gets a 64-bit integer that represents the total number of elements in all the dimensions of the array.
virtual auto	max_length () const noexcept -> size_type
	Returns the maximum number of elements the container is able to hold due to system or library implementation limitations, i.e. std::distance(xtd::array::begin(), xtd::array::end()) for the largest container.
auto	sync_root () const noexcept -> const xtd::object &override
	Gets an object that can be used to synchronize access to the the xtd::collections::generic::icollection <type_t>.
auto	contains (const type_t &value) const noexcept -> bool override
	Determines whether an element is in the array.
auto	copy_to (xtd::array< type_t > &array) const -> void
	Copies the entire xtd::array <type_t> to a compatible one-dimensional array.
auto	equals (const object &obj) const noexcept -> bool override
	Determines whether this instance and a specified object, which must also be a xtd::basic_array object, have the same value.
virtual auto	fill (const value_type &value) noexcept -> void
	Assigns the value to all elements in the container.
auto	get_enumerator () const noexcept -> xtd::collections::generic::enumerator< value_type > override
	Returns an enumerator that iterates through a collection.
constexpr auto	get_length (size_type dimension) const -> size_type
	Gets the total number of elements in all the dimensions of the array.
auto	get_lengths () const -> xtd::array< size_type, 1 >
	Gets an array of the number of elements of all the dimensions of the array.
constexpr auto	get_long_length (size_type dimension) const -> xtd::int64
	Gets a 64-bit integer that represents the total number of elements in all the dimensions of the array.
constexpr auto	get_lower_bound (size_type dimension) const -> size_type
	Gets the lower bound of the specified dimension in the array.
constexpr auto	get_upper_bound (size_type dimension) const -> size_type
	Gets the upper bound of the specified dimension in the array.
auto	get_value (const xtd::array< size_type > &indexes) const -> const value_type &
	Gets the value at the specified position in the multidimensional array. The indexes are specified as 32-bit integers array.
auto	index_of (const type_t &value) const noexcept -> size_type override
	Determines the index of a specific item in the xtd::array <type_t>.
auto	set_value (const type_t &value, const xtd::array< size_type > &indexes) -> void
	Determines the index of a specific item in the xtd::basic_array <type_t>.
auto	sort () -> basic_array< type_t > &
	Sorts the elements in the entire xtd::basic_array <type_t> using the default comparer.
auto	to_string () const noexcept -> xtd::string override
	Returns a xtd::string that represents the current object.
auto	operator= (const basic_array &other) -> basic_array &
	Copy assignment operator. Replaces the contents with a copy of the contents of other.
auto	operator[] (size_type index) const -> const_reference override
	Returns a reference to the element at specified location index.
	operator const base_type & () const noexcept
	Returns a reference to the underlying base type.
	operator base_type & () noexcept
	Returns a reference to the underlying base type.
auto	operator() (const xtd::array< size_type > &indexes) -> type_t &
	Gets the value at the specified position in the multidimensional array. The indexes are specified as a 32-bit integer array.
	object ()=default
	Create a new instance of the ultimate base class object.
virtual auto	get_hash_code () const noexcept -> xtd::usize
	Serves as a hash function for a particular type.
virtual auto	get_type () const noexcept -> type_object
	Gets the type of the current instance.
template<typename object_t>
auto	memberwise_clone () const -> xtd::unique_ptr_object< object_t >
	Creates a shallow copy of the current object.
virtual auto	copy_to (xtd::array< type_t > &array, xtd::usize array_index) const -> void=0
	Copies the elements of the xtd::collections::generic::icollection <type_t> to an xtd::array, starting at a particular xtd::array index.
virtual auto	operator[] (xtd::usize index) -> type_t &=0
	Sets the element at the specified index.
virtual auto	begin () const -> const_iterator
	Returns an iterator to the first element of the enumerable.
virtual auto	cbegin () const -> const_iterator
	Returns an iterator to the first element of the enumerable.
virtual auto	cend () const -> const_iterator
	Returns an iterator to the element following the last element of the enumerable.
virtual auto	end () const -> const_iterator
	Returns an iterator to the element following the last element of the enumerable.
auto	aggregate (const std::function< type_t(const type_t &, const type_t &)> &funcfunc) const -> type_t
	Applies an accumulator function over a sequence.
auto	all (const std::function< bool(const type_t &)> &predicatepredicate) const -> bool
	Determines whether all elements of a sequence satisfy a condition.
auto	any () const noexcept -> bool
	Determines whether a sequence contains any elements.
auto	append (const type_t &element) const noexcept
	Appends a value to the end of the sequence.
auto	as_enumerable () const noexcept
	Returns the input typed as xtd::collections::generic::ienumerable <type_t>.
auto	average () const noexcept
	Computes the average of a sequence of source_t values.
auto	cast () const noexcept
	Casts the elements of an xtd::collections::generic::ienumerable to the specified type.
auto	chunk (xtd::usize size) const
	Splits the elements of a sequence into chunks of size at most size.
auto	concat (const ienumerable< type_t > &second) const noexcept
	Concatenates two sequences.
auto	contains (const type_t &value) const noexcept -> bool
	Determines whether a sequence contains a specified element by using the default equality comparer.
auto	count () const noexcept -> xtd::usize
	Returns the number of elements in current sequence.
auto	count_by (const std::function< key_t(const type_t &)> &key_selector) const noexcept
	Returns the count of elements in the current sequence grouped by key.
auto	default_if_empty () const noexcept
	Returns the elements of the specified sequence or the type parameter's default value in a singleton collection if the current sequence is empty.
auto	distinct () const noexcept
	Returns distinct elements from a sequence by using the default equality comparer to compare values.
auto	first_or_default (const std::function< bool(const type_t &)> &predicatepredicate, const type_t &default_value) const noexcept -> type_t
	Returns the first element of the sequence that satisfies a condition, or a specified default value if no such element is found.
auto	order () const
	Sorts the elements of a sequence in ascending order.
auto	order_by (const std::function< type_t(const type_t &)> &key_selector) const
	Sorts the elements of a sequence in ascending order according to a key.
auto	order_by_descending (const std::function< key_t(const type_t &)> &key_selector) const
	Sorts the elements of a sequence in descending order according to a key.
auto	select (auto &&selector) const
	Projects each element of a sequence into a new form.
auto	to_array () const noexcept -> xtd::array< type_t >
	Creates a xtd::array <type_t> from an xtd::collections::generic::ienumerable <type_t>.
auto	to_list () const noexcept -> xtd::collections::generic::list< type_t >
	Creates a xtd::collections::generic::list <type_t> from an xtd::collections::generic::ienumerable <type_t>.
auto	where (auto &&predicatepredicate) const
	Filters a sequence of values based on a predicate.
virtual auto	empty () const noexcept -> bool
	Checks whether the container is empty.
virtual auto	size () const noexcept -> xtd::usize
	Gets the number of elements contained in the xtd::collections::generic::icollection <type_t>.
virtual auto	operator<< (const type_t &item) -> icollection< type_t > &
	The shift left operator adds an item to the xtd::collections::generic::icollection <type_t>.
virtual auto	operator>> (const type_t &item) -> icollection< type_t > &
	The shift right operator removes the first occurrence of a specific object from the xtd::collections::generic::icollection <type_t>.
virtual auto	equals (const type_t &) const noexcept -> bool=0
	Indicates whether the current object is equal to another object of the same type.
template<typename object_a_t, typename object_b_t>
static auto	equals (const object_a_t &object_a, const object_b_t &object_b) noexcept -> bool
	Determines whether the specified object instances are considered equal.
template<typename object_a_t, typename object_b_t>
static auto	reference_equals (const object_a_t &object_a, const object_b_t &object_b) noexcept -> bool
	Determines whether the specified object instances are the same instance.
static auto	to_const_iterator (typename source_collection_t::const_iterator &value, const source_collection_t &source_collection, const target_collection_t &target_collection) noexcept -> typename target_collection_t::const_iterator
	Converts source iterator to target iterator.
static auto	to_iterator (typename source_collection_t::const_iterator &value, const source_collection_t &source_collection, const target_collection_t &target_collection) noexcept -> typename target_collection_t::const_iterator
	Converts source iterator to target iterator.
	abstract_object ()=default
	Initializes a new instance of the xtd::abstract_object class.

Member Typedef Documentation

value_type

template<typename type_t, xtd::usize rank_, typename allocator_t>

using xtd::array< type_t, rank_, allocator_t >::value_type

Represents the array value type.

allocator_type

template<typename type_t, xtd::usize rank_, typename allocator_t>

using xtd::array< type_t, rank_, allocator_t >::allocator_type

Represents the array allocator type.

base_type

template<typename type_t, xtd::usize rank_, typename allocator_t>

using xtd::array< type_t, rank_, allocator_t >::base_type

Represents the array base type.

size_type

template<typename type_t, xtd::usize rank_, typename allocator_t>

using xtd::array< type_t, rank_, allocator_t >::size_type

Represents the array size type (usually xtd::usize).

difference_type

template<typename type_t, xtd::usize rank_, typename allocator_t>

using xtd::array< type_t, rank_, allocator_t >::difference_type

Represents the array difference type (usually xtd::ptrdiff).

reference

template<typename type_t, xtd::usize rank_, typename allocator_t>

using xtd::array< type_t, rank_, allocator_t >::reference

Represents the reference of array value type.

const_reference

template<typename type_t, xtd::usize rank_, typename allocator_t>

using xtd::array< type_t, rank_, allocator_t >::const_reference

Represents the const reference of array value type.

pointer

template<typename type_t, xtd::usize rank_, typename allocator_t>

using xtd::array< type_t, rank_, allocator_t >::pointer

Represents the pointer of array value type.

const_pointer

template<typename type_t, xtd::usize rank_, typename allocator_t>

using xtd::array< type_t, rank_, allocator_t >::const_pointer

Represents the const pointer of array value type.

iterator

template<typename type_t, xtd::usize rank_, typename allocator_t>

using xtd::array< type_t, rank_, allocator_t >::iterator

Represents the iterator of array value type.

const_iterator

template<typename type_t, xtd::usize rank_, typename allocator_t>

using xtd::array< type_t, rank_, allocator_t >::const_iterator

Represents the const iterator of array value type.

reverse_iterator

template<typename type_t, xtd::usize rank_, typename allocator_t>

using xtd::array< type_t, rank_, allocator_t >::reverse_iterator

Represents the reverse iterator of array value type.

const_reverse_iterator

template<typename type_t, xtd::usize rank_, typename allocator_t>

using xtd::array< type_t, rank_, allocator_t >::const_reverse_iterator

Represents the const reverse iterator of array value type.

Constructor & Destructor Documentation

array() [1/9]

template<typename type_t, xtd::usize rank_, typename allocator_t>

xtd::array< type_t, rank_, allocator_t >::array ( )

default

Initializes a new instance of the array class that is empty.

Remarks

The array class is not thread safe.

Examples

The following code example demonstrates different methods to create an array.

array() [2/9]

template<typename type_t, xtd::usize rank_, typename allocator_t>

xtd::array< type_t, rank_, allocator_t >::array ( const array< type_t, rank_, allocator_t > & array )

inline

Copy constructor with specified array.

Parameters

array

The xtd::array which elements will be inserted from.

array() [3/9]

template<typename type_t, xtd::usize rank_, typename allocator_t>

xtd::array< type_t, rank_, allocator_t >::array ( array< type_t, rank_, allocator_t > && array )

inline

Move constructor with specified array.

Parameters

array

The xtd::array which elements will be inserted from.

array() [4/9]

template<typename type_t, xtd::usize rank_, typename allocator_t>

xtd::array< type_t, rank_, allocator_t >::array ( const array< xtd::usize, 1 > & lengths )

inlineexplicit

Initializes a new instance of the array class with lengths for each rank specified.

Parameters

lengths

the lengths for each rank.

Remarks

The array class is not thread safe.

Examples

The following code example demonstrates different methods to create an array.

array() [5/9]

template<typename type_t, xtd::usize rank_, typename allocator_t>

xtd::array< type_t, rank_, allocator_t >::array ( const array< xtd::usize, 1 > & lengths, const type_t & value )

inline

Initializes a new instance of the array class with lengths for each rank specified.

Parameters

lengths

the lengths for each rank.

Remarks

The array class is not thread safe.

Examples

The following code example demonstrates different methods to create an array.

array() [6/9]

template<typename type_t, xtd::usize rank_, typename allocator_t>

xtd::array< type_t, rank_, allocator_t >::array ( const xtd::collections::generic::ienumerable< type_t > & enumerable )

inlineexplicit

Initializes a new instance of the array and copy array array specified.

Parameters

array

the array to copy.

Remarks

The array class is not thread safe.

Examples

The following code example demonstrates different methods to create an array.

array() [7/9]

template<typename type_t, xtd::usize rank_, typename allocator_t>

xtd::array< type_t, rank_, allocator_t >::array ( const xtd::collections::generic::ilist< type_t > & list )

inlineexplicit

Initializes a new instance of the array and copy array array specified.

Parameters

array

the array to copy.

Remarks

The array class is not thread safe.

Examples

The following code example demonstrates different methods to create an array.

array() [8/9]

template<typename type_t, xtd::usize rank_, typename allocator_t>

template<typename input_iterator_t>

xtd::array< type_t, rank_, allocator_t >::array ( input_iterator_t first, input_iterator_t last )

inline

Constructs the container with the contents of the range [first, last).

Parameters

first	The first iterator the range to copy the elements from.
last	The last iterator the range to copy the elements from.

array() [9/9]

template<typename type_t, xtd::usize rank_, typename allocator_t>

xtd::array< type_t, rank_, allocator_t >::array ( std::initializer_list< type_t > items )

inline

Constructs the container with the contents of the specified initializer list.

Parameters

items

The initializer list to initialize the elements of the container with.

Member Function Documentation

rank()

template<typename type_t, xtd::usize rank_, typename allocator_t>

xtd::usize xtd::array< type_t, rank_, allocator_t >::rank ( ) const

inlineoverridevirtualnoexcept

Gets the rank (number of dimensions) of the array.

Returns

The rank (number of dimensions) of the array.

Examples

The following code example demonstrates methods to get the rank of an array.

Reimplemented from xtd::basic_array< type_t, allocator_t >.

to_string()

template<typename type_t, xtd::usize rank_, typename allocator_t>

xtd::string xtd::array< type_t, rank_, allocator_t >::to_string ( ) const

overridevirtualnoexcept

Returns a xtd::string that represents the current object.

Returns

A string that represents the current object.

Reimplemented from xtd::object.

operator=() [1/2]

template<typename type_t, xtd::usize rank_, typename allocator_t>

array & xtd::array< type_t, rank_, allocator_t >::operator= ( const array< type_t, rank_, allocator_t > & )

default

Copy assignment operator. Replaces the contents with a copy of the contents of other.

Parameters

other

Another container to use as data source.

Returns

This current instance.

operator=() [2/2]

template<typename type_t, xtd::usize rank_, typename allocator_t>

array & xtd::array< type_t, rank_, allocator_t >::operator= ( array< type_t, rank_, allocator_t > && )

default

Move assignment operator. Replaces the contents with those of other using move semantics (i.e. the data in other is moved from other into this container). other is in a valid but unspecified state afterwards.

Parameters

other

Another base type container to use as data source.

Returns

This current instance.

---

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

• xtd.core/include/xtd/array.hpp