xtd 0.2.0
Loading...
Searching...
No Matches
xtd::collections::generic::list< type_t, allocator_t > Class Template Reference
Inheritance diagram for xtd::collections::generic::list< type_t, allocator_t >:
xtd::object xtd::collections::generic::ilist< type_t > xtd::iequatable< xtd::collections::generic::list< type_t, allocator_t > > xtd::collections::generic::icollection< type_t > xtd::interface xtd::extensions::equality_operators< type_t, equatable_t > xtd::collections::generic::ienumerable< type_t > xtd::collections::generic::extensions::collection_operators< type_t, icollection< type_t > > xtd::interface xtd::collections::generic::extensions::enumerable_iterators< type_t, xtd::collections::generic::ienumerable< type_t > > xtd::collections::generic::extensions::enumerable< ienumerable< type_t >, type_t >

Definition

template<class type_t, class allocator_t>
class xtd::collections::generic::list< type_t, allocator_t >

Represents a strongly typed list of objects that can be accessed by index. Provides methods to search, sort, and manipulate lists.

template<class type_t>
class list : public xtd::object, xtd::collections::generic::ilist<type_t>, public xtd::iequatable<xtd::collections::generic::list<type_t>>
Represents a collection of objects that can be individually accessed by index.
Definition ilist.hpp:41
Represents a strongly typed list of objects that can be accessed by index. Provides methods to search...
Definition list.hpp:80
Defines a generalized method that a value type or class implements to create a type-specific method f...
Definition iequatable.hpp:22
Supports all classes in the xtd class hierarchy and provides low-level services to derived classes....
Definition object.hpp:44
Header
#include <xtd/collections/generic/list>
Namespace
xtd::collections::generic
Library
xtd.core
Examples
The following example demonstrates how to add, remove, and insert a simple business object in a xtd::collections::generic::list <type_t>.
#include <xtd/xtd>
using namespace xtd;
using namespace xtd::collections::generic;
// Simple business object. A part_id is used to identify a part
// but the part name be different for the same Id.
class part : public object, public iequatable<part> {
public:
string part_name;
int part_id = 0;
part() = default;
part(const string& name, int id) : part_name {name}, part_id {id} {}
string to_string() const noexcept override {return string::format("ID: {} Name: {}", part_id, part_name);}
bool equals(const object& obj) const noexcept override {return is<part>(obj) && equals(as<part>(obj));}
bool equals(const part& other) const noexcept override {return part_id == other.part_id;}
size get_hash_code() const noexcept override {return object::get_hash_code();}
};
class example {
public:
static auto main() -> void {
auto parts = list<part> {};
console::write_line("\ncapacity: {0}", parts.capacity());
parts.add(part {"crank arm", 1234});
parts.add(part {"chain ring", 1334});
parts.add(part {"seat", 1434});
parts.add(part {"cassette", 1534});
parts.add(part {"shift lever", 1634});
console::write_line();
for (auto part : parts)
console::write_line(part);
console::write_line("\ncapacity: {0}", parts.capacity());
console::write_line("count: {0}", parts.count());
parts.trim_excess();
console::write_line("\ntrim_excess()");
console::write_line("capacity: {0}", parts.capacity());
console::write_line("count: {0}", parts.count());
parts.clear();
console::write_line("\nclear()");
console::write_line("capacity: {0}", parts.capacity());
console::write_line("count: {0}", parts.count());
}
};
startup_(example::main);
// This code produces the following output :
//
// capacity: 0
//
// ID: 1234 Name: crank arm
// ID: 1334 Name: chain ring
// ID: 1434 Name: seat
// ID: 1534 Name: cassette
// ID: 1634 Name: shift lever
//
// capacity: 8
// count: 5
//
// trim_excess()
// capacity: 5
// count: 5
//
// clear()
// capacity: 5
// count: 0
Represents the standard input, output, and error streams for console applications.
Definition console.hpp:36
#define startup_(main_method)
Defines the entry point to be called when the application loads. Generally this is set either to the ...
Definition startup.hpp:175
size_t size
Represents a size of any object in bytes.
Definition size.hpp:23
std::string to_string(const value_t &value, const std::string &fmt, const std::locale &loc)
Convert a specified value into a string with specified format and locale.
Definition to_string.hpp:41
@ other
The operating system is other.
The xtd::collections::generic namespace contains interfaces and classes that define generic collectio...
Definition comparer.hpp:16
The xtd namespace contains all fundamental classes to access Hardware, Os, System,...
Definition xtd_about_box.hpp:10
The following example demonstrates several properties and methods of the xtd::collections::generic::list <type_t> generic class of type string. (For an example of a xtd::collections::generic::list <type_t> of complex types, see the xtd::collections::generic::list::contains method.)

The parameterless constructor is used to create a list of strings with the default capacity. The xtd::collections::generic::list::capacity property is displayed and then the xtd::collections::generic::list::add method is used to add several items. The items are listed, and the xtd::collections::generic::list::capacity property is displayed again, along with the xtd::collections::generic::list::count property, to show that the capacity has been increased as needed.

The xtd::collections::generic::list::contains method is used to test for the presence of an item in the list, the Insert method is used to insert a new item in the middle of the list, and the contents of the list are displayed again.

The default xtd::collections::generic::list::operator [] is used to retrieve an item, the xtd::collections::generic::list::remove method is used to remove the first instance of the duplicate item added earlier, and the contents are displayed again. The xtd::collections::generic::list::remove method always removes the first instance it encounters.

The xtd::collections::generic::list::trim_excess method is used to reduce the capacity to match the count, and the xtd::collections::generic::list::capacity and xtd::collections::generic::list::count properties are displayed. If the unused capacity had been less than 10 percent of total capacity, the list would not have been resized.

Finally, the xtd::collections::generic::list::clear method is used to remove all items from the list, and the xtd::collections::generic::list::capacity and xtd::collections::generic::list::count properties are displayed.

#include <xtd/xtd>
using namespace xtd;
using namespace xtd::collections::generic;
class example {
public:
static auto main() -> void {
auto dinosaurs = list<string> {};
console::write_line("\ncapacity: {0}", dinosaurs.capacity());
dinosaurs.add("Tyrannosaurus");
dinosaurs.add("Amargasaurus");
dinosaurs.add("Mamenchisaurus");
dinosaurs.add("Deinonychus");
dinosaurs.add("Compsognathus");
console::write_line();
for (auto dinosaur : dinosaurs)
console::write_line(dinosaur);
console::write_line("\ncapacity: {0}", dinosaurs.capacity());
console::write_line("count: {0}", dinosaurs.count());
console::write_line("\ncontains(\"Deinonychus\"): {0}", dinosaurs.contains("Deinonychus"));
console::write_line("\ninsert(2, \"Compsognathus\")");
dinosaurs.insert(2, "Compsognathus");
console::write_line();
for (auto dinosaur : dinosaurs)
console::write_line(dinosaur);
// Shows accessing the list using the Item property.
console::write_line("\ndinosaurs[3]: {0}", dinosaurs[3]);
console::write_line("\nremove(\"Compsognathus\")");
dinosaurs.remove("Compsognathus");
console::write_line();
for (auto dinosaur : dinosaurs)
console::write_line(dinosaur);
dinosaurs.trim_excess();
console::write_line("\ntrim_excess()");
console::write_line("capacity: {0}", dinosaurs.capacity());
console::write_line("count: {0}", dinosaurs.count());
dinosaurs.clear();
console::write_line("\nclear()");
console::write_line("capacity: {0}", dinosaurs.capacity());
console::write_line("count: {0}", dinosaurs.count());
}
};
startup_(example::main);
// This code produces the following output :
//
// capacity: 0
//
// Tyrannosaurus
// Amargasaurus
// Mamenchisaurus
// Deinonychus
// Compsognathus
//
// capacity: 8
// count: 5
//
// contains("Deinonychus"): true
//
// insert(2, "Compsognathus")
//
// Tyrannosaurus
// Amargasaurus
// Compsognathus
// Mamenchisaurus
// Deinonychus
// Compsognathus
//
// dinosaurs[3]: Mamenchisaurus
//
// remove("Compsognathus")
//
// Tyrannosaurus
// Amargasaurus
// Mamenchisaurus
// Deinonychus
// Compsognathus
//
// trim_excess()
// capacity: 5
// count: 5
// clear()
// capacity: 5
// count: 0
Remarks
The xtd::collections::generic::list <type_t> class instanciate as xtd::collections::generic::list::base_type a std::vector with xtd::collections::generic::helpers::allocator instead std::allocator. Use xtd::collections::generic::list::get_base_type() to access the underlying std::vector.
The xtd::collections::generic::list <type_t> class can also be used to manage a dynamic array of bool exactly as other types unlike std::vector with xtd::collections::generic::helpers::allocator instead std::allocator. When the type_tis bool The underlying std::vector uses xtd::byte.
The xtd::collections::generic::list <type_t> class is the generic equivalent of the xtd::collections::array_list class. It implements the xtd::collections::generic::ilist <type_t> generic interface by using an array whose size is dynamically increased as required.
You can add items to a xtd::collections::generic::list <type_t> by using the xtd::collections::generic::list::add or xtd::collections::generic::list::add_range methods.
The xtd::collections::generic::list <type_t> class uses both an equality comparer and an ordering comparer.
The xtd::collections::generic::list <type_t> is not guaranteed to be sorted. You must sort the xtd::collections::generic::list <type_t> before performing operations (such as xtd::collections::binary_search) that require the xtd::collections::generic::list <type_t> to be sorted.
Elements in this collection can be accessed using an integer index. Indexes in this collection are zero-based.
For an immutable version of the xtd::collections::generic::list <type_t> class, see xtd::collections::immutale::immutable_list <type_t>.
Performance considerations
As xtd::collections::generic::list <type_t> instantiates and uses only the methods of std::vector, the performance of xtd::collections::generic::list <type_t> is practically identical to that of std::vector.
Examples
action.cpp, animation.cpp, array_list.cpp, array_list2.cpp, assert_does_not_throw.cpp, assert_throws.cpp, assert_throws_any.cpp, assume_does_not_throw.cpp, assume_throws.cpp, assume_throws_any.cpp, auto_reset_event.cpp, border_style.cpp, boxing.cpp, calculator.cpp, collection_assert.cpp, collection_assert_all_items_are_instances_of.cpp, collection_assert_all_items_are_not_null.cpp, collection_assert_all_items_are_unique.cpp, collection_assert_are_equal.cpp, collection_assert_are_equivalent.cpp, collection_assert_are_not_equal.cpp, collection_assert_are_not_equivalent.cpp, collection_assert_contains.cpp, collection_assert_does_not_contain.cpp, collection_assert_is_empty.cpp, collection_assert_is_not_empty.cpp, collection_assert_is_ordered.cpp, collection_assume.cpp, collection_assume_all_items_are_instances_of.cpp, collection_assume_all_items_are_not_null.cpp, collection_assume_all_items_are_unique.cpp, collection_assume_are_equal.cpp, collection_assume_are_equivalent.cpp, collection_assume_are_not_equal.cpp, collection_assume_are_not_equivalent.cpp, collection_assume_contains.cpp, collection_assume_does_not_contain.cpp, collection_assume_is_empty.cpp, collection_assume_is_not_empty.cpp, collection_assume_is_ordered.cpp, collection_valid.cpp, collection_valid_all_items_are_instances_of.cpp, collection_valid_all_items_are_not_null.cpp, collection_valid_all_items_are_unique.cpp, collection_valid_are_equal.cpp, collection_valid_are_equivalent.cpp, collection_valid_are_not_equal.cpp, collection_valid_are_not_equivalent.cpp, collection_valid_contains.cpp, collection_valid_does_not_contain.cpp, collection_valid_is_empty.cpp, collection_valid_is_not_empty.cpp, collection_valid_is_ordered.cpp, colored_forms.cpp, colored_tab_pages.cpp, console_clear.cpp, console_color2.cpp, console_color3.cpp, console_color4.cpp, console_firework.cpp, console_song.cpp, console_song2.cpp, console_song3.cpp, console_unicode.cpp, date_time_add_hours.cpp, date_time_add_minutes.cpp, date_time_now.cpp, date_time_now2.cpp, date_time_today.cpp, default_trace_listener.cpp, dot_matrix_display.cpp, draw_point.cpp, fibonacci_series.cpp, file_info_move_to.cpp, font_families.cpp, form_paint.cpp, form_show.cpp, format_class.cpp, format_class_object.cpp, format_sequence_containers.cpp, fourteen_segment_display.cpp, generic_icollection.cpp, generic_ienumerable.cpp, generic_ienumerable2.cpp, generic_ienumerator.cpp, generic_ilist.cpp, generic_list.cpp, generic_list2.cpp, generic_list3.cpp, generic_list4.cpp, generic_list_as_read_only.cpp, graph_control.cpp, graphics.cpp, ienumerable.cpp, ienumerator.cpp, iobservable_iobserver.cpp, ip_address.cpp, labels_and_unicode_text.cpp, lock_guard.cpp, manual_reset_event.cpp, monitor.cpp, mutex.cpp, nine_segment_display.cpp, open_file_box.cpp, painting.cpp, random1.cpp, random2.cpp, random3.cpp, read_only_collection.cpp, semaphore.cpp, seven_segment_display.cpp, sixteen_segment_display.cpp, sprintf_class.cpp, sprintf_class_with_specified_formating.cpp, sprintf_class_with_specified_formating_with_to_string.cpp, stopwatch.cpp, user_control.cpp, valid_does_not_throw.cpp, valid_throws.cpp, valid_throws_any.cpp, and wiggly.cpp.

Public Aliases

using value_type = type_t
 Represents the list value type.
 
using allocator_type = typename xtd::collections::generic::helpers::allocator< typename std::conditional< std::is_same< bool, value_type >::value, xtd::byte, value_type >::type >
 Represents the list allocator type.
 
using base_type = std::vector< typename std::conditional< std::is_same< bool, value_type >::value, xtd::byte, value_type >::type, allocator_type >
 Represents the list base type.
 
using const_base_type = const base_type
 Represents the list base type.
 
using size_type = xtd::size
 Represents the list size type (usually xtd::size).
 
using difference_type = xtd::ptrdiff
 Represents the list difference type (usually xtd::ptrdiff).
 
using reference = value_type &
 Represents the reference of list value type.
 
using const_reference = const value_type &
 Represents the const reference of list value type.
 
using pointer = value_type *
 Represents the pointer of list value type.
 
using const_pointer = const value_type *
 Represents the const pointer of list value type.
 
using iterator = typename xtd::collections::generic::ienumerable< type_t >::iterator
 Represents the iterator of list value type.
 
using const_iterator = typename xtd::collections::generic::ienumerable< type_t >::const_iterator
 Represents the const iterator of list value type.
 
using reverse_iterator = typename base_type::reverse_iterator
 Represents the reverse iterator of list value type.
 
using const_reverse_iterator = typename base_type::const_reverse_iterator
 Represents the const reverse iterator of list value type.
 
using read_only_collection = xtd::collections::object_model::read_only_collection< value_type >
 Represents the read only collection of of list.
 

Public Fields

static constexpr size_type npos
 This is a special value equal to the maximum value representable by the type size_type.
 

Public Constructors

 list () noexcept=default
 Initializes a new instance of the xtd::collections::generic::list class that is empty.
 
 list (const allocator_type &alloc) noexcept
 Constructs an empty container with the given allocator.
 
 list (size_type count, const type_t &value, const allocator_type &alloc=allocator_type())
 Constructs the container with specified count copies of elements with specified value.
 
 list (size_type count, const allocator_type &alloc=allocator_type())
 Constructs the container with specified count default-inserted instances of type_t. No copies are made.
 
template<class input_iterator_t >
 list (input_iterator_t first, input_iterator_t last, const allocator_type &alloc=allocator_type())
 Constructs the container with the contents of the range [first, last).
 
 list (const xtd::collections::generic::ienumerable< type_t > &collection, const allocator_type &alloc=allocator_type())
 Initializes a new instance of the xtd::collections::generic::list <type_t> class that contains elements copied from the specified collection and has sufficient capacity to accommodate the number of elements copied.
 
 list (const list &list)
 Default copy constructor with specified list.
 
 list (const base_type &list)
 Copy constructor with specified base type list.
 
 list (const list &list, const allocator_type &alloc)
 Default copy constructor with specified list, and allocator.
 
 list (const base_type &list, const allocator_type &alloc)
 Default copy constructor with specified base type list, and allocator.
 
 list (std::initializer_list< type_t > items, const allocator_type &alloc=allocator_type())
 Constructs the container with the contents of the specified initializer list, and allocator.
 
 list (list &&other)
 Move constructor with specified list.
 
 list (base_type &&other)
 Move constructor with specified base type list.
 
 list (list &&other, const allocator_type &alloc)
 Move constructor with specified list, and allocator.
 
 list (base_type &&other, const allocator_type &alloc)
 Move constructor with specified base tyoe list, and allocator.
 

Public Properties

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 enumarable.
 
iterator begin () noexcept override
 Returns an iterator to the first element of the enumarable.
 
virtual size_type capacity () const noexcept
 Gets the total number of elements the internal data structure can hold without resizing.
 
virtual void capacity (size_type value)
 Sets the total number of elements the internal data structure can hold without resizing.
 
const_iterator cbegin () const noexcept override
 Returns an iterator to the first element of the enumarable.
 
const_iterator cend () const noexcept override
 Returns an iterator to the element following the last element of the enumarable.
 
size_type count () const noexcept override
 Gets the number of elements contained in the xtd::collections::generic::list <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::collections::generic::list::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::collections::generic::list::begin() == xtd::collections::generic::list::end().
 
const_iterator end () const noexcept override
 Returns an iterator to the element following the last element of the enumarable.
 
iterator end () noexcept override
 Returns an iterator to the element following the last element of the enumarable.
 
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
 Gets a value indicating whether the xtd::collections::generic::list <type_t> has a fixed size.
 
bool is_read_only () const noexcept override
 Gets a value indicating whether the xtd::collections::generic::list <type_t> is read-only.
 
bool is_synchronized () const noexcept override
 Gets a value indicating whether access to the xtd::collections::generic::list <type_t> is synchronized (thread safe).
 
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 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::collections::generic::list::begin(), xtd::collections::generic::list::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::collections::generic::list::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::collections::generic::list::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::collections::generic::list::begin(), xtd::collections::generic::list::end()).
 
const xtd::objectsync_root () const noexcept override
 Gets an object that can be used to synchronize access to the the xtd::collections::generic::list <type_t>.
 

Public Methods

void add (const type_t &item) override
 Adds an object to the end of the xtd::collections::generic::list <type_t>.
 
void add_range (const xtd::collections::generic::ienumerable< type_t > &enumerable)
 Adds copy of elements from the specified collection to the end of the xtd::collections::generic::list <type_t>.
 
void add_range (std::initializer_list< type_t > il)
 Adds copy of elements from the specified collection to the end of the xtd::collections::generic::list <type_t>.
 
read_only_collection as_read_only () const noexcept
 Returns a read-only xtd::collections::object_model::read_only_collection <type_t> wrapper for the current collection.
 
void assign (size_type count, const type_t &value)
 Replaces the contents with count copies of value value.
 
template<class input_iterator_t >
void assign (input_iterator_t first, input_iterator_t last)
 Replaces the contents with copies of those in the range [first, last).
 
virtual void assign (std::initializer_list< type_t > items)
 Replaces the contents with the elements from the initializer list items.
 
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.
 
xtd::size binary_search (const type_t &item) const
 Searches the entire sorted xtd::collections::generic::list <type_t> for an element using the default comparer and returns the zero-based index of the element.
 
xtd::size binary_search (const type_t &item, const xtd::collections::generic::icomparer< type_t > &comparer) const
 Searches the entire sorted xtd::collections::generic::list <type_t> for an element using the specified comparer and returns the zero-based index of the element.
 
xtd::size binary_search (xtd::size index, xtd::size count, const type_t &item, const xtd::collections::generic::icomparer< type_t > &comparer) const
 Searches a range of elements in the sorted xtd::collections::generic::list <type_t> for an element using the specified comparer and returns the zero-based index of the element.
 
void clear () override
 Removes all elements from the xtd::collections::generic::list <type_t>.
 
bool contains (const type_t &value) const noexcept override
 Determines whether an element is in the xtd::colllections::generic::list <type_t>.
 
template<class output_t >
list< output_t > convert_all (xtd::converter< output_t, const type_t & > converter) const
 Converts the elements in the current xtd::colllections::generic::list <type_t> to another type, and returns a list containing the converted elements.
 
virtual void copy_to (xtd::array< type_t > &array) const
 Copies the entire xtd::collections::generic::list <type_t> to a compatible one-dimensional array.
 
void copy_to (xtd::array< type_t > &array, size_type array_index) const override
 Copies the entire xtd::colllections::generic::list <type_t> to a compatible one-dimensional array, starting at the specified index of the target array.
 
virtual void copy_to (size_type index, xtd::array< type_t > &array, size_type array_index, size_type count) const
 Copies the entire xtd::collections::generic::list <type_t> to a compatible one-dimensional array, starting at the specified index of the target array.
 
template<class ... args_t>
iterator emplace (const_iterator pos, args_t &&... args)
 Inserts a new element into the container directly before pos.
 
template<class ... args_t>
reference emplace_back (args_t &&... args)
 Appends a new element to the end of the container. The element is constructed through std::allocator_traits::construct, which typically uses placement-new to construct the element in-place at the location provided by the container. The arguments args... are forwarded to the constructor as std::forward<Args>(args)....
 
xtd::size ensure_capacity (xtd::size capacity)
 Ensures that the capacity of this list is at least the specified capacity. If the current capacity is less than capacity, it is increased to at least the specified capacity.
 
bool equals (const object &obj) const noexcept override
 Determines whether the specified object is equal to the current object.
 
bool equals (const list &rhs) const noexcept override
 Indicates whether the current object is equal to another object of the same type.
 
virtual iterator erase (const_iterator pos)
 Erases the specified elements from the container.
 
virtual iterator erase (const_iterator first, const_iterator last)
 Erases the specified elements from the container.
 
bool exists (xtd::predicate< const type_t & > match) const
 Determines whether the xtd::collections::generic::list <type_t> contains elements that match the conditions defined by the specified predicate.
 
type_t find (xtd::predicate< const type_t & > match) const
 Searches for an element that matches the conditions defined by the specified predicate, and returns the first occurrence within the entire xtd::collections::generic::list <type_t>.
 
list< type_t > find_all (xtd::predicate< const type_t & > match) const
 Retrieves all the elements that match the conditions defined by the specified predicate.
 
xtd::size find_index (xtd::predicate< const type_t & > match) const
 Searches for an element that matches the conditions defined by the specified predicate, and returns the zero-based index of the first occurrence within the entire xtd::collections::generic::list <type_t>.
 
xtd::size find_index (xtd::size start_index, xtd::predicate< const type_t & > match) const
 Searches for an element that matches the conditions defined by the specified predicate, and returns the zero-based index of the first occurrence within the range of elements in the xtd::collections::generic::list <type_t> that extends from the specified index to the last element.
 
xtd::size find_index (xtd::size start_index, xtd::size count, xtd::predicate< const type_t & > match) const
 Searches for an element that matches the conditions defined by the specified predicate, and returns the zero-based index of the first occurrence within the range of elements in the xtd::collections::generic::list <type_t> that starts at the specified index and contains the specified number of elements.
 
type_t find_last (xtd::predicate< const type_t & > match) const
 Searches for an element that matches the conditions defined by the specified predicate, and returns the last occurrence within the entire xtd::collections::generic::list <type_t>.
 
xtd::size find_last_index (xtd::predicate< const type_t & > match) const
 Searches for an element that matches the conditions defined by the specified predicate, and returns the zero-based index of the last occurrence within the entire xtd::collections::generic::list <type_t>.
 
xtd::size find_last_index (xtd::size start_index, xtd::predicate< const type_t & > match) const
 Searches for an element that matches the conditions defined by the specified predicate, and returns the zero-based index of the last occurrence within the range of elements in the xtd::collections::generic::list <type_t> that extends from the first element to the specified index.
 
xtd::size find_last_index (xtd::size start_index, xtd::size count, xtd::predicate< const type_t & > match) const
 Searches for an element that matches the conditions defined by the specified predicate, and returns the zero-based index of the last occurrence within the range of elements in the xtd::collections::generic::list <type_t> that contains the specified number of elements and ends at the specified index.
 
void for_each (xtd::action< const type_t & > action)
 Performs the specified action on each element of the xtd::collections::generic::list <type_t>.
 
virtual allocator_type get_allocator () const
 Returns the allocator associated with the container.
 
virtual base_typeget_base_type () noexcept
 Returns the underlying base type.
 
virtual const base_typeget_base_type () const noexcept
 Returns the underlying base type.
 
enumerator< value_typeget_enumerator () const noexcept override
 Returns an enumerator that iterates through the xtd::collections::generic::list <type_t>.
 
list get_range (size_type index, size_type count)
 Creates a shallow copy of a range of elements in the source xtd::collections::generic::list <type_t>.
 
size_type index_of (const type_t &value) const noexcept override
 Determines the index of a specific item in the xtd::collections::generic::list <type_t>.
 
virtual size_type index_of (const type_t &value, size_type index) const
 Determines the index of a specific item in the xtd::collections::generic::list <type_t>.
 
virtual size_type index_of (const type_t &value, size_type index, size_type count) const
 Determines the index of a specific item in the xtd::collections::generic::list <type_t>.
 
virtual iterator insert (const_iterator pos, const type_t &value)
 Inserts elements at the specified location in the container.
 
virtual iterator insert (const_iterator pos, const type_t &&value)
 Inserts elements at the specified location in the container.
 
virtual iterator insert (const_iterator pos, size_type count, const type_t &value)
 Inserts elements at the specified location in the container.
 
template<class input_iterator_t >
iterator insert (const_iterator pos, input_iterator_t first, input_iterator_t last)
 Inserts elements at the specified location in the container.
 
virtual iterator insert (const_iterator pos, const std::initializer_list< type_t > &items)
 Inserts elements at the specified location in the container.
 
void insert (size_type index, const type_t &value) override
 Inserts an element into the xtd::collections::generic::list <type_t> at the specified index.
 
virtual void insert_range (size_type index, const xtd::collections::generic::ienumerable< type_t > &enumerable)
 Inserts copy of elements from a collection into the xtd::collections::generic::list <type_t> at the specified index.
 
virtual void insert_range (size_type index, const std::initializer_list< type_t > &items)
 Inserts copy of elements from a collection into the xtd::collections::generic::list <type_t> at the specified index.
 
size_type last_index_of (const type_t &value) const
 Determines the last index of a specific item in the xtd::collections::generic::list <type_t>.
 
size_type last_index_of (const type_t &value, size_type index) const
 Determines the last index of a specific item in the xtd::collections::generic::list <type_t>.
 
size_type last_index_of (const type_t &value, size_type index, size_type count) const
 Determines the last index of a specific item in the xtd::collections::generic::list <type_t>.
 
virtual void pop_back ()
 Removes the last element of the container.
 
virtual void push_back (const type_t &value)
 Appends the given element value to the end of the container.
 
virtual void push_back (type_t &&value)
 Appends the given element value to the end of the container.
 
bool remove (const type_t &item) override
 Removes the first occurrence of a specific object from the xtd::collections::generic::list <type_t>.
 
xtd::size remove_all (const xtd::predicate< const type_t & > &match)
 Removes all the elements that match the conditions defined by the specified predicate.
 
void remove_at (size_type index) override
 Removes the element at the specified index of the xtd::collections::generic::list <type_t>.
 
virtual void remove_range (size_type index, size_type count)
 Removes a range of elements from the xtd::collections::generic::list <type_t>.
 
virtual void reserve (size_type new_cap)
 Increase the capacity of the vector (the total number of elements that the vector can hold without requiring reallocation) to a value that's greater or equal to new_cap. If new_cap is greater than the current capacity(), new storage is allocated, otherwise the function does nothing.
 
virtual void resize (size_type count)
 Resizes the container to contain count elements, does nothing if count == size(). @param count The new size of the container. @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.
 
virtual void resize (size_type count, const value_type &value)
 Resizes the container to contain count elements, does nothing if count == size(). @param count The new size of the container. @param value The value to initialize the new elements with. @remarks If the current size is greater thancount, the container is reduced to its firstcountelements. @remarks If the current size is less thancount, additional copies ofvalue` are appended.
 
void reverse ()
 Reverses the order of the elements in the entire xtd::collections::generic::list <type_t>.
 
void reverse (size_type index, size_type count)
 Reverses the order of the elements in the specified range.
 
virtual void shrink_to_fit ()
 Requests the removal of unused capacity.
 
list< type_t > slice (size_type start, size_type length) const
 Creates a shallow copy of a range of elements in the source xtd::collections::generic::list <type_t>.
 
void sort ()
 Sorts the elements in the entire xtd::collections::generic::list <type_t> using the default comparer.
 
void sort (xtd::comparison< const type_t & > comparison)
 Sorts the elements in the entire xtd::collections::generic::list <type_t> using the specified xtd::comparison <type_t>.
 
void sort (const xtd::collections::generic::icomparer< type_t > &comparer)
 Sorts the elements in the entire xtd::collections::generic::list <type_t> using the specified comparer.
 
void sort (xtd::size index, xtd::size count, const xtd::collections::generic::icomparer< type_t > &comparer)
 Sorts the elements in a range of elements in xtd::collections::generic::list <type_t> using the specified comparer.
 
virtual void swap (list &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.
 
virtual xtd::array< value_typeto_array () const noexcept
 Copies the elements of the xtd::collections::generic::list <type_t> to a new array.
 
string to_string () const noexcept override
 Returns a xtd::string that represents the current object.
 
virtual void trim_excess ()
 Sets the capacity to the actual number of elements in the xtd::collections::generic::list <type_t>, if that number is less than a threshold value.
 
bool true_for_all (xtd::predicate< const type_t & > match) const
 Determines whether every element in the xtd::collections::generic::list <type_t> matches the conditions defined by the specified predicate.
 

Public Operators

listoperator= (const list &other)=default
 Copy assignment operator. Replaces the contents with a copy of the contents of other.
 
listoperator= (list &&other) noexcept
 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.
 
listoperator= (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.
 

Additional Inherited Members

- Public Types inherited from xtd::collections::generic::ilist< type_t >
using iterator = typename icollection< type_t >::iterator
 Represents the iterator of xtd::collections::generic::ienumerable value type.
 
using const_iterator = typename icollection< type_t >::const_iterator
 Represents the const iterator of xtd::collections::generic::ienumerable value type.
 
- Public Types inherited from xtd::collections::generic::icollection< type_t >
using value_type = typename xtd::collections::generic::ienumerable< type_t >::value_type
 Represents the xtd::collections::generic::icollection value type.
 
using iterator = typename xtd::collections::generic::ienumerable< type_t >::iterator
 Represents the iterator of xtd::collections::generic::ienumerable value type.
 
using const_iterator = typename xtd::collections::generic::ienumerable< type_t >::const_iterator
 Represents the const iterator of xtd::collections::generic::ienumerable value type.
 
- Public Types inherited from xtd::collections::generic::ienumerable< type_t >
using value_type = type_t
 Represents the xtd::collections::generic::ienumerable value type.
 
using iterator = typename xtd::collections::generic::extensions::enumerable_iterators< type_t, xtd::collections::generic::ienumerable< type_t > >::iterator
 Represents the iterator of xtd::collections::generic::ienumerable value type.
 
using const_iterator = typename xtd::collections::generic::extensions::enumerable_iterators< type_t, xtd::collections::generic::ienumerable< type_t > >::const_iterator
 Represents the const iterator of xtd::collections::generic::ienumerable value type.
 
- Public Types inherited from xtd::collections::generic::extensions::enumerable_iterators< type_t, xtd::collections::generic::ienumerable< type_t > >
using iterator = enumerable_iterator
 Represents the iterator of enumarable value type.
 
using const_iterator = const enumerable_iterator
 Represents the const iterator of enumarable value type.
 
- Public Types inherited from xtd::collections::generic::extensions::enumerable< ienumerable< type_t >, type_t >
using enumerable_type = ienumerable< type_t >
 Represents the ienumerable enumerable type.
 
using source_type = type_t
 Represents the ienumerable source type.
 
using ienumerable = typename xtd::linq::enumerable::ienumerable< type_t >
 Represents the ienumerable value type.
 
using list = typename xtd::linq::enumerable::list< type_t >
 Represents the list value type.
 
- Static Public Attributes inherited from xtd::collections::generic::ilist< type_t >
static constexpr xtd::size npos
 This is a special value equal to the maximum value representable by the type xtd::size.
 
- Public Member Functions inherited from xtd::object
 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::uptr< object_t > memberwise_clone () const
 Creates a shallow copy of the current object.
 
- Public Member Functions inherited from xtd::collections::generic::ilist< type_t >
- Public Member Functions inherited from xtd::collections::generic::icollection< type_t >
- Public Member Functions inherited from xtd::collections::generic::ienumerable< type_t >
- Public Member Functions inherited from xtd::collections::generic::extensions::enumerable_iterators< type_t, xtd::collections::generic::ienumerable< type_t > >
- Public Member Functions inherited from xtd::collections::generic::extensions::enumerable< ienumerable< type_t >, type_t >
type_t aggregate (const std::function< type_t(const type_t &, const type_t &)> &func) const
 Applies an accumulator function over a sequence.
 
type_t aggregate (const type_t &seed, const std::function< type_t(const type_t &, const type_t &)> &func) const
 Applies an accumulator function over a sequence. The specified seed value is used as the initial accumulator value.
 
accumulate_t aggregate (const accumulate_t &seed, const std::function< accumulate_t(const type_t &, const accumulate_t &)> &func) const
 Applies an accumulator function over a sequence. The specified seed value is used as the initial accumulator value.
 
type_t aggregate (const type_t &seed, const std::function< type_t(const type_t &, const type_t &)> &func, const std::function< type_t(const type_t &)> &result_selector) const
 Applies an accumulator function over a sequence. The specified seed value is used as the initial accumulator value, and the specified function is used to select the result value.
 
result_t aggregate (const accumulate_t &seed, const std::function< accumulate_t(const type_t &, const accumulate_t &)> &func, const std::function< result_t(const accumulate_t &)> &result_selector) const
 Applies an accumulator function over a sequence. The specified seed value is used as the initial accumulator value, and the specified function is used to select the result value.
 
bool all (const std::function< bool(const type_t &)> &predicate) const
 Determines whether all elements of a sequence satisfy a condition.
 
bool any () const noexcept
 Determines whether a sequence contains any elements.
 
bool any (const std::function< bool(const type_t &)> &predicate) const
 Determines whether any element of a sequence satisfies a condition.
 
const ienumerable< type_t > & append (const type_t &element) const noexcept
 Appends a value to the end of the sequence.
 
const ienumerable< type_t > & as_enumerable () const noexcept
 Returns the input typed as xtd::collections::generic::ienumerable <type_t>.
 
auto average () const noexcept
 Computes the average of a sequence of source_t values.
 
const ienumerable< result_t > & cast () const noexcept
 Casts the elements of an xtd::collections::generic::ienumerable to the specified type.
 
const ienumerable< xtd::array< type_t > > & chunk (size_t size) const
 Splits the elements of a sequence into chunks of size at most size.
 
const ienumerable< type_t > & concat (const ienumerable< type_t > &second) const noexcept
 Concatenates two sequences.
 
bool contains (const type_t &value) const noexcept
 Determines whether a sequence contains a specified element by using the default equality comparer.
 
bool contains (const type_t &value, const xtd::collections::generic::iequality_comparer< type_t > &comparer) const noexcept
 Determines whether a sequence contains a specified element by using a specified equality comparer.
 
size_t count () const noexcept
 Returns the number of elements in current sequence.
 
size_t count (const std::function< bool(const type_t &)> &predicate) const noexcept
 Returns a number that represents how many elements in the specified sequence satisfy a condition.
 
const ienumerable< key_value_pair< key_t, xtd::size > > & count_by (const std::function< key_t(const type_t &)> &key_selector) const noexcept
 Returns the count of elements in the current sequence grouped by key.
 
const ienumerable< key_value_pair< key_t, xtd::size > > & count_by (const std::function< key_t(const type_t &)> &key_selector, const iequality_comparer< key_t > &key_comparer) const noexcept
 Returns the count of elements in the current sequence grouped by key.
 
const ienumerable< type_t > & default_if_empty () const noexcept
 Returns the elements of the specified sequence or the type parameter's default value in a singleton collection if the current sequence is empty.
 
const ienumerable< type_t > & default_if_empty (const type_t &default_value) const noexcept
 Returns the elements of the specified sequence or the specified value in a singleton collection if the current sequence is empty.
 
type_t first_or_default (const std::function< bool(const type_t &)> &predicate, const type_t &default_value) const noexcept
 Returns the first element of the sequence that satisfies a condition, or a specified default value if no such element is found.
 
type_t first_or_default (const std::function< bool(const type_t &)> &predicate) const noexcept
 Returns the first element of the sequence that satisfies a condition or a default value if no such element is found.
 
type_t first_or_default (const type_t default_value) const noexcept
 Returns the first element of the sequence that satisfies a condition or a default value if no such element is found.
 
type_t first_or_default () const noexcept
 Returns the first element of the sequence that satisfies a condition or a default value if no such element is found.
 
const ienumerable< result_t > & select (const std::function< result_t(const type_t &)> &selector) const
 Projects each element of a sequence into a new form.
 
const ienumerable< type_t > & select (const std::function< type_t(const type_t &)> &selector) const
 Projects each element of a sequence into a new form.
 
const ienumerable< result_t > & select (const std::function< result_t(const type_t &, size_t index)> &selector) const
 Projects each element of a sequence into a new form by incorporating the element's index.
 
const ienumerable< type_t > & select (const std::function< type_t(const type_t &, size_t index)> &selector) const
 Projects each element of a sequence into a new form by incorporating the element's index.
 
const list< type_t > & to_list () const noexcept
 Creates a xtd::collections::generic::list <type_t> from an xtd::collections::generic::ienumerable <type_t>.
 
const ienumerable< type_t > & where (const std::function< bool(const type_t &)> &predicate) const
 Filters a sequence of values based on a predicate.
 
const ienumerable< type_t > & where (const std::function< bool(const type_t &, size_t)> &predicate) const
 Filters a sequence of values based on a predicate. Each element's index is used in the logic of the predicate function.
 
- Public Member Functions inherited from xtd::collections::generic::extensions::collection_operators< type_t, icollection< type_t > >
virtual icollection< type_t > & operator<< (const type_t &item)
 The shift left operator adds an item to the xtd::collections::generic::icollection <type_t>.
 
virtual icollection< type_t > & operator>> (const type_t &item)
 The shift right operator removes tthe first occurrence of a specific object from the xtd::collections::generic::icollection <type_t>.
 
- Public Member Functions inherited from xtd::iequatable< xtd::collections::generic::list< type_t, allocator_t > >
- Static Public Member Functions inherited from xtd::object
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.
 
- Static Public Member Functions inherited from xtd::collections::generic::extensions::enumerable_iterators< type_t, xtd::collections::generic::ienumerable< type_t > >
static target_collection_t::const_iterator to_iterator (typename source_collection_t::const_iterator &value, const source_collection_t &source_collection, const target_collection_t &target_collection) noexcept
 Converts source iterator to target iterator.
 
static target_collection_t::iterator to_iterator (typename source_collection_t::iterator &value, const source_collection_t &source_collection, const target_collection_t &target_collection) noexcept
 Converts source iterator to target iterator.
 
static target_collection_t::const_iterator to_iterator (typename source_collection_t::const_iterator &value, source_collection_t &source_collection, target_collection_t &target_collection) noexcept
 Converts source iterator to target iterator.
 
static target_collection_t::iterator to_iterator (typename source_collection_t::iterator &value, source_collection_t &source_collection, target_collection_t &target_collection) noexcept
 Converts source iterator to target iterator.
 

Member Typedef Documentation

◆ value_type

template<class type_t , class allocator_t >
using xtd::collections::generic::list< type_t, allocator_t >::value_type = type_t

Represents the list value type.

◆ allocator_type

template<class type_t , class allocator_t >
using xtd::collections::generic::list< type_t, allocator_t >::allocator_type = typename xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, value_type>::value, xtd::byte, value_type>::type>

Represents the list allocator type.

◆ base_type

template<class type_t , class allocator_t >
using xtd::collections::generic::list< type_t, allocator_t >::base_type = std::vector<typename std::conditional<std::is_same<bool, value_type>::value, xtd::byte, value_type>::type, allocator_type>

Represents the list base type.

◆ const_base_type

template<class type_t , class allocator_t >
using xtd::collections::generic::list< type_t, allocator_t >::const_base_type = const base_type

Represents the list base type.

◆ size_type

template<class type_t , class allocator_t >
using xtd::collections::generic::list< type_t, allocator_t >::size_type = xtd::size

Represents the list size type (usually xtd::size).

◆ difference_type

template<class type_t , class allocator_t >
using xtd::collections::generic::list< type_t, allocator_t >::difference_type = xtd::ptrdiff

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

◆ reference

template<class type_t , class allocator_t >
using xtd::collections::generic::list< type_t, allocator_t >::reference = value_type&

Represents the reference of list value type.

◆ const_reference

template<class type_t , class allocator_t >
using xtd::collections::generic::list< type_t, allocator_t >::const_reference = const value_type&

Represents the const reference of list value type.

◆ pointer

template<class type_t , class allocator_t >
using xtd::collections::generic::list< type_t, allocator_t >::pointer = value_type*

Represents the pointer of list value type.

◆ const_pointer

template<class type_t , class allocator_t >
using xtd::collections::generic::list< type_t, allocator_t >::const_pointer = const value_type*

Represents the const pointer of list value type.

◆ iterator

template<class type_t , class allocator_t >
using xtd::collections::generic::list< type_t, allocator_t >::iterator = typename xtd::collections::generic::ienumerable<type_t>::iterator

Represents the iterator of list value type.

◆ const_iterator

template<class type_t , class allocator_t >
using xtd::collections::generic::list< type_t, allocator_t >::const_iterator = typename xtd::collections::generic::ienumerable<type_t>::const_iterator

Represents the const iterator of list value type.

◆ reverse_iterator

template<class type_t , class allocator_t >
using xtd::collections::generic::list< type_t, allocator_t >::reverse_iterator = typename base_type::reverse_iterator

Represents the reverse iterator of list value type.

◆ const_reverse_iterator

template<class type_t , class allocator_t >
using xtd::collections::generic::list< type_t, allocator_t >::const_reverse_iterator = typename base_type::const_reverse_iterator

Represents the const reverse iterator of list value type.

◆ read_only_collection

template<class type_t , class allocator_t >
using xtd::collections::generic::list< type_t, allocator_t >::read_only_collection = xtd::collections::object_model::read_only_collection<value_type>

Represents the read only collection of of list.

Constructor & Destructor Documentation

◆ list() [1/15]

template<class type_t , class allocator_t >
xtd::collections::generic::list< type_t, allocator_t >::list ( )
defaultnoexcept

Initializes a new instance of the xtd::collections::generic::list class that is empty.

Examples
The code example adds, inserts, and removes items, showing how the capacity changes as these methods are used.
#include <xtd/xtd>
using namespace xtd;
using namespace xtd::collections::generic;
// Simple business object. A part_id is used to identify a part
// but the part name be different for the same Id.
class part : public object, public iequatable<part> {
public:
string part_name;
int part_id = 0;
part() = default;
part(const string& name, int id) : part_name {name}, part_id {id} {}
string to_string() const noexcept override {return string::format("ID: {} Name: {}", part_id, part_name);}
bool equals(const object& obj) const noexcept override {return is<part>(obj) && equals(as<part>(obj));}
bool equals(const part& other) const noexcept override {return part_id == other.part_id;}
size get_hash_code() const noexcept override {return object::get_hash_code();}
};
class example {
public:
static auto main() -> void {
auto parts = list<part> {};
console::write_line("\ncapacity: {0}", parts.capacity());
parts.add(part {"crank arm", 1234});
parts.add(part {"chain ring", 1334});
parts.add(part {"seat", 1434});
parts.add(part {"cassette", 1534});
parts.add(part {"shift lever", 1634});
console::write_line();
for (auto part : parts)
console::write_line(part);
console::write_line("\ncapacity: {0}", parts.capacity());
console::write_line("count: {0}", parts.count());
parts.trim_excess();
console::write_line("\ntrim_excess()");
console::write_line("capacity: {0}", parts.capacity());
console::write_line("count: {0}", parts.count());
parts.clear();
console::write_line("\nclear()");
console::write_line("capacity: {0}", parts.capacity());
console::write_line("count: {0}", parts.count());
}
};
startup_(example::main);
// This code produces the following output :
//
// capacity: 0
//
// ID: 1234 Name: crank arm
// ID: 1334 Name: chain ring
// ID: 1434 Name: seat
// ID: 1534 Name: cassette
// ID: 1634 Name: shift lever
//
// capacity: 8
// count: 5
//
// trim_excess()
// capacity: 5
// count: 5
//
// clear()
// capacity: 5
// count: 0
Remarks
The capacity of a xtd::collections::generic::list is the number of elements that the xtd::collections::generic::list can hold. As elements are added to a xtd::collections::generic::list, the capacity is automatically increased as required by reallocating the internal array.
If the size of the collection can be estimated, using the xtd::collections::generic::list (size_type) constructor and specifying the initial capacity eliminates the need to perform a number of resizing operations while adding elements to the xtd::collections::generic::list.
The capacity can be decreased by calling the xtd::collections::generic::list::trim_excess method or by setting the xtd::collections::generic::list::capacity property explicitly. Decreasing the capacity reallocates memory and copies all the elements in the xtd::collections::generic::list.
This constructor is an O(1) operation.
The following code example demonstrates the default constructor of the xtd::collections::generic::list generic class. The default constructor creates a list with the default capacity, as demonstrated by displaying the xtd::collections::generic::list::capacity property.

◆ list() [2/15]

template<class type_t , class allocator_t >
xtd::collections::generic::list< type_t, allocator_t >::list ( const allocator_type alloc)
inlineexplicitnoexcept

Constructs an empty container with the given allocator.

Parameters
allocThe allocator to use for all memory allocations of this container.

◆ list() [3/15]

template<class type_t , class allocator_t >
xtd::collections::generic::list< type_t, allocator_t >::list ( size_type  count,
const type_t &  value,
const allocator_type alloc = allocator_type() 
)
inline

Constructs the container with specified count copies of elements with specified value.

Parameters
countThe size of the container.
valueThe value to initialize elements of the container with.
allocThe allocator to use for all memory allocations of this container.

◆ list() [4/15]

template<class type_t , class allocator_t >
xtd::collections::generic::list< type_t, allocator_t >::list ( size_type  count,
const allocator_type alloc = allocator_type() 
)
inlineexplicit

Constructs the container with specified count default-inserted instances of type_t. No copies are made.

Parameters
countThe size of the container.
allocThe allocator to use for all memory allocations of this container.

◆ list() [5/15]

template<class type_t , class allocator_t >
template<class input_iterator_t >
xtd::collections::generic::list< type_t, allocator_t >::list ( input_iterator_t  first,
input_iterator_t  last,
const allocator_type alloc = allocator_type() 
)
inline

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

Parameters
firstThe first iterator the range to copy the elements from.
lastThe last iterator the range to copy the elements from.
allocThe allocator to use for all memory allocations of this container.

◆ list() [6/15]

template<class type_t , class allocator_t >
xtd::collections::generic::list< type_t, allocator_t >::list ( const xtd::collections::generic::ienumerable< type_t > &  collection,
const allocator_type alloc = allocator_type() 
)
inline

Initializes a new instance of the xtd::collections::generic::list <type_t> class that contains elements copied from the specified collection and has sufficient capacity to accommodate the number of elements copied.

Parameters
collectionThe collection whose elements are copied to the new list.
allocThe allocator to use for all memory allocations of this container.
Examples
The following code example demonstrates the xtd::collections::generic::list <type_t> constructor and various methods of the xtd::collections::generic::list <type_t> class that act on ranges. An array of strings is created and passed to the constructor, populating the list with the elements of the array. The xtd::collections::generic::list::capacity property is then displayed, to show that the initial capacity is exactly what is required to hold the input elements.
#include <xtd/xtd>
using namespace xtd;
using namespace xtd::collections::generic;
class example {
public:
static auto main() -> void {
auto input = array<string> {"Brachiosaurus", "Amargasaurus", "Mamenchisaurus"};
auto dinosaurs = list<string>(input);
console::write_line("\ncapacity: {0}", dinosaurs.capacity());
console::write_line();
for (auto dinosaur : dinosaurs)
console::write_line(dinosaur);
console::write_line("\nadd_range(dinosaurs)");
dinosaurs.add_range(dinosaurs);
console::write_line();
for(auto dinosaur : dinosaurs)
console::write_line(dinosaur);
console::write_line("\nremove_range(2, 2)");
dinosaurs.remove_range(2, 2);
console::write_line();
for(auto dinosaur : dinosaurs)
console::write_line(dinosaur);
input = {"Tyrannosaurus", "Deinonychus", "Velociraptor"};
console::write_line("\ninsert_range(3, input)");
dinosaurs.insert_range(3, input);
console::write_line();
for(auto dinosaur : dinosaurs)
console::write_line(dinosaur);
console::write_line("\noutput = dinosaurs.get_range(2, 3).to_array()");
auto output = dinosaurs.get_range(2, 3).to_array();
console::write_line();
for (auto dinosaur : output)
console::write_line(dinosaur);
}
};
startup_(example::main);
// This code produces the following output :
//
//
// capacity: 3
//
// Brachiosaurus
// Amargasaurus
// Mamenchisaurus
//
// add_range(dinosaurs)
//
// Brachiosaurus
// Amargasaurus
// Mamenchisaurus
// Brachiosaurus
// Amargasaurus
// Mamenchisaurus
//
// remove_range(2, 2)
//
// Brachiosaurus
// Amargasaurus
// Amargasaurus
// Mamenchisaurus
//
// insert_range(3, input)
//
// Brachiosaurus
// Amargasaurus
// Amargasaurus
// Tyrannosaurus
// Deinonychus
// Velociraptor
// Mamenchisaurus
//
// output = dinosaurs.get_range(2, 3).to_array()
//
// Amargasaurus
// Tyrannosaurus
// Deinonychus
Provides methods for creating, manipulating, searching, and sorting arrays, thereby serving as the ba...
Definition array.hpp:59
Remarks
The elements are copied onto the xtd::collections::generic::list <type_t> in the same order they are read by the enumerator of the collection.
This constructor is an O(n) operation, where n is the number of elements in collection.

◆ list() [7/15]

template<class type_t , class allocator_t >
xtd::collections::generic::list< type_t, allocator_t >::list ( const list< type_t, allocator_t > &  list)
inline

Default copy constructor with specified list.

Parameters
listThe xtd::collections::generic::list which elements will be inserted from.

◆ list() [8/15]

template<class type_t , class allocator_t >
xtd::collections::generic::list< type_t, allocator_t >::list ( const base_type list)
inline

Copy constructor with specified base type list.

Parameters
listThe xtd::collections::generic::list::base_type which elements will be inserted from.

◆ list() [9/15]

template<class type_t , class allocator_t >
xtd::collections::generic::list< type_t, allocator_t >::list ( const list< type_t, allocator_t > &  list,
const allocator_type alloc 
)
inline

Default copy constructor with specified list, and allocator.

Parameters
listThe xtd::collections::generic::list which elements will be inserted from.
allocThe allocator to use for all memory allocations of this container.

◆ list() [10/15]

template<class type_t , class allocator_t >
xtd::collections::generic::list< type_t, allocator_t >::list ( const base_type list,
const allocator_type alloc 
)
inline

Default copy constructor with specified base type list, and allocator.

Parameters
listThe xtd::collections::generic::list which elements will be inserted from.
allocThe allocator to use for all memory allocations of this container.

◆ list() [11/15]

template<class type_t , class allocator_t >
xtd::collections::generic::list< type_t, allocator_t >::list ( std::initializer_list< type_t >  items,
const allocator_type alloc = allocator_type() 
)
inline

Constructs the container with the contents of the specified initializer list, and allocator.

Parameters
itemsThe initializer list to initialize the elements of the container with.
allocThe allocator to use for all memory allocations of this container.

◆ list() [12/15]

template<class type_t , class allocator_t >
xtd::collections::generic::list< type_t, allocator_t >::list ( list< type_t, allocator_t > &&  other)
inline

Move constructor with specified list.

Parameters
listThe xtd::collections::generic::list::base_type which elements will be moved from.

◆ list() [13/15]

template<class type_t , class allocator_t >
xtd::collections::generic::list< type_t, allocator_t >::list ( base_type &&  other)
inline

Move constructor with specified base type list.

Parameters
listThe xtd::collections::generic::list::base_type which elements will be moved from.

◆ list() [14/15]

template<class type_t , class allocator_t >
xtd::collections::generic::list< type_t, allocator_t >::list ( list< type_t, allocator_t > &&  other,
const allocator_type alloc 
)
inline

Move constructor with specified list, and allocator.

Parameters
listThe xtd::collections::generic::list::base_type which elements will be moved from.
allocThe allocator to use for all memory allocations of this container.

◆ list() [15/15]

template<class type_t , class allocator_t >
xtd::collections::generic::list< type_t, allocator_t >::list ( base_type &&  other,
const allocator_type alloc 
)
inline

Move constructor with specified base tyoe list, and allocator.

Parameters
listThe xtd::collections::generic::list::base_type which elements will be moved from.
allocThe allocator to use for all memory allocations of this container.

Member Function Documentation

◆ back() [1/2]

template<class type_t , class allocator_t >
virtual reference xtd::collections::generic::list< type_t, allocator_t >::back ( )
inlinevirtual

Returns a reference to the last element in the container.

Returns
Reference to the first element.
Remarks
Calling front on an empty container causes undefined behavior.

◆ back() [2/2]

template<class type_t , class allocator_t >
virtual const_reference xtd::collections::generic::list< type_t, allocator_t >::back ( ) const
inlinevirtual

Returns a reference to the last element in the container.

Returns
Reference to the first element.
Remarks
Calling front on an empty container causes undefined behavior.

◆ begin() [1/2]

template<class type_t , class allocator_t >
const_iterator xtd::collections::generic::list< type_t, allocator_t >::begin ( ) const
inlineoverridevirtualnoexcept

Returns an iterator to the first element of the enumarable.

Returns
Iterator to the first element.

Reimplemented from xtd::collections::generic::extensions::enumerable_iterators< type_t, xtd::collections::generic::ienumerable< type_t > >.

Examples
console_clear.cpp.

◆ begin() [2/2]

template<class type_t , class allocator_t >
iterator xtd::collections::generic::list< type_t, allocator_t >::begin ( )
inlineoverridevirtualnoexcept

Returns an iterator to the first element of the enumarable.

Returns
Iterator to the first element.

Reimplemented from xtd::collections::generic::extensions::enumerable_iterators< type_t, xtd::collections::generic::ienumerable< type_t > >.

◆ capacity() [1/2]

template<class type_t , class allocator_t >
virtual size_type xtd::collections::generic::list< type_t, allocator_t >::capacity ( ) const
inlinevirtualnoexcept

Gets the total number of elements the internal data structure can hold without resizing.

Returns
Capacity of the currently allocated storage. @exceptions xtd::argument_out_of_range_exception xtd::collections::generic::list::capacity is set to a value that is less than xtd::collections::generic::list::count.
Examples
The following example demonstrates how to add, remove, and insert a simple business object in a xtd::collections::generic::list <type_t>.
#include <xtd/xtd>
using namespace xtd;
using namespace xtd::collections::generic;
// Simple business object. A part_id is used to identify a part
// but the part name be different for the same Id.
class part : public object, public iequatable<part> {
public:
string part_name;
int part_id = 0;
part() = default;
part(const string& name, int id) : part_name {name}, part_id {id} {}
string to_string() const noexcept override {return string::format("ID: {} Name: {}", part_id, part_name);}
bool equals(const object& obj) const noexcept override {return is<part>(obj) && equals(as<part>(obj));}
bool equals(const part& other) const noexcept override {return part_id == other.part_id;}
size get_hash_code() const noexcept override {return object::get_hash_code();}
};
class example {
public:
static auto main() -> void {
auto parts = list<part> {};
console::write_line("\ncapacity: {0}", parts.capacity());
parts.add(part {"crank arm", 1234});
parts.add(part {"chain ring", 1334});
parts.add(part {"seat", 1434});
parts.add(part {"cassette", 1534});
parts.add(part {"shift lever", 1634});
console::write_line();
for (auto part : parts)
console::write_line(part);
console::write_line("\ncapacity: {0}", parts.capacity());
console::write_line("count: {0}", parts.count());
parts.trim_excess();
console::write_line("\ntrim_excess()");
console::write_line("capacity: {0}", parts.capacity());
console::write_line("count: {0}", parts.count());
parts.clear();
console::write_line("\nclear()");
console::write_line("capacity: {0}", parts.capacity());
console::write_line("count: {0}", parts.count());
}
};
startup_(example::main);
// This code produces the following output :
//
// capacity: 0
//
// ID: 1234 Name: crank arm
// ID: 1334 Name: chain ring
// ID: 1434 Name: seat
// ID: 1534 Name: cassette
// ID: 1634 Name: shift lever
//
// capacity: 8
// count: 5
//
// trim_excess()
// capacity: 5
// count: 5
//
// clear()
// capacity: 5
// count: 0
The following example demonstrates several properties and methods of the xtd::collections::generic::list <type_t> generic class of type string. (For an example of a xtd::collections::generic::list <type_t> of complex types, see the xtd::collections::generic::list::contains method.)

The parameterless constructor is used to create a list of strings with the default capacity. The xtd::collections::generic::list::capacity property is displayed and then the xtd::collections::generic::list::add method is used to add several items. The items are listed, and the xtd::collections::generic::list::capacity property is displayed again, along with the xtd::collections::generic::list::count property, to show that the capacity has been increased as needed.

The xtd::collections::generic::list::contains method is used to test for the presence of an item in the list, the Insert method is used to insert a new item in the middle of the list, and the contents of the list are displayed again.

The default xtd::collections::generic::list::operator [] is used to retrieve an item, the xtd::collections::generic::list::remove method is used to remove the first instance of the duplicate item added earlier, and the contents are displayed again. The xtd::collections::generic::list::remove method always removes the first instance it encounters.

The xtd::collections::generic::list::trim_excess method is used to reduce the capacity to match the count, and the xtd::collections::generic::list::capacity and xtd::collections::generic::list::count properties are displayed. If the unused capacity had been less than 10 percent of total capacity, the list would not have been resized.

Finally, the xtd::collections::generic::list::clear method is used to remove all items from the list, and the xtd::collections::generic::list::capacity and xtd::collections::generic::list::count properties are displayed.

#include <xtd/xtd>
using namespace xtd;
using namespace xtd::collections::generic;
class example {
public:
static auto main() -> void {
auto dinosaurs = list<string> {};
console::write_line("\ncapacity: {0}", dinosaurs.capacity());
dinosaurs.add("Tyrannosaurus");
dinosaurs.add("Amargasaurus");
dinosaurs.add("Mamenchisaurus");
dinosaurs.add("Deinonychus");
dinosaurs.add("Compsognathus");
console::write_line();
for (auto dinosaur : dinosaurs)
console::write_line(dinosaur);
console::write_line("\ncapacity: {0}", dinosaurs.capacity());
console::write_line("count: {0}", dinosaurs.count());
console::write_line("\ncontains(\"Deinonychus\"): {0}", dinosaurs.contains("Deinonychus"));
console::write_line("\ninsert(2, \"Compsognathus\")");
dinosaurs.insert(2, "Compsognathus");
console::write_line();
for (auto dinosaur : dinosaurs)
console::write_line(dinosaur);
// Shows accessing the list using the Item property.
console::write_line("\ndinosaurs[3]: {0}", dinosaurs[3]);
console::write_line("\nremove(\"Compsognathus\")");
dinosaurs.remove("Compsognathus");
console::write_line();
for (auto dinosaur : dinosaurs)
console::write_line(dinosaur);
dinosaurs.trim_excess();
console::write_line("\ntrim_excess()");
console::write_line("capacity: {0}", dinosaurs.capacity());
console::write_line("count: {0}", dinosaurs.count());
dinosaurs.clear();
console::write_line("\nclear()");
console::write_line("capacity: {0}", dinosaurs.capacity());
console::write_line("count: {0}", dinosaurs.count());
}
};
startup_(example::main);
// This code produces the following output :
//
// capacity: 0
//
// Tyrannosaurus
// Amargasaurus
// Mamenchisaurus
// Deinonychus
// Compsognathus
//
// capacity: 8
// count: 5
//
// contains("Deinonychus"): true
//
// insert(2, "Compsognathus")
//
// Tyrannosaurus
// Amargasaurus
// Compsognathus
// Mamenchisaurus
// Deinonychus
// Compsognathus
//
// dinosaurs[3]: Mamenchisaurus
//
// remove("Compsognathus")
//
// Tyrannosaurus
// Amargasaurus
// Mamenchisaurus
// Deinonychus
// Compsognathus
//
// trim_excess()
// capacity: 5
// count: 5
// clear()
// capacity: 5
// count: 0
Remarks
xtd::collections::generic::list::capacity is the number of elements that the xtd::collections::generic::list <type_t> can store before resizing is required, whereas xtd::collections::generic::list::count is the number of elements that are actually in the xtd::collections::generic::list <type_t>.
xtd::collections::generic::list::capacity is always greater than or equal to xtd::collections::generic::list::count. If xtd::collections::generic::list::count exceeds xtd::collections::generic::list::capacity while adding elements, the capacity is increased by automatically reallocating the internal array before copying the old elements and adding the new elements.
If the capacity is significantly larger than the count and you want to reduce the memory used by the xtd::collections::generic::list <type_t>, you can decrease capacity by calling the xtd::collections::generic::list::trim_excess method or by setting the xtd::collections::generic::list::capacity property explicitly to a lower value. When the value of xtd::collections::generic::list::capacity is set explicitly, the internal array is also reallocated to accommodate the specified capacity, and all the elements are copied.
Retrieving the value of this property is an O(1) operation; setting the property is an O(n) operation, where n is the new capacity.

◆ capacity() [2/2]

template<class type_t , class allocator_t >
virtual void xtd::collections::generic::list< type_t, allocator_t >::capacity ( size_type  value)
inlinevirtual

Sets the total number of elements the internal data structure can hold without resizing.

Returns
Capacity of the currently allocated storage. @exceptions xtd::argument_out_of_range_exception xtd::collections::generic::list::capacity is set to a value that is less than xtd::collections::generic::list::count.
Examples
The following example demonstrates how to add, remove, and insert a simple business object in a xtd::collections::generic::list <type_t>.
#include <xtd/xtd>
using namespace xtd;
using namespace xtd::collections::generic;
// Simple business object. A part_id is used to identify a part
// but the part name be different for the same Id.
class part : public object, public iequatable<part> {
public:
string part_name;
int part_id = 0;
part() = default;
part(const string& name, int id) : part_name {name}, part_id {id} {}
string to_string() const noexcept override {return string::format("ID: {} Name: {}", part_id, part_name);}
bool equals(const object& obj) const noexcept override {return is<part>(obj) && equals(as<part>(obj));}
bool equals(const part& other) const noexcept override {return part_id == other.part_id;}
size get_hash_code() const noexcept override {return object::get_hash_code();}
};
class example {
public:
static auto main() -> void {
auto parts = list<part> {};
console::write_line("\ncapacity: {0}", parts.capacity());
parts.add(part {"crank arm", 1234});
parts.add(part {"chain ring", 1334});
parts.add(part {"seat", 1434});
parts.add(part {"cassette", 1534});
parts.add(part {"shift lever", 1634});
console::write_line();
for (auto part : parts)
console::write_line(part);
console::write_line("\ncapacity: {0}", parts.capacity());
console::write_line("count: {0}", parts.count());
parts.trim_excess();
console::write_line("\ntrim_excess()");
console::write_line("capacity: {0}", parts.capacity());
console::write_line("count: {0}", parts.count());
parts.clear();
console::write_line("\nclear()");
console::write_line("capacity: {0}", parts.capacity());
console::write_line("count: {0}", parts.count());
}
};
startup_(example::main);
// This code produces the following output :
//
// capacity: 0
//
// ID: 1234 Name: crank arm
// ID: 1334 Name: chain ring
// ID: 1434 Name: seat
// ID: 1534 Name: cassette
// ID: 1634 Name: shift lever
//
// capacity: 8
// count: 5
//
// trim_excess()
// capacity: 5
// count: 5
//
// clear()
// capacity: 5
// count: 0
The following example demonstrates several properties and methods of the xtd::collections::generic::list <type_t> generic class of type string. (For an example of a xtd::collections::generic::list <type_t> of complex types, see the xtd::collections::generic::list::contains method.)

The parameterless constructor is used to create a list of strings with the default capacity. The xtd::collections::generic::list::capacity property is displayed and then the xtd::collections::generic::list::add method is used to add several items. The items are listed, and the xtd::collections::generic::list::capacity property is displayed again, along with the xtd::collections::generic::list::count property, to show that the capacity has been increased as needed.

The xtd::collections::generic::list::contains method is used to test for the presence of an item in the list, the Insert method is used to insert a new item in the middle of the list, and the contents of the list are displayed again.

The default xtd::collections::generic::list::operator [] is used to retrieve an item, the xtd::collections::generic::list::remove method is used to remove the first instance of the duplicate item added earlier, and the contents are displayed again. The xtd::collections::generic::list::remove method always removes the first instance it encounters.

The xtd::collections::generic::list::trim_excess method is used to reduce the capacity to match the count, and the xtd::collections::generic::list::capacity and xtd::collections::generic::list::count properties are displayed. If the unused capacity had been less than 10 percent of total capacity, the list would not have been resized.

Finally, the xtd::collections::generic::list::clear method is used to remove all items from the list, and the xtd::collections::generic::list::capacity and xtd::collections::generic::list::count properties are displayed.

#include <xtd/xtd>
using namespace xtd;
using namespace xtd::collections::generic;
class example {
public:
static auto main() -> void {
auto dinosaurs = list<string> {};
console::write_line("\ncapacity: {0}", dinosaurs.capacity());
dinosaurs.add("Tyrannosaurus");
dinosaurs.add("Amargasaurus");
dinosaurs.add("Mamenchisaurus");
dinosaurs.add("Deinonychus");
dinosaurs.add("Compsognathus");
console::write_line();
for (auto dinosaur : dinosaurs)
console::write_line(dinosaur);
console::write_line("\ncapacity: {0}", dinosaurs.capacity());
console::write_line("count: {0}", dinosaurs.count());
console::write_line("\ncontains(\"Deinonychus\"): {0}", dinosaurs.contains("Deinonychus"));
console::write_line("\ninsert(2, \"Compsognathus\")");
dinosaurs.insert(2, "Compsognathus");
console::write_line();
for (auto dinosaur : dinosaurs)
console::write_line(dinosaur);
// Shows accessing the list using the Item property.
console::write_line("\ndinosaurs[3]: {0}", dinosaurs[3]);
console::write_line("\nremove(\"Compsognathus\")");
dinosaurs.remove("Compsognathus");
console::write_line();
for (auto dinosaur : dinosaurs)
console::write_line(dinosaur);
dinosaurs.trim_excess();
console::write_line("\ntrim_excess()");
console::write_line("capacity: {0}", dinosaurs.capacity());
console::write_line("count: {0}", dinosaurs.count());
dinosaurs.clear();
console::write_line("\nclear()");
console::write_line("capacity: {0}", dinosaurs.capacity());
console::write_line("count: {0}", dinosaurs.count());
}
};
startup_(example::main);
// This code produces the following output :
//
// capacity: 0
//
// Tyrannosaurus
// Amargasaurus
// Mamenchisaurus
// Deinonychus
// Compsognathus
//
// capacity: 8
// count: 5
//
// contains("Deinonychus"): true
//
// insert(2, "Compsognathus")
//
// Tyrannosaurus
// Amargasaurus
// Compsognathus
// Mamenchisaurus
// Deinonychus
// Compsognathus
//
// dinosaurs[3]: Mamenchisaurus
//
// remove("Compsognathus")
//
// Tyrannosaurus
// Amargasaurus
// Mamenchisaurus
// Deinonychus
// Compsognathus
//
// trim_excess()
// capacity: 5
// count: 5
// clear()
// capacity: 5
// count: 0
Remarks
xtd::collections::generic::list::capacity is the number of elements that the xtd::collections::generic::list <type_t> can store before resizing is required, whereas xtd::collections::generic::list::count is the number of elements that are actually in the xtd::collections::generic::list <type_t>.
xtd::collections::generic::list::capacity is always greater than or equal to xtd::collections::generic::list::count. If xtd::collections::generic::list::count exceeds xtd::collections::generic::list::capacity while adding elements, the capacity is increased by automatically reallocating the internal array before copying the old elements and adding the new elements.
If the capacity is significantly larger than the count and you want to reduce the memory used by the xtd::collections::generic::list <type_t>, you can decrease capacity by calling the xtd::collections::generic::list::trim_excess method or by setting the xtd::collections::generic::list::capacity property explicitly to a lower value. When the value of xtd::collections::generic::list::capacity is set explicitly, the internal array is also reallocated to accommodate the specified capacity, and all the elements are copied.
Retrieving the value of this property is an O(1) operation; setting the property is an O(n) operation, where n is the new capacity.

◆ cbegin()

template<class type_t , class allocator_t >
const_iterator xtd::collections::generic::list< type_t, allocator_t >::cbegin ( ) const
inlineoverridevirtualnoexcept

Returns an iterator to the first element of the enumarable.

Returns
Iterator to the first element.

Reimplemented from xtd::collections::generic::extensions::enumerable_iterators< type_t, xtd::collections::generic::ienumerable< type_t > >.

◆ cend()

template<class type_t , class allocator_t >
const_iterator xtd::collections::generic::list< type_t, allocator_t >::cend ( ) const
inlineoverridevirtualnoexcept

Returns an iterator to the element following the last element of the enumarable.

Returns
Iterator to the element following the last element.

Reimplemented from xtd::collections::generic::extensions::enumerable_iterators< type_t, xtd::collections::generic::ienumerable< type_t > >.

◆ count()

template<class type_t , class allocator_t >
size_type xtd::collections::generic::list< type_t, allocator_t >::count ( ) const
inlineoverridevirtualnoexcept

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

Returns
The number of elements contained in the xtd::collections::generic::list <type_t>.
Examples
The following example demonstrates how to add, remove, and insert a simple business object in a xtd::collections::generic::list <type_t>.
#include <xtd/xtd>
using namespace xtd;
using namespace xtd::collections::generic;
// Simple business object. A part_id is used to identify a part
// but the part name be different for the same Id.
class part : public object, public iequatable<part> {
public:
string part_name;
int part_id = 0;
part() = default;
part(const string& name, int id) : part_name {name}, part_id {id} {}
string to_string() const noexcept override {return string::format("ID: {} Name: {}", part_id, part_name);}
bool equals(const object& obj) const noexcept override {return is<part>(obj) && equals(as<part>(obj));}
bool equals(const part& other) const noexcept override {return part_id == other.part_id;}
size get_hash_code() const noexcept override {return object::get_hash_code();}
};
class example {
public:
static auto main() -> void {
auto parts = list<part> {};
console::write_line("\ncapacity: {0}", parts.capacity());
parts.add(part {"crank arm", 1234});
parts.add(part {"chain ring", 1334});
parts.add(part {"seat", 1434});
parts.add(part {"cassette", 1534});
parts.add(part {"shift lever", 1634});
console::write_line();
for (auto part : parts)
console::write_line(part);
console::write_line("\ncapacity: {0}", parts.capacity());
console::write_line("count: {0}", parts.count());
parts.trim_excess();
console::write_line("\ntrim_excess()");
console::write_line("capacity: {0}", parts.capacity());
console::write_line("count: {0}", parts.count());
parts.clear();
console::write_line("\nclear()");
console::write_line("capacity: {0}", parts.capacity());
console::write_line("count: {0}", parts.count());
}
};
startup_(example::main);
// This code produces the following output :
//
// capacity: 0
//
// ID: 1234 Name: crank arm
// ID: 1334 Name: chain ring
// ID: 1434 Name: seat
// ID: 1534 Name: cassette
// ID: 1634 Name: shift lever
//
// capacity: 8
// count: 5
//
// trim_excess()
// capacity: 5
// count: 5
//
// clear()
// capacity: 5
// count: 0
The following example demonstrates several properties and methods of the xtd::collections::generic::list <type_t> generic class of type string. (For an example of a xtd::collections::generic::list <type_t> of complex types, see the xtd::collections::generic::list::contains method.)

The parameterless constructor is used to create a list of strings with the default capacity. The xtd::collections::generic::list::capacity property is displayed and then the xtd::collections::generic::list::add method is used to add several items. The items are listed, and the xtd::collections::generic::list::capacity property is displayed again, along with the xtd::collections::generic::list::count property, to show that the capacity has been increased as needed.

The xtd::collections::generic::list::contains method is used to test for the presence of an item in the list, the Insert method is used to insert a new item in the middle of the list, and the contents of the list are displayed again.

The default xtd::collections::generic::list::operator [] is used to retrieve an item, the xtd::collections::generic::list::remove method is used to remove the first instance of the duplicate item added earlier, and the contents are displayed again. The xtd::collections::generic::list::remove method always removes the first instance it encounters.

The xtd::collections::generic::list::trim_excess method is used to reduce the capacity to match the count, and the xtd::collections::generic::list::capacity and xtd::collections::generic::list::count properties are displayed. If the unused capacity had been less than 10 percent of total capacity, the list would not have been resized.

Finally, the xtd::collections::generic::list::clear method is used to remove all items from the list, and the xtd::collections::generic::list::capacity and xtd::collections::generic::list::count properties are displayed.

#include <xtd/xtd>
using namespace xtd;
using namespace xtd::collections::generic;
class example {
public:
static auto main() -> void {
auto dinosaurs = list<string> {};
console::write_line("\ncapacity: {0}", dinosaurs.capacity());
dinosaurs.add("Tyrannosaurus");
dinosaurs.add("Amargasaurus");
dinosaurs.add("Mamenchisaurus");
dinosaurs.add("Deinonychus");
dinosaurs.add("Compsognathus");
console::write_line();
for (auto dinosaur : dinosaurs)
console::write_line(dinosaur);
console::write_line("\ncapacity: {0}", dinosaurs.capacity());
console::write_line("count: {0}", dinosaurs.count());
console::write_line("\ncontains(\"Deinonychus\"): {0}", dinosaurs.contains("Deinonychus"));
console::write_line("\ninsert(2, \"Compsognathus\")");
dinosaurs.insert(2, "Compsognathus");
console::write_line();
for (auto dinosaur : dinosaurs)
console::write_line(dinosaur);
// Shows accessing the list using the Item property.
console::write_line("\ndinosaurs[3]: {0}", dinosaurs[3]);
console::write_line("\nremove(\"Compsognathus\")");
dinosaurs.remove("Compsognathus");
console::write_line();
for (auto dinosaur : dinosaurs)
console::write_line(dinosaur);
dinosaurs.trim_excess();
console::write_line("\ntrim_excess()");
console::write_line("capacity: {0}", dinosaurs.capacity());
console::write_line("count: {0}", dinosaurs.count());
dinosaurs.clear();
console::write_line("\nclear()");
console::write_line("capacity: {0}", dinosaurs.capacity());
console::write_line("count: {0}", dinosaurs.count());
}
};
startup_(example::main);
// This code produces the following output :
//
// capacity: 0
//
// Tyrannosaurus
// Amargasaurus
// Mamenchisaurus
// Deinonychus
// Compsognathus
//
// capacity: 8
// count: 5
//
// contains("Deinonychus"): true
//
// insert(2, "Compsognathus")
//
// Tyrannosaurus
// Amargasaurus
// Compsognathus
// Mamenchisaurus
// Deinonychus
// Compsognathus
//
// dinosaurs[3]: Mamenchisaurus
//
// remove("Compsognathus")
//
// Tyrannosaurus
// Amargasaurus
// Mamenchisaurus
// Deinonychus
// Compsognathus
//
// trim_excess()
// capacity: 5
// count: 5
// clear()
// capacity: 5
// count: 0
Remarks
xtd::collections::generic::list::capacity is the number of elements that the xtd::collections::generic::list <type_t> can store before resizing is required, whereas xtd::collections::generic::list::count is the number of elements that are actually in the xtd::collections::generic::list <type_t>.
xtd::collections::generic::list::capacity is always greater than or equal to xtd::collections::generic::list::count. If xtd::collections::generic::list::count exceeds xtd::collections::generic::list::capacity while adding elements, the capacity is increased by automatically reallocating the internal array before copying the old elements and adding the new elements.
If the capacity is significantly larger than the count and you want to reduce the memory used by the xtd::collections::generic::list <type_t>, you can decrease capacity by calling the xtd::collections::generic::list::trim_excess method or by setting the xtd::collections::generic::list::capacity property explicitly to a lower value. When the value of xtd::collections::generic::list::capacity is set explicitly, the internal array is also reallocated to accommodate the specified capacity, and all the elements are copied.
Retrieving the value of this property is an O(1) operation; setting the property is an O(n) operation, where n is the new capacity.

Implements xtd::collections::generic::icollection< type_t >.

Examples
ienumerable.cpp, and ienumerator.cpp.

◆ crbegin()

template<class type_t , class allocator_t >
virtual const_reverse_iterator xtd::collections::generic::list< type_t, allocator_t >::crbegin ( ) const
inlinevirtualnoexcept

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::collections::generic::list::rend().

Returns
Reverse iterator to the first element.
Remarks
If the vector is empty, the returned iterator will be equal to xtd::collections::generic::list::rend().

◆ crend()

template<class type_t , class allocator_t >
virtual const_reverse_iterator xtd::collections::generic::list< type_t, allocator_t >::crend ( ) const
inlinevirtualnoexcept

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.

Returns
Reverse iterator to the element following the last element.
Remarks
This element acts as a placeholder; attempting to access it results in undefined behavior.

◆ data() [1/2]

template<class type_t , class allocator_t >
virtual pointer xtd::collections::generic::list< type_t, allocator_t >::data ( )
inlinevirtualnoexcept

Returns pointer to the underlying array serving as element storage.

Returns
Pointer to the underlying element storage. For non-empty containers, the returned pointer compares equal to the address of the first element.
Remarks
The pointer is such that range [xtd::collections::generic::list::data(), xtd::collections::generic::list::data() + xtd::collections::generic::list::size()) is always a valid range, even if the container is empty (xtd::collections::generic::list::data() is not dereferenceable in that case).

◆ data() [2/2]

template<class type_t , class allocator_t >
virtual const_pointer xtd::collections::generic::list< type_t, allocator_t >::data ( ) const
inlinevirtualnoexcept

Returns pointer to the underlying array serving as element storage.

Returns
Pointer to the underlying element storage. For non-empty containers, the returned pointer compares equal to the address of the first element.
Remarks
The pointer is such that range [xtd::collections::generic::list::data(), xtd::collections::generic::list::data() + xtd::collections::generic::list::size()) is always a valid range, even if the container is empty (xtd::collections::generic::list::data() is not dereferenceable in that case).

◆ empty()

template<class type_t , class allocator_t >
virtual bool xtd::collections::generic::list< type_t, allocator_t >::empty ( ) const
inlinevirtualnoexcept

Checks if the container has no elements, i.e. whether xtd::collections::generic::list::begin() == xtd::collections::generic::list::end().

Returns
true if the container is empty, false otherwise.

◆ end() [1/2]

template<class type_t , class allocator_t >
const_iterator xtd::collections::generic::list< type_t, allocator_t >::end ( ) const
inlineoverridevirtualnoexcept

Returns an iterator to the element following the last element of the enumarable.

Returns
Iterator to the element following the last element.

Reimplemented from xtd::collections::generic::extensions::enumerable_iterators< type_t, xtd::collections::generic::ienumerable< type_t > >.

Examples
console_clear.cpp.

◆ end() [2/2]

template<class type_t , class allocator_t >
iterator xtd::collections::generic::list< type_t, allocator_t >::end ( )
inlineoverridevirtualnoexcept

Returns an iterator to the element following the last element of the enumarable.

Returns
Iterator to the element following the last element.

Reimplemented from xtd::collections::generic::extensions::enumerable_iterators< type_t, xtd::collections::generic::ienumerable< type_t > >.

◆ front() [1/2]

template<class type_t , class allocator_t >
virtual reference xtd::collections::generic::list< type_t, allocator_t >::front ( )
inlinevirtual

Returns a reference to the first element in the container.

Returns
Reference to the first element.
Remarks
Calling front on an empty container causes undefined behavior.

◆ front() [2/2]

template<class type_t , class allocator_t >
virtual const_reference xtd::collections::generic::list< type_t, allocator_t >::front ( ) const
inlinevirtual

Returns a reference to the first element in the container.

Returns
Reference to the first element.
Remarks
Calling front on an empty container causes undefined behavior.

◆ is_fixed_size()

template<class type_t , class allocator_t >
bool xtd::collections::generic::list< type_t, allocator_t >::is_fixed_size ( ) const
inlineoverridevirtualnoexcept

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

Returns
true if the xtd::collections::generic::list <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.

Implements xtd::collections::generic::ilist< type_t >.

◆ is_read_only()

template<class type_t , class allocator_t >
bool xtd::collections::generic::list< type_t, allocator_t >::is_read_only ( ) const
inlineoverridevirtualnoexcept

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

Returns
true if the xtd::collections::generic::list <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::list <type_t> interface only supports addition and removal operations. For example, the xtd::collections::generic::list::is_read_only property of an array that is cast or converted to an xtd::collections::generic::list <type_t> object returns true, even though individual array elements can be modified.

Implements xtd::collections::generic::icollection< type_t >.

◆ is_synchronized()

template<class type_t , class allocator_t >
bool xtd::collections::generic::list< type_t, allocator_t >::is_synchronized ( ) const
inlineoverridevirtualnoexcept

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

Returns
true if access to the xtd::collections::generic::list <type_t> is synchronized (thread safe); otherwise, false.
Remarks
xtd::collections::generic::list::sync_root returns an object, which can be used to synchronize access to the xtd::collections::generic::list <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::list::sync_root property during the entire enumeration.
list& my_collection = some_collection;
lock_(my_collection.sync_root()) {
for (auto item : my_collection) {
// Insert your code here.
}
}
const xtd::object & sync_root() const noexcept override
Gets an object that can be used to synchronize access to the the xtd::collections::generic::list <typ...
Definition list.hpp:461
#define lock_(object)
The lock_ keyword marks a statement block as a critical section by obtaining the mutual-exclusion loc...
Definition lock.hpp:85

Implements xtd::collections::generic::icollection< type_t >.

◆ items() [1/2]

template<class type_t , class allocator_t >
virtual const_base_type & xtd::collections::generic::list< type_t, allocator_t >::items ( ) const
inlinevirtualnoexcept

Returns the underlying base type items.

Returns
The underlying base type items.

◆ items() [2/2]

template<class type_t , class allocator_t >
virtual base_type & xtd::collections::generic::list< type_t, allocator_t >::items ( )
inlinevirtualnoexcept

Returns the underlying base type items.

Returns
The underlying base type items.

◆ max_size()

template<class type_t , class allocator_t >
virtual size_type xtd::collections::generic::list< type_t, allocator_t >::max_size ( ) const
inlinevirtualnoexcept

Returns the maximum number of elements the container is able to hold due to system or library implementation limitations, i.e. std::distance(xtd::collections::generic::list::begin(), xtd::collections::generic::list::end()) for the largest container.

Returns
Maximum number of elements.

◆ rbegin() [1/2]

template<class type_t , class allocator_t >
virtual reverse_iterator xtd::collections::generic::list< type_t, allocator_t >::rbegin ( )
inlinevirtualnoexcept

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::collections::generic::list::rend().

Returns
Reverse iterator to the first element.
Remarks
If the vector is empty, the returned iterator will be equal to xtd::collections::generic::list::rend().

◆ rbegin() [2/2]

template<class type_t , class allocator_t >
virtual const_reverse_iterator xtd::collections::generic::list< type_t, allocator_t >::rbegin ( ) const
inlinevirtualnoexcept

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::collections::generic::list::rend().

Returns
Reverse iterator to the first element.
Remarks
If the vector is empty, the returned iterator will be equal to xtd::collections::generic::list::rend().

◆ rend() [1/2]

template<class type_t , class allocator_t >
virtual reverse_iterator xtd::collections::generic::list< type_t, allocator_t >::rend ( )
inlinevirtualnoexcept

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.

Returns
Reverse iterator to the element following the last element.
Remarks
This element acts as a placeholder; attempting to access it results in undefined behavior.

◆ rend() [2/2]

template<class type_t , class allocator_t >
virtual const_reverse_iterator xtd::collections::generic::list< type_t, allocator_t >::rend ( ) const
inlinevirtualnoexcept

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.

Returns
Reverse iterator to the element following the last element.
Remarks
This element acts as a placeholder; attempting to access it results in undefined behavior.

◆ size()

template<class type_t , class allocator_t >
virtual size_type xtd::collections::generic::list< type_t, allocator_t >::size ( ) const
inlinevirtualnoexcept

Returns the number of elements in the container, i.e. std::distance(xtd::collections::generic::list::begin(), xtd::collections::generic::list::end()).

Returns
The number of elements in the container.
Examples
border_style.cpp, calculator.cpp, default_trace_listener.cpp, font_families.cpp, ienumerable.cpp, ienumerator.cpp, ip_address.cpp, and labels_and_unicode_text.cpp.

◆ sync_root()

template<class type_t , class allocator_t >
const xtd::object & xtd::collections::generic::list< type_t, allocator_t >::sync_root ( ) const
inlineoverridevirtualnoexcept

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

Returns
An object that can be used to synchronize access to the the xtd::collections::generic::list <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::list::sync_root property. The synchronizing code must perform operations on the xtd::collections::generic::list::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::list::sync_root looks as follows:
list& 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::list::sync_root property during the entire enumeration.
@code
list& my_collection = some_collection;
lock_(my_collection.sync_root()) {
for (auto item : my_collection) {
// Insert your code here.
}
}
Defines the base class for predefined exceptions in the xtd namespace.
Definition exception.hpp:28
Provides a mechanism that synchronizes access to objects with xtd::threading::monitor.
Definition lock_guard.hpp:32
bool is(std::any value)
Checks if the result of an expression is compatible with a given type.
Definition is.hpp:365
@ a
The A key.
Supports a simple iteration over a generic collection.
Definition enumerator.hpp:40

Implements xtd::collections::generic::icollection< type_t >.

◆ add()

template<class type_t , class allocator_t >
void xtd::collections::generic::list< type_t, allocator_t >::add ( const type_t &  item)
inlineoverridevirtual

Adds an object to the end of the xtd::collections::generic::list <type_t>.

Parameters
itemThe object to be added to the end of the xtd::collections::generic::list <type_t>. @)ar Examples The following example demonstrates how to add, remove, and insert a simple business object in a xtd::collections::generic::list <type_t>.
#include <xtd/xtd>
using namespace xtd;
using namespace xtd::collections::generic;
// Simple business object. A part_id is used to identify the type of part
// but the part name can change.
class part : public object, public iequatable<part> {
public:
string part_name;
int part_id = 0;
part() = default;
part(const string& name, int id) : part_name {name}, part_id {id} {}
string to_string() const noexcept override {return string::format("ID: {} Name: {}", part_id, part_name);}
bool equals(const object& obj) const noexcept override {return is<part>(obj) && equals(as<part>(obj));}
bool equals(const part& other) const noexcept override {return part_id == other.part_id;}
size get_hash_code() const noexcept override {return part_id;}
};
class example {
public:
static auto main() -> void {
// Create a list of parts.
auto parts = list<part>();
// Add parts to the list.
parts.add(part {"crank arm", 1234});
parts.add(part {"chain ring", 1334});
parts.add(part {"regular seat", 1434});
parts.add(part {"banana seat", 1444});
parts.add(part {"cassette", 1534});
parts.add(part {"shift lever", 1634});
// Write out the parts in the list. This will call the overridden ToString method
// in the part class.
console::write_line();
for (auto part : parts)
console::write_line(part);
// Check the list for part #1734. This calls the iequatable::equals method of the part class, which checks the partId for equality.
console::write_line("\ncontains(\"1734\"): {0}", parts.contains(part {"", 1734}));
// Insert a new item at position 2.
console::write_line("\nInsert(2, \"1834\")");
parts.insert(2, part {"brake lever", 1834});
//console::write_line();
for (auto part : parts)
console::write_line(part);
console::write_line("\nparts[3]: {0}", parts[3]);
console::write_line("\nremove(\"1534\")");
// This will remove part 1534 even though the partName is different, because the equals method only checks part_id for equality.
parts.remove(part {"cogs", 1534});
console::write_line();
for (auto part : parts)
console::write_line(part);
console::write_line("\nremove_at(3)");
// This will remove the part at index 3.
parts.remove_at(3);
console::write_line();
for (auto part : parts)
console::write_line(part);
}
};
startup_(example::main);
// This code produces the following output :
//
//
// ID: 1234 Name: crank arm
// ID: 1334 Name: chain ring
// ID: 1434 Name: regular seat
// ID: 1444 Name: banana seat
// ID: 1534 Name: cassette
// ID: 1634 Name: shift lever
//
// contains("1734"): false
//
// Insert(2, "1834")
// ID: 1234 Name: crank arm
// ID: 1334 Name: chain ring
// ID: 1834 Name: brake lever
// ID: 1434 Name: regular seat
// ID: 1444 Name: banana seat
// ID: 1534 Name: cassette
// ID: 1634 Name: shift lever
//
// parts[3]: ID: 1434 Name: regular seat
//
// remove("1534")
//
// ID: 1234 Name: crank arm
// ID: 1334 Name: chain ring
// ID: 1834 Name: brake lever
// ID: 1434 Name: regular seat
// ID: 1444 Name: banana seat
// ID: 1634 Name: shift lever
//
// remove_at(3)
//
// ID: 1234 Name: crank arm
// ID: 1334 Name: chain ring
// ID: 1834 Name: brake lever
// ID: 1444 Name: banana seat
// ID: 1634 Name: shift lever
The following example demonstrates several properties and methods of the xtd::collections::generic::list <type_t> generic class, including the xtd::collections::generic::list::add method. The parameterless constructor is used to create a list of strings with a capacity of 0. The xtd::collections::generic::list::capacity property is displayed, and then the xtd::collections::generic::list::add method is used to add several items. The items are listed, and the xtd::collections::generic::list::capacity property is displayed again, along with the xtd::collections::generic::list::count property, to show that the capacity has been increased as needed.

Other properties and methods are used to search for, insert, and remove elements from the list, and finally to clear the list.

#include <xtd/xtd>
using namespace xtd;
using namespace xtd::collections::generic;
class example {
public:
static auto main() -> void {
auto dinosaurs = list<string> {};
console::write_line("\ncapacity: {0}", dinosaurs.capacity());
dinosaurs.add("Tyrannosaurus");
dinosaurs.add("Amargasaurus");
dinosaurs.add("Mamenchisaurus");
dinosaurs.add("Deinonychus");
dinosaurs.add("Compsognathus");
console::write_line();
for (auto dinosaur : dinosaurs)
console::write_line(dinosaur);
console::write_line("\ncapacity: {0}", dinosaurs.capacity());
console::write_line("count: {0}", dinosaurs.count());
console::write_line("\ncontains(\"Deinonychus\"): {0}", dinosaurs.contains("Deinonychus"));
console::write_line("\ninsert(2, \"Compsognathus\")");
dinosaurs.insert(2, "Compsognathus");
console::write_line();
for (auto dinosaur : dinosaurs)
console::write_line(dinosaur);
// Shows accessing the list using the Item property.
console::write_line("\ndinosaurs[3]: {0}", dinosaurs[3]);
console::write_line("\nremove(\"Compsognathus\")");
dinosaurs.remove("Compsognathus");
console::write_line();
for (auto dinosaur : dinosaurs)
console::write_line(dinosaur);
dinosaurs.trim_excess();
console::write_line("\ntrim_excess()");
console::write_line("capacity: {0}", dinosaurs.capacity());
console::write_line("count: {0}", dinosaurs.count());
dinosaurs.clear();
console::write_line("\nclear()");
console::write_line("capacity: {0}", dinosaurs.capacity());
console::write_line("count: {0}", dinosaurs.count());
}
};
startup_(example::main);
// This code produces the following output :
//
// capacity: 0
//
// Tyrannosaurus
// Amargasaurus
// Mamenchisaurus
// Deinonychus
// Compsognathus
//
// capacity: 8
// count: 5
//
// contains("Deinonychus"): true
//
// insert(2, "Compsognathus")
//
// Tyrannosaurus
// Amargasaurus
// Compsognathus
// Mamenchisaurus
// Deinonychus
// Compsognathus
//
// dinosaurs[3]: Mamenchisaurus
//
// remove("Compsognathus")
//
// Tyrannosaurus
// Amargasaurus
// Mamenchisaurus
// Deinonychus
// Compsognathus
//
// trim_excess()
// capacity: 5
// count: 5
// clear()
// capacity: 5
// count: 0
Remarks
xtd::collections::generic::list <type_t> allows duplicate elements.
If xtd::collections::generic::list::count already equals xtd::collections::generic::list::capacity, the capacity of the xtd::collections::generic::list <type_t> is increased by automatically reallocating the internal array, and the existing elements are copied to the new array before the new element is added.
If xtd::collections::generic::list::count is less than xtd::collections::generic::list::capacity, this method is an O(1) operation. If the capacity needs to be increased to accommodate the new element, this method becomes an O(n) operation, where n is xtd::collections::generic::list::count.

Implements xtd::collections::generic::icollection< type_t >.

Examples
read_only_collection.cpp.

◆ add_range() [1/2]

template<class type_t , class allocator_t >
void xtd::collections::generic::list< type_t, allocator_t >::add_range ( const xtd::collections::generic::ienumerable< type_t > &  enumerable)
inline

Adds copy of elements from the specified collection to the end of the xtd::collections::generic::list <type_t>.

Parameters
collectionThe collection whose elements should be added to the end of the xtd::collections::generic::list <type_t>.
Examples
The following code example demonstrates the xtd::collections::generic::list <type_t> constructor and various methods of the xtd::collections::generic::list <type_t> class that act on ranges. An array of strings is created and passed to the constructor, populating the list with the elements of the array. The xtd::collections::generic::list::capacity property is then displayed, to show that the initial capacity is exactly what is required to hold the input elements.
#include <xtd/xtd>
using namespace xtd;
using namespace xtd::collections::generic;
class example {
public:
static auto main() -> void {
auto input = array<string> {"Brachiosaurus", "Amargasaurus", "Mamenchisaurus"};
auto dinosaurs = list<string>(input);
console::write_line("\ncapacity: {0}", dinosaurs.capacity());
console::write_line();
for (auto dinosaur : dinosaurs)
console::write_line(dinosaur);
console::write_line("\nadd_range(dinosaurs)");
dinosaurs.add_range(dinosaurs);
console::write_line();
for(auto dinosaur : dinosaurs)
console::write_line(dinosaur);
console::write_line("\nremove_range(2, 2)");
dinosaurs.remove_range(2, 2);
console::write_line();
for(auto dinosaur : dinosaurs)
console::write_line(dinosaur);
input = {"Tyrannosaurus", "Deinonychus", "Velociraptor"};
console::write_line("\ninsert_range(3, input)");
dinosaurs.insert_range(3, input);
console::write_line();
for(auto dinosaur : dinosaurs)
console::write_line(dinosaur);
console::write_line("\noutput = dinosaurs.get_range(2, 3).to_array()");
auto output = dinosaurs.get_range(2, 3).to_array();
console::write_line();
for (auto dinosaur : output)
console::write_line(dinosaur);
}
};
startup_(example::main);
// This code produces the following output :
//
//
// capacity: 3
//
// Brachiosaurus
// Amargasaurus
// Mamenchisaurus
//
// add_range(dinosaurs)
//
// Brachiosaurus
// Amargasaurus
// Mamenchisaurus
// Brachiosaurus
// Amargasaurus
// Mamenchisaurus
//
// remove_range(2, 2)
//
// Brachiosaurus
// Amargasaurus
// Amargasaurus
// Mamenchisaurus
//
// insert_range(3, input)
//
// Brachiosaurus
// Amargasaurus
// Amargasaurus
// Tyrannosaurus
// Deinonychus
// Velociraptor
// Mamenchisaurus
//
// output = dinosaurs.get_range(2, 3).to_array()
//
// Amargasaurus
// Tyrannosaurus
// Deinonychus
Remarks
The order of the elements in the collection is preserved in the xtd::collections::generic::list <type_t>.
If the new xtd::collections::generic::list::count (the current xtd::collections::generic::list::count plus the size of the collection) will be greater than xtd::collections::generic::list::capacity, the capacity of the xtd::collections::generic::list <type_t> is increased by automatically reallocating the internal array to accommodate the new elements, and the existing elements are copied to the new array before the new elements are added.
If the xtd::collections::generic::list <type_t> can accommodate the new elements without increasing the xtd::collections::generic::list::capacity, this method is an O(n) operation, where n is the number of elements to be added. If the capacity needs to be increased to accommodate the new elements, this method becomes an O(n + m) operation, where n is the number of elements to be added and m is xtd::collections::generic::list::count.

◆ add_range() [2/2]

template<class type_t , class allocator_t >
void xtd::collections::generic::list< type_t, allocator_t >::add_range ( std::initializer_list< type_t >  il)
inline

Adds copy of elements from the specified collection to the end of the xtd::collections::generic::list <type_t>.

Parameters
ilThe collection whose elements should be added to the end of the xtd::collections::generic::list <type_t>.
Examples
The following code example demonstrates the xtd::collections::generic::list <type_t> constructor and various methods of the xtd::collections::generic::list <type_t> class that act on ranges. An array of strings is created and passed to the constructor, populating the list with the elements of the array. The xtd::collections::generic::list::capacity property is then displayed, to show that the initial capacity is exactly what is required to hold the input elements.
#include <xtd/xtd>
using namespace xtd;
using namespace xtd::collections::generic;
class example {
public:
static auto main() -> void {
auto input = array<string> {"Brachiosaurus", "Amargasaurus", "Mamenchisaurus"};
auto dinosaurs = list<string>(input);
console::write_line("\ncapacity: {0}", dinosaurs.capacity());
console::write_line();
for (auto dinosaur : dinosaurs)
console::write_line(dinosaur);
console::write_line("\nadd_range(dinosaurs)");
dinosaurs.add_range(dinosaurs);
console::write_line();
for(auto dinosaur : dinosaurs)
console::write_line(dinosaur);
console::write_line("\nremove_range(2, 2)");
dinosaurs.remove_range(2, 2);
console::write_line();
for(auto dinosaur : dinosaurs)
console::write_line(dinosaur);
input = {"Tyrannosaurus", "Deinonychus", "Velociraptor"};
console::write_line("\ninsert_range(3, input)");
dinosaurs.insert_range(3, input);
console::write_line();
for(auto dinosaur : dinosaurs)
console::write_line(dinosaur);
console::write_line("\noutput = dinosaurs.get_range(2, 3).to_array()");
auto output = dinosaurs.get_range(2, 3).to_array();
console::write_line();
for (auto dinosaur : output)
console::write_line(dinosaur);
}
};
startup_(example::main);
// This code produces the following output :
//
//
// capacity: 3
//
// Brachiosaurus
// Amargasaurus
// Mamenchisaurus
//
// add_range(dinosaurs)
//
// Brachiosaurus
// Amargasaurus
// Mamenchisaurus
// Brachiosaurus
// Amargasaurus
// Mamenchisaurus
//
// remove_range(2, 2)
//
// Brachiosaurus
// Amargasaurus
// Amargasaurus
// Mamenchisaurus
//
// insert_range(3, input)
//
// Brachiosaurus
// Amargasaurus
// Amargasaurus
// Tyrannosaurus
// Deinonychus
// Velociraptor
// Mamenchisaurus
//
// output = dinosaurs.get_range(2, 3).to_array()
//
// Amargasaurus
// Tyrannosaurus
// Deinonychus
Remarks
The order of the elements in the collection is preserved in the xtd::collections::generic::list <type_t>.
If the new xtd::collections::generic::list::count (the current xtd::collections::generic::list::count plus the size of the collection) will be greater than xtd::collections::generic::list::capacity, the capacity of the xtd::collections::generic::list <type_t> is increased by automatically reallocating the internal array to accommodate the new elements, and the existing elements are copied to the new array before the new elements are added.
If the xtd::collections::generic::list <type_t> can accommodate the new elements without increasing the xtd::collections::generic::list::capacity, this method is an O(n) operation, where n is the number of elements to be added. If the capacity needs to be increased to accommodate the new elements, this method becomes an O(n + m) operation, where n is the number of elements to be added and m is xtd::collections::generic::list::count.

◆ as_read_only()

template<class type_t , class allocator_t >
read_only_collection xtd::collections::generic::list< type_t, allocator_t >::as_read_only ( ) const
inlinenoexcept

Returns a read-only xtd::collections::object_model::read_only_collection <type_t> wrapper for the current collection.

Returns
An object that acts as a read-only wrapper around the current xtd::collections::generic::list <type_t>.
Remarks
To prevent any modifications to the xtd::collections::generic::list <type_t> object, expose it only through this wrapper. A xtd::collections::object_model::read_only_collection <type_t> object does not expose methods that modify the collection. However, if changes are made to the underlying xtd::collections::generic::list <type_t> object, the read-only collection reflects those changes.
This method is an O(1) operation.

◆ assign() [1/3]

template<class type_t , class allocator_t >
void xtd::collections::generic::list< type_t, allocator_t >::assign ( size_type  count,
const type_t &  value 
)
inline

Replaces the contents with count copies of value value.

Parameters
countThe new size of the container.
valueThe value to initialize elements of the container with.

◆ assign() [2/3]

template<class type_t , class allocator_t >
template<class input_iterator_t >
void xtd::collections::generic::list< type_t, allocator_t >::assign ( input_iterator_t  first,
input_iterator_t  last 
)
inline

Replaces the contents with copies of those in the range [first, last).

Parameters
firstThe first iterator the range to copy the elements from.
lastThe last iterator the range to copy the elements from.
Warning
The behavior is undefined if either argument is an iterator this current instance.

◆ assign() [3/3]

template<class type_t , class allocator_t >
virtual void xtd::collections::generic::list< type_t, allocator_t >::assign ( std::initializer_list< type_t >  items)
inlinevirtual

Replaces the contents with the elements from the initializer list items.

Parameters
itemsthe initializer list to copy the values from.

◆ at() [1/2]

template<class type_t , class allocator_t >
virtual reference xtd::collections::generic::list< type_t, allocator_t >::at ( size_type  index)
inlinevirtual

Returns a reference to the element at specified location pos, with bounds checking.

Parameters
indexThe position of the element to return.
Returns
Reference to the requested element.
Exceptions
std::out_of_rangeIf pos is not within the range of the container.

◆ at() [2/2]

template<class type_t , class allocator_t >
virtual const_reference xtd::collections::generic::list< type_t, allocator_t >::at ( size_type  index) const
inlinevirtual

Returns a reference to the element at specified location pos, with bounds checking.

Parameters
indexThe position of the element to return.
Returns
Reference to the requested element.
Exceptions
std::out_of_rangeIf pos is not within the range of the container.

◆ binary_search() [1/3]

template<class type_t , class allocator_t >
xtd::size xtd::collections::generic::list< type_t, allocator_t >::binary_search ( const type_t &  item) const
inline

Searches the entire sorted xtd::collections::generic::list <type_t> for an element using the default comparer and returns the zero-based index of the element.

Parameters
itemThe object to locate.
Returns
The zero-based index of item in the sorted xtd::collections::generic::list <type_t>, if item is found; otherwise, a number greater than xtd::collections::genric::list::count that is the bitwise complement of the index of the next element that is larger than item or, if there is no larger element, the bitwise complement of xtd::collections::genric::list::count.
Exceptions
xtd::invalid_operation_exceptionThe default comparer xtd::collections::generic::comparer::default_comparer cannot find an implementation of the xtd::icomparable <type_t> generic interface.
Examples
The xtd::collections::generic::list::binary_search method overload is then used to search for two strings that are not in the list, and the xtd::collections::generic::list::insert method is used to insert them. The return value of the xtd::collections::generic::list::binary_search method is greater than xtd::collections::generic::list::count in each case, because the strings are not in the list. Taking the bitwise complement of this number produces the index of the first element in the list that is larger than the search string, and inserting at this location preserves the sort order. The second search string is larger than any element in the list, so the insertion position is at the end of the list.
#include <xtd/xtd>
using namespace xtd;
using namespace xtd::collections::generic;
class example {
public:
static auto main() -> void {
auto dinosaurs = list<string> {};
dinosaurs.add("Pachycephalosaurus");
dinosaurs.add("Amargasaurus");
dinosaurs.add("Mamenchisaurus");
dinosaurs.add("Deinonychus");
console::write_line();
for (auto dinosaur : dinosaurs)
console::write_line(dinosaur);
console::write_line("\nsort");
dinosaurs.sort();
console::write_line();
for (auto dinosaur : dinosaurs)
console::write_line(dinosaur);
console::write_line("\nbinary_search and insert \"Coelophysis\":");
auto index = dinosaurs.binary_search("Coelophysis");
if (index > dinosaurs.count()) dinosaurs.insert(~index, "Coelophysis");
console::write_line();
for (string dinosaur : dinosaurs)
console::write_line(dinosaur);
console::write_line("\nbinary_search and insert \"Tyrannosaurus\":");
index = dinosaurs.binary_search("Tyrannosaurus");
if (index > dinosaurs.count()) dinosaurs.insert(~index, "Tyrannosaurus");
console::write_line();
for (auto dinosaur : dinosaurs)
console::write_line(dinosaur);
}
};
startup_(example::main);
// This code produces the following output :
//
//
// Pachycephalosaurus
// Amargasaurus
// Mamenchisaurus
// Deinonychus
//
// sort
//
// Amargasaurus
// Deinonychus
// Mamenchisaurus
// Pachycephalosaurus
//
// binary_search and insert "Coelophysis":
//
// Amargasaurus
// Coelophysis
// Deinonychus
// Mamenchisaurus
// Pachycephalosaurus
//
// binary_search and insert "Tyrannosaurus":
//
// Amargasaurus
// Coelophysis
// Deinonychus
// Mamenchisaurus
// Pachycephalosaurus
// Tyrannosaurus
void add(const type_t &item) override
Adds an object to the end of the xtd::collections::generic::list <type_t>.
Definition list.hpp:480
Remarks
This method uses the default comparer xtd::collections::generic::comparer::default_comparer for type type_t to determine the order of list elements. The xtd::collections::generic::comparer::default_comparer property checks whether type type_t implements the xtd::icomparable <type_t> generic interface and uses that implementation, if available. If not, xtd::collections::generic::comparer::default_comparer checks whether type type_t implements the xtd::icomparable interface. If type type_t does not implement either interface, xtd::collections::generic::comparer::default_comparer throws an xtd::invalid_operation_exception.
The xtd::collections::generic::list <type_t> must already be sorted according to the comparer implementation; otherwise, the result is incorrect.
If the xtd::collections::generic::list <type_t> contains more than one element with the same value, the method returns only one of the occurrences, and it might return any one of the occurrences, not necessarily the first one.
If the xtd::collections::generic::list <type_t> does not contain the specified value, the method returns an integer greater than xtd::collections::generic::list::count. You can apply the bitwise complement operation (~) to this integer to get the index of the first element that is larger than the search value. When inserting the value into the xtd::collections::generic::list <type_t>, this index should be used as the insertion point to maintain the sort order.
This method is an O(log n) operation, where n is the number of elements in the range.
The following code example demonstrates the xtd::collections::generic::list::sort() method overload and the xtd::collections::generic::list::binary_search method overload. A xtd::collections::generic::list <type_t> of strings is created and populated with four strings, in no particular order. The list is displayed, sorted, and displayed again.

◆ binary_search() [2/3]

template<class type_t , class allocator_t >
xtd::size xtd::collections::generic::list< type_t, allocator_t >::binary_search ( const type_t &  item,
const xtd::collections::generic::icomparer< type_t > &  comparer 
) const
inline

Searches the entire sorted xtd::collections::generic::list <type_t> for an element using the specified comparer and returns the zero-based index of the element.

Parameters
itemThe object to locate.
comparerThe xtd::collections::generic::icomparer <type_t> implementation to use when comparing elements.
Returns
The zero-based index of item in the sorted xtd::collections::generic::list <type_t>, if item is found; otherwise, a number greater than xtd::collections::genric::list::count that is the bitwise complement of the index of the next element that is larger than item or, if there is no larger element, the bitwise complement of xtd::collections::genric::list::count.
Exceptions
xtd::invalid_operation_exceptionThe default comparer xtd::collections::generic::comparer::default_comparer cannot find an implementation of the xtd::icomparable <type_t> generic interface.
Remarks
The comparer customizes how the elements are compared. For example, you can use a xtd::case_insensitive_comparer instance as the comparer to perform case-insensitive string searches.
If comparer is provided, the elements of the xtd::collections::generic::list <type_t> are compared to the specified value using the specified xtd::collections::generic::icomparer <type_t> implementation.
The xtd::collections::generic::list <type_t> must already be sorted according to the comparer implementation; otherwise, the result is incorrect.
If the xtd::collections::generic::list <type_t> contains more than one element with the same value, the method returns only one of the occurrences, and it might return any one of the occurrences, not necessarily the first one.
If the xtd::collections::generic::list <type_t> does not contain the specified value, the method returns an integer greater than xtd::collections::generic::list::count. You can apply the bitwise complement operation (~) to this integer to get the index of the first element that is larger than the search value. When inserting the value into the xtd::collections::generic::list <type_t>, this index should be used as the insertion point to maintain the sort order.
This method is an O(log n) operation, where n is the number of elements in the range.

◆ binary_search() [3/3]

template<class type_t , class allocator_t >
xtd::size xtd::collections::generic::list< type_t, allocator_t >::binary_search ( xtd::size  index,
xtd::size  count,
const type_t &  item,
const xtd::collections::generic::icomparer< type_t > &  comparer 
) const
inline

Searches a range of elements in the sorted xtd::collections::generic::list <type_t> for an element using the specified comparer and returns the zero-based index of the element.

Parameters
indexThe zero-based starting index of the range to search.
countThe length of the range to search.
itemThe object to locate.
comparerThe xtd::collections::generic::icomparer <type_t> implementation to use when comparing elements, or null to use the default comparer xtd::collections::generic::comparer<type_t>::default_comparer.
Returns
The zero-based index of item in the sorted xtd::collections::generic::list <type_t>, if item is found; otherwise, a number greater than xtd::collections::genric::list::count that is the bitwise complement of the index of the next element that is larger than item or, if there is no larger element, the bitwise complement of xtd::collections::genric::list::count.
Exceptions
xtd::argument_exception`index` and `count` do not denote a valid range in the xtd::collections::generic::list <type_t>.
xtd::invalid_operation_exceptionThe default comparer xtd::collections::generic::comparer::default_comparer cannot find an implementation of the xtd::icomparable <type_t> generic interface.
Remarks
The comparer customizes how the elements are compared. For example, you can use a xtd::case_insensitive_comparer instance as the comparer to perform case-insensitive string searches.
If comparer is provided, the elements of the xtd::collections::generic::list <type_t> are compared to the specified value using the specified xtd::collections::generic::icomparer <type_t> implementation.
The xtd::collections::generic::list <type_t> must already be sorted according to the comparer implementation; otherwise, the result is incorrect.
If the xtd::collections::generic::list <type_t> contains more than one element with the same value, the method returns only one of the occurrences, and it might return any one of the occurrences, not necessarily the first one.
If the xtd::collections::generic::list <type_t> does not contain the specified value, the method returns an integer greater than xtd::collections::generic::list::count. You can apply the bitwise complement operation (~) to this integer to get the index of the first element that is larger than the search value. When inserting the value into the xtd::collections::generic::list <type_t>, this index should be used as the insertion point to maintain the sort order.
This method is an O(log n) operation, where n is the number of elements in the range.

◆ clear()

template<class type_t , class allocator_t >
void xtd::collections::generic::list< type_t, allocator_t >::clear ( )
inlineoverridevirtual

Removes all elements from the xtd::collections::generic::list <type_t>.

Remarks
xtd::collections::generic::list::count is set to 0, and references to other objects from elements of the collection are also released.
xtd::collections::generic::list::capacity remains unchanged. To reset the capacity of the xtd::collections::generic::list <type_t>, call the xtd::collections::generic::list::trim_excess method or set the xtd::collections::generic::list::capacity property directly. Decreasing the capacity reallocates memory and copies all the elements in the xtd::collections::generic::list <type_t>. Trimming an empty xtd::collections::generic::list <type_t> sets the capacity of the xtd::collections::generic::list <type_t> to the default capacity.
This method is an O(n) operation, where n is xtd::collections::generic::list::count.

Implements xtd::collections::generic::icollection< type_t >.

◆ contains()

template<class type_t , class allocator_t >
bool xtd::collections::generic::list< type_t, allocator_t >::contains ( const type_t &  value) const
inlineoverridevirtualnoexcept

Determines whether an element is in the xtd::colllections::generic::list <type_t>.

Parameters
valueThe object to locate in the xtd::colllections::generic::list <type_t>. The value can be null for reference types.
Returns
true if item is found in the xtd::colllections::generic::list <type_t>; otherwise, false.

Implements xtd::collections::generic::icollection< type_t >.

◆ convert_all()

template<class type_t , class allocator_t >
template<class output_t >
list< output_t > xtd::collections::generic::list< type_t, allocator_t >::convert_all ( xtd::converter< output_t, const type_t & >  converter) const
inline

Converts the elements in the current xtd::colllections::generic::list <type_t> to another type, and returns a list containing the converted elements.

Template Parameters
output_tThe type of the elements of the target array.
Parameters
converterA xtd::converter <output_t, input_t> delegate that converts each element from one type to another type.
Returns
A xtd::collections::generic::list <type_t> of the target type containing the converted elements from the current xtd::collections::generic::list <type_t>.
Examples
The following example defines a method named point_f_to_point that converts a xtd::drawing::point_f structure to a xtd::drawing::point structure. The example then creates a xtd::collections::generic::list <type_t> of xtd::drawing::point_f structures, creates a xtd::converter <point_f, point> delegate to represent the point_f_to_point method, and passes the delegate to the xtd::collections::generic::list::convert_all method. The xtd::collections::generic::list::convert_all method passes each element of the input list to the point_f_to_point method and puts the converted elements into a new list of Point structures. Both lists are displayed.
#include <xtd/xtd>
using namespace xtd;
using namespace xtd::collections::generic;
using namespace xtd::drawing;
class example {
public:
static auto main() -> void {
auto lpf = list<point_f> {};
lpf.add(point_f {27.8f, 32.62f});
lpf.add(point_f {99.3f, 147.273f});
lpf.add(point_f {7.5f, 1412.2f});
console::write_line();
for (const auto& p : lpf)
console::write_line(p);
console::write_line();
for (const auto& p : lp)
console::write_line(p);
}
static point point_f_to_point(const point_f& pf) {
return point {as<int>(pf.x), as<int>(pf.y)};
}
};
startup_(example::main);
// This code produces the following output :
//
//
// {x=27.8, y=32.62}
// {x=99.3, y=147.273}
// {x=7.5, y=1412.2}
//
// {x=28, y=33}
// {x=99, y=147}
// {x=8, y=1412}
list< output_t > convert_all(xtd::converter< output_t, const type_t & > converter) const
Converts the elements in the current xtd::colllections::generic::list <type_t> to another type,...
Definition list.hpp:637
xtd::delegate< output_t(input_t input)> converter
Represents a method that converts an object from one type to another type.
Definition converter.hpp:33
@ p
The P key.
The xtd::drawing namespace provides access to GDI+ basic graphics functionality. More advanced functi...
Definition actions_system_images.hpp:11
Represents an ordered pair of floating-point x- and y-coordinates that defines a point in a two-dimen...
Definition point_f.hpp:35
float x
Gets or sets the x-coordinate of this xtd::drawing::point_f.
Definition point_f.hpp:72
float y
Gets or sets the y-coordinate of this xtd::drawing::point_f.
Definition point_f.hpp:76
Represents an ordered pair of integer x- and y-coordinates that defines a point in a two-dimensional ...
Definition point.hpp:54

◆ copy_to() [1/3]

template<class type_t , class allocator_t >
virtual void xtd::collections::generic::list< type_t, allocator_t >::copy_to ( xtd::array< type_t > &  array) const
inlinevirtual

Copies the entire xtd::collections::generic::list <type_t> to a compatible one-dimensional array.

Parameters
arrayThe one-dimensional xtd::array that is the destination of the elements copied from ICollection. The xtd::array must have zero-based indexing.
Exceptions
ArgumentNullExceptionarray is null.
ArgumentExceptionThe number of elements in the source xtd::collections::generic::list <type_t> is greater than the number of elements that the destination array can contain.
Examples
The following code example demonstrates all three overloads of the CopyTo method. A xtd::collections::generic::list <type_t> of strings is created and populated with 5 strings. An empty string array of 15 elements is created, and the copy_to(type_t[]) method overload is used to copy all the elements of the list to the array beginning at the first element of the array. The CopyTo(type_t[], Int32) method overload is used to copy all the elements of the list to the array beginning at array index 6 (leaving index 5 empty). Finally, the CopyTo(Int32, type_t[], Int32, Int32) method overload is used to copy 3 elements from the list, beginning with index 2, to the array beginning at array index 12 (leaving index 11 empty). The contents of the array are then displayed.
Remarks
TThis method uses xtd::array::copy to copy the elements.
The elements are copied to the xtd::array in the same order in which the enumerator iterates through the xtd::collections::generic::list <type_t>.
This method is an O(n) operation, where n is xtd::collections::generic::list::count.

◆ copy_to() [2/3]

template<class type_t , class allocator_t >
void xtd::collections::generic::list< type_t, allocator_t >::copy_to ( xtd::array< type_t > &  array,
size_type  array_index 
) const
inlineoverridevirtual

Copies the entire xtd::colllections::generic::list <type_t> to a compatible one-dimensional array, starting at the specified index of the target array.

Parameters
arrayThe one-dimensional Array that is the destination of the elements copied from xtd::colllections::generic::list <type_t>. The Array must have zero-based indexing.
array_indexThe zero-based index in array at which copying begins.
Exceptions
xtd::argument_exceptionThe number of elements in the source xtd::colllections::generic::list <type_t> is greater than the available space from arrayIndex to the end of the destination array.
Remarks
This method uses xtd::array::copy to copy the elements.
The elements are copied to the xtd::array in the same order in which the enumerator iterates through the xtd::colllections::generic::list <type_t>.
This method is an O(n) operation, where n is xtd::colllections::generic::list::count.

Implements xtd::collections::generic::icollection< type_t >.

◆ copy_to() [3/3]

template<class type_t , class allocator_t >
virtual void xtd::collections::generic::list< type_t, allocator_t >::copy_to ( size_type  index,
xtd::array< type_t > &  array,
size_type  array_index,
size_type  count 
) const
inlinevirtual

Copies the entire xtd::collections::generic::list <type_t> to a compatible one-dimensional array, starting at the specified index of the target array.

Parameters
indexThe zero-based index in the source xtd::collections::generic::list <type_t> at which copying begins.
arrayThe one-dimensional xtd::array that is the destination of the elements copied from ICollection. The xtd::array must have zero-based indexing.
arrayIndexThe zero-based index in array at which copying begins;
countThe number of elements to copy.
Exceptions
ArgumentNullExceptionarray is null.
ArgumentOutOfRangeExceptionThe arrayIndex or count is less than 0.
ArgumentExceptionThe number of elements in the source xtd::collections::generic::list <type_t> is greater than the number of elements that the destination array can contain.
Examples
The following code example demonstrates all three overloads of the CopyTo method. A xtd::collections::generic::list <type_t> of strings is created and populated with 5 strings. An empty string array of 15 elements is created, and the CopyTo(type_t[]) method overload is used to copy all the elements of the list to the array beginning at the first element of the array. The CopyTo(type_t[], Int32) method overload is used to copy all the elements of the list to the array beginning at array index 6 (leaving index 5 empty). Finally, the CopyTo(Int32, type_t[], Int32, Int32) method overload is used to copy 3 elements from the list, beginning with index 2, to the array beginning at array index 12 (leaving index 11 empty). The contents of the array are then displayed.
Remarks
TThis method uses xtd::array::copy to copy the elements.
The elements are copied to the xtd::array in the same order in which the enumerator iterates through the xtd::collections::generic::list <type_t>.
This method is an O(n) operation, where n is xtd::collections::generic::list::count.

◆ emplace()

template<class type_t , class allocator_t >
template<class ... args_t>
iterator xtd::collections::generic::list< type_t, allocator_t >::emplace ( const_iterator  pos,
args_t &&...  args 
)
inline

Inserts a new element into the container directly before pos.

Parameters
posThe iterator before which the new element will be constructed.
argsarguments to forward to the constructor of the element.
Remarks
The element is constructed through std::allocator_traits::construct, which typically uses placement-new to construct the element in-place at a location provided by the container. However, if the required location has been occupied by an existing element, the inserted element is constructed at another location at first, and then move assigned into the required location.
The arguments args... are forwarded to the constructor as std::forward<args_t>(args).... args... may directly or indirectly refer to a value in the container.
If after the operation the new xtd::collections::generic::list::size() is greater than old xtd::collections::generic::list::capacity() a reallocation takes place, in which case all iterators (including the xtd::collections::generic::list::end() iterator) and all references to the elements are invalidated. Otherwise, only the iterators and references before the insertion point remain valid.

◆ emplace_back()

template<class type_t , class allocator_t >
template<class ... args_t>
reference xtd::collections::generic::list< type_t, allocator_t >::emplace_back ( args_t &&...  args)
inline

Appends a new element to the end of the container. The element is constructed through std::allocator_traits::construct, which typically uses placement-new to construct the element in-place at the location provided by the container. The arguments args... are forwarded to the constructor as std::forward<Args>(args)....

Parameters
argsThe arguments to forward to the constructor of the element.
Returns
A reference to the inserted element.
Remarks
If after the operation the new xtd::collections::generic::list::size() is greater than old xtd::collections::generic::list::capacity() a reallocation takes place, in which case all iterators (including the xtd::collections::generic::list::end() iterator) and all references to the elements are invalidated. Otherwise only the xtd::collections::generic::list::end() iterator is invalidated.
Examples
array_list.cpp.

◆ ensure_capacity()

template<class type_t , class allocator_t >
xtd::size xtd::collections::generic::list< type_t, allocator_t >::ensure_capacity ( xtd::size  capacity)
inline

Ensures that the capacity of this list is at least the specified capacity. If the current capacity is less than capacity, it is increased to at least the specified capacity.

Parameters
capacityThe minimum capacity to ensure.
Returns
The new capacity of this list.

◆ equals() [1/2]

template<class type_t , class allocator_t >
bool xtd::collections::generic::list< type_t, allocator_t >::equals ( const object obj) const
inlineoverridevirtualnoexcept

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

Parameters
objThe object to compare with the current object.
Returns
true if the specified object is equal to the current object. otherwise, false.
Examples
The following code example compares the current instance with another object.
#include <xtd/console>
using namespace xtd;
auto main() -> int {
auto object1 = new_ptr<object>();
auto object2 = new_ptr<object>();
auto object3 = object2;
console::write_line(object1->equals(*object3));
console::write_line(*object1 == *object3);
object3 = object1;
console::write_line(object1->equals(*object3));
console::write_line(*object1 == *object3);
}
// This code produces the following output :
//
// false
// false
// true
// true
static void write_line()
Writes the current line terminator to the standard output stream using the specified format informati...

Reimplemented from xtd::object.

◆ equals() [2/2]

template<class type_t , class allocator_t >
bool xtd::collections::generic::list< type_t, allocator_t >::equals ( const list< type_t, allocator_t > &  ) const
inlineoverridevirtualnoexcept

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

Parameters
objAn object to compare with this object.
Returns
true if the current object is equal to the other parameter; otherwise, false.

Implements xtd::iequatable< xtd::collections::generic::list< type_t, allocator_t > >.

◆ erase() [1/2]

template<class type_t , class allocator_t >
virtual iterator xtd::collections::generic::list< type_t, allocator_t >::erase ( const_iterator  pos)
inlinevirtual

Erases the specified elements from the container.

Parameters
posThe iterator to the element to remove.
Returns
Iterator following the last removed element.
Remarks
Removes the element at pos.
Iterators (including the xtd::collections::generic::list::end() iterator) and references to the elements at or after the point of the erase are invalidated.
The iterator pos must be valid and dereferenceable. Thus the xtd::collections::generic::list::end() iterator (which is valid, but is not dereferenceable) cannot be used as a value for pos. @remarks Ifpos` refers to the last element, then thextd::collections::generic::list:: end() iterator is returned.

◆ erase() [2/2]

template<class type_t , class allocator_t >
virtual iterator xtd::collections::generic::list< type_t, allocator_t >::erase ( const_iterator  first,
const_iterator  last 
)
inlinevirtual

Erases the specified elements from the container.

Parameters
posThe iterator to the element to remove.
Returns
Iterator following the last removed element.
Remarks
Removes the elements in the range [first, last).
Iterators (including the xtd::collections::generic::list::end() iterator) and references to the elements at or after the point of the erase are invalidated.
The iterator first does not need to be dereferenceable if first == last: erasing an empty range is a no-op.
If last == end() prior to removal, then the updated xtd::collections::generic::list::end() iterator is returned.
If [first, last) is an empty range, then last is returned.

◆ exists()

template<class type_t , class allocator_t >
bool xtd::collections::generic::list< type_t, allocator_t >::exists ( xtd::predicate< const type_t & >  match) const
inline

Determines whether the xtd::collections::generic::list <type_t> contains elements that match the conditions defined by the specified predicate.

Parameters
matchThe xtd::predicate <type_t> delegate that defines the conditions of the elements to search for.
Returns
true if the xtd::collections::generic::list <type_t> contains one or more elements that match the conditions defined by the specified predicate; otherwise, false.
Examples
The following example demonstrates the xtd::collections::generic::list::exists method and several other methods that use the xtd::predicate <type_t> generic delegate.
A xtd::collections::generic::list <type_t> of strings is created, containing 8 dinosaur names, two of which (at positions 1 and 5) end with "saurus". The example also defines a search predicate method named ends_with_saurus, which accepts a string parameter and returns a boolean value indicating whether the input string ends in "saurus".
The xtd::collections::generic::list::find, xtd::collections::generic::list::find_last, and xtd::collections::generic::list::findA_all methods are used to search the list with the search predicate method, and then the xtd::collections::generic::list::remove_all method is used to remove all entries ending with "saurus".
Finally, the xtd::collections::generic::list::exists method is called. It traverses the list from the beginning, passing each element in turn to the ends_with_saurus method. The search stops and the method returns true if the ends_with_saurus method returns true for any element. The xtd::collections::generic::list::exists method returns false because all such elements have been removed.
#include <xtd/xtd>
using namespace xtd;
using namespace xtd::collections::generic;
class example {
public:
static auto main() -> void {
auto dinosaurs = list<string> {};
dinosaurs.add("Compsognathus");
dinosaurs.add("Amargasaurus");
dinosaurs.add("Oviraptor");
dinosaurs.add("Velociraptor");
dinosaurs.add("Deinonychus");
dinosaurs.add("Dilophosaurus");
dinosaurs.add("Gallimimus");
dinosaurs.add("Triceratops");
console::write_line();
for (const auto& dinosaur : dinosaurs)
console::write_line(dinosaur);
console::write_line("\ntrue_for_all(ends_with_saurus): {0}", dinosaurs.true_for_all(predicate<const string&> {ends_with_saurus}));
console::write_line("\nfind(ends_with_saurus): {0}", dinosaurs.find(predicate<const string&> {ends_with_saurus}));
console::write_line("\nfindLast(ends_with_saurus): {0}", dinosaurs.find_last(predicate<const string&> {ends_with_saurus}));
console::write_line("\nfind_all(ends_with_saurus):");
auto sublist = dinosaurs.find_all(predicate<const string&> {ends_with_saurus});
for (const auto& dinosaur : sublist)
console::write_line(dinosaur);
console::write_line("\n{0} elements removed by remove_all(ends_with_saurus).", dinosaurs.remove_all(predicate<const string&> {ends_with_saurus}));
console::write_line("\nlist now contains:");
for (const auto& dinosaur : dinosaurs)
console::write_line(dinosaur);
console::write_line("\nexists(ends_with_saurus): {0}", dinosaurs.exists(predicate<const string&> {ends_with_saurus}));
}
private:
// Search predicate returns true if a string ends in "saurus".
static bool ends_with_saurus(const string& s) {
return s.to_lower().ends_with("saurus");
}
};
startup_(example::main);
// This code produces the following output :
//
//
// Compsognathus
// Amargasaurus
// Oviraptor
// Velociraptor
// Deinonychus
// Dilophosaurus
// Gallimimus
// Triceratops
//
// true_for_all(ends_with_saurus): false
//
// find(ends_with_saurus): Amargasaurus
//
// findLast(ends_with_saurus): Dilophosaurus
//
// find_all(ends_with_saurus):
// Amargasaurus
// Dilophosaurus
//
// 2 elements removed by remove_all(ends_with_saurus).
//
// list now contains:
// Compsognathus
// Oviraptor
// Velociraptor
// Deinonychus
// Gallimimus
// Triceratops
//
// exists(ends_with_saurus): false
xtd::func< bool, type_t > predicate
Represents a delegate that defines a set of criteria and determines whether the specified object meet...
Definition predicate.hpp:16
@ s
The S key.
Remarks
The xtd::predicate <type_t> is a delegate to a method that returns true if the object passed to it matches the conditions defined in the delegate. The elements of the current xtd::collections::generic::list <type_t> are individually passed to the xtd::predicate <type_t> delegate, and the elements that match the conditions are removed from the xtd::collections::generic::list <type_t>.
This method performs a linear search; therefore, this method is an O(n) operation, where n is xtd::collections::generic::list::count.

◆ find()

template<class type_t , class allocator_t >
type_t xtd::collections::generic::list< type_t, allocator_t >::find ( xtd::predicate< const type_t & >  match) const
inline

Searches for an element that matches the conditions defined by the specified predicate, and returns the first occurrence within the entire xtd::collections::generic::list <type_t>.

Parameters
matchThe xtd::predicate <type_t> delegate that defines the conditions of the elements to search for.
Returns
The first element that matches the conditions defined by the specified predicate, if found; otherwise, the default value for type type_t.
Examples
The following example demonstrates the xtd::collections::generic::list::exists method and several other methods that use the xtd::predicate <type_t> generic delegate.
A xtd::collections::generic::list <type_t> of strings is created, containing 8 dinosaur names, two of which (at positions 1 and 5) end with "saurus". The example also defines a search predicate method named ends_with_saurus, which accepts a string parameter and returns a boolean value indicating whether the input string ends in "saurus".
The xtd::collections::generic::list::find, xtd::collections::generic::list::find_last, and xtd::collections::generic::list::findA_all methods are used to search the list with the search predicate method, and then the xtd::collections::generic::list::remove_all method is used to remove all entries ending with "saurus".
Finally, the xtd::collections::generic::list::exists method is called. It traverses the list from the beginning, passing each element in turn to the ends_with_saurus method. The search stops and the method returns true if the ends_with_saurus method returns true for any element. The xtd::collections::generic::list::exists method returns false because all such elements have been removed.
#include <xtd/xtd>
using namespace xtd;
using namespace xtd::collections::generic;
class example {
public:
static auto main() -> void {
auto dinosaurs = list<string> {};
dinosaurs.add("Compsognathus");
dinosaurs.add("Amargasaurus");
dinosaurs.add("Oviraptor");
dinosaurs.add("Velociraptor");
dinosaurs.add("Deinonychus");
dinosaurs.add("Dilophosaurus");
dinosaurs.add("Gallimimus");
dinosaurs.add("Triceratops");
console::write_line();
for (const auto& dinosaur : dinosaurs)
console::write_line(dinosaur);
console::write_line("\ntrue_for_all(ends_with_saurus): {0}", dinosaurs.true_for_all(predicate<const string&> {ends_with_saurus}));
console::write_line("\nfind(ends_with_saurus): {0}", dinosaurs.find(predicate<const string&> {ends_with_saurus}));
console::write_line("\nfindLast(ends_with_saurus): {0}", dinosaurs.find_last(predicate<const string&> {ends_with_saurus}));
console::write_line("\nfind_all(ends_with_saurus):");
auto sublist = dinosaurs.find_all(predicate<const string&> {ends_with_saurus});
for (const auto& dinosaur : sublist)
console::write_line(dinosaur);
console::write_line("\n{0} elements removed by remove_all(ends_with_saurus).", dinosaurs.remove_all(predicate<const string&> {ends_with_saurus}));
console::write_line("\nlist now contains:");
for (const auto& dinosaur : dinosaurs)
console::write_line(dinosaur);
console::write_line("\nexists(ends_with_saurus): {0}", dinosaurs.exists(predicate<const string&> {ends_with_saurus}));
}
private:
// Search predicate returns true if a string ends in "saurus".
static bool ends_with_saurus(const string& s) {
return s.to_lower().ends_with("saurus");
}
};
startup_(example::main);
// This code produces the following output :
//
//
// Compsognathus
// Amargasaurus
// Oviraptor
// Velociraptor
// Deinonychus
// Dilophosaurus
// Gallimimus
// Triceratops
//
// true_for_all(ends_with_saurus): false
//
// find(ends_with_saurus): Amargasaurus
//
// findLast(ends_with_saurus): Dilophosaurus
//
// find_all(ends_with_saurus):
// Amargasaurus
// Dilophosaurus
//
// 2 elements removed by remove_all(ends_with_saurus).
//
// list now contains:
// Compsognathus
// Oviraptor
// Velociraptor
// Deinonychus
// Gallimimus
// Triceratops
//
// exists(ends_with_saurus): false
Remarks
The xtd::predicate <type_t> is a delegate to a method that returns true if the object passed to it matches the conditions defined in the delegate. The elements of the current xtd::collections::generic::list <type_t> are individually passed to the xtd::predicate <type_t> delegate, and the elements that match the conditions are removed from the xtd::collections::generic::list <type_t>.
This method performs a linear search; therefore, this method is an O(n) operation, where n is xtd::collections::generic::list::count.

◆ find_all()

template<class type_t , class allocator_t >
list< type_t > xtd::collections::generic::list< type_t, allocator_t >::find_all ( xtd::predicate< const type_t & >  match) const
inline

Retrieves all the elements that match the conditions defined by the specified predicate.

Parameters
matchThe xtd::predicate <type_t> delegate that defines the conditions of the elements to search for.
Returns
A xtd::collections::generic::list <type_t> containing all the elements that match the conditions defined by the specified predicate, if found; otherwise, an empty xtd::collections::generic::list <type_t>.
Examples
The following example demonstrates the xtd::collections::generic::list::exists method and several other methods that use the xtd::predicate <type_t> generic delegate.
A xtd::collections::generic::list <type_t> of strings is created, containing 8 dinosaur names, two of which (at positions 1 and 5) end with "saurus". The example also defines a search predicate method named ends_with_saurus, which accepts a string parameter and returns a boolean value indicating whether the input string ends in "saurus".
The xtd::collections::generic::list::find, xtd::collections::generic::list::find_last, and xtd::collections::generic::list::findA_all methods are used to search the list with the search predicate method, and then the xtd::collections::generic::list::remove_all method is used to remove all entries ending with "saurus".
Finally, the xtd::collections::generic::list::exists method is called. It traverses the list from the beginning, passing each element in turn to the ends_with_saurus method. The search stops and the method returns true if the ends_with_saurus method returns true for any element. The xtd::collections::generic::list::exists method returns false because all such elements have been removed.
#include <xtd/xtd>
using namespace xtd;
using namespace xtd::collections::generic;
class example {
public:
static auto main() -> void {
auto dinosaurs = list<string> {};
dinosaurs.add("Compsognathus");
dinosaurs.add("Amargasaurus");
dinosaurs.add("Oviraptor");
dinosaurs.add("Velociraptor");
dinosaurs.add("Deinonychus");
dinosaurs.add("Dilophosaurus");
dinosaurs.add("Gallimimus");
dinosaurs.add("Triceratops");
console::write_line();
for (const auto& dinosaur : dinosaurs)
console::write_line(dinosaur);
console::write_line("\ntrue_for_all(ends_with_saurus): {0}", dinosaurs.true_for_all(predicate<const string&> {ends_with_saurus}));
console::write_line("\nfind(ends_with_saurus): {0}", dinosaurs.find(predicate<const string&> {ends_with_saurus}));
console::write_line("\nfindLast(ends_with_saurus): {0}", dinosaurs.find_last(predicate<const string&> {ends_with_saurus}));
console::write_line("\nfind_all(ends_with_saurus):");
auto sublist = dinosaurs.find_all(predicate<const string&> {ends_with_saurus});
for (const auto& dinosaur : sublist)
console::write_line(dinosaur);
console::write_line("\n{0} elements removed by remove_all(ends_with_saurus).", dinosaurs.remove_all(predicate<const string&> {ends_with_saurus}));
console::write_line("\nlist now contains:");
for (const auto& dinosaur : dinosaurs)
console::write_line(dinosaur);
console::write_line("\nexists(ends_with_saurus): {0}", dinosaurs.exists(predicate<const string&> {ends_with_saurus}));
}
private:
// Search predicate returns true if a string ends in "saurus".
static bool ends_with_saurus(const string& s) {
return s.to_lower().ends_with("saurus");
}
};
startup_(example::main);
// This code produces the following output :
//
//
// Compsognathus
// Amargasaurus
// Oviraptor
// Velociraptor
// Deinonychus
// Dilophosaurus
// Gallimimus
// Triceratops
//
// true_for_all(ends_with_saurus): false
//
// find(ends_with_saurus): Amargasaurus
//
// findLast(ends_with_saurus): Dilophosaurus
//
// find_all(ends_with_saurus):
// Amargasaurus
// Dilophosaurus
//
// 2 elements removed by remove_all(ends_with_saurus).
//
// list now contains:
// Compsognathus
// Oviraptor
// Velociraptor
// Deinonychus
// Gallimimus
// Triceratops
//
// exists(ends_with_saurus): false
Remarks
The xtd::predicate <type_t> is a delegate to a method that returns true if the object passed to it matches the conditions defined in the delegate. The elements of the current xtd::collections::generic::list <type_t> are individually passed to the xtd::predicate <type_t> delegate, and the elements that match the conditions are removed from the xtd::collections::generic::list <type_t>.
This method performs a linear search; therefore, this method is an O(n) operation, where n is xtd::collections::generic::list::count.

◆ find_index() [1/3]

template<class type_t , class allocator_t >
xtd::size xtd::collections::generic::list< type_t, allocator_t >::find_index ( xtd::predicate< const type_t & >  match) const
inline

Searches for an element that matches the conditions defined by the specified predicate, and returns the zero-based index of the first occurrence within the entire xtd::collections::generic::list <type_t>.

Parameters
matchThe xtd::predicate <type_t> delegate that defines the conditions of the elements to search for.
Returns
The zero-based index of the first occurrence of an element that matches the conditions defined by match, if found; otherwise, xtd::collections::generic::list::npos.
Remarks
The xtd::predicate <type_t> is a delegate to a method that returns true if the object passed to it matches the conditions defined in the delegate. The elements of the current xtd::collections::generic::list <type_t> are individually passed to the xtd::predicate <type_t> delegate, and the elements that match the conditions are removed from the xtd::collections::generic::list <type_t>.
This method performs a linear search; therefore, this method is an O(n) operation, where n is xtd::collections::generic::list::count.

◆ find_index() [2/3]

template<class type_t , class allocator_t >
xtd::size xtd::collections::generic::list< type_t, allocator_t >::find_index ( xtd::size  start_index,
xtd::predicate< const type_t & >  match 
) const
inline

Searches for an element that matches the conditions defined by the specified predicate, and returns the zero-based index of the first occurrence within the range of elements in the xtd::collections::generic::list <type_t> that extends from the specified index to the last element.

Parameters
start_indexThe zero-based starting index of the search.
matchThe xtd::predicate <type_t> delegate that defines the conditions of the elements to search for.
Returns
The zero-based index of the first occurrence of an element that matches the conditions defined by match, if found; otherwise, xtd::collections::generic::list::npos.
Exceptions
xtd::argument_out_of_range_exception`start_index` is outside the range of valid indexes for the xtd::collections::generic::list <type_t>..
Remarks
The xtd::predicate <type_t> is a delegate to a method that returns true if the object passed to it matches the conditions defined in the delegate. The elements of the current xtd::collections::generic::list <type_t> are individually passed to the xtd::predicate <type_t> delegate, and the elements that match the conditions are removed from the xtd::collections::generic::list <type_t>.
This method performs a linear search; therefore, this method is an O(n) operation, where n is xtd::collections::generic::list::count.

◆ find_index() [3/3]

template<class type_t , class allocator_t >
xtd::size xtd::collections::generic::list< type_t, allocator_t >::find_index ( xtd::size  start_index,
xtd::size  count,
xtd::predicate< const type_t & >  match 
) const
inline

Searches for an element that matches the conditions defined by the specified predicate, and returns the zero-based index of the first occurrence within the range of elements in the xtd::collections::generic::list <type_t> that starts at the specified index and contains the specified number of elements.

Parameters
start_indexThe zero-based starting index of the search.
countThe number of elements in the section to search.
matchThe xtd::predicate <type_t> delegate that defines the conditions of the elements to search for.
Returns
The zero-based index of the first occurrence of an element that matches the conditions defined by match, if found; otherwise, xtd::collections::generic::list::npos.
Exceptions
xtd::argument_out_of_range_exception`start_index` is outside the range of valid indexes for the xtd::collections::generic::list <type_t>.
-or-
`start_index` and `count` do not specify a valid section in the xtd::collections::generic::list <type_t>.
Remarks
The xtd::predicate <type_t> is a delegate to a method that returns true if the object passed to it matches the conditions defined in the delegate. The elements of the current xtd::collections::generic::list <type_t> are individually passed to the xtd::predicate <type_t> delegate, and the elements that match the conditions are removed from the xtd::collections::generic::list <type_t>.
This method performs a linear search; therefore, this method is an O(n) operation, where n is xtd::collections::generic::list::count.

◆ find_last()

template<class type_t , class allocator_t >
type_t xtd::collections::generic::list< type_t, allocator_t >::find_last ( xtd::predicate< const type_t & >  match) const
inline

Searches for an element that matches the conditions defined by the specified predicate, and returns the last occurrence within the entire xtd::collections::generic::list <type_t>.

Parameters
matchThe xtd::predicate <type_t> delegate that defines the conditions of the elements to search for.
Returns
The last element that matches the conditions defined by the specified predicate, if found; otherwise, the default value for type type_t.
Examples
The following example demonstrates the xtd::collections::generic::list::exists method and several other methods that use the xtd::predicate <type_t> generic delegate.
A xtd::collections::generic::list <type_t> of strings is created, containing 8 dinosaur names, two of which (at positions 1 and 5) end with "saurus". The example also defines a search predicate method named ends_with_saurus, which accepts a string parameter and returns a boolean value indicating whether the input string ends in "saurus".
The xtd::collections::generic::list::find, xtd::collections::generic::list::find_last, and xtd::collections::generic::list::findA_all methods are used to search the list with the search predicate method, and then the xtd::collections::generic::list::remove_all method is used to remove all entries ending with "saurus".
Finally, the xtd::collections::generic::list::exists method is called. It traverses the list from the beginning, passing each element in turn to the ends_with_saurus method. The search stops and the method returns true if the ends_with_saurus method returns true for any element. The xtd::collections::generic::list::exists method returns false because all such elements have been removed.
#include <xtd/xtd>
using namespace xtd;
using namespace xtd::collections::generic;
class example {
public:
static auto main() -> void {
auto dinosaurs = list<string> {};
dinosaurs.add("Compsognathus");
dinosaurs.add("Amargasaurus");
dinosaurs.add("Oviraptor");
dinosaurs.add("Velociraptor");
dinosaurs.add("Deinonychus");
dinosaurs.add("Dilophosaurus");
dinosaurs.add("Gallimimus");
dinosaurs.add("Triceratops");
console::write_line();
for (const auto& dinosaur : dinosaurs)
console::write_line(dinosaur);
console::write_line("\ntrue_for_all(ends_with_saurus): {0}", dinosaurs.true_for_all(predicate<const string&> {ends_with_saurus}));
console::write_line("\nfind(ends_with_saurus): {0}", dinosaurs.find(predicate<const string&> {ends_with_saurus}));
console::write_line("\nfindLast(ends_with_saurus): {0}", dinosaurs.find_last(predicate<const string&> {ends_with_saurus}));
console::write_line("\nfind_all(ends_with_saurus):");
auto sublist = dinosaurs.find_all(predicate<const string&> {ends_with_saurus});
for (const auto& dinosaur : sublist)
console::write_line(dinosaur);
console::write_line("\n{0} elements removed by remove_all(ends_with_saurus).", dinosaurs.remove_all(predicate<const string&> {ends_with_saurus}));
console::write_line("\nlist now contains:");
for (const auto& dinosaur : dinosaurs)
console::write_line(dinosaur);
console::write_line("\nexists(ends_with_saurus): {0}", dinosaurs.exists(predicate<const string&> {ends_with_saurus}));
}
private:
// Search predicate returns true if a string ends in "saurus".
static bool ends_with_saurus(const string& s) {
return s.to_lower().ends_with("saurus");
}
};
startup_(example::main);
// This code produces the following output :
//
//
// Compsognathus
// Amargasaurus
// Oviraptor
// Velociraptor
// Deinonychus
// Dilophosaurus
// Gallimimus
// Triceratops
//
// true_for_all(ends_with_saurus): false
//
// find(ends_with_saurus): Amargasaurus
//
// findLast(ends_with_saurus): Dilophosaurus
//
// find_all(ends_with_saurus):
// Amargasaurus
// Dilophosaurus
//
// 2 elements removed by remove_all(ends_with_saurus).
//
// list now contains:
// Compsognathus
// Oviraptor
// Velociraptor
// Deinonychus
// Gallimimus
// Triceratops
//
// exists(ends_with_saurus): false
Remarks
The xtd::predicate <type_t> is a delegate to a method that returns true if the object passed to it matches the conditions defined in the delegate. The elements of the current xtd::collections::generic::list <type_t> are individually passed to the xtd::predicate <type_t> delegate, and the elements that match the conditions are removed from the xtd::collections::generic::list <type_t>.
This method performs a linear search; therefore, this method is an O(n) operation, where n is xtd::collections::generic::list::count.

◆ find_last_index() [1/3]

template<class type_t , class allocator_t >
xtd::size xtd::collections::generic::list< type_t, allocator_t >::find_last_index ( xtd::predicate< const type_t & >  match) const
inline

Searches for an element that matches the conditions defined by the specified predicate, and returns the zero-based index of the last occurrence within the entire xtd::collections::generic::list <type_t>.

Parameters
matchThe xtd::predicate <type_t> delegate that defines the conditions of the elements to search for.
Returns
The zero-based index of the last occurrence of an element that matches the conditions defined by match, if found; otherwise, xtd::collections::generic::list::npos.
Remarks
The xtd::predicate <type_t> is a delegate to a method that returns true if the object passed to it matches the conditions defined in the delegate. The elements of the current xtd::collections::generic::list <type_t> are individually passed to the xtd::predicate <type_t> delegate, and the elements that match the conditions are removed from the xtd::collections::generic::list <type_t>.
This method performs a linear search; therefore, this method is an O(n) operation, where n is xtd::collections::generic::list::count.

◆ find_last_index() [2/3]

template<class type_t , class allocator_t >
xtd::size xtd::collections::generic::list< type_t, allocator_t >::find_last_index ( xtd::size  start_index,
xtd::predicate< const type_t & >  match 
) const
inline

Searches for an element that matches the conditions defined by the specified predicate, and returns the zero-based index of the last occurrence within the range of elements in the xtd::collections::generic::list <type_t> that extends from the first element to the specified index.

Parameters
start_indexThe zero-based starting index of the backward search.
matchThe xtd::predicate <type_t> delegate that defines the conditions of the elements to search for.
Returns
The zero-based index of the last occurrence of an element that matches the conditions defined by match, if found; otherwise, xtd::collections::generic::list::npos.
Exceptions
xtd::argument_out_of_range_exception`start_index` is outside the range of valid indexes for the xtd::collections::generic::list <type_t>.
Remarks
The xtd::predicate <type_t> is a delegate to a method that returns true if the object passed to it matches the conditions defined in the delegate. The elements of the current xtd::collections::generic::list <type_t> are individually passed to the xtd::predicate <type_t> delegate, and the elements that match the conditions are removed from the xtd::collections::generic::list <type_t>.
This method performs a linear search; therefore, this method is an O(n) operation, where n is xtd::collections::generic::list::count.

◆ find_last_index() [3/3]

template<class type_t , class allocator_t >
xtd::size xtd::collections::generic::list< type_t, allocator_t >::find_last_index ( xtd::size  start_index,
xtd::size  count,
xtd::predicate< const type_t & >  match 
) const
inline

Searches for an element that matches the conditions defined by the specified predicate, and returns the zero-based index of the last occurrence within the range of elements in the xtd::collections::generic::list <type_t> that contains the specified number of elements and ends at the specified index.

Parameters
start_indexThe zero-based starting index of the backward search.
countThe number of elements in the section to search.
matchThe xtd::predicate <type_t> delegate that defines the conditions of the elements to search for.
Returns
The zero-based index of the last occurrence of an element that matches the conditions defined by match, if found; otherwise, xtd::collections::generic::list::npos.
Exceptions
xtd::argument_out_of_range_exception`start_index` is outside the range of valid indexes for the xtd::collections::generic::list <type_t>.
-or-
`start_index` and `count` do not specify a valid section in the xtd::collections::generic::list <type_t>.
Remarks
The xtd::predicate <type_t> is a delegate to a method that returns true if the object passed to it matches the conditions defined in the delegate. The elements of the current xtd::collections::generic::list <type_t> are individually passed to the xtd::predicate <type_t> delegate, and the elements that match the conditions are removed from the xtd::collections::generic::list <type_t>.
This method performs a linear search; therefore, this method is an O(n) operation, where n is xtd::collections::generic::list::count.

◆ for_each()

template<class type_t , class allocator_t >
void xtd::collections::generic::list< type_t, allocator_t >::for_each ( xtd::action< const type_t & >  action)
inline

Performs the specified action on each element of the xtd::collections::generic::list <type_t>.

Parameters
actionThe xtd::action <type_t> delegate to perform on each element of the xtd::collections::generic::list <type_t>.
Examples
The following example demonstrates the use of the xtd::action <type_t> delegate to print the contents of a xtd::collections::generic::list <type_t> object. In this example the print method is used to display the contents of the list to the console.
#include <xtd/xtd>
using namespace xtd;
using namespace xtd::collections::generic;
class example {
public:
static auto main() -> void {
auto names = list<string> {};
names.add("Bruce");
names.add("Alfred");
names.add("Tim");
names.add("Richard");
names.for_each(action<const string&> {print});
names.for_each(action<const string&> {[](const string& name) {
console::write_line(name);
}});
}
private:
static void print(const string& s) {
console::write_line(s);
}
};
startup_(example::main);
// This code produces the following output :
//
// Bruce
// Alfred
// Tim
// Richard
// Bruce
// Alfred
// Tim
// Richard
delegate< void(arguments_t...)> action
Represents a xtd::delegate that has variable parameters and does not return a value.
Definition action.hpp:20
void print(FILE *file, arg_t &&value)
Writes the text representation of the specified value to the file output stream.
Definition print.hpp:19
Remarks
The xtd::action <type_t> is a delegate to a method that performs an action on the object passed to it. The elements of the current xtd::collections::generic::list <type_t> are individually passed to the xtd::action <type_t> delegate.
This method is an O(n) operation, where n is xtd::collections::generic::list::count.
Modifying the underlying collection in the body of the Action<T> delegate is not supported and causes undefined behavior.

◆ get_allocator()

template<class type_t , class allocator_t >
virtual allocator_type xtd::collections::generic::list< type_t, allocator_t >::get_allocator ( ) const
inlinevirtual

Returns the allocator associated with the container.

Returns
The associated allocator.

◆ get_base_type() [1/2]

template<class type_t , class allocator_t >
virtual base_type & xtd::collections::generic::list< type_t, allocator_t >::get_base_type ( )
inlinevirtualnoexcept

Returns the underlying base type.

Returns
The underlying base type.
Warning
Don't manipulate the xtd::collections::generic::list::base_type yourself, otherwise the expected result may be undefined.

◆ get_base_type() [2/2]

template<class type_t , class allocator_t >
virtual const base_type & xtd::collections::generic::list< type_t, allocator_t >::get_base_type ( ) const
inlinevirtualnoexcept

Returns the underlying base type.

Returns
The underlying base type.

◆ get_enumerator()

template<class type_t , class allocator_t >
enumerator< value_type > xtd::collections::generic::list< type_t, allocator_t >::get_enumerator ( ) const
inlineoverridevirtualnoexcept

Returns an enumerator that iterates through the xtd::collections::generic::list <type_t>.

Returns
A xtd::collections::generic::.enumerator for the xtd::collections::generic::list <type_t>.

Implements xtd::collections::generic::ienumerable< type_t >.

◆ get_range()

template<class type_t , class allocator_t >
list xtd::collections::generic::list< type_t, allocator_t >::get_range ( size_type  index,
size_type  count 
)
inline

Creates a shallow copy of a range of elements in the source xtd::collections::generic::list <type_t>.

Parameters
indexThe zero-based xtd::collections::generic::list <type_t> index at which the range starts.
countThe number of elements in the range.
Returns
A shallow copy of a range of elements in the source xtd::collections::generic::list <type_t>.
Exceptions
xtd::argument_exceptionindex and count do ! denote a valid range of elements in the xtd::collections::generic::list <type_t>.
Examples
The following code example demonstrates the xtd::collections::generic::list::get_range method and other methods of the xtd::collections::generic::list <type_t> class that act on ranges. At the end of the code example, the xtd::collections::generic::list::get_range method is used to get three items from the list, beginning with index location 2. The xtd::collections::generic::ist::to_array method is called on the resulting xtd::collections::generic::list <type_t>, creating an array of three elements. The elements of the array are displayed.
Remarks
A shallow copy of a collection of reference types, or a subset of that collection, contains only the references to the elements of the collection. The objects themselves are ! copied. The references in the new list point to the same objects as the references in the original list.
A shallow copy of a collection of value types, or a subset of that collection, contains the elements of the collection. However, if the elements of the collection contain references to other objects, those objects are ! copied. The references in the elements of the new collection point to the same objects as the references in the elements of the original collection.
In contrast, a deep copy of a collection copies the elements and everything directly or indirectly referenced by the elements.
This method is an O(n) operation, where n is count.

◆ index_of() [1/3]

template<class type_t , class allocator_t >
size_type xtd::collections::generic::list< type_t, allocator_t >::index_of ( const type_t &  value) const
inlineoverridevirtualnoexcept

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

Parameters
valueThe object to locate in the xtd::collections::generic::list <type_t>.
Returns
The index of value if found in the list; otherwise, xtd::collections::generic::ilist::npos.

Implements xtd::collections::generic::ilist< type_t >.

◆ index_of() [2/3]

template<class type_t , class allocator_t >
virtual size_type xtd::collections::generic::list< type_t, allocator_t >::index_of ( const type_t &  value,
size_type  index 
) const
inlinevirtual

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

Parameters
valueThe object to locate in the xtd::collections::generic::list <type_t>.
indexThe zero-based starting index of the search.
Returns
The index of value if found in the xtd::collections::generic::list; otherwise, xtd::collections::generic::ilist::npos.
Exceptions
xtd::argument_out_of_range_exception`index` is outside the range of valid indexes for the xtd::collections::generic::list <type_t>.

◆ index_of() [3/3]

template<class type_t , class allocator_t >
virtual size_type xtd::collections::generic::list< type_t, allocator_t >::index_of ( const type_t &  value,
size_type  index,
size_type  count 
) const
inlinevirtual

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

Parameters
valueThe object to locate in the xtd::collections::generic::list <type_t>.
indexThe zero-based starting index of the search.
countThe number of elements in the section to search
Returns
The index of value if found in the xtd::collections::generic::list; otherwise, xtd::collections::generic::ilist::npos.
Exceptions
xtd::argument_out_of_range_exception`index` and `countù do not specify a valid section in the xtd::collections::generic::list <type_t>.

◆ insert() [1/6]

template<class type_t , class allocator_t >
virtual iterator xtd::collections::generic::list< type_t, allocator_t >::insert ( const_iterator  pos,
const type_t &  value 
)
inlinevirtual

Inserts elements at the specified location in the container.

Parameters
posthe iterator before which the content will be inserted (pos may be the end() iterator).
valueThe element value to insert.
Returns
The iterator pointing to the inserted value.
Remarks
Inserts value before pos.
If after the operation the new xtd::collections::generic::list::size() is greater than old xtd::collections::generic::list::capacity() a reallocation takes place, in which case all iterators (including the xtd::collections::generic::list::end() iterator) and all references to the elements are invalidated. Otherwise, only the iterators and references before the insertion point remain valid.

◆ insert() [2/6]

template<class type_t , class allocator_t >
virtual iterator xtd::collections::generic::list< type_t, allocator_t >::insert ( const_iterator  pos,
const type_t &&  value 
)
inlinevirtual

Inserts elements at the specified location in the container.

Parameters
posthe iterator before which the content will be inserted (pos may be the end() iterator).
valueThe element value to insert.
Returns
The iterator pointing to the inserted value.
Remarks
Inserts value before pos.
If after the operation the new xtd::collections::generic::list::size() is greater than old xtd::collections::generic::list::capacity() a reallocation takes place, in which case all iterators (including the xtd::collections::generic::list::end() iterator) and all references to the elements are invalidated. Otherwise, only the iterators and references before the insertion point remain valid.

◆ insert() [3/6]

template<class type_t , class allocator_t >
virtual iterator xtd::collections::generic::list< type_t, allocator_t >::insert ( const_iterator  pos,
size_type  count,
const type_t &  value 
)
inlinevirtual

Inserts elements at the specified location in the container.

Parameters
posthe iterator before which the content will be inserted (pos may be the end() iterator).
countThe number of elements to insert.
valueThe element value to insert.
Returns
The iterator pointing to the first element inserted, or pos if count == 0.
Remarks
Iterator pointing to the first element inserted, or pos if count == 0.
If after the operation the new xtd::collections::generic::list::size() is greater than old xtd::collections::generic::list::capacity() a reallocation takes place, in which case all iterators (including the xtd::collections::generic::list::end() iterator) and all references to the elements are invalidated. Otherwise, only the iterators and references before the insertion point remain valid.

◆ insert() [4/6]

template<class type_t , class allocator_t >
template<class input_iterator_t >
iterator xtd::collections::generic::list< type_t, allocator_t >::insert ( const_iterator  pos,
input_iterator_t  first,
input_iterator_t  last 
)
inline

Inserts elements at the specified location in the container.

Parameters
firstThe first range of elements to insert, cannot be iterators into container for which insert is called
lastThe last range of elements to insert, cannot be iterators into container for which insert is called
Returns
The iterator pointing to the first element inserted, or pos if first == last.
Remarks
Inserts elements from range [first, last) before pos.
If first and last are iterators into *this, the behavior is undefined.
If after the operation the new xtd::collections::generic::list::size() is greater than old xtd::collections::generic::list::capacity() a reallocation takes place, in which case all iterators (including the xtd::collections::generic::list::end() iterator) and all references to the elements are invalidated. Otherwise, only the iterators and references before the insertion point remain valid.

◆ insert() [5/6]

template<class type_t , class allocator_t >
virtual iterator xtd::collections::generic::list< type_t, allocator_t >::insert ( const_iterator  pos,
const std::initializer_list< type_t > &  items 
)
inlinevirtual

Inserts elements at the specified location in the container.

Parameters
posthe iterator before which the content will be inserted (pos may be the end() iterator).
itemsThe initializer list to insert the values from.
Returns
The iterator pointing to the first element inserted, or pos if items is empty.
Remarks
Inserts value before pos.
Inserts elements from initializer list items before pos.

◆ insert() [6/6]

template<class type_t , class allocator_t >
void xtd::collections::generic::list< type_t, allocator_t >::insert ( size_type  index,
const type_t &  value 
)
inlineoverridevirtual

Inserts an element into the xtd::collections::generic::list <type_t> at the specified index.

Parameters
indexThe zero-based index at which the new element should be inserted.
valueThe element should be inserted into the xtd::collections::generic::list <type_t>.
Exceptions
xtd::argument_out_of_range_exceptionindex is is greater than xtd::collections::generic::list::count.
Remarks
xtd::collections::generic::list <type_t> allows duplicate elements.

Implements xtd::collections::generic::ilist< type_t >.

◆ insert_range() [1/2]

template<class type_t , class allocator_t >
virtual void xtd::collections::generic::list< type_t, allocator_t >::insert_range ( size_type  index,
const xtd::collections::generic::ienumerable< type_t > &  enumerable 
)
inlinevirtual

Inserts copy of elements from a collection into the xtd::collections::generic::list <type_t> at the specified index.

Parameters
indexThe zero-based index at which the new elements should be inserted.
collectionThe collection whose elements should be inserted into the xtd::collections::generic::list <type_t>.
Exceptions
xtd::argument_out_of_range_exceptionindex is is greater than xtd::collections::generic::list::count.
Examples
The following code example demonstrates the xtd::collections::generic::list <type_t> constructor and various methods of the xtd::collections::generic::list <type_t> class that act on ranges. An array of strings is created and passed to the constructor, populating the list with the elements of the array. The xtd::collections::generic::list::capacity property is then displayed, to show that the initial capacity is exactly what is required to hold the input elements.
#include <xtd/xtd>
using namespace xtd;
using namespace xtd::collections::generic;
class example {
public:
static auto main() -> void {
auto input = array<string> {"Brachiosaurus", "Amargasaurus", "Mamenchisaurus"};
auto dinosaurs = list<string>(input);
console::write_line("\ncapacity: {0}", dinosaurs.capacity());
console::write_line();
for (auto dinosaur : dinosaurs)
console::write_line(dinosaur);
console::write_line("\nadd_range(dinosaurs)");
dinosaurs.add_range(dinosaurs);
console::write_line();
for(auto dinosaur : dinosaurs)
console::write_line(dinosaur);
console::write_line("\nremove_range(2, 2)");
dinosaurs.remove_range(2, 2);
console::write_line();
for(auto dinosaur : dinosaurs)
console::write_line(dinosaur);
input = {"Tyrannosaurus", "Deinonychus", "Velociraptor"};
console::write_line("\ninsert_range(3, input)");
dinosaurs.insert_range(3, input);
console::write_line();
for(auto dinosaur : dinosaurs)
console::write_line(dinosaur);
console::write_line("\noutput = dinosaurs.get_range(2, 3).to_array()");
auto output = dinosaurs.get_range(2, 3).to_array();
console::write_line();
for (auto dinosaur : output)
console::write_line(dinosaur);
}
};
startup_(example::main);
// This code produces the following output :
//
//
// capacity: 3
//
// Brachiosaurus
// Amargasaurus
// Mamenchisaurus
//
// add_range(dinosaurs)
//
// Brachiosaurus
// Amargasaurus
// Mamenchisaurus
// Brachiosaurus
// Amargasaurus
// Mamenchisaurus
//
// remove_range(2, 2)
//
// Brachiosaurus
// Amargasaurus
// Amargasaurus
// Mamenchisaurus
//
// insert_range(3, input)
//
// Brachiosaurus
// Amargasaurus
// Amargasaurus
// Tyrannosaurus
// Deinonychus
// Velociraptor
// Mamenchisaurus
//
// output = dinosaurs.get_range(2, 3).to_array()
//
// Amargasaurus
// Tyrannosaurus
// Deinonychus
Remarks
xtd::collections::generic::list <type_t> allows duplicate elements.
The order of the elements in the collection is preserved in the xtd::collections::generic::list <type_t>.

◆ insert_range() [2/2]

template<class type_t , class allocator_t >
virtual void xtd::collections::generic::list< type_t, allocator_t >::insert_range ( size_type  index,
const std::initializer_list< type_t > &  items 
)
inlinevirtual

Inserts copy of elements from a collection into the xtd::collections::generic::list <type_t> at the specified index.

Parameters
indexThe zero-based index at which the new elements should be inserted.
collectionThe collection whose elements should be inserted into the xtd::collections::generic::list <type_t>.
Exceptions
xtd::argument_out_of_range_exceptionindex is is greater than xtd::collections::generic::list::count.
Examples
The following code example demonstrates the xtd::collections::generic::list <type_t> constructor and various methods of the xtd::collections::generic::list <type_t> class that act on ranges. An array of strings is created and passed to the constructor, populating the list with the elements of the array. The xtd::collections::generic::list::capacity property is then displayed, to show that the initial capacity is exactly what is required to hold the input elements.
#include <xtd/xtd>
using namespace xtd;
using namespace xtd::collections::generic;
class example {
public:
static auto main() -> void {
auto input = array<string> {"Brachiosaurus", "Amargasaurus", "Mamenchisaurus"};
auto dinosaurs = list<string>(input);
console::write_line("\ncapacity: {0}", dinosaurs.capacity());
console::write_line();
for (auto dinosaur : dinosaurs)
console::write_line(dinosaur);
console::write_line("\nadd_range(dinosaurs)");
dinosaurs.add_range(dinosaurs);
console::write_line();
for(auto dinosaur : dinosaurs)
console::write_line(dinosaur);
console::write_line("\nremove_range(2, 2)");
dinosaurs.remove_range(2, 2);
console::write_line();
for(auto dinosaur : dinosaurs)
console::write_line(dinosaur);
input = {"Tyrannosaurus", "Deinonychus", "Velociraptor"};
console::write_line("\ninsert_range(3, input)");
dinosaurs.insert_range(3, input);
console::write_line();
for(auto dinosaur : dinosaurs)
console::write_line(dinosaur);
console::write_line("\noutput = dinosaurs.get_range(2, 3).to_array()");
auto output = dinosaurs.get_range(2, 3).to_array();
console::write_line();
for (auto dinosaur : output)
console::write_line(dinosaur);
}
};
startup_(example::main);
// This code produces the following output :
//
//
// capacity: 3
//
// Brachiosaurus
// Amargasaurus
// Mamenchisaurus
//
// add_range(dinosaurs)
//
// Brachiosaurus
// Amargasaurus
// Mamenchisaurus
// Brachiosaurus
// Amargasaurus
// Mamenchisaurus
//
// remove_range(2, 2)
//
// Brachiosaurus
// Amargasaurus
// Amargasaurus
// Mamenchisaurus
//
// insert_range(3, input)
//
// Brachiosaurus
// Amargasaurus
// Amargasaurus
// Tyrannosaurus
// Deinonychus
// Velociraptor
// Mamenchisaurus
//
// output = dinosaurs.get_range(2, 3).to_array()
//
// Amargasaurus
// Tyrannosaurus
// Deinonychus
Remarks
xtd::collections::generic::list <type_t> allows duplicate elements.
The order of the elements in the collection is preserved in the xtd::collections::generic::list <type_t>.

◆ last_index_of() [1/3]

template<class type_t , class allocator_t >
size_type xtd::collections::generic::list< type_t, allocator_t >::last_index_of ( const type_t &  value) const
inline

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

Parameters
valueThe object to locate in the xtd::collections::generic::list <type_t>.
Returns
Int32 The last index of value if found in the list; otherwise, xtd::collections::generic::list::npos.

◆ last_index_of() [2/3]

template<class type_t , class allocator_t >
size_type xtd::collections::generic::list< type_t, allocator_t >::last_index_of ( const type_t &  value,
size_type  index 
) const
inline

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

Parameters
valueThe object to locate in the xtd::collections::generic::list <type_t>.
indexThe zero-based starting index of the search.
Returns
Int32 The last index of value if found in the list; otherwise, xtd::collections::generic::list::npos.
Exceptions
xd::argument_exceptionThe parameters `indexù is greater than xtd::collections::generic::list::count().

◆ last_index_of() [3/3]

template<class type_t , class allocator_t >
size_type xtd::collections::generic::list< type_t, allocator_t >::last_index_of ( const type_t &  value,
size_type  index,
size_type  count 
) const
inline

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

Parameters
valueThe object to locate in the xtd::collections::generic::list <type_t>.
indexThe zero-based starting index of the search.
countThe number of elements in the section to search
Returns
Int32 The last index of value if found in the list; otherwise, xtd::collections::generic::list::npos.
Exceptions
xd::argument_exception`index` and `count` do not specify a valid section in the xtd::collections::generic::list <type_t>.

◆ pop_back()

template<class type_t , class allocator_t >
virtual void xtd::collections::generic::list< type_t, allocator_t >::pop_back ( )
inlinevirtual

Removes the last element of the container.

Remarks
Calling pop_back on an empty container results in undefined behavior.
Iterators (including the xtd::collections::generic::list::end() iterator) and references to the last element are invalidated.

◆ push_back() [1/2]

template<class type_t , class allocator_t >
virtual void xtd::collections::generic::list< type_t, allocator_t >::push_back ( const type_t &  value)
inlinevirtual

Appends the given element value to the end of the container.

Parameters
valueThe value of the element to append.
Remarks
If after the operation the new xtd::collections::generic::list::size() is greater than old xtd::collections::generic::list::capacity() a reallocation takes place, in which case all iterators (including the xtd::collections::generic::list::end() iterator) and all references to the elements are invalidated. Otherwise only the xtd::collections::generic::list::end() iterator is invalidated.
The new element is initialized as a copy of value.
Examples
boxing.cpp, console_firework.cpp, file_info_move_to.cpp, and generic_ienumerable.cpp.

◆ push_back() [2/2]

template<class type_t , class allocator_t >
virtual void xtd::collections::generic::list< type_t, allocator_t >::push_back ( type_t &&  value)
inlinevirtual

Appends the given element value to the end of the container.

Parameters
valueThe value of the element to append.
Remarks
If after the operation the new xtd::collections::generic::list::size() is greater than old xtd::collections::generic::list::capacity() a reallocation takes place, in which case all iterators (including the xtd::collections::generic::list::end() iterator) and all references to the elements are invalidated. Otherwise only the xtd::collections::generic::list::end() iterator is invalidated.
value is moved into the new element.

◆ remove()

template<class type_t , class allocator_t >
bool xtd::collections::generic::list< type_t, allocator_t >::remove ( const type_t &  item)
inlineoverridevirtual

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

Parameters
itemThe object to remove from the xtd::collections::generic::list <type_t>.
Returns
true if item is successfully removed; otherwise, false. This method also returns false if item was not found in the xtd::collections::generic::list <type_t>.
Remarks
If type typ_t implements the xtd::iequatable <type_t> generic interface, the equality comparer is the xtd::iequatable::equals method of that interface; otherwise, the default equality comparer is xtd::object::equals.
This method performs a linear search; therefore, this method is an O(n) operation, where n is xtd::collections::generic::list::count.

Implements xtd::collections::generic::icollection< type_t >.

◆ remove_all()

template<class type_t , class allocator_t >
xtd::size xtd::collections::generic::list< type_t, allocator_t >::remove_all ( const xtd::predicate< const type_t & > &  match)
inline

Removes all the elements that match the conditions defined by the specified predicate.

Parameters
matchThe xtd::predicate <type_t> delegate that defines the conditions of the elements to search for.
Returns
The number of elements removed from the xtd::collections::generic::list <type_t>.
Examples
The following example demonstrates the xtd::collections::generic::list::exists method and several other methods that use the xtd::predicate <type_t> generic delegate.
A xtd::collections::generic::list <type_t> of strings is created, containing 8 dinosaur names, two of which (at positions 1 and 5) end with "saurus". The example also defines a search predicate method named ends_with_saurus, which accepts a string parameter and returns a boolean value indicating whether the input string ends in "saurus".
The xtd::collections::generic::list::find, xtd::collections::generic::list::find_last, and xtd::collections::generic::list::findA_all methods are used to search the list with the search predicate method, and then the xtd::collections::generic::list::remove_all method is used to remove all entries ending with "saurus".
Finally, the xtd::collections::generic::list::exists method is called. It traverses the list from the beginning, passing each element in turn to the ends_with_saurus method. The search stops and the method returns true if the ends_with_saurus method returns true for any element. The xtd::collections::generic::list::exists method returns false because all such elements have been removed.
#include <xtd/xtd>
using namespace xtd;
using namespace xtd::collections::generic;
class example {
public:
static auto main() -> void {
auto dinosaurs = list<string> {};
dinosaurs.add("Compsognathus");
dinosaurs.add("Amargasaurus");
dinosaurs.add("Oviraptor");
dinosaurs.add("Velociraptor");
dinosaurs.add("Deinonychus");
dinosaurs.add("Dilophosaurus");
dinosaurs.add("Gallimimus");
dinosaurs.add("Triceratops");
console::write_line();
for (const auto& dinosaur : dinosaurs)
console::write_line(dinosaur);
console::write_line("\ntrue_for_all(ends_with_saurus): {0}", dinosaurs.true_for_all(predicate<const string&> {ends_with_saurus}));
console::write_line("\nfind(ends_with_saurus): {0}", dinosaurs.find(predicate<const string&> {ends_with_saurus}));
console::write_line("\nfindLast(ends_with_saurus): {0}", dinosaurs.find_last(predicate<const string&> {ends_with_saurus}));
console::write_line("\nfind_all(ends_with_saurus):");
auto sublist = dinosaurs.find_all(predicate<const string&> {ends_with_saurus});
for (const auto& dinosaur : sublist)
console::write_line(dinosaur);
console::write_line("\n{0} elements removed by remove_all(ends_with_saurus).", dinosaurs.remove_all(predicate<const string&> {ends_with_saurus}));
console::write_line("\nlist now contains:");
for (const auto& dinosaur : dinosaurs)
console::write_line(dinosaur);
console::write_line("\nexists(ends_with_saurus): {0}", dinosaurs.exists(predicate<const string&> {ends_with_saurus}));
}
private:
// Search predicate returns true if a string ends in "saurus".
static bool ends_with_saurus(const string& s) {
return s.to_lower().ends_with("saurus");
}
};
startup_(example::main);
// This code produces the following output :
//
//
// Compsognathus
// Amargasaurus
// Oviraptor
// Velociraptor
// Deinonychus
// Dilophosaurus
// Gallimimus
// Triceratops
//
// true_for_all(ends_with_saurus): false
//
// find(ends_with_saurus): Amargasaurus
//
// findLast(ends_with_saurus): Dilophosaurus
//
// find_all(ends_with_saurus):
// Amargasaurus
// Dilophosaurus
//
// 2 elements removed by remove_all(ends_with_saurus).
//
// list now contains:
// Compsognathus
// Oviraptor
// Velociraptor
// Deinonychus
// Gallimimus
// Triceratops
//
// exists(ends_with_saurus): false
Remarks
The xtd::predicate <type_t> is a delegate to a method that returns true if the object passed to it matches the conditions defined in the delegate. The elements of the current xtd::collections::generic::list <type_t> are individually passed to the xtd::predicate <type_t> delegate, and the elements that match the conditions are removed from the xtd::collections::generic::list <type_t>.
This method performs a linear search; therefore, this method is an O(n) operation, where n is xtd::collections::generic::list::count.

◆ remove_at()

template<class type_t , class allocator_t >
void xtd::collections::generic::list< type_t, allocator_t >::remove_at ( size_type  index)
inlineoverridevirtual

Removes the element at the specified index of the xtd::collections::generic::list <type_t>.

Parameters
indexThe zero-based index of the item to remove
Exceptions
ArgumentOutOfRangeExceptionindex is less than 0 or index is greater than xtd::collections::generic::list::count.

Implements xtd::collections::generic::ilist< type_t >.

◆ remove_range()

template<class type_t , class allocator_t >
virtual void xtd::collections::generic::list< type_t, allocator_t >::remove_range ( size_type  index,
size_type  count 
)
inlinevirtual

Removes a range of elements from the xtd::collections::generic::list <type_t>.

Parameters
indexThe zero-based index of the item to remove
countThe number of elements to remove
Exceptions
xtd::argument_out_of_range_exceptionindex or count is less than 0 or index + count is greater than xtd::collections::generic::list::count.
Examples
The following code example demonstrates the xtd::collections::generic::list <type_t> constructor and various methods of the xtd::collections::generic::list <type_t> class that act on ranges. An array of strings is created and passed to the constructor, populating the list with the elements of the array. The xtd::collections::generic::list::capacity property is then displayed, to show that the initial capacity is exactly what is required to hold the input elements.
#include <xtd/xtd>
using namespace xtd;
using namespace xtd::collections::generic;
class example {
public:
static auto main() -> void {
auto input = array<string> {"Brachiosaurus", "Amargasaurus", "Mamenchisaurus"};
auto dinosaurs = list<string>(input);
console::write_line("\ncapacity: {0}", dinosaurs.capacity());
console::write_line();
for (auto dinosaur : dinosaurs)
console::write_line(dinosaur);
console::write_line("\nadd_range(dinosaurs)");
dinosaurs.add_range(dinosaurs);
console::write_line();
for(auto dinosaur : dinosaurs)
console::write_line(dinosaur);
console::write_line("\nremove_range(2, 2)");
dinosaurs.remove_range(2, 2);
console::write_line();
for(auto dinosaur : dinosaurs)
console::write_line(dinosaur);
input = {"Tyrannosaurus", "Deinonychus", "Velociraptor"};
console::write_line("\ninsert_range(3, input)");
dinosaurs.insert_range(3, input);
console::write_line();
for(auto dinosaur : dinosaurs)
console::write_line(dinosaur);
console::write_line("\noutput = dinosaurs.get_range(2, 3).to_array()");
auto output = dinosaurs.get_range(2, 3).to_array();
console::write_line();
for (auto dinosaur : output)
console::write_line(dinosaur);
}
};
startup_(example::main);
// This code produces the following output :
//
//
// capacity: 3
//
// Brachiosaurus
// Amargasaurus
// Mamenchisaurus
//
// add_range(dinosaurs)
//
// Brachiosaurus
// Amargasaurus
// Mamenchisaurus
// Brachiosaurus
// Amargasaurus
// Mamenchisaurus
//
// remove_range(2, 2)
//
// Brachiosaurus
// Amargasaurus
// Amargasaurus
// Mamenchisaurus
//
// insert_range(3, input)
//
// Brachiosaurus
// Amargasaurus
// Amargasaurus
// Tyrannosaurus
// Deinonychus
// Velociraptor
// Mamenchisaurus
//
// output = dinosaurs.get_range(2, 3).to_array()
//
// Amargasaurus
// Tyrannosaurus
// Deinonychus
Remarks
The items are removed and all the elements following them in the xtd::collections::generic::list <type_t> have their indexes reduced by count.

◆ reserve()

template<class type_t , class allocator_t >
virtual void xtd::collections::generic::list< type_t, allocator_t >::reserve ( size_type  new_cap)
inlinevirtual

Increase the capacity of the vector (the total number of elements that the vector can hold without requiring reallocation) to a value that's greater or equal to new_cap. If new_cap is greater than the current capacity(), new storage is allocated, otherwise the function does nothing.

Parameters
new_capThe new capacity of the vector, in number of elements.
Remarks
xtd::collections::generic::list::reserve does not change the size of the vector.
If new_cap is greater than xtd::collections::generic::list::capacity property, all iterators, including the xtd::collections::generic::list::end iterator, and all references to the elements are invalidated; otherwise, no iterators or references are invalidated.
After a call to xtd::collections::generic::list::reserve, insertions will not trigger reallocation unless the insertion would make the size of the vector greater than the value of xtd::collections::generic::list::capacity.

◆ resize() [1/2]

template<class type_t , class allocator_t >
virtual void xtd::collections::generic::list< type_t, allocator_t >::resize ( size_type  count)
inlinevirtual

Resizes the container to contain count elements, does nothing if count == size(). @param count The new size of the container. @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.

◆ resize() [2/2]

template<class type_t , class allocator_t >
virtual void xtd::collections::generic::list< type_t, allocator_t >::resize ( size_type  count,
const value_type value 
)
inlinevirtual

Resizes the container to contain count elements, does nothing if count == size(). @param count The new size of the container. @param value The value to initialize the new elements with. @remarks If the current size is greater thancount, the container is reduced to its firstcountelements. @remarks If the current size is less thancount, additional copies ofvalue` are appended.

◆ reverse() [1/2]

template<class type_t , class allocator_t >
void xtd::collections::generic::list< type_t, allocator_t >::reverse ( )
inline

Reverses the order of the elements in the entire xtd::collections::generic::list <type_t>.

Examples
The following example demonstrates both overloads of the xtd::collections::generic::list::reverse method. The example creates a xtd::collections::generic::list <type_t> of strings and adds six strings. The xtd::collections::generic::list::reverse () method overload is used to reverse the list, and then the xtd::collections::generic::list::reverse (xtd::size, xtd::size) method overload is used to reverse the middle of the list, beginning with element 1 and encompassing four elements.
#include <xtd/xtd>
using namespace xtd;
using namespace xtd::collections::generic;
class example {
public:
static auto main() -> void {
auto dinosaurs = list<string> {};
dinosaurs.add("Pachycephalosaurus");
dinosaurs.add("Parasauralophus");
dinosaurs.add("Mamenchisaurus");
dinosaurs.add("Amargasaurus");
dinosaurs.add("Coelophysis");
dinosaurs.add("Oviraptor");
console::write_line();
for (const auto& dinosaur : dinosaurs)
console::write_line(dinosaur);
dinosaurs.reverse();
console::write_line();
for (const auto& dinosaur : dinosaurs)
console::write_line(dinosaur);
dinosaurs.reverse(1, 4);
console::write_line();
for (const auto& dinosaur : dinosaurs)
console::write_line(dinosaur);
}
};
startup_(example::main);
// This code produces the following output :
//
//
// Pachycephalosaurus
// Parasauralophus
// Mamenchisaurus
// Amargasaurus
// Coelophysis
// Oviraptor
//
// Oviraptor
// Coelophysis
// Amargasaurus
// Mamenchisaurus
// Parasauralophus
// Pachycephalosaurus
//
// Oviraptor
// Parasauralophus
// Mamenchisaurus
// Amargasaurus
// Coelophysis
// Pachycephalosaurus
Remarks
This method uses xtd::array::reverse to reverse the order of the elements.
This method is an O(n) operation, where n is xtd::collections::generic::list::count.

◆ reverse() [2/2]

template<class type_t , class allocator_t >
void xtd::collections::generic::list< type_t, allocator_t >::reverse ( size_type  index,
size_type  count 
)
inline

Reverses the order of the elements in the specified range.

Parameters
indexThe zero-based starting index of the range to reverse.
countThe number of elements in the range to reverse.
Exceptions
xtd::argument_exception`index` and `count` do not denote a valid range of elements in the xtd::collections::generic::list <type_t>.
Examples
The following example demonstrates both overloads of the xtd::collections::generic::list::reverse method. The example creates a xtd::collections::generic::list <type_t> of strings and adds six strings. The xtd::collections::generic::list::reverse () method overload is used to reverse the list, and then the xtd::collections::generic::list::reverse (xtd::size, xtd::size) method overload is used to reverse the middle of the list, beginning with element 1 and encompassing four elements.
#include <xtd/xtd>
using namespace xtd;
using namespace xtd::collections::generic;
class example {
public:
static auto main() -> void {
auto dinosaurs = list<string> {};
dinosaurs.add("Pachycephalosaurus");
dinosaurs.add("Parasauralophus");
dinosaurs.add("Mamenchisaurus");
dinosaurs.add("Amargasaurus");
dinosaurs.add("Coelophysis");
dinosaurs.add("Oviraptor");
console::write_line();
for (const auto& dinosaur : dinosaurs)
console::write_line(dinosaur);
dinosaurs.reverse();
console::write_line();
for (const auto& dinosaur : dinosaurs)
console::write_line(dinosaur);
dinosaurs.reverse(1, 4);
console::write_line();
for (const auto& dinosaur : dinosaurs)
console::write_line(dinosaur);
}
};
startup_(example::main);
// This code produces the following output :
//
//
// Pachycephalosaurus
// Parasauralophus
// Mamenchisaurus
// Amargasaurus
// Coelophysis
// Oviraptor
//
// Oviraptor
// Coelophysis
// Amargasaurus
// Mamenchisaurus
// Parasauralophus
// Pachycephalosaurus
//
// Oviraptor
// Parasauralophus
// Mamenchisaurus
// Amargasaurus
// Coelophysis
// Pachycephalosaurus
Remarks
This method uses xtd::array::reverse to reverse the order of the elements.
This method is an O(n) operation, where n is xtd::collections::generic::list::count.

◆ shrink_to_fit()

template<class type_t , class allocator_t >
virtual void xtd::collections::generic::list< type_t, allocator_t >::shrink_to_fit ( )
inlinevirtual

Requests the removal of unused capacity.

Remarks
It is a non-binding request to reduce xtd::collections::generic::list::capacity() to xtd::collections::generic::list::size(). It depends on the implementation whether the request is fulfilled.
If reallocation occurs, all iterators (including the xtd::collections::generic::list::end() iterator) and all references to the elements are invalidated. If no reallocation occurs, no iterators or references are invalidated.

◆ slice()

template<class type_t , class allocator_t >
list< type_t > xtd::collections::generic::list< type_t, allocator_t >::slice ( size_type  start,
size_type  length 
) const
inline

Creates a shallow copy of a range of elements in the source xtd::collections::generic::list <type_t>.

Parameters
startThe zero-based xtd::collections::generic::list <type_t> index at which the range starts.
lengthThe length of the range.
Returns
A shallow copy of a range of elements in the source xtd::collections::generic::list <type_t>.
Exceptions
xt::argument_exception`start` and `length` do not denote a valid range of elements in the xtd::collections::generic::list <type_t>.

◆ sort() [1/4]

template<class type_t , class allocator_t >
void xtd::collections::generic::list< type_t, allocator_t >::sort ( )
inline

Sorts the elements in the entire xtd::collections::generic::list <type_t> using the default comparer.

Exceptions
xtd::invalid_operation_exceptionThe default comparer xtd::collections::generic::comparer::default_comparer cannot find an implementation of the xtd::icomparable <type_t> generic interface.
Examples
The xtd::collections::generic::list::binary_search method overload is then used to search for two strings that are not in the list, and the xtd::collections::generic::list::insert method is used to insert them. The return value of the xtd::collections::generic::list::binary_search method is gretaer than xtd::collections::generic::list::count in each case, because the strings are not in the list. Taking the bitwise complement of this negative number produces the index of the first element in the list that is larger than the search string, and inserting at this location preserves the sort order. The second search string is larger than any element in the list, so the insertion position is at the end of the list.
#include <xtd/xtd>
using namespace xtd;
using namespace xtd::collections::generic;
class example {
public:
static auto main() -> void {
auto dinosaurs = list<string> {};
dinosaurs.add("Pachycephalosaurus");
dinosaurs.add("Amargasaurus");
dinosaurs.add("Mamenchisaurus");
dinosaurs.add("Deinonychus");
console::write_line();
for (auto dinosaur : dinosaurs)
console::write_line(dinosaur);
console::write_line("\nsort");
dinosaurs.sort();
console::write_line();
for (auto dinosaur : dinosaurs)
console::write_line(dinosaur);
console::write_line("\nbinary_search and insert \"Coelophysis\":");
auto index = dinosaurs.binary_search("Coelophysis");
if (index > dinosaurs.count()) dinosaurs.insert(~index, "Coelophysis");
console::write_line();
for (string dinosaur : dinosaurs)
console::write_line(dinosaur);
console::write_line("\nbinary_search and insert \"Tyrannosaurus\":");
index = dinosaurs.binary_search("Tyrannosaurus");
if (index > dinosaurs.count()) dinosaurs.insert(~index, "Tyrannosaurus");
console::write_line();
for (auto dinosaur : dinosaurs)
console::write_line(dinosaur);
}
};
startup_(example::main);
// This code produces the following output :
//
//
// Pachycephalosaurus
// Amargasaurus
// Mamenchisaurus
// Deinonychus
//
// sort
//
// Amargasaurus
// Deinonychus
// Mamenchisaurus
// Pachycephalosaurus
//
// binary_search and insert "Coelophysis":
//
// Amargasaurus
// Coelophysis
// Deinonychus
// Mamenchisaurus
// Pachycephalosaurus
//
// binary_search and insert "Tyrannosaurus":
//
// Amargasaurus
// Coelophysis
// Deinonychus
// Mamenchisaurus
// Pachycephalosaurus
// Tyrannosaurus
Remarks
This method uses the default comparer xtd::collections::generic::comparer::default_comparer for type type_t to determine the order of list elements. The xtd::collections::generic::comparer::default_comparer property checks whether type type_t implements the xtd::icomparable <type_t> generic interface and uses that implementation, if available. If not, xtd::collections::generic::comparer::default_comparer checks whether type T implements the xtd::icomparable interface. If type type_t does not implement either interface, xtd::collections::generic::comparer::default_comparer throws an xtd::invalid_operation_exception.
This method uses xtd::array::sort, which uses the QuickSort algorithm. This implementation performs an unstable sort; that is, if two elements are equal, their order might ! be preserved. In contrast, a stable sort preserves the order of elements that are equal.
On average, this method is an O(n log n) operation, where n is xtd::collections::generic::list::count; in the worst case it is an O(n ^ 2) operation.
The following code example demonstrates the xtd::collections::generic::list::sort method overload and the xtd::collections::generic::list::binary_search method overload. A xtd::collections::generic::list <type_t> of strings is created and populated with four strings, in no particular order. The list is displayed, sorted, and displayed again.

◆ sort() [2/4]

template<class type_t , class allocator_t >
void xtd::collections::generic::list< type_t, allocator_t >::sort ( xtd::comparison< const type_t & >  comparison)
inline

Sorts the elements in the entire xtd::collections::generic::list <type_t> using the specified xtd::comparison <type_t>.

Exceptions
xtd::argument_exceptionThe implementation of comparison caused an error during the sort. For example, comparison might not return 0 when comparing an item with itself.
Remarks
If comparison is provided, the elements of the xtd::collections::generic::list <type_t> are sorted using the method represented by the delegate.
This method uses xtd::array::sort, which uses the QuickSort algorithm. This implementation performs an unstable sort; that is, if two elements are equal, their order might ! be preserved. In contrast, a stable sort preserves the order of elements that are equal.
On average, this method is an O(n log n) operation, where n is xtd::collections::generic::list::count; in the worst case it is an O(n ^ 2) operation.

◆ sort() [3/4]

template<class type_t , class allocator_t >
void xtd::collections::generic::list< type_t, allocator_t >::sort ( const xtd::collections::generic::icomparer< type_t > &  comparer)
inline

Sorts the elements in the entire xtd::collections::generic::list <type_t> using the specified comparer.

Parameters
comparerThe xtd::collections::generic::icomparer <type_t> implementation to use when comparing elements, or null to use the default comparer xtd::collections::generic::comparer::default_comparer.
Exceptions
xtd::argument_exceptionThe implementation of comparison caused an error during the sort. For example, comparison might not return 0 when comparing an item with itself.
Remarks
If comparer is provided, the elements of the xtd::collections::generic::list <type_t> are sorted using the specified xtd::collections::generic::icomparer <type_t> implementation.
This method uses xtd::array::sort, which uses the QuickSort algorithm. This implementation performs an unstable sort; that is, if two elements are equal, their order might ! be preserved. In contrast, a stable sort preserves the order of elements that are equal.
On average, this method is an O(n log n) operation, where n is xtd::collections::generic::list::count; in the worst case it is an O(n ^ 2) operation.

◆ sort() [4/4]

template<class type_t , class allocator_t >
void xtd::collections::generic::list< type_t, allocator_t >::sort ( xtd::size  index,
xtd::size  count,
const xtd::collections::generic::icomparer< type_t > &  comparer 
)
inline

Sorts the elements in a range of elements in xtd::collections::generic::list <type_t> using the specified comparer.

Parameters
indexThe zero-based starting index of the range to sort.
countThe length of the range to sort.
comparerThe xtd::collections::generic::icomparer <type_t> implementation to use when comparing elements, or null to use the default comparer xtd::collections::generic::comparer::default_comparer.
Exceptions
xtd::argument_exceptionThe implementation of comparison caused an error during the sort. For example, comparison might not return 0 when comparing an item with itself.
Remarks
If comparer is provided, the elements of the xtd::collections::generic::list <type_t> are sorted using the specified xtd::collections::generic::icomparer <type_t> implementation.
This method uses xtd::array::sort, which uses the QuickSort algorithm. This implementation performs an unstable sort; that is, if two elements are equal, their order might ! be preserved. In contrast, a stable sort preserves the order of elements that are equal.
On average, this method is an O(n log n) operation, where n is xtd::collections::generic::list::count; in the worst case it is an O(n ^ 2) operation.

◆ swap()

template<class type_t , class allocator_t >
virtual void xtd::collections::generic::list< type_t, allocator_t >::swap ( list< type_t, allocator_t > &  other)
inlinevirtualnoexcept

Exchanges the contents and capacity of the container with those of other. Does not invoke any move, copy, or swap operations on individual elements.

Remarks
All iterators and references remain valid. The xtd::collections::generic::list::end() iterator is invalidated.

◆ to_array()

template<class type_t , class allocator_t >
virtual xtd::array< value_type > xtd::collections::generic::list< type_t, allocator_t >::to_array ( ) const
inlinevirtualnoexcept

Copies the elements of the xtd::collections::generic::list <type_t> to a new array.

Returns
An array containing copies of the elements of the xtd::collections::generic::list <type_t>.
Examples
The following code example demonstrates the xtd::collections::generic::list <type_t> constructor and various methods of the xtd::collections::generic::list <type_t> class that act on ranges. An array of strings is created and passed to the constructor, populating the list with the elements of the array. The xtd::collections::generic::list::capacity property is then displayed, to show that the initial capacity is exactly what is required to hold the input elements.
#include <xtd/xtd>
using namespace xtd;
using namespace xtd::collections::generic;
class example {
public:
static auto main() -> void {
auto input = array<string> {"Brachiosaurus", "Amargasaurus", "Mamenchisaurus"};
auto dinosaurs = list<string>(input);
console::write_line("\ncapacity: {0}", dinosaurs.capacity());
console::write_line();
for (auto dinosaur : dinosaurs)
console::write_line(dinosaur);
console::write_line("\nadd_range(dinosaurs)");
dinosaurs.add_range(dinosaurs);
console::write_line();
for(auto dinosaur : dinosaurs)
console::write_line(dinosaur);
console::write_line("\nremove_range(2, 2)");
dinosaurs.remove_range(2, 2);
console::write_line();
for(auto dinosaur : dinosaurs)
console::write_line(dinosaur);
input = {"Tyrannosaurus", "Deinonychus", "Velociraptor"};
console::write_line("\ninsert_range(3, input)");
dinosaurs.insert_range(3, input);
console::write_line();
for(auto dinosaur : dinosaurs)
console::write_line(dinosaur);
console::write_line("\noutput = dinosaurs.get_range(2, 3).to_array()");
auto output = dinosaurs.get_range(2, 3).to_array();
console::write_line();
for (auto dinosaur : output)
console::write_line(dinosaur);
}
};
startup_(example::main);
// This code produces the following output :
//
//
// capacity: 3
//
// Brachiosaurus
// Amargasaurus
// Mamenchisaurus
//
// add_range(dinosaurs)
//
// Brachiosaurus
// Amargasaurus
// Mamenchisaurus
// Brachiosaurus
// Amargasaurus
// Mamenchisaurus
//
// remove_range(2, 2)
//
// Brachiosaurus
// Amargasaurus
// Amargasaurus
// Mamenchisaurus
//
// insert_range(3, input)
//
// Brachiosaurus
// Amargasaurus
// Amargasaurus
// Tyrannosaurus
// Deinonychus
// Velociraptor
// Mamenchisaurus
//
// output = dinosaurs.get_range(2, 3).to_array()
//
// Amargasaurus
// Tyrannosaurus
// Deinonychus
Remarks
The elements are copied using xtd::array::copy, which is an O(n) operation, where n is xtd::collections::generic::list::count.
This method is an O(n) operation, where n is xtd::collections::generic::list::count.

◆ to_string()

template<class type_t , class allocator_t >
string xtd::collections::generic::list< type_t, allocator_t >::to_string ( ) const
inlineoverridevirtualnoexcept

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

Returns
A string that represents the current object.

Reimplemented from xtd::object.

◆ trim_excess()

template<class type_t , class allocator_t >
virtual void xtd::collections::generic::list< type_t, allocator_t >::trim_excess ( )
inlinevirtual

Sets the capacity to the actual number of elements in the xtd::collections::generic::list <type_t>, if that number is less than a threshold value.

Examples
The following example demonstrates how to add, remove, and insert a simple business object in a xtd::collections::generic::list <type_t>.
#include <xtd/xtd>
using namespace xtd;
using namespace xtd::collections::generic;
// Simple business object. A part_id is used to identify a part
// but the part name be different for the same Id.
class part : public object, public iequatable<part> {
public:
string part_name;
int part_id = 0;
part() = default;
part(const string& name, int id) : part_name {name}, part_id {id} {}
string to_string() const noexcept override {return string::format("ID: {} Name: {}", part_id, part_name);}
bool equals(const object& obj) const noexcept override {return is<part>(obj) && equals(as<part>(obj));}
bool equals(const part& other) const noexcept override {return part_id == other.part_id;}
size get_hash_code() const noexcept override {return object::get_hash_code();}
};
class example {
public:
static auto main() -> void {
auto parts = list<part> {};
console::write_line("\ncapacity: {0}", parts.capacity());
parts.add(part {"crank arm", 1234});
parts.add(part {"chain ring", 1334});
parts.add(part {"seat", 1434});
parts.add(part {"cassette", 1534});
parts.add(part {"shift lever", 1634});
console::write_line();
for (auto part : parts)
console::write_line(part);
console::write_line("\ncapacity: {0}", parts.capacity());
console::write_line("count: {0}", parts.count());
parts.trim_excess();
console::write_line("\ntrim_excess()");
console::write_line("capacity: {0}", parts.capacity());
console::write_line("count: {0}", parts.count());
parts.clear();
console::write_line("\nclear()");
console::write_line("capacity: {0}", parts.capacity());
console::write_line("count: {0}", parts.count());
}
};
startup_(example::main);
// This code produces the following output :
//
// capacity: 0
//
// ID: 1234 Name: crank arm
// ID: 1334 Name: chain ring
// ID: 1434 Name: seat
// ID: 1534 Name: cassette
// ID: 1634 Name: shift lever
//
// capacity: 8
// count: 5
//
// trim_excess()
// capacity: 5
// count: 5
//
// clear()
// capacity: 5
// count: 0
The following example demonstrates several properties and methods of the xtd::collections::generic::list <type_t> generic class of type string. (For an example of a xtd::collections::generic::list <type_t> of complex types, see the xtd::collections::generic::list::contains method.)

The parameterless constructor is used to create a list of strings with the default capacity. The xtd::collections::generic::list::capacity property is displayed and then the xtd::collections::generic::list::add method is used to add several items. The items are listed, and the xtd::collections::generic::list::capacity property is displayed again, along with the xtd::collections::generic::list::count property, to show that the capacity has been increased as needed.

The xtd::collections::generic::list::contains method is used to test for the presence of an item in the list, the Insert method is used to insert a new item in the middle of the list, and the contents of the list are displayed again.

The default xtd::collections::generic::list::operator [] is used to retrieve an item, the xtd::collections::generic::list::remove method is used to remove the first instance of the duplicate item added earlier, and the contents are displayed again. The xtd::collections::generic::list::remove method always removes the first instance it encounters.

The xtd::collections::generic::list::trim_excess method is used to reduce the capacity to match the count, and the xtd::collections::generic::list::capacity and xtd::collections::generic::list::count properties are displayed. If the unused capacity had been less than 10 percent of total capacity, the list would not have been resized.

Finally, the xtd::collections::generic::list::clear method is used to remove all items from the list, and the xtd::collections::generic::list::capacity and xtd::collections::generic::list::count properties are displayed.

#include <xtd/xtd>
using namespace xtd;
using namespace xtd::collections::generic;
class example {
public:
static auto main() -> void {
auto dinosaurs = list<string> {};
console::write_line("\ncapacity: {0}", dinosaurs.capacity());
dinosaurs.add("Tyrannosaurus");
dinosaurs.add("Amargasaurus");
dinosaurs.add("Mamenchisaurus");
dinosaurs.add("Deinonychus");
dinosaurs.add("Compsognathus");
console::write_line();
for (auto dinosaur : dinosaurs)
console::write_line(dinosaur);
console::write_line("\ncapacity: {0}", dinosaurs.capacity());
console::write_line("count: {0}", dinosaurs.count());
console::write_line("\ncontains(\"Deinonychus\"): {0}", dinosaurs.contains("Deinonychus"));
console::write_line("\ninsert(2, \"Compsognathus\")");
dinosaurs.insert(2, "Compsognathus");
console::write_line();
for (auto dinosaur : dinosaurs)
console::write_line(dinosaur);
// Shows accessing the list using the Item property.
console::write_line("\ndinosaurs[3]: {0}", dinosaurs[3]);
console::write_line("\nremove(\"Compsognathus\")");
dinosaurs.remove("Compsognathus");
console::write_line();
for (auto dinosaur : dinosaurs)
console::write_line(dinosaur);
dinosaurs.trim_excess();
console::write_line("\ntrim_excess()");
console::write_line("capacity: {0}", dinosaurs.capacity());
console::write_line("count: {0}", dinosaurs.count());
dinosaurs.clear();
console::write_line("\nclear()");
console::write_line("capacity: {0}", dinosaurs.capacity());
console::write_line("count: {0}", dinosaurs.count());
}
};
startup_(example::main);
// This code produces the following output :
//
// capacity: 0
//
// Tyrannosaurus
// Amargasaurus
// Mamenchisaurus
// Deinonychus
// Compsognathus
//
// capacity: 8
// count: 5
//
// contains("Deinonychus"): true
//
// insert(2, "Compsognathus")
//
// Tyrannosaurus
// Amargasaurus
// Compsognathus
// Mamenchisaurus
// Deinonychus
// Compsognathus
//
// dinosaurs[3]: Mamenchisaurus
//
// remove("Compsognathus")
//
// Tyrannosaurus
// Amargasaurus
// Mamenchisaurus
// Deinonychus
// Compsognathus
//
// trim_excess()
// capacity: 5
// count: 5
// clear()
// capacity: 5
// count: 0
Remarks
This method can be used to minimize a collection's memory overhead if no new elements will be added to the collection. The cost of reallocating and copying a large xtd::collections::generic::list <type_t> can be considerable, however, so the xtd::collections::generic::list::trim_excess method does nothing if the list is at more than 90 percent of capacity. This avoids incurring a large reallocation cost for a relatively small gain.
This method is an O(n) operation, where n is xtd::collections::generic::list::count.
To reset a xtd::collections::generic::list <type_t> to its initial state, call the xtd::collections::generic::list::clear method before calling the xtd::collections::generic::list::trim_excess method. Trimming an empty xtd::collections::generic::list <type_t> sets the capacity of the xtd::collections::generic::list <type_t> to the default capacity.
The capacity can also be set using the xtd::collections::generic::list::capacity property.

◆ true_for_all()

template<class type_t , class allocator_t >
bool xtd::collections::generic::list< type_t, allocator_t >::true_for_all ( xtd::predicate< const type_t & >  match) const
inline

Determines whether every element in the xtd::collections::generic::list <type_t> matches the conditions defined by the specified predicate.

Parameters
matchThe xtd::predicate <type_t> delegate that defines the conditions of the elements to search for.
Returns
true if every element in the xtd::collections::generic::list <type_t> matches the conditions defined by the specified predicate; otherwise, false. If the list has no elements, the return value is true.
Examples
The following example demonstrates the xtd::collections::generic::list::exists method and several other methods that use the xtd::predicate <type_t> generic delegate.
A xtd::collections::generic::list <type_t> of strings is created, containing 8 dinosaur names, two of which (at positions 1 and 5) end with "saurus". The example also defines a search predicate method named ends_with_saurus, which accepts a string parameter and returns a boolean value indicating whether the input string ends in "saurus".
The xtd::collections::generic::list::find, xtd::collections::generic::list::find_last, and xtd::collections::generic::list::findA_all methods are used to search the list with the search predicate method, and then the xtd::collections::generic::list::remove_all method is used to remove all entries ending with "saurus".
Finally, the xtd::collections::generic::list::exists method is called. It traverses the list from the beginning, passing each element in turn to the ends_with_saurus method. The search stops and the method returns true if the ends_with_saurus method returns true for any element. The xtd::collections::generic::list::exists method returns false because all such elements have been removed.
#include <xtd/xtd>
using namespace xtd;
using namespace xtd::collections::generic;
class example {
public:
static auto main() -> void {
auto dinosaurs = list<string> {};
dinosaurs.add("Compsognathus");
dinosaurs.add("Amargasaurus");
dinosaurs.add("Oviraptor");
dinosaurs.add("Velociraptor");
dinosaurs.add("Deinonychus");
dinosaurs.add("Dilophosaurus");
dinosaurs.add("Gallimimus");
dinosaurs.add("Triceratops");
console::write_line();
for (const auto& dinosaur : dinosaurs)
console::write_line(dinosaur);
console::write_line("\ntrue_for_all(ends_with_saurus): {0}", dinosaurs.true_for_all(predicate<const string&> {ends_with_saurus}));
console::write_line("\nfind(ends_with_saurus): {0}", dinosaurs.find(predicate<const string&> {ends_with_saurus}));
console::write_line("\nfindLast(ends_with_saurus): {0}", dinosaurs.find_last(predicate<const string&> {ends_with_saurus}));
console::write_line("\nfind_all(ends_with_saurus):");
auto sublist = dinosaurs.find_all(predicate<const string&> {ends_with_saurus});
for (const auto& dinosaur : sublist)
console::write_line(dinosaur);
console::write_line("\n{0} elements removed by remove_all(ends_with_saurus).", dinosaurs.remove_all(predicate<const string&> {ends_with_saurus}));
console::write_line("\nlist now contains:");
for (const auto& dinosaur : dinosaurs)
console::write_line(dinosaur);
console::write_line("\nexists(ends_with_saurus): {0}", dinosaurs.exists(predicate<const string&> {ends_with_saurus}));
}
private:
// Search predicate returns true if a string ends in "saurus".
static bool ends_with_saurus(const string& s) {
return s.to_lower().ends_with("saurus");
}
};
startup_(example::main);
// This code produces the following output :
//
//
// Compsognathus
// Amargasaurus
// Oviraptor
// Velociraptor
// Deinonychus
// Dilophosaurus
// Gallimimus
// Triceratops
//
// true_for_all(ends_with_saurus): false
//
// find(ends_with_saurus): Amargasaurus
//
// findLast(ends_with_saurus): Dilophosaurus
//
// find_all(ends_with_saurus):
// Amargasaurus
// Dilophosaurus
//
// 2 elements removed by remove_all(ends_with_saurus).
//
// list now contains:
// Compsognathus
// Oviraptor
// Velociraptor
// Deinonychus
// Gallimimus
// Triceratops
//
// exists(ends_with_saurus): false
Remarks
The xtd::predicate <type_t> is a delegate to a method that returns true if the object passed to it matches the conditions defined in the delegate. The elements of the current xtd::collections::generic::list <type_t> are individually passed to the xtd::predicate <type_t> delegate, and the elements that match the conditions are removed from the xtd::collections::generic::list <type_t>.
This method performs a linear search; therefore, this method is an O(n) operation, where n is xtd::collections::generic::list::count.

◆ operator=() [1/3]

template<class type_t , class allocator_t >
list & xtd::collections::generic::list< type_t, allocator_t >::operator= ( const list< type_t, allocator_t > &  other)
default

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

Parameters
otherAnother container to use as data source.
Returns
This current instance.

◆ operator=() [2/3]

template<class type_t , class allocator_t >
list & xtd::collections::generic::list< type_t, allocator_t >::operator= ( list< type_t, allocator_t > &&  other)
inlinenoexcept

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

Parameters
otherAnother base type container to use as data source.
Returns
This current instance.

◆ operator=() [3/3]

template<class type_t , class allocator_t >
list & xtd::collections::generic::list< type_t, allocator_t >::operator= ( std::initializer_list< type_t > &  items)
inline

Replaces the contents with those identified by initializer list ilist.

Parameters
itemsInitializer list to use as data source
Returns
This current instance.

◆ operator[]() [1/2]

template<class type_t , class allocator_t >
const_reference xtd::collections::generic::list< type_t, allocator_t >::operator[] ( size_type  index) const
inlineoverridevirtual

Returns a reference to the element at specified location index.

Parameters
indexThe position of the element to return.
Returns
Reference to the requested element.
Exceptions
std::out_of_rangeIf `index` is not within the range of the container.

Implements xtd::collections::generic::ilist< type_t >.

◆ operator[]() [2/2]

template<class type_t , class allocator_t >
reference xtd::collections::generic::list< type_t, allocator_t >::operator[] ( size_type  index)
inlineoverridevirtual

Returns a reference to the element at specified location index.

Parameters
indexThe position of the element to return.
Returns
Reference to the requested element.
Exceptions
std::out_of_rangeIf `index` is not within the range of the container.

Implements xtd::collections::generic::ilist< type_t >.

◆ operator const base_type &()

template<class type_t , class allocator_t >
xtd::collections::generic::list< type_t, allocator_t >::operator const base_type & ( ) const
inlinenoexcept

Returns a reference to the underlying base type.

Returns
Reference to the underlying base type.

◆ operator base_type &()

template<class type_t , class allocator_t >
xtd::collections::generic::list< type_t, allocator_t >::operator base_type & ( )
inlinenoexcept

Returns a reference to the underlying base type.

Returns
Reference to the underlying base type.

Member Data Documentation

◆ npos

template<class type_t , class allocator_t >
constexpr size_type xtd::collections::generic::list< type_t, allocator_t >::npos
inlinestaticconstexpr

This is a special value equal to the maximum value representable by the type size_type.


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