xtd::index Struct Reference

Inheritance diagram for xtd::index:

Definition

Represents a type that can be used to index a collection either from the beginning or the end.

class index : public xtd::object, xtd::iequatable<index>;

Header

#include <xtd/range>

Namespace

xtd

Library

xtd.core

Examples

The following example demonstrates how to use xtd::index with xtd::collections::generic::list.

#include <xtd/xtd>
 
auto main() -> int {
  auto items = list {1, 2, 3, 4, 5, 6, 7, 8, 9, 10};
  
  xtd::println("items[xtd::index::from_start(0)] = {}", items[xtd::index::from_start(0)]);
  xtd::println("items(xtd::index {{1, false}}) = {}", items(xtd::index {1, false}));
  xtd::println("items[xtd::index {{2}}] = {}", items[xtd::index {2}]);
  xtd::println("items(xtd::index {{~3, true}}) = {}", items(xtd::index {~3, true}));
  xtd::println("items[xtd::index {{4}}] = {}", items[xtd::index {4}]);
  xtd::println("items(xtd::index {{5}}) = {}", items(xtd::index {5}));
  xtd::println("items[xtd::index {{6}}] = {}", items[xtd::index {6}]);
  xtd::println("items(xtd::index {{7}}) = {}", items(xtd::index {7}));
  xtd::println("items[xtd::index {{8}}] = {}", items[xtd::index {8}]);
  xtd::println("items(xtd::index::from_start(9)) = {}", items(xtd::index::from_start(9)));
  xtd::println();
  xtd::println("items[xtd::index::from_end(1)] = {}", items[xtd::index::from_end(1)]);
  xtd::println("items(xtd::index {{2}}, true)) = {}", items(xtd::index {2, true}));
  xtd::println("items[xtd::index {{~3}}] = {}", items[xtd::index {~3}]);
  xtd::println("items(xtd::index {{~4, false}}) = {}", items(xtd::index {~4, false}));
  xtd::println("items[xtd::index {{~5}}] = {}", items[xtd::index {~5}]);
  xtd::println("items(xtd::index {{~6}}) = {}", items(xtd::index {~6}));
  xtd::println("items[xtd::index {{~7}}] = {}", items[xtd::index {~7}]);
  xtd::println("items(xtd::index {{~8}}) = {}", items(xtd::index {~8}));
  xtd::println("items[xtd::index {{~9}}] = {}", items[xtd::index {~9}]);
  xtd::println("items(xtd::index::from_end(10)) = {}", items(xtd::index::from_end(10)));
}
 
// This code produces the following output :
//
// items[xtd::index::from_start(0)] = 1
// items(xtd::index {1, false}) = 2
// items[xtd::index {2}] = 3
// items(xtd::index {~3, true}) = 4
// items[xtd::index {4}] = 5
// items(xtd::index {5}) = 6
// items[xtd::index {6}] = 7
// items(xtd::index {7}) = 8
// items[xtd::index {8}] = 9
// items(xtd::index::from_start(9)) = 10
 
//
// items[xtd::index::from_end(1)] = 10
// items(xtd::index {2, true}) = 9
// items[xtd::index {~3}] = 8
// items(xtd::index {~4, false}) = 7
// items[xtd::index {~5}] = 6
// items(xtd::index {~6}) = 5
// items[xtd::index {~7}] = 4
// items(xtd::index {~8}) = 3
// items[xtd::index {~9}] = 2
// items(xtd::index::from_end(10)) = 1

The following example demonstrates how to use index literal operator.

#include <xtd/xtd>
 
auto main() -> int {
  auto items = list {1, 2, 3, 4, 5, 6, 7, 8, 9, 10};
  
  println(R"(items["0"_i] = {})", items["0"_i]);
  println("items(1_i) = {}", items(1_i));
  println(R"(items[u8"(2"_i] = {})", items[u8"2"_i]);
  println("items(3_i) = {}", items(3_i));
  println("items[4_i] = {}", items[4_i]);
  println("items(5_i) = {}", items(5_i));
  println("items[6_i] = {}", items[6_i]);
  println("items(7_i) = {}", items(7_i));
  println("items[8_i] = {}", items[8_i]);
  println(R"(items(u"9"_i) = {})", items(u"9"_i));
  println();
  println(R"(items["~1"_i] = {})", items["~1"_i]);
  println("items(~2_i) = {}", items(~2_i));
  println(R"(items[U"~3"_i] = {})", items[U"~3"_i]);
  println("items(~4_i) = {}", items(~4_i));
  println("items[~5_i] = {}", items[~5_i]);
  println("items(~6_i) = {}", items(~6_i));
  println("items[~7_i] = {}", items[~7_i]);
  println("items(~8_i) = {}", items(~8_i));
  println("items[~9_i] = {}", items[~9_i]);
  println(R"(items(L"~10"_i) = {})", items(L"~10"_i));
}
 
// This code produces the following output :
//
// items["0"_i] = 1
// items(1_i) = 2
// items[u8"2"_i] = 3
// items(3_i) = 4
// items[4_i] = 5
// items(5_i) = 6
// items[6_i] = 7
// items(7_i) = 8
// items[8_i] = 9
// items(u"9"_i) = 10
//
// items["~1"_i] = 10
// items(~2_i) = 9
// items[U"~3"_i] = 8
// items(~4_i) = 7
// items[~5_i] = 6
// items(~6_i) = 5
// items[~7_i] = 4
// items(~8_i) = 3
// items[~9_i] = 2
// items(L"~10"_i) = 1

The following example shows how to create your own collection with xtd::index operator.

#include <xtd/xtd>
 
struct persona {
  string name;
  int age;
  
  auto to_string() const noexcept -> string {return string::format("persona {{{}, {}}}", name, age);}
};
 
class persona_collection {
public:
  persona_collection() = default;
  persona_collection(std::initializer_list<persona> items) : items_ {items} {}
 
  auto to_string() const noexcept -> string {return string::format("[{}]", string::join(", ", items_));}
  
  auto operator [](usize index) -> persona& {return items_[index];}
  auto operator [](usize index) const -> const persona& {return items_[index];}
  auto operator [](xtd::index index) -> persona& {return operator [](index.get_offset(items_.count()));}
  auto operator [](xtd::index index) const -> const persona& {return operator [](index.get_offset(items_.count()));}
 
private:
  list<persona> items_;
};
 
auto main() -> int {
  auto items = persona_collection {{.name = "Oliver Queen", .age = 24}, {.name = "Laurel Lance", .age = 23}, {.name = "John \"Dig\" Diggle", .age = 27}, {.name = "Thea Queen", .age = 20}, {.name = "Felicity Smoak", .age = 22}};
  
  println("items = {}", items);
  
  println();
  println("items[0_i] = {}", items[0_i]);
  println("items[2] = {}", items[2]);
  println("items[~1_i] = {}", items[~1_i]);
  
  println();
  println("items[1_i] = {}", items[1_i]);
  items[1_i].age = 24;
  println("items[1_i] (updated) = {}", items[1_i]);
}
 
// This code produces the following output :
//
// items = [persona {Oliver Queen, 24}, persona {Laurel Lance, 23}, persona {John "Dig" Diggle, 27}, persona {Thea Queen, 20}, persona {Felicity Smoak, 22}]
//
// items[0_i] = persona {Oliver Queen, 24}
// items[2] = persona {John "Dig" Diggle, 27}
// items[~1_i] = persona {Felicity Smoak, 22}
//
// items[1_i] = persona {Laurel Lance, 23}
// items[1_i] (updated) = persona {Laurel Lance, 24}

Examples

index.cpp.

Public Aliases
using	value_type
	Represents the xtd::index index type.

Public Static Properties
static const index	end
	Represents a value that is not a valid position in a collection.
static const index	last
	Represents the index of the last valid element in a collection.
static const index	start
	Represents the index of the first valid element in a collection.

Public Constructors
constexpr	index () noexcept=default
	Instantiates a new xtd::index instance.
constexpr	index (xtd::integer auto value, xtd::logical auto from_end) noexcept
	Initializes a new xtd::index with a specified index position and a value that indicates if the index is from the beginning or the end of a collection.
constexpr	index (xtd::integer auto value) noexcept
	Initializes a new xtd::index with a specified index position and a value that indicates if the index is from the beginning or the end of a collection.

Public Properties
constexpr auto	value () const noexcept -> value_type
	Gets an xtd::index that represents the exclusive end index of the range.
constexpr auto	is_from_end () const noexcept -> bool
	Gets a value that indicates whether the index is from the start or the end.

Public Methods
auto	equals (const object &obj) const noexcept -> bool override
	Determines whether the specified object is equal to the current object.
auto	equals (const index &value) const noexcept -> bool override
	Indicates whether the current object is equal to another object of the same type.
auto	get_hash_code () const noexcept -> xtd::usize override
	Serves as a hash function for a particular type.
auto	get_offset (value_type length) const noexcept -> xtd::usize
	Calculates the offset from the start of the collection using the specified collection length.
auto	to_string () const noexcept -> xtd::string override
	Returns the string representation of the current Range object.
constexpr auto	to_usize () const noexcept -> value_type
	Returns the xtd::usize representation of the current Range object.

Public Static Methods
static constexpr auto	from_end (xtd::integer auto value)
	Creates an xtd::ndex from the end of a collection at a specified index position.
static constexpr auto	from_start (xtd::integer auto value)
	Creates an xtd::ndex from the start of a collection at a specified index position.
static auto	parse (const xtd::string &value) -> xtd::index
	Converts the string to xtd::index equivalent.
static auto	try_parse (const xtd::string &value, xtd::index &result) noexcept -> bool
	Converts the string to xtd::index equivalent. A return value indicates whether the conversion succeeded or failed.

Additional Inherited Members
	object ()=default
	Create a new instance of the ultimate base class object.
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.
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.

Member Typedef Documentation

value_type

using xtd::index::value_type

Represents the xtd::index index type.

Constructor & Destructor Documentation

index() [1/3]

xtd::index::index ( )

constexprdefaultnoexcept

Instantiates a new xtd::index instance.

index() [2/3]

xtd::index::index ( xtd::integer auto value, xtd::logical auto from_end )

inlineconstexprnoexcept

Initializes a new xtd::index with a specified index position and a value that indicates if the index is from the beginning or the end of a collection.

Parameters

value	The index value. It has to be greater then or equal to zero.
from_end	true to index from the end of the collection, or false to index from the beginning of the collection.

Remarks

If the xtd::index is constructed from the end, an index value of 1 points to the last element, and an index value of 0 points beyond the last element.

index() [3/3]

xtd::index::index ( xtd::integer auto value )

inlineexplicitconstexprnoexcept

Initializes a new xtd::index with a specified index position and a value that indicates if the index is from the beginning or the end of a collection.

Parameters

value

The index value. It has to be greater then or equal to zero.

Remarks

If the xtd::index is constructed from the end, an index value of 1 points to the last element, and an index value of 0 points beyond the last element.

Member Function Documentation

value()

auto xtd::index::value ( ) const -> value_type

inlinenodiscardconstexprnoexcept

Gets an xtd::index that represents the exclusive end index of the range.

Returns

The end index of the range.

is_from_end()

auto xtd::index::is_from_end ( ) const -> bool

inlinenodiscardconstexprnoexcept

Gets a value that indicates whether the index is from the start or the end.

Returns

true if the xtd::index is from the end; otherwise, false.

equals() [1/2]

auto xtd::index::equals ( const object & obj ) const -> bool

nodiscardoverridevirtualnoexcept

Determines whether the specified object is equal to the current object.

Parameters

obj	The object to compare with the current object.

Returns

true if the specified object is equal to the current object. otherwise, false.

Reimplemented from xtd::object.

equals() [2/2]

auto xtd::index::equals ( const index & value ) const -> bool

nodiscardoverridevirtualnoexcept

Indicates whether the current object is equal to another object of the same type.

Parameters

obj	An object to compare with this object.

Returns

true if the current object is equal to the other parameter; otherwise, false.

Implements xtd::iequatable< index >.

get_hash_code()

auto xtd::index::get_hash_code ( ) const -> xtd::usize

nodiscardoverridevirtualnoexcept

Serves as a hash function for a particular type.

Returns

A hash code for the current object.

Reimplemented from xtd::object.

get_offset()

auto xtd::index::get_offset ( value_type length ) const -> xtd::usize

nodiscardnoexcept

Calculates the offset from the start of the collection using the specified collection length.

Parameters

length

The length of the collection that the xtd::index will be used with. Must be a positive value.

Returns

The offset.

to_string()

auto xtd::index::to_string ( ) const -> xtd::string

nodiscardoverridevirtualnoexcept

Returns the string representation of the current Range object.

Returns

The string representation of the range.

Reimplemented from xtd::object.

to_usize()

auto xtd::index::to_usize ( ) const -> value_type

inlinenodiscardconstexprnoexcept

Returns the xtd::usize representation of the current Range object.

Returns

The xtd::usize representation of the range.

from_end()

constexpr auto xtd::index::from_end ( xtd::integer auto value )

inlinestaticconstexpr

Creates an xtd::ndex from the end of a collection at a specified index position.

Parameters

value

The index value from the end of a collection.

Returns

The index value.

Examples

index.cpp.

from_start()

constexpr auto xtd::index::from_start ( xtd::integer auto value )

inlinestaticconstexpr

Creates an xtd::ndex from the start of a collection at a specified index position.

Parameters

value

The index value from the start of a collection.

Returns

The index value.

Examples

index.cpp.

parse()

auto xtd::index::parse ( const xtd::string & value ) -> xtd::index

staticnodiscard

Converts the string to xtd::index equivalent.

Parameters

value

A string containing a xtd::index to convert.

Returns

A xtd::index equivalent to the native value contained in value.

try_parse()

auto xtd::index::try_parse ( const xtd::string & value, xtd::index & result ) -> bool

staticnodiscardnoexcept

Converts the string to xtd::index equivalent. A return value indicates whether the conversion succeeded or failed.

Parameters

value	A string containing a xtd::index to convert.
result	A xtd::index equivalent to the native value contained in value.

Returns

true if s was converted successfully; otherwise, false.

Member Data Documentation

end

const index xtd::index::end

static

Represents a value that is not a valid position in a collection.

Remarks

This constant is typically used to indicate the absence of an index or a failed search operation. It is equivalent to the maximum value of xtd::usize.

The xtd::index::end is equivalent to ~0_i. With bitwise operator the code is more concise.

Examples

auto items = array {10, 20, 30, 40};
if (items.index_of(50) == index::end)
  console::write_line("Value not found");

The wollowing exemple shows the same example with bitwise operator as index.

auto items = array {10, 20, 30, 40};
if (items.index_of(50) == ~0_i)
  console::write_line("Value not found");

Examples

xtd_collection_indexer.cpp.

last

const index xtd::index::last

static

Represents the index of the last valid element in a collection.

Remarks

Unlike xtd::index::end (which means "no position"), xtd::index::last points to the last accessible element of a collection. It is equivalent to items.count() - 1.

Note

This constant is provided for readability and convenience. For example, items[xtd::index::last] directly accesses the last element without manually subtracting one from the collection count.

Remarks

The xtd::index::last is equivalent to ~1_i. With bitwise operator the code is more concise.

Examples

auto items = array {10, 20, 30, 40};
console::write_line(items[index::last]); // Prints 40
console::write_line(items[index::last - 1]); // Prints 30

The wollowing exemple shows the same example with bitwise operator as index.

auto items = array {10, 20, 30, 40};
console::write_line(items[~1_i]); // Prints 40
console::write_line(items[~2_i]); // Prints 30

Examples

xtd_collection_indexer.cpp.

start

const index xtd::index::start

static

Represents the index of the first valid element in a collection.

Remarks

Unlike xtd::index::end (which means "no position"), xtd::index::start points to the first accessible element of a collection. It is equivalent to 0.

Note

This constant is provided for readability and convenience. For example, items[xtd::index::start] directly accesses the fist element.

Remarks

The xtd::index::start is equivalent to 0. With 0 the code is more concise.

Examples

auto items = array {10, 20, 30, 40};
println(items[index::start]); // Prints 10
println(items[index::start + 1]); // Prints 20

The wollowing exemple shows the same example without index.

auto items = array {10, 20, 30, 40};
console::write_line(items[0]); // Prints 10
console::write_line(items[1]); // Prints 20

Examples

xtd_collection_indexer.cpp.

---

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

• xtd.core/include/xtd/index.hpp