xtd::collections::generic Namespace Reference

Definition

The xtd::collections::generic namespace contains interfaces and classes that define generic collections, which allow users to create strongly typed collections that provide better type safety and performance than non-generic strongly typed collections.

Namespaces
namespace	extensions
	The xtd::extensions namespace contains interface extensions.
namespace	helpers
	The xtd::collections::generic::helpers namespace contains helpers for generic collections, sush as comparer, equator an hasher structs.

Classes
class	comparer
	Provides a base class for implementations of the xtd::collections::generic::icomparer <type_t> generic interface. More...
class	dictionary
	Represents a collection of keys and values. More...
class	empty_comparer
	Provides an empty comparer class. More...
class	enumerable_generator
	Represents an enumerable enumerable_generator. More...
struct	enumerator
	Supports a simple iteration over a generic collection. More...
struct	enumerator<>
	Supports a simple iteration over a generic collection. More...
class	equality_comparer
	Provides a base class for implementations of the xtd::collections::generic::iequality_comparer <type_t> generic interface. More...
class	hash_set
	Represents a set of values. More...
class	icomparer
	Exposes a method that compares two objects. More...
class	idictionary
	Represents a generic collection of key/value pairs. More...
class	ienumerable
	Exposes the enumerator, which supports a simple iteration over a collection of a specified type. More...
class	ienumerable_abstract
	Abstract object that represent ienumerable. More...
class	ienumerator
	Supports a simple iteration over a generic collection. More...
class	iequality_comparer
	Defines methods to support the comparison of objects for equality. More...
class	iset
	Provides the base interface for the abstraction of sets. More...
class	key_not_found_exception
	The exception that is thrown when the key specified for accessing an element in a collection does not match any key in the collection. More...
struct	key_value_pair
	Defines a key/value pair that can be set or retrieved. More...
struct	key_value_pair< >
	Defines a key/value pair that can be set or retrieved. More...
class	linked_list
	Represents a doubly linked list. More...
class	linked_list_node
	Represents a node in a LinkedList<T>. This class cannot be inherited. More...
class	list
	Represents a strongly typed list of objects that can be accessed by index. Provides methods to search, sort, and manipulate lists. More...
class	ordered_dictionary
	Represents a collection of key/value pairs that are accessible by the key or index. More...
class	queue
	Represents a first-in, first-out collection of objects. More...
class	stack
	Represents a variable size last-in-first-out (LIFO) collection of instances of the same specified type. More...

Alias
template<xtd::collections::generic::enumerable enumerable_type>
using	enumerable_value_type
	Represents the enumerable value type.
template<class key_t, class value_t, class lesser_t = helpers::lesser<key_t>, class allocator_t = helpers::allocator<std::pair<const key_t, value_t >>>
using	sorted_dictionary
	Represents a collection of key/value pairs that are sorted on the key.
template<class key_t, class value_t, class allocator_t = helpers::allocator<std::pair<const key_t, value_t>>>
using	sorted_list
	Represents a collection of key/value pairs that are sorted by the keys and are accessible by key and by index.
template<class type_t, class lesser_t = xtd::collections::generic::helpers::lesser<type_t>, class allocator_t = xtd::collections::generic::helpers::allocator<type_t >>
using	sorted_set
	Represents a collection of objects that is maintained in sorted order.

Public Aliases
Defines methods to manipulate generic collections. Definition template<class type_t> class icollection : public xtd::collections::generic::ienumerable<type_t>, public xtd::collections::generic::extensions::collection_common<type_t, icollection<type_t>>; Header #include <xtd/collections/generic/icollection> Namespace xtd::collections::generic Library xtd.core Examples The following example implements the xtd::collections::generic::icollection <type_t> interface to create a collection of custom box objects named box_collection. Each box has height, length, and width properties, which are used to define equality. Equality can be defined as all dimensions being the same or the volume being the same. The box class implements the xtd::iequatable <type_t> interface to define the default equality as the dimensions being the same. The box_collection class implements the xtd::collections::generic::icollection::contains method to use the default equality to determine whether a box is in the collection. This method is used by the xtd::collections::generic::icollection::add method so that each box added to the collection has a unique set of dimensions. The box_collection class also provides an overload of the xtd::collections::generic::icollection::contains method that takes a specified xtd::collections::generic::iequality_comparer <type_t> interface, such as box_same_dimensions and box_same_volume` classes in the example. This example also implements an xtd::collections::generic::ienumerator <type_t> interface for the box_collection class so that the collection can be enumerated. #include <xtd/xtd> class program { public: static auto main() -> void { auto boxes = box_collection {}; boxes.add(program::box {10, 4, 6}); boxes.add(program::box {4, 6, 10}); boxes.add(program::box {6, 10, 4}); boxes.add(program::box {12, 8, 10}); // Same dimensions. Cannot be added: boxes.add(program::box {10, 4, 6}); // Test the Remove method. display(boxes); console::write_line("Removing 6x10x4"); boxes.remove(program::box {6, 10, 4}); display(boxes); // Test the Contains method. auto box_check = program::box {8, 12, 10}; console::write_line("Contains {}x{}x{} by dimensions: {}", box_check.height, box_check.length, box_check.width, boxes.contains(box_check)); // Test the Contains method overload with a specified equality comparer. console::write_line("Contains {}x{}x{} by volume: {}", box_check.height, box_check.length, box_check.width, boxes.contains(box_check, box_same_volume {})); } struct box : public object, public iequatable<program::box> { // Public Constructors : box() = default; box(int h, int l, int w) : height {h}, length{l}, width {w} {} // Public Properties : int height = 0; int length = 0; int width = 0; // Public Methods : bool equals(const object& o) const noexcept override {return is<program::box>(o) && equals(as<program::box>(o));} bool equals(const program::box& o) const noexcept override {return box_same_dimensions {}.equals(*this, o);} }; class box_collection : public icollection<program::box> { public: // Public Constructors : box_collection(const std::initializer_list<program::box>& boxes) : boxes_(boxes) {} // Public Properties : xtd::size count() const noexcept override {return boxes_.count();} bool is_read_only() const noexcept override {return false;} bool is_synchronized() const noexcept override {return false;} const object& sync_root() const noexcept override {return sync_root_;} // Public Methods : void add(const program::box& item) override { if (!contains(item)) boxes_.add(item); else console::write_line("A box with {}x{}x{} dimensions was already added to the collection.", item.height, item.length, item.width); } void clear() override {boxes_.clear();} bool contains(const program::box& item) const noexcept override {return boxes_.contains(item);} bool contains(const program::box& item, const iequality_comparer<program::box>& comparer) const noexcept { for (auto box : boxes_) if (comparer.equals(box, item)) return true; return false; } void copy_to(array<program::box>& array, xtd::size array_index) const override {boxes_.copy_to(array, array_index);} enumerator<program::box> get_enumerator() const override {return {new_ptr<box_enumerator>(boxes_)};} bool remove(const program::box& item) override {return boxes_.remove(item);} private: list<program::box> boxes_; object sync_root_; }; class box_enumerator : public ienumerator<program::box> { public: // Public Constructors : explicit box_enumerator(const list<program::box>& items) : items_(items) {} // Public Properties : const program::box& current() const override {return items_[index_];} // Public Methods : bool move_next() override {return ++index_ < items_.count();} void reset() override {index_ = size_object::max_value;} protected: const list<program::box>& items_; size index_ = size_object::max_value; }; // Defines two boxes as equal if they have the same dimensions. class box_same_dimensions : public iequality_comparer<program::box> { public: // Public Methods : bool equals(const program::box& b1, const program::box& b2) const noexcept override {return b1.height == b2.height && b1.length == b2.length && b1.width == b2.width;} size get_hash_code(const program::box& box) const noexcept override {return hash_code::combine(box.height, box.length, box.width);} }; // Defines two boxes as equal if they have the same volume. class box_same_volume : public iequality_comparer<program::box> { public: // Public Methods : bool equals(const program::box& b1, const program::box& b2) const noexcept override {return b1.height * b1.length * b1.width == b2.height * b2.length * b2.width;} size get_hash_code(const program::box& box) const noexcept override { auto hash_code = hash_code::combine(box.height, box.length, box.width); console::write_line("HC: {}", hash_code); return hash_code; } }; static void display(const box_collection& boxes) { console::write_line("\nheight length width hash code"); for (auto box : boxes) console::write_line("{,-6} {,-6} {,-6} {}", box.height, box.length, box.width, box.get_hash_code()); // Results by manipulating the enumerator directly: //auto enumerator = boxes.get_enumerator(); //console::write_line("\nheight length width hash code"); //while (enumerator.move_next()) { // auto b = enumerator.current(); // console::write_line("{,-6} {,-6} {,-6} {}", b.height, b.length, b.width, b.get_hash_code()); //} console::write_line(); } }; startup_(program::main); // This code can produce the following output : // // A box with 10x4x6 dimensions was already added to the collection. // // height length width hash code // 10 4 6 215240349697 // 4 6 10 215240349697 // 6 10 4 215240349697 // 12 8 10 215240349697 // // Removing 6x10x4 // // height length width hash code // 10 4 6 215240349697 // 4 6 10 215240349697 // 12 8 10 215240349697 // // Contains 8x12x10 by dimensions: false // Contains 8x12x10 by volume: true Remarks The xtd::collections::generic::icollection <type_t> interface is the base interface for classes in the xtd::collections::generic namespace. The xtd::collections::generic::icollection <type_t> interface extends xtd::collections::generic::ienumerable <type_t>; xtd::collections::generic::idictionary <key_t, value_t> and xtd::collections::generic::ilist <type_t> are more specialized interfaces that extend xtd::collections::generic::icollection <type_t>. A xtd::collections::generic::idictionary <key_t, value_t> implementation is a collection of key/value pairs, like the xtd::collections::generic::dictoinary <key_t, value_t> class. A xtd::collections::generic::ilist <type_t> implementation is a collection of values, and its members can be accessed by index, like the xtd::collections::generic::list <type_t> class. If neither the xtd::collections::generic::idictionary <key_t, value_t> interface nor the xtd::collections::generic::ilist <type_t> interface meet the requirements of the required collection, derive the new collection class from the xtd::collections::generic::icollection <type_t> interface instead for more flexibility. */ template<class type_t> class icollection : public xtd::collections::generic::ienumerable<type_t>, public xtd::collections::generic::extensions::collection_common<type_t, icollection<type_t >> { public: / /** Represents the xtd::collections::generic::icollection value type.
using	value_type

Public Fields
Represents a collection of objects that can be individually accessed by index. Definition template<class type_t> class ilist : public xtd::collections::generic::icollection<type_t> Header #include <xtd/collections/generic/ilist> Namespace xtd::collections::generic Library xtd.core Examples The following example implements the xtd::collections::generic::ilist <type_t> interface to create a collection of custom box objects named box_collection. Each box has height, length, and width properties, which are used to define equality. Equality can be defined as all dimensions being the same or the volume being the same. The box class implements the xtd::iequatable <type_t> interface to define the default equality as the dimensions being the same. The box_collection class implements the xtd::collections::generic::ibox::index_of method to use the default equality to determine whether a box is in the collection. This method is used by the xtd::collections::generic::icollection::add method so that each box added to the collection has a unique set of dimensions. The box_collection class also provides an overload of the xtd::collections::generic::icollection::contains method that takes a specified xtd::collections::generic::iequality_comparer <type_t> interface, such as box_same_dimensions and box_same_volume` classes in the example. This example also implements an xtd::collections::generic::ienumerator <type_t> interface for the box_collection class so that the collection can be enumerated. #include <xtd/xtd> class program { public: static auto main() -> void { auto boxes = box_collection {}; boxes.add(program::box {10, 4, 6}); boxes.add(program::box {4, 6, 10}); boxes.add(program::box {6, 10, 4}); boxes.add(program::box {12, 8, 10}); // Same dimensions. Cannot be added: boxes.add(program::box {10, 4, 6}); // Test the Remove method. display(boxes); console::write_line("Removing 6x10x4"); boxes.remove(program::box {6, 10, 4}); display(boxes); // Test the Contains method. auto box_check = program::box {8, 12, 10}; console::write_line("Contains {}x{}x{} by dimensions: {}", box_check.height, box_check.length, box_check.width, boxes.contains(box_check)); // Test the Contains method overload with a specified equality comparer. console::write_line("Contains {}x{}x{} by volume: {}", box_check.height, box_check.length, box_check.width, boxes.contains(box_check, box_same_volume {})); } struct box : public object, public iequatable<program::box> { // Public Constructors : box() = default; box(int h, int l, int w) : height {h}, length{l}, width {w} {} // Public Properties : int height = 0; int length = 0; int width = 0; // Public Methods : bool equals(const object& o) const noexcept override {return is<program::box>(o) && equals(as<program::box>(o));} bool equals(const program::box& o) const noexcept override {return box_same_dimensions {}.equals(*this, o);} }; class box_collection : public ilist<program::box> { public: // Public Constructors : box_collection(const std::initializer_list<program::box>& boxes) : boxes_(boxes) {} // Public Properties : xtd::size count() const noexcept override {return boxes_.count();} bool is_fixed_size() const noexcept override {return false;} bool is_read_only() const noexcept override {return false;} bool is_synchronized() const noexcept override {return false;} const object& sync_root() const noexcept override {return sync_root_;} // Public Methods : void add(const program::box& item) override { if (!contains(item)) boxes_.add(item); else console::write_line("A box with {}x{}x{} dimensions was already added to the collection.", item.height, item.length, item.width); } void clear() override {boxes_.clear();} bool contains(const program::box& item) const noexcept override {return index_of(item) != npos;} bool contains(const program::box& item, const iequality_comparer<program::box>& comparer) const noexcept { for (auto box : boxes_) if (comparer.equals(box, item)) return true; return false; } void copy_to(array<program::box>& array, xtd::size array_index) const override {boxes_.copy_to(array, array_index);} enumerator<program::box> get_enumerator() const override {return {new_ptr<box_enumerator>(boxes_)};} xtd::size index_of(const program::box& item) const noexcept override { for (auto index = 0_z; index < count(); ++index) if (boxes_[index] == item) return index; return npos; } void insert(xtd::size index, const program::box& item) override { if (index >= count()) throw argument_out_of_range_exception {}; boxes_.insert(index, item); } bool remove(const program::box& item) override {return boxes_.remove(item);} void remove_at(xtd::size index) override { if (index >= count()) throw argument_out_of_range_exception {}; boxes_.remove_at(index); } // Public Operators : const program::box& operator [](xtd::size index) const override { if (index >= count()) throw argument_out_of_range_exception {}; return boxes_[index]; } program::box& operator [](xtd::size index) override { if (index >= count()) throw argument_out_of_range_exception {}; return boxes_[index]; } private: list<program::box> boxes_; object sync_root_; }; class box_enumerator : public ienumerator<program::box> { public: // Public Constructors : explicit box_enumerator(const list<program::box>& items) : items_(items) {} // Public Properties : const program::box& current() const override {return items_[index_];} // Public Methods : bool move_next() override {return ++index_ < items_.count();} void reset() override {index_ = size_object::max_value;} protected: const list<program::box>& items_; size index_ = size_object::max_value; }; // Defines two boxes as equal if they have the same dimensions. class box_same_dimensions : public iequality_comparer<program::box> { public: // Public Methods : bool equals(const program::box& b1, const program::box& b2) const noexcept override {return b1.height == b2.height && b1.length == b2.length && b1.width == b2.width;} size get_hash_code(const program::box& box) const noexcept override {return hash_code::combine(box.height, box.length, box.width);} }; // Defines two boxes as equal if they have the same volume. class box_same_volume : public iequality_comparer<program::box> { public: // Public Methods : bool equals(const program::box& b1, const program::box& b2) const noexcept override {return b1.height * b1.length * b1.width == b2.height * b2.length * b2.width;} size get_hash_code(const program::box& box) const noexcept override { auto hash_code = hash_code::combine(box.height, box.length, box.width); console::write_line("HC: {}", hash_code); return hash_code; } }; static void display(const box_collection& boxes) { console::write_line("\nheight length width hash code"); for (auto index = 0_z; index < boxes.count(); ++index) console::write_line("{,-6} {,-6} {,-6} {}", boxes[index].height, boxes[index].length, boxes[index].width, boxes[index].get_hash_code()); // Results by manipulating the iterator directly: //console::write_line("\nheight length width hash code"); //for (auto box : boxes) // console::write_line("{,-6} {,-6} {,-6} {}", box.height, box.length, box.width, box.get_hash_code()); // Results by manipulating the enumerator directly: //auto enumerator = boxes.get_enumerator(); //console::write_line("\nheight length width hash code"); //while (enumerator.move_next()) { // auto b = enumerator.current(); // console::write_line("{,-6} {,-6} {,-6} {}", b.height, b.length, b.width, b.get_hash_code()); //} console::write_line(); } }; startup_(program::main); // This code can produce the following output : // // A box with 10x4x6 dimensions was already added to the collection. // // height length width hash code // 10 4 6 215240349697 // 4 6 10 215240349697 // 6 10 4 215240349697 // 12 8 10 215240349697 // // Removing 6x10x4 // // height length width hash code // 10 4 6 215240349697 // 4 6 10 215240349697 // 12 8 10 215240349697 // // Contains 8x12x10 by dimensions: false // Contains 8x12x10 by volume: true Remarks The xtd::collections::generic::ilist <type_t> interface is the base interface for classes in the xtd::collections::generic namespace. The xtd::collections::generic::ilist <type_t> interface extends xtd::collections::generic::ienumerable <type_t>; xtd::collections::generic::idictionary <key_t, value_t> and xtd::collections::generic::ilist <type_t> are more specialized interfaces that extend xtd::collections::generic::ilist <type_t>. A xtd::collections::generic::idictionary <key_t, value_t> implementation is a collection of key/value pairs, like the xtd::collections::generic::dictoinary <key_t, value_t> class. A xtd::collections::generic::ilist <type_t> implementation is a collection of values, and its members can be accessed by index, like the xtd::collections::generic::list <type_t> class. If neither the xtd::collections::generic::idictionary <key_t, value_t> interface nor the xtd::collections::generic::ilist <type_t> interface meet the requirements of the required collection, derive the new collection class from the xtd::collections::generic::ilist <type_t> interface instead for more flexibility. */ template<class type_t> class ilist : public icollection<type_t> { public: / /** 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::size. Examples auto items = list {1, 2, 3}; if (items.index_of(42) == items.npos) console::write_line("Value not found");
static constexpr xtd::size	npos
static constexpr xtd::size	bpos
	Represents the index of the first valid element in a collection.
static constexpr xtd::size	epos
	Represents the index of the last valid element in a collection.

Public Properties
virtual auto	count () const noexcept -> xtd::size=0
	Gets the number of elements contained in the xtd::collections::generic::icollection <type_t>.
virtual auto	is_read_only () const noexcept -> bool=0
	Gets a value indicating whether the xtd::collections::generic::icollection <type_t> is read-only.
virtual auto	is_synchronized () const noexcept -> bool=0
	Gets a value indicating whether access to the xtd::collections::generic::icollection <type_t> is synchronized (thread safe).
virtual auto	sync_root () const noexcept -> const xtd::object &=0
	Gets an object that can be used to synchronize access to the the xtd::collections::generic::icollection <type_t>.
virtual auto	is_fixed_size () const noexcept -> bool=0
	Gets a value indicating whether the xtd::collections::generic::ilist <type_t> has a fixed size.

Public Methods
virtual auto	add (const type_t &item) -> void=0
	Adds an item to the xtd::collections::generic::icollection <type_t>.
virtual auto	clear () -> void=0
	Removes all items from the xtd::collections::generic::icollection <type_t>.
virtual auto	contains (const type_t &item) const noexcept -> bool=0
	Determines whether the xtd::collections::generic::icollection <type_t> contains a specific value.
virtual auto	copy_to (xtd::array< type_t > &array, xtd::size 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	remove (const type_t &item) -> bool=0
	Removes the first occurrence of a specific object from the xtd::collections::generic::icollection <type_t>.
virtual auto	index_of (const type_t &item) const noexcept -> xtd::size=0
	Determines the index of a specific item in the xtd::collections::generic::ilist <type_t>.
virtual auto	insert (xtd::size index, const type_t &item) -> void=0
	Inserts an item to the xtd::collections::generic::ilist <type_t> at the specified index.
virtual auto	remove_at (xtd::size index) -> void=0
	Removes the xtd::collections::generic::ilist <type_t> item at the specified index.

Public Operators
virtual auto	operator[] (xtd::size index) const -> const type_t &=0
	Gets the element at the specified index.

Function Documentation

count()

virtual auto xtd::collections::generic::count ( ) const -> xtd::size

nodiscardpure virtualnoexcept

Gets the number of elements contained in the xtd::collections::generic::icollection <type_t>.

Returns

The number of elements contained in the xtd::collections::generic::icollection <type_t>.

is_read_only()

virtual auto xtd::collections::generic::is_read_only ( ) const -> bool

nodiscardpure virtualnoexcept

Gets a value indicating whether the xtd::collections::generic::icollection <type_t> is read-only.

Returns

true if the xtd::collections::generic::icollection <type_t> is read-only; otherwise, false.

Remarks

A collection that is read-only does not allow the addition or removal of elements after the collection is created. Note that read-only in this context does not indicate whether individual elements of the collection can be modified, since the xtd::collections::generic::icollection <type_t> interface only supports addition and removal operations. For example, the xtd::collections::generic::icollection::is_read_only property of an array that is cast or converted to an xtd::collections::generic::icollection <type_t> object returns true, even though individual array elements can be modified.

is_synchronized()

virtual auto xtd::collections::generic::is_synchronized ( ) const -> bool

nodiscardpure virtualnoexcept

Gets a value indicating whether access to the xtd::collections::generic::icollection <type_t> is synchronized (thread safe).

Returns

true if access to the xtd::collections::generic::icollection <type_t> is synchronized (thread safe); otherwise, false.

Remarks

xtd::collections::generic::icollection::sync_root returns an object, which can be used to synchronize access to the xtd::collections::generic::icollection <type_t>.

Most collection classes in the xtd::collections namespace also implement a synchronized method, which provides a synchronized wrapper around the underlying collection.

Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads.

The following code example shows how to lock the collection using the xtd::collections::generic::icollection::sync_root property during the entire enumeration.

icollection& my_collection = some_collection;
lock_(my_collection.sync_root()) {
  for (auto item : my_collection) {
    // Insert your code here.
  }
}

sync_root()

virtual auto xtd::collections::generic::sync_root ( ) const -> const xtd::object &

nodiscardpure virtualnoexcept

Gets an object that can be used to synchronize access to the the xtd::collections::generic::icollection <type_t>.

Returns

An object that can be used to synchronize access to the the xtd::collections::generic::icollection <type_t>.

Remarks

For collections whose underlying store is not publicly available, the expected implementation is to return the current instance. Note that the pointer to the current instance might not be sufficient for collections that wrap other collections; those should return the underlying collection's sync_root property.

Most collection classes in the xts::.collections namespace also implement a synchronized method, which provides a synchronized wrapper around the underlying collection. However, derived classes can provide their own synchronized version of the collection using the xtd::collections::generic::icollection::sync_root property. The synchronizing code must perform operations on the xtd::collections::generic::icollection::sync_root property of the collection, not directly on the collection. This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the collection instance.

In the absence of a synchronized method on a collection, the expected usage for the xtd::collections::generic::icollection::sync_root looks as follows:

icollection& my_collection = some_collection;
lock_(my_collection.sync_root()) {
  // Some operation on the collection, which is now thread safe.
}
@encode
@remarks Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads.
@remarks The following code example shows how to lock the collection using the xtd::collections::generic::icollection::sync_root property during the entire enumeration.
@code
icollection& my_collection = some_collection;
lock_(my_collection.sync_root()) {
  for (auto item : my_collection) {
    // Insert your code here.
  }
}

add()

virtual auto xtd::collections::generic::add ( const type_t & item ) -> void

pure virtual

Adds an item to the xtd::collections::generic::icollection <type_t>.

Parameters

item	The object to add to the xtd::collections::generic::icollection <type_t>.

Exceptions

xtd::not_supported_exception

The xtd::collections::generic::icollection <type_t> is read-only.

clear()

virtual auto xtd::collections::generic::clear ( ) -> void

pure virtual

Removes all items from the xtd::collections::generic::icollection <type_t>.

Exceptions

xtd::not_supported_exception

The xtd::collections::generic::icollection <type_t> is read-only.

Remarks

xtd::collections::generic::icollection::count must be set to 0, and references to other objects from elements of the collection must be released.

contains()

virtual auto xtd::collections::generic::contains ( const type_t & item ) const -> bool

nodiscardpure virtualnoexcept

Determines whether the xtd::collections::generic::icollection <type_t> contains a specific value.

Parameters

item	The object to locate in the xtd::collections::generic::icollection <type_t>.

Returns

true if item is found in the xtd::collections::generic::icollection <type_t>; otherwise, false.

Remarks

Implementations can vary in how they determine equality of objects; for example, xtd::collections::generic::list <type_t> uses xtd::collections::generic::compoarer <type_t>::default_comparer, whereas xtd::collections::generic::dictionary <key_t, value_t> allows the user to specify the xtd::collections::generic::icompoarer <type_t> implementation to use for comparing keys.

copy_to()

virtual auto xtd::collections::generic::copy_to ( xtd::array< type_t > & array, xtd::size array_index ) const -> void

pure virtual

Copies the elements of the xtd::collections::generic::icollection <type_t> to an xtd::array, starting at a particular xtd::array index.

Parameters

array	The one-dimensional xtd::array that is the destination of the elements copied from xtd::collections::generic::icollection <type_t>. The xtd::array must have zero-based indexing.
array_index	The zero-based index in array at which copying begins.

Exceptions

xtd::argument_exception

The number of elements in the source xtd::collections::generic::icollection <type_t> is greater than the available space from `array_index` to the end of the destination `array`.

remove()

virtual auto xtd::collections::generic::remove ( const type_t & item ) -> bool

pure virtual

Removes the first occurrence of a specific object from the xtd::collections::generic::icollection <type_t>.

Parameters

item	The object to remove from the xtd::collections::generic::icollection <type_t>.

Returns

true if item was successfully removed from the xtd::collections::generic::icollection <type_t>; otherwise, false. This method also returns false if item is not found in the original xtd::collections::generic::icollection <type_t>.

Exceptions

xtd::not_supported_exception

The xtd::collections::generic::icollection <type_t> is read-only.

Remarks

Implementations can vary in how they determine equality of objects; for example, xtd::collections::generic::list <type_t> uses xtd::collections::generic::compoarer <type_t>::default_comparer, whereas, xtd::collections::generic::dictionary <key_t, value_t> allows the user to specify the xtd::collections::generic::icompoarer <type_t> implementation to use for comparing keys.

In collections of contiguous elements, such as lists, the elements that follow the removed element move up to occupy the vacated spot. If the collection is indexed, the indexes of the elements that are moved are also updated. This behavior does not apply to collections where elements are conceptually grouped into buckets, such as a hash table.

is_fixed_size()

virtual auto xtd::collections::generic::is_fixed_size ( ) const -> bool

pure virtualnoexcept

Gets a value indicating whether the xtd::collections::generic::ilist <type_t> has a fixed size.

Returns

true if the xtd::collections::generic::ilist <type_t> has a fixed size; otherwise, false.

Remarks

A collection with a fixed size does not allow the addition or removal of elements after the collection is created, but it allows the modification of existing elements.

index_of()

virtual auto xtd::collections::generic::index_of ( const type_t & item ) const -> xtd::size

nodiscardpure virtualnoexcept

Determines the index of a specific item in the xtd::collections::generic::ilist <type_t>.

Parameters

item	The object to locate in the xtd::collections::generic::ilist <type_t>.

Returns

The index of item if found in the list; otherwise, xtd::collections::generic::ilist::npos.

Remarks

If an object occurs multiple times in the list, the xtd::collections::generic::ilist::index_of method always returns the first instance found.

insert()

virtual auto xtd::collections::generic::insert ( xtd::size index, const type_t & item ) -> void

pure virtual

Inserts an item to the xtd::collections::generic::ilist <type_t> at the specified index.

Parameters

index	The zero-based index at which item should be inserted.
item	The object to insert into the xtd::collections::generic::ilist <type_t>.

Exceptions

xtd::argument_out_of_range_exception	`index` is not a valid index in the xtd::collections::generic::ilist <type_t>.
xtd::not_supported_exception	The xtd::collections::generic::ilist <type_t> is read-only.

Remarks

If index equals the number of items in the xtd::collections::generic::ilist <type_t>, then item is appended to the list.

In collections of contiguous elements, such as lists, the elements that follow the insertion point move down to accommodate the new element. If the collection is indexed, the indexes of the elements that are moved are also updated. This behavior does not apply to collections where elements are conceptually grouped into buckets, such as a hash table.

remove_at()

virtual auto xtd::collections::generic::remove_at ( xtd::size index ) -> void

pure virtual

Removes the xtd::collections::generic::ilist <type_t> item at the specified index.

Parameters

index

The zero-based index of the item to remove.

Exceptions

xtd::argument_out_of_range_exception	`index` is not a valid index in the xtd::collections::generic::ilist <type_t>.
xtd::not_supported_exception	The xtd::collections::generic::ilist <type_t> is read-only.

Remarks

In collections of contiguous elements, such as lists, the elements that follow the removed element move up to occupy the vacated spot. If the collection is indexed, the indexes of the elements that are moved are also updated. This behavior does not apply to collections where elements are conceptually grouped into buckets, such as a hash table.

operator[]()

auto xtd::collections::generic::operator[] ( xtd::size index ) const -> const type_t &

pure virtual

Gets the element at the specified index.

Sets the element at the specified index.

Parameters

index

The zero-based index of the element to get.

Remarks

This operator provides the ability to access a specific element in the collection by using the following syntax: my_collection[index].

Parameters

index

The zero-based index of the element to set.

Remarks

This operator provides the ability to access a specific element in the collection by using the following syntax: my_collection[index].

Variable Documentation

bpos

xtd::size xtd::collections::generic::bpos

inlinestaticconstexpr

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

Remarks

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

Examples

auto items = list {10, 20, 30, 40};
console::write_line(items[bpos]); // Prints 10
console::write_line(items[bpos + 1]); // Prints Z0

epos

xtd::size xtd::collections::generic::epos

inlinestaticconstexpr

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

Remarks

Unlike xtd::npos (which means "no position"), xtd::epos 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::epos] directly accesses the last element without manually subtracting one from the collection count.

Remarks

The epos is equivalent to ~1_z. With bitwise operator the code is more concise.

Examples

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

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

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