xtd 0.2.0
xtd::array<> Class Reference
Inheritance diagram for xtd::array<>:
xtd::basic_array< type_t, allocator_t > xtd::static_object xtd::array_abstract_object xtd::iequatable< basic_array< type_t, allocator_t > > xtd::abstract_object xtd::interface xtd::extensions::equality_operators< type_t, iequatable< type_t > > xtd::object

Definition

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

Definition
template<class type_t, xtd::size rank_, class allocator_t>
class array : public xtd::basic_array<type_t, allocator_t>;
array()=default
Base object that represent array.
Definition basic_array.hpp:44
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/any_object>
#include <xtd/array>
#include <xtd/console>
using namespace xtd;
auto print_values(const array<int>& my_arr) {
for (auto i : my_arr)
console::write("\t{}", i);
}
auto print_values(const array<any_object>& my_arr) {
for (auto o : my_arr)
console::write("\t{}", o);
}
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
static void copy(const array< source_type_t, source_rank, source_allocator_t > &source_array, const array< destination_type_t, destination_rank, destination_allocator_t > &destination_array, xtd::size length)
Copies a range of elements from an xtd::array starting at the first element and pastes them into anot...
Definition array_static.hpp:196
Provides methods for creating, manipulating, searching, and sorting arrays, thereby serving as the ba...
Definition array.hpp:61
static void write(arg_t &&value)
Writes the text representation of the specified value to the standard output stream.
Definition console.hpp:462
static void write_line()
Writes the current line terminator to the standard output stream using the specified format informati...
@ i
The I key.
Definition console_key.hpp:104
@ o
The O key.
Definition console_key.hpp:116
The xtd namespace contains all fundamental classes to access Hardware, Os, System,...
Definition abstract_object.hpp:8

Public Static Methods

template<class type_t, class allocator_t>
static xtd::collections::object_model::read_only_collection< type_t > as_read_only (const xtd::array< type_t, 1, allocator_t > &array)
 Returns a read-only wrapper for the specified array.
 
template<class type_t, class allocator_t>
static int32 binary_search (const array< type_t, 1, allocator_t > &array, int32 index, int32 length, const type_t &value)
 Searches a range of elements in a one-dimensional sorted array for a value, using the xtd::icomparable interface implemented by each element of the array and by the specified value.
 
template<class type_t, class allocator_t>
static xtd::size binary_search (const array< type_t, 1, allocator_t > &array, xtd::size index, xtd::size count, const type_t &value, const xtd::collections::generic::icomparer< type_t > &comparer)
 Searches a range of elements in a one-dimensional sorted array for a value, using the specified xtd::icomparer interface.
 
template<class type_t, class allocator_t>
static xtd::size binary_search (const array< type_t, 1, allocator_t > &array, const type_t &value)
 Searches an entire one-dimensional sorted array for a specific element, using the xtd::icomparable interface implemented by each element of the array and by the specified object.
 
template<class type_t, class allocator_t>
static xtd::size binary_search (const array< type_t, 1, allocator_t > &array, const type_t &value, const xtd::collections::generic::icomparer< type_t > &comparer)
 Searches a range of elements in a one-dimensional sorted array for a value, using the specified xtd::icomparer interface.
 
template<class type_t, xtd::size rank, class allocator_t>
static void clear (const array< type_t, rank, allocator_t > &array)
 Clears the contents of an array.
 
template<class type_t, xtd::size rank, class allocator_t>
static void clear (const array< type_t, rank, allocator_t > &array, xtd::size index, xtd::size length)
 Sets a range of elements in an array to the default value of each element type.
 
template<class source_type_t, xtd::size source_rank, class source_allocator_t, class destination_type_t, xtd::size destination_rank, class destination_allocator_t>
static void copy (const array< source_type_t, source_rank, source_allocator_t > &source_array, const array< destination_type_t, destination_rank, destination_allocator_t > &destination_array, xtd::size length)
 Copies a range of elements from an xtd::array starting at the first element and pastes them into another xtd::array starting at the first element. The length is specified as an xtd::size.
 
template<class source_type_t, xtd::size source_rank, class source_allocator_t, class destination_type_t, xtd::size destination_rank, class destination_allocator_t>
static void copy (const array< source_type_t, source_rank, source_allocator_t > &source_array, xtd::size source_index, const array< destination_type_t, destination_rank, destination_allocator_t > &destination_array, xtd::size destination_index, xtd::size length)
 Copies a range of elements from an xtd::array starting at the specified source index and pastes them to another xtd::array starting at the specified destination index. The length and the indexes are specified as 64-bit integers.
 

Public Constructors

 array ()=default
 Initializes a new instance of the array class that is empty.
 
 array (const array< xtd::size, 1 > &lengths)
 Initializes a new instance of the array class with lengths for each rank specified.
 

Public Properties

xtd::size rank () const noexcept override
 Gets the rank (number of dimensions) of the array.
 

Public Operators

arrayoperator= (const array &)=default
 
arrayoperator= (array &&)=default
 

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::size).
 
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.
 
static constexpr size_type npos
 This is a special value equal to the maximum value representable by the type xtd::size.
 
virtual reference back ()
 Returns a reference to the last element in the container.
 
virtual const_reference back () const
 Returns a reference to the last element in the container.
 
const_iterator begin () const noexcept override
 Returns an iterator to the first element of the enumerable.
 
iterator begin () noexcept override
 Returns an iterator to the first element of the enumerable.
 
const_iterator cbegin () const noexcept override
 Returns an iterator to the first element of the enumerable.
 
const_iterator cend () const noexcept override
 Returns an iterator to the element following the last element of the enumerable.
 
size_type count () const noexcept override
 Gets the number of elements contained in the xtd::array <type_t>.
 
virtual const_reverse_iterator crbegin () const noexcept
 Returns a reverse iterator to the first element of the reversed vector. It corresponds to the last element of the non-reversed vector. If the vector is empty, the returned iterator is equal to xtd::array::rend().
 
virtual const_reverse_iterator crend () const noexcept
 Returns a reverse iterator to the element following the last element of the reversed vector. It corresponds to the element preceding the first element of the non-reversed vector. This element acts as a placeholder, attempting to access it results in undefined behavior.
 
virtual pointer data () noexcept
 Returns pointer to the underlying array serving as element storage.
 
virtual const_pointer data () const noexcept
 Returns pointer to the underlying array serving as element storage.
 
virtual bool empty () const noexcept
 Checks if the container has no elements, i.e. whether xtd::array::begin() == xtd::array::end().
 
const_iterator end () const noexcept override
 Returns an iterator to the element following the last element of the enumerable.
 
iterator end () noexcept override
 Returns an iterator to the element following the last element of the enumerable.
 
virtual reference front ()
 Returns a reference to the first element in the container.
 
virtual const_reference front () const
 Returns a reference to the first element in the container.
 
bool is_fixed_size () const noexcept override
 
bool is_read_only () const noexcept override
 
bool is_synchronized () const noexcept override
 
virtual const base_typeitems () const noexcept
 Returns the underlying base type items.
 
virtual base_typeitems () noexcept
 Returns the underlying base type items.
 
virtual size_type length () const noexcept
 Gets a size that represents the total number of elements in all the dimensions of the array.
 
virtual xtd::int64 long_length ()
 Gets a 64-bit integer that represents the total number of elements in all the dimensions of the array.
 
virtual size_type max_size () const noexcept
 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.
 
virtual reverse_iterator rbegin () noexcept
 Returns a reverse iterator to the first element of the reversed vector. It corresponds to the last element of the non-reversed vector. If the vector is empty, the returned iterator is equal to xtd::array::rend().
 
virtual const_reverse_iterator rbegin () const noexcept
 Returns a reverse iterator to the first element of the reversed vector. It corresponds to the last element of the non-reversed vector. If the vector is empty, the returned iterator is equal to xtd::array::rend().
 
virtual reverse_iterator rend () noexcept
 Returns a reverse iterator to the element following the last element of the reversed vector. It corresponds to the element preceding the first element of the non-reversed vector. This element acts as a placeholder, attempting to access it results in undefined behavior.
 
virtual const_reverse_iterator rend () const noexcept
 Returns a reverse iterator to the element following the last element of the reversed vector. It corresponds to the element preceding the first element of the non-reversed vector. This element acts as a placeholder, attempting to access it results in undefined behavior.
 
virtual size_type size () const noexcept
 Returns the number of elements in the container, i.e. std::distance(xtd::array::begin(), xtd::array::end()).
 
const xtd::objectsync_root () const noexcept override
 
virtual reference at (size_type index)
 Returns a reference to the element at specified location pos, with bounds checking.
 
virtual const_reference at (size_type index) const
 Returns a reference to the element at specified location pos, with bounds checking.
 
bool contains (const type_t &value) const noexcept override
 Determines whether an element is in the array.
 
void copy_to (xtd::array< type_t > &array, size_type index) const override
 
void copy_to (xtd::array< type_t > &array, xtd::int64 index) const
 Copies all the elements of the current one-dimensional array to the specified one-dimensional array starting at the specified destination array index. The index is specified as a 64-bit integer.
 
bool equals (const object &obj) const noexcept override
 Determines whether the specified object is equal to the current object.
 
bool equals (const basic_array &rhs) const noexcept override
 
virtual void fill (const value_type &value) noexcept
 Assigns the value to all elements in the container.
 
xtd::collections::generic::enumerator< value_typeget_enumerator () const noexcept override
 
constexpr size_type get_length (size_type dimension) const
 Gets the total number of elements in all the dimensions of the array.
 
constexpr xtd::int64 get_long_length (size_type dimension) const
 Gets a 64-bit integer that represents the total number of elements in all the dimensions of the array.
 
constexpr size_type get_lower_bound (size_type dimension) const
 Gets the lower bound of the specified dimension in the array.
 
constexpr size_type get_upper_bound (size_type dimension) const
 Gets the upper bound of the specified dimension in the array.
 
const value_typeget_value (const xtd::array< size_type > &indexes) const
 Gets the value at the specified position in the multidimensional array. The indexes are specified as 32-bit integers array.
 
size_type index_of (const type_t &value) const noexcept override
 Determines the index of a specific item in the xtd::array <type_t>.
 
void resize (size_type new_size, value_type value)
 Resizes the container to contain count elements, does nothing if count == size(). / @param new_size The new size of the container. / @exception xtd::argument_out_of_range_exception Ifnew_sizeis outside greather than xtd::array::max_size. / @remarks If the current size is greater thancount, the container is reduced to its firstcountelements. / @remarks If the current size is less thancount`, additional default-inserted elements are appended. void resize(size_type new_size) {resize(new_size, value_type {});}.
 
void set_value (const type_t &value, const xtd::array< size_type > &indexes)
 Sets a value to the element at the specified position in the multidimensional array.
 
virtual void swap (basic_array &other) noexcept
 Exchanges the contents and capacity of the container with those of other. Does not invoke any move, copy, or swap operations on individual elements.
 
xtd::string to_string () const noexcept override
 Returns a xtd::string that represents the current object.
 
basic_arrayoperator= (const basic_array &other)
 Copy assignment operator. Replaces the contents with a copy of the contents of other.
 
basic_arrayoperator= (basic_array &&other) noexcept=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.
 
basic_arrayoperator= (std::initializer_list< type_t > &items)
 Replaces the contents with those identified by initializer list ilist.
 
const_reference operator[] (size_type index) const override
 Returns a reference to the element at specified location index.
 
reference operator[] (size_type index) 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.
 
type_t & operator() (const xtd::array< size_type > &indexes)
 Gets the value at the specified position in the multidimensional array. The indexes are specified as a 32-bit integer array.
 
const type_t & operator() (const xtd::array< size_type > &indexes) const
 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 xtd::size get_hash_code () const noexcept
 Serves as a hash function for a particular type.
 
virtual type_object get_type () const noexcept
 Gets the type of the current instance.
 
template<class object_t>
xtd::unique_ptr_object< object_t > memberwise_clone () const
 Creates a shallow copy of the current object.
 
virtual bool equals (const type_t &) const noexcept=0
 Indicates whether the current object is equal to another object of the same type.
 
static size_type index_of (const basic_array &array, const value_type &value) noexcept
 Determines the index of a specific item in the array specified.
 
static size_type index_of (const basic_array &array, const value_type &value, size_type index)
 Determines the index of a specific item in the array specified.
 
static size_type index_of (const basic_array &array, const value_type &value, size_type index, size_type count)
 Determines the index of a specific item in the array specified.
 
static void reverse (basic_array &array) noexcept
 Reverses the order of the elements in the entire xtd::basic_array.
 
static void reverse (basic_array &array, size_type index, size_type count)
 Reverses the order of the elements in the specified range.
 
template<class object_a_t, class object_b_t>
static bool equals (const object_a_t &object_a, const object_b_t &object_b) noexcept
 Determines whether the specified object instances are considered equal.
 
template<class object_a_t, class object_b_t>
static bool reference_equals (const object_a_t &object_a, const object_b_t &object_b) noexcept
 Determines whether the specified object instances are the same instance.
 
 abstract_object ()=default
 Initializes a new instance of the xtd::abstract_object class.
 

Constructor & Destructor Documentation

◆ array() [1/2]

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/2]

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

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

Parameters
lengthsthe lengths for each rank.
Remarks
The array class is not thread safe.
Examples
The following code example demonstrates different methods to create an array.

Member Function Documentation

◆ as_read_only()

template<class type_t, class allocator_t>
static xtd::collections::object_model::read_only_collection< type_t > xtd::array<>::as_read_only ( const xtd::array< type_t, 1, allocator_t > & array)
static

Returns a read-only wrapper for the specified array.

Parameters
arrayThe one-dimensional, zero-based array to wrap in a read-only xtd::collections::object_model::read_only_collection<type_t> wrapper.
Returns
A read-only xtd::collections::object_model::read_only_collection<type_t> wrapper for the specified array.
Remarks
To prevent any modifications to the array, expose the array only through this wrapper.
A collection that is read-only is simply a collection with a wrapper that prevents modifying the collection; therefore, if changes are made to the underlying collection, the read-only collection reflects those changes.
This method is an O(n) operation.
Examples
The following example wraps an array in a read-only xtd::collections::object_model::read_only_collection<type_t>.
#include <xtd/array>
#include <xtd/as>
#include <xtd/console>
#include <xtd/not_supported_exception>
using namespace xtd;
using namespace xtd::collections::generic;
auto print_index_and_values(const array<string>& my_arr) {
for (auto i = 0_z; i < my_arr.length(); ++i)
console::write_line(" [{0}] : {1}", i, my_arr[i]);
}
auto print_index_and_values(const ilist<string>& my_list) {
for (auto i = 0_z; i < my_list.count(); ++i)
console::write_line( " [{0}] : {1}", i, my_list[i]);
}
auto main() -> int {
// Create and initialize a new string array.
auto my_arr = array<string> {"The", "quick", "brown", "fox"};
// Display the values of the array.
console::write_line("The string array initially contains the following values:");
print_index_and_values(my_arr);
// Create a read-only ilist wrapper around the array.
auto my_list = array<>::as_read_only(my_arr);
// Display the values of the read-only ilist.
console::write_line("The read-only ilist contains the following values:");
print_index_and_values(my_list);
// Attempt to change a value through the wrapper.
try {
my_list[3] = "CAT";
} catch (const not_supported_exception& e) {
console::write_line("{} - {}", e.get_type(), e.message());
}
// Change a value in the original array.
my_arr[2] = "RED";
// Display the values of the array.
console::write_line("After changing the third element, the string array contains the following values:");
print_index_and_values( my_arr );
// Display the values of the read-only ilist.
console::write_line("After changing the third element, the read-only ilist contains the following values:");
print_index_and_values(my_list);
}
// This code produces the following output :
//
// The string array initially contains the following values:
// [0] : The
// [1] : quick
// [2] : brown
// [3] : fox
//
// The read-only ilist contains the following values:
// [0] : The
// [1] : quick
// [2] : brown
// [3] : fox
//
// xtd::not_supported_exception - Collection is read-only.
//
// After changing the third element, the string array contains the following values:
// [0] : The
// [1] : quick
// [2] : RED
// [3] : fox
//
// After changing the third element, the read-only ilist contains the following values:
// [0] : The
// [1] : quick
// [2] : RED
// [3] : fox
//
static xtd::collections::object_model::read_only_collection< type_t > as_read_only(const xtd::array< type_t, 1, allocator_t > &array)
Returns a read-only wrapper for the specified array.
virtual size_type length() const noexcept
Gets a size that represents the total number of elements in all the dimensions of the array.
Definition basic_array.hpp:209
The exception that is thrown when an invoked method is not supported, or when there is an attempt to ...
Definition not_supported_exception.hpp:18
@ e
The E key.
Definition console_key.hpp:96
The xtd::collections::generic namespace contains interfaces and classes that define generic collectio...
Definition comparer.hpp:16

◆ binary_search() [1/4]

template<class type_t, class allocator_t>
static int32 xtd::array<>::binary_search ( const array< type_t, 1, allocator_t > & array,
int32 index,
int32 length,
const type_t & value )
inlinestatic

Searches a range of elements in a one-dimensional sorted array for a value, using the xtd::icomparable interface implemented by each element of the array and by the specified value.

Parameters
arrayThe sorted one-dimensional array to search.
indexThe starting index of the range to search.
lengthThe length of the range to search.
valueThe object to search for.
Returns
int32 The index of the specified value in the specified array, if value is found; otherwise, a negative number. If value is not found and value is less than one or more elements in array, the negative number returned is the bitwise complement of the index of the first element that is larger than value. If value is not found and value is greater than all elements in array, the negative number returned is the bitwise complement of (the index of the last element plus 1). If this method is called with a non-sorted array, the return value can be incorrect and a negative number could be returned, even if value is present in array.
Exceptions
xtd::rank_exceptionarray is multidimensional.
xtd::argument_out_of_range_exceptionindex is less than the lower bound of array.
-or-<bre> length is less than zero.
xtd::argument_exceptionindex and length do not specify a valid range in array.
-or-<bre> value is of a type that is not compatible with the elements of array.
xtd::invalid_operation_exceptionvalue does not implement the xtd::icomparable interface, and the search encounters an element that does not implement the xtd::icomparable interface.
Remarks
This method does not support searching arrays that contain negative indexes. array must be sorted before calling this method.
If the array does not contain the specified value, the method returns a negative integer. You can apply the bitwise complement operator ~ to the negative result to produce an index. If this index is one greater than the upper bound of the array, there are no elements larger than value in the array. Otherwise, it is the index of the first element that is larger than value.
Either value or every element of array must implement the xtd::icomparable interface, which is used for comparisons. The elements of array must already be sorted in increasing value according to the sort order defined by the xtd::icomparable implementation; otherwise, the result might be incorrect.
Note
If value does not implement the xtd::icomparable interface, the elements of array are not tested for xtd::icomparable before the search begins. An exception is thrown if the search encounters an element that does not implement xtd::icomparable.
Remarks
Duplicate elements are allowed. If the array contains more than one element equal to value, the method returns the index of only one of the occurrences, and not necessarily the first one.
null can always be compared with any other reference type; therefore, comparisons with null do not generate an exception.
Note
For every element tested, value is passed to the appropriate xtd::icomparable implementation, even if value is null. That is, the xtd::icomparable implementation determines how a given element compares to null.
Remarks
This method is an O(log n) operation, where n is length.

◆ binary_search() [2/4]

template<class type_t, class allocator_t>
static xtd::size xtd::array<>::binary_search ( const array< type_t, 1, allocator_t > & array,
xtd::size index,
xtd::size count,
const type_t & value,
const xtd::collections::generic::icomparer< type_t > & comparer )
inlinestatic

Searches a range of elements in a one-dimensional sorted array for a value, using the specified xtd::icomparer interface.

Parameters
arrayThe sorted one-dimensional array to search.
indexThe starting index of the range to search.
lengthThe length of the range to search.
valueThe object to search for.
comparerThe xtd::icomparer implementation to use when comparing elements.
-or-<bre> null to use the xtd::icomparable implementation of each element.
Returns
int32 The index of the specified value in the specified array, if value is found; otherwise, a negative number. If value is not found and value is less than one or more elements in array, the negative number returned is the bitwise complement of the index of the first element that is larger than value. If value is not found and value is greater than all elements in array, the negative number returned is the bitwise complement of (the index of the last element plus 1). If this method is called with a non-sorted array, the return value can be incorrect and a negative number could be returned, even if value is present in array.
Exceptions
xtd::rank_exceptionarray is multidimensional.
xtd::argument_out_of_range_exceptionindex is less than the lower bound of array.
-or-<bre> length is less than zero.
xtd::argument_exceptionindex and length do not specify a valid range in array.
-or-<bre> value is of a type that is not compatible with the elements of array.
xtd::invalid_operation_exceptionvalue does not implement the xtd::icomparable interface, and the search encounters an element that does not implement the xtd::icomparable interface.
Remarks
This method does not support searching arrays that contain negative indexes. array must be sorted before calling this method.
If the array does not contain the specified value, the method returns a negative integer. You can apply the bitwise complement operator ~ to the negative result to produce an index. If this index is one greater than the upper bound of the array, there are no elements larger than value in the array. Otherwise, it is the index of the first element that is larger than value.
The comparer customizes how the elements are compared. For example, you can use a xtd::collections::case_insensitive_comparer as the comparer to perform case-insensitive string searches.
If comparer is not null, the elements of array are compared to the specified value using the specified xtd::icomparer implementation. The elements of array must already be sorted in increasing value according to the sort order defined by comparer; otherwise, the result might be incorrect.
If comparer is null, the comparison is done using the xtd::icomparable implementation provided by the element itself or by the specified value. The elements of array must already be sorted in increasing value according to the sort order defined by the xtd::icomparable implementation; otherwise, the result might be incorrect.
Note
If comparer is null and value does not implement the xtd::icomparable interface, the elements of array are not tested for xtd::icomparable before the search begins. An exception is thrown if the search encounters an element that does not implement xtd::icomparable.
Remarks
Duplicate elements are allowed. If the array contains more than one element equal to value, the method returns the index of only one of the occurrences, and not necessarily the first one.
null can always be compared with any other reference type; therefore, comparisons with null do not generate an exception when using xtd::icomparable.
Note
For every element tested, value is passed to the appropriate xtd::icomparable implementation, even if value is null. That is, the xtd::icomparable implementation determines how a given element compares to null.
Remarks
This method is an O(log n) operation, where n is length.

◆ binary_search() [3/4]

template<class type_t, class allocator_t>
static xtd::size xtd::array<>::binary_search ( const array< type_t, 1, allocator_t > & array,
const type_t & value )
inlinestatic

Searches an entire one-dimensional sorted array for a specific element, using the xtd::icomparable interface implemented by each element of the array and by the specified object.

Parameters
arrayThe sorted one-dimensional array to search.
valueThe object to search for.
Returns
int32 The index of the specified value in the specified array, if value is found; otherwise, a negative number. If value is not found and value is less than one or more elements in array, the negative number returned is the bitwise complement of the index of the first element that is larger than value. If value is not found and value is greater than all elements in array, the negative number returned is the bitwise complement of (the index of the last element plus 1). If this method is called with a non-sorted array, the return value can be incorrect and a negative number could be returned, even if value is present in array.
Exceptions
xtd::rank_exceptionarray is multidimensional.
xtd::argument_exceptionvalue is of a type that is not compatible with the elements of array.
xtd::invalid_operation_exceptionvalue does not implement the xtd::icomparable interface, and the search encounters an element that does not implement the xtd::icomparable interface.
Remarks
This method does not support searching arrays that contain negative indexes. array must be sorted before calling this method.
If the array does not contain the specified value, the method returns a negative integer. You can apply the bitwise complement operator ~ to the negative result to produce an index. If this index is one greater than the upper bound of the array, there are no elements larger than value in the array. Otherwise, it is the index of the first element that is larger than value.
Either value or every element of array must implement the xtd::icomparable interface, which is used for comparisons. The elements of array must already be sorted in increasing value according to the sort order defined by the xtd::icomparable implementation; otherwise, the result might be incorrect.
Note
Ifvalue does not implement the xtd::icomparable interface, the elements of array are not tested for xtd::icomparable before the search begins. An exception is thrown if the search encounters an element that does not implement xtd::icomparable.
Remarks
Duplicate elements are allowed. If the array contains more than one element equal to value, the method returns the index of only one of the occurrences, and not necessarily the first one.
null can always be compared with any other reference type; therefore, comparisons with null do not generate an exception.
Note
For every element tested, value is passed to the appropriate xtd::icomparable implementation, even if value is null. That is, the xtd::icomparable implementation determines how a given element compares to null.
Remarks
This method is an O(log n) operation, where n is the Length of array.

◆ binary_search() [4/4]

template<class type_t, class allocator_t>
static xtd::size xtd::array<>::binary_search ( const array< type_t, 1, allocator_t > & array,
const type_t & value,
const xtd::collections::generic::icomparer< type_t > & comparer )
inlinestatic

Searches a range of elements in a one-dimensional sorted array for a value, using the specified xtd::icomparer interface.

Parameters
arrayThe sorted one-dimensional array to search.
valueThe object to search for.
comparerThe xtd::icomparer implementation to use when comparing elements.
-or-<bre> null to use the xtd::icomparable implementation of each element.
Returns
int32 The index of the specified value in the specified array, if value is found; otherwise, a negative number. If value is not found and value is less than one or more elements in array, the negative number returned is the bitwise complement of the index of the first element that is larger than value. If value is not found and value is greater than all elements in array, the negative number returned is the bitwise complement of (the index of the last element plus 1). If this method is called with a non-sorted array, the return value can be incorrect and a negative number could be returned, even if value is present in array.
Exceptions
xtd::rank_exceptionarray is multidimensional.
xtd::argument_out_of_range_exceptionindex is less than the lower bound of array.
-or-<bre> length is less than zero.
xtd::argument_exceptionindex and length do not specify a valid range in array.
-or-<bre> value is of a type that is not compatible with the elements of array.
xtd::invalid_operation_exceptionvalue does not implement the xtd::icomparable interface, and the search encounters an element that does not implement the xtd::icomparable interface.
Remarks
This method does not support searching arrays that contain negative indexes. array must be sorted before calling this method.
If the array does not contain the specified value, the method returns a negative integer. You can apply the bitwise complement operator ~ to the negative result to produce an index. If this index is one greater than the upper bound of the array, there are no elements larger than value in the array. Otherwise, it is the index of the first element that is larger than value.
The comparer customizes how the elements are compared. For example, you can use a xtd::collections::case_insensitive_comparer as the comparer to perform case-insensitive string searches.
If comparer is not null, the elements of array are compared to the specified value using the specified xtd::icomparer implementation. The elements of array must already be sorted in increasing value according to the sort order defined by comparer; otherwise, the result might be incorrect.
If comparer is null, the comparison is done using the xtd::icomparable implementation provided by the element itself or by the specified value. The elements of array must already be sorted in increasing value according to the sort order defined by the xtd::icomparable implementation; otherwise, the result might be incorrect.
Note
If comparer is null and value does not implement the xtd::icomparable interface, the elements of array are not tested for xtd::icomparable before the search begins. An exception is thrown if the search encounters an element that does not implement xtd::icomparable.
Remarks
Duplicate elements are allowed. If the array contains more than one element equal to value, the method returns the index of only one of the occurrences, and not necessarily the first one.
null can always be compared with any other reference type; therefore, comparisons with null do not generate an exception when using xtd::icomparable.
Note
For every element tested, value is passed to the appropriate xtd::icomparable implementation, even if value is null. That is, the xtd::icomparable implementation determines how a given element compares to null.
Remarks
This method is an O(log n) operation, where n is length.

◆ clear() [1/2]

template<class type_t, xtd::size rank, class allocator_t>
static void xtd::array<>::clear ( const array< type_t, rank, allocator_t > & array)
inlinestatic

Clears the contents of an array.

Parameters
arrayThe array to clear.

◆ clear() [2/2]

template<class type_t, xtd::size rank, class allocator_t>
static void xtd::array<>::clear ( const array< type_t, rank, allocator_t > & array,
xtd::size index,
xtd::size length )
inlinestatic

Sets a range of elements in an array to the default value of each element type.

Parameters
arrayThe array whose elements need to be cleared.
indexThe starting index of the range of elements to clear.
lengthThe number of elements to clear.
Exceptions
xtd::index_out_of_range_exceptionThe sum of `index` and `length` is greater than the size of array.
Examples
The following example uses the xtd::array::clear method to reset integer values in a one-dimensional, two-dimensional, and three-dimensional array.

◆ copy() [1/2]

template<class source_type_t, xtd::size source_rank, class source_allocator_t, class destination_type_t, xtd::size destination_rank, class destination_allocator_t>
static void xtd::array<>::copy ( const array< source_type_t, source_rank, source_allocator_t > & source_array,
const array< destination_type_t, destination_rank, destination_allocator_t > & destination_array,
xtd::size length )
inlinestatic

Copies a range of elements from an xtd::array starting at the first element and pastes them into another xtd::array starting at the first element. The length is specified as an xtd::size.

Parameters
source_arrayThe xtd::array that contains the data to copy.
destination_arrayThe xtd::rray that receives the data.
lengthAn xtd::size that represents the number of elements to copy.
Exceptions
xtd::argument_out_of_range_exceptionThe `length` is greater than `source_array` size.<ber>-or-
The `length` is greater than `destination_array` size.

◆ copy() [2/2]

template<class source_type_t, xtd::size source_rank, class source_allocator_t, class destination_type_t, xtd::size destination_rank, class destination_allocator_t>
static void xtd::array<>::copy ( const array< source_type_t, source_rank, source_allocator_t > & source_array,
xtd::size source_index,
const array< destination_type_t, destination_rank, destination_allocator_t > & destination_array,
xtd::size destination_index,
xtd::size length )
static

Copies a range of elements from an xtd::array starting at the specified source index and pastes them to another xtd::array starting at the specified destination index. The length and the indexes are specified as 64-bit integers.

Parameters
source_arrayThe xtd::rray that contains the data to copy.
source_indexAn xtd::size that represents the index in source_array at which copying begins.
destination_arrayThe xtd::array that receives the data.
destination_indexAn xtd::size that represents the index in destination_array at which storing begins.
lengthAn xtd::size that represents the number of elements to copy.
Exceptions
xtd::argument_out_of_range_exceptionThe sum of the `source_index` and `length` is greater than `source_array` size.<ber>-or-
The sum of the `destination_index` and `length` is greater than `destination_array` size.

◆ rank()

xtd::size 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 >.


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