xtd::collections::generic::list< type_t, allocator_t > Class Template Reference

Inheritance diagram for xtd::collections::generic::list< type_t, allocator_t >:

Definition

template<typename type_t, typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>
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<typename type_t>
class list : public xtd::object, xtd::collections::generic::ilist<type_t>, public xtd::iequatable<xtd::collections::generic::list<type_t>>

Header

#include <xtd/collections/generic/list

Namespace

xtd::collections::generic

Library

xtd.core

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.

• Methods such as xtd::collections::generic::list::contains, xtd::collections::generic::list::index_of, xtd::collections::generic::list::last_index_of, and xtd::collections::generic::list::remove use an equality comparer for the list elements. The default equality comparer for type type_t is determined as follows. If type type_t implements the xtd::iequatable <type_t> generic interface, then the equality comparer is the xtd::iequatable::equals method of that interface; otherwise, if the type_tinherits of the xtd::object class, the default equality comparer is xtd::object::equals. If the type_t does not implement the xtd::iequality <type_t> interface and does not inherit from xtd::object, the type_t must implement the euqality operator : bool operator ==(const type_t& rhs) const noexcept.
• Methods such as xtd::collections::generic::list::binary_search and xtd::collections::generic::list::sort use an ordering comparer for the list elements. The default comparer for type type_t is determined as follows. If type type_t implements the xtd::icomparable <type_t> generic interface, then the default comparer is the xtd::icomaprable::compare_to method of that interface. If the type_t type does not implement the xtd::icomparable <type_t> interface, the type_t type must implement the less than operator : bool operator <(const type_t& rhs) const noexcept.

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

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

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, environment_exit.cpp, environment_program_exit.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, main.cpp, main3.cpp, main4.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, socket_tcp_ip_v4.cpp, socket_tcp_ip_v4_without_thread.cpp, socket_tcp_ip_v6.cpp, socket_udp_ip_v4.cpp, socket_udp_ip_v6.cpp, sprintf_class.cpp, sprintf_class_with_specified_formating.cpp, sprintf_class_with_specified_formating_with_to_string.cpp, startup3.cpp, startup4.cpp, stopwatch.cpp, test_forms.cpp, udp_client_ip_v4.cpp, udp_client_ip_v6.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 = typename 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	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::ilist< type_t >::iterator
	Represents the iterator of list value type.
using	const_iterator = typename xtd::collections::generic::ilist< 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 = typename 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<typename 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::ilist <type_t> has a fixed size.
bool	is_read_only () const noexcept override
	Gets a value indicating whether the xtd::collections::generic::icollection <type_t> is read-only.
bool	is_synchronized () const noexcept override
	Gets a value indicating whether access to the xtd::collections::generic::icollection <type_t> is synchronized (thread safe).
virtual const base_type &	items () const noexcept
	Returns the underlying base type items.
virtual base_type &	items () 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::object &	sync_root () const noexcept override
	Gets an object that can be used to synchronize access to the the xtd::collections::generic::icollection <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>.
void	assign (size_type count, const type_t &value)
	Replaces the contents with count copies of value value.
template<typename 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).
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.
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.
void	clear () override
	Removes all items from the xtd::collections::generic::icollection <type_t>.
bool	contains (const type_t &value) const noexcept override
	Determines whether the xtd::collections::generic::icollection <type_t> contains a specific value.
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 elements of the xtd::collections::generic::icollection <type_t> to an xtd::array, starting at a particular xtd::array index.
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<typename... args_t>
iterator	emplace (const_iterator pos, args_t &&... args)
	Inserts a new element into the container directly before pos.
template<typename... 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)....
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
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.
virtual allocator_type	get_allocator () const
	Returns the allocator associated with the container.
virtual base_type &	get_base_type () noexcept
	Returns the underlying base type.
virtual const base_type &	get_base_type () const noexcept
	Returns the underlying base type.
enumerator< value_type >	get_enumerator () const noexcept override
	Returns an enumerator that iterates through a collection.
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<typename 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.
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::icollection <type_t>.
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.
virtual void	shrink_to_fit ()
	Requests the removal of unused capacity.
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_type >	to_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.

Public Operators
list &	operator= (const list &other)=default
	Copy assignment operator. Replaces the contents with a copy of the contents of other.
list &	operator= (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.
list &	operator= (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	iterator = typename ienumerable< type_t >::iterator
	Represents the iterator of xtd::collections::generic::ienumerable value type.
using	const_iterator = typename 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	iterator = typename enumerable_iterators< type_t, ienumerable< type_t > >::iterator
	Represents the iterator of xtd::collections::generic::ienumerable value type.
using	const_iterator = typename enumerable_iterators< type_t, ienumerable< type_t > >::const_iterator
	Represents the const iterator of xtd::collections::generic::ienumerable value type.
Public Types inherited from xtd::collections::generic::enumerable_iterators< type_t, ienumerable< type_t > >
using	const_iterator = const iterator
	Represents the const iterator of enumarable 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 size_t	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<typename 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::enumerable_iterators< type_t, ienumerable< type_t > >
Public Member Functions inherited from xtd::iequatable< type_t >
virtual bool	equals (const type_t &) const noexcept=0
	Indicates whether the current object is equal to another object of the same type.
Static Public Member Functions inherited from xtd::object
template<typename object_a_t , typename 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<typename object_a_t , typename 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.

Member Typedef Documentation

value_type

template<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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

Represents the list value type.

allocator_type

template<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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

Represents the list base type.

size_type

template<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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

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

difference_type

template<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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

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

reference

template<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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

Represents the reference of list value type.

const_reference

template<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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

Represents the const reference of list value type.

pointer

template<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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

Represents the pointer of list value type.

const_pointer

template<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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

Represents the const pointer of list value type.

iterator

template<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

using xtd::collections::generic::list< type_t, allocator_t >::iterator = typename xtd::collections::generic::ilist<type_t>::iterator

Represents the iterator of list value type.

const_iterator

template<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

using xtd::collections::generic::list< type_t, allocator_t >::const_iterator = typename xtd::collections::generic::ilist<type_t>::const_iterator

Represents the const iterator of list value type.

reverse_iterator

template<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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

Represents the read only collection of of list.

Constructor & Destructor Documentation

list() [1/15]

template<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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

defaultnoexcept

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

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.

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

list() [2/15]

template<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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

inlineexplicitnoexcept

Constructs an empty container with the given allocator.

Parameters

alloc

The allocator to use for all memory allocations of this container.

list() [3/15]

template<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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

count	The size of the container.
value	The value to initialize elements of the container with.
alloc	The allocator to use for all memory allocations of this container.

list() [4/15]

template<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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

count	The size of the container.
alloc	The allocator to use for all memory allocations of this container.

list() [5/15]

template<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

template<typename 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

first	The first iterator the range to copy the elements from.
last	The last iterator the range to copy the elements from.
alloc	The allocator to use for all memory allocations of this container.

list() [6/15]

template<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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

collection	The collection whose elements are copied to the new list.
alloc	The 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

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<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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

inline

Default copy constructor with specified list.

Parameters

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

list() [8/15]

template<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

xtd::collections::generic::list< type_t, allocator_t >::list ( const base_type &  list )

inline

Copy constructor with specified base type list.

Parameters

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

list() [9/15]

template<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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

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

list() [10/15]

template<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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

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

list() [11/15]

template<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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

items	The initializer list to initialize the elements of the container with.
alloc	The allocator to use for all memory allocations of this container.

list() [12/15]

template<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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

inline

Move constructor with specified list.

Parameters

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

list() [13/15]

template<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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

inline

Move constructor with specified base type list.

Parameters

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

list() [14/15]

template<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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

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

list() [15/15]

template<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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

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

Member Function Documentation

back() [1/2]

template<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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::enumerable_iterators< type_t, ienumerable< type_t > >.

Examples

console_clear.cpp, socket_tcp_ip_v4.cpp, socket_tcp_ip_v4_without_thread.cpp, socket_tcp_ip_v6.cpp, and socket_udp_ip_v4.cpp.

begin() [2/2]

template<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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::enumerable_iterators< type_t, ienumerable< type_t > >.

capacity() [1/2]

template<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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::enumerable_iterators< type_t, ienumerable< type_t > >.

cend()

template<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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::enumerable_iterators< type_t, ienumerable< type_t > >.

count()

template<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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::enumerable_iterators< type_t, ienumerable< type_t > >.

Examples

console_clear.cpp.

end() [2/2]

template<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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::enumerable_iterators< type_t, ienumerable< type_t > >.

front() [1/2]

template<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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

inlineoverridevirtualnoexcept

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

Returns

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

Remarks

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

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

is_read_only()

template<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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

inlineoverridevirtualnoexcept

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

Returns

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

Remarks

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

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

is_synchronized()

template<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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

inlineoverridevirtualnoexcept

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

Returns

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

Remarks

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

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

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

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

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

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

items() [1/2]

template<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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, environment_exit.cpp, environment_program_exit.cpp, font_families.cpp, ienumerable.cpp, ienumerator.cpp, ip_address.cpp, labels_and_unicode_text.cpp, main.cpp, udp_client_ip_v4.cpp, and udp_client_ip_v6.cpp.

sync_root()

template<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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::icollection <type_t>.

Returns

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

Remarks

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

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

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

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

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

add()

template<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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

item

The 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<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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

collection

The 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<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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

il	The 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.

assign() [1/3]

template<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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

count	The new size of the container.
value	The value to initialize elements of the container with.

assign() [2/3]

template<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

template<typename 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

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

Warning

The behavior is undefined if either argument is an iterator this current instance.

as_read_only()

template<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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() [3/3]

template<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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

items

the initializer list to copy the values from.

at() [1/2]

template<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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

index

The position of the element to return.

Returns

Reference to the requested element.

Exceptions

std::out_of_range

If pos is not within the range of the container.

at() [2/2]

template<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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

index

The position of the element to return.

Returns

Reference to the requested element.

Exceptions

std::out_of_range

If pos is not within the range of the container.

clear()

template<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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

inlineoverridevirtual

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

Exceptions

xtd::not_supported_exception

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

Remarks

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

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

contains()

template<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

bool xtd::collections::generic::list< type_t, allocator_t >::contains ( const type_t &  item ) const

inlineoverridevirtualnoexcept

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

Parameters

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

Returns

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

Remarks

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

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

copy_to() [1/3]

template<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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

array

The one-dimensional xtd::array that is the destination of the elements copied from ICollection. The xtd::array must have zero-based indexing.

Exceptions

ArgumentNullException	array is null.
ArgumentException	The 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.

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.

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.

copy_to() [2/3]

template<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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

inlineoverridevirtual

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

Parameters

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

Exceptions

xtd::argument_exception

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

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

copy_to() [3/3]

template<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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

index	The zero-based index in the source xtd::collections::generic::list <type_t> at which copying begins.
array	The one-dimensional xtd::array that is the destination of the elements copied from ICollection. The xtd::array must have zero-based indexing.
arrayIndex	The zero-based index in array at which copying begins;
count	The number of elements to copy.

Exceptions

ArgumentNullException	array is null.
ArgumentOutOfRangeException	The arrayIndex or count is less than 0.
ArgumentException	The 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.

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.

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.

emplace()

template<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

template<typename... 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

pos	The iterator before which the new element will be constructed.
args	arguments 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<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

template<typename... 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

args	The 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.

equals()

template<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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

obj	The 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

Reimplemented from xtd::object.

erase() [1/2]

template<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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

inlinevirtual

Erases the specified elements from the container.

Parameters

pos	The 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<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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

pos	The 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.

get_allocator()

template<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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

inlineoverridevirtualnoexcept

Returns an enumerator that iterates through a collection.

Returns

An xtd::collections::generic::enumerator object that can be used to iterate through the collection.

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

get_range()

template<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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

index	The zero-based xtd::collections::generic::list <type_t> index at which the range starts.
count	The 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_exception

index 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<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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

value

The 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<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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

value	The object to locate in the xtd::collections::generic::list <type_t>.
index	The 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<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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

value	The object to locate in the xtd::collections::generic::list <type_t>.
index	The zero-based starting index of the search.
count	The 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<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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

pos	the iterator before which the content will be inserted (pos may be the end() iterator).
value	The 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<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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

pos	the iterator before which the content will be inserted (pos may be the end() iterator).
value	The 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<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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

pos	the iterator before which the content will be inserted (pos may be the end() iterator).
count	The number of elements to insert.
value	The 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<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

template<typename 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

first	The first range of elements to insert, cannot be iterators into container for which insert is called
last	The 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<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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

pos	the iterator before which the content will be inserted (pos may be the end() iterator).
items	The 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<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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

index	The zero-based index at which the new element should be inserted.
value	The element should be inserted into the xtd::collections::generic::list <type_t>.

Exceptions

xtd::argument_out_of_range_exception

index 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<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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

index	The zero-based index at which the new elements should be inserted.
collection	The collection whose elements should be inserted into the xtd::collections::generic::list <type_t>.

Exceptions

xtd::argument_out_of_range_exception

index 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<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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

index	The zero-based index at which the new elements should be inserted.
collection	The collection whose elements should be inserted into the xtd::collections::generic::list <type_t>.

Exceptions

xtd::argument_out_of_range_exception

index 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>.

pop_back()

template<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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

value

The 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, and file_info_move_to.cpp.

push_back() [2/2]

template<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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

value

The 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<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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::icollection <type_t>.

Parameters

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

Returns

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

Exceptions

xtd::not_supported_exception

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

Remarks

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

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

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

remove_at()

template<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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

index

The zero-based index of the item to remove

Exceptions

ArgumentOutOfRangeException

index is less than 0 or index is greater than xtd::collections::generic::list::count.

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

remove_range()

template<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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

index	The zero-based index of the item to remove
count	The number of elements to remove

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

Exceptions

xtd::argument_out_of_range_exception

index or count is less than 0 or index + count is greater than xtd::collections::generic::list::count.

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<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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_cap

The 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<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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.

shrink_to_fit()

template<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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.

swap()

template<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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>.

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.

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

to_string()

template<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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.

Examples

The following code example demonstrates what to_string returns.

#include <xtd/xtd>
 
using namespace xtd;
 
namespace examples {
  namespace object_test {
    class object1 : public object {
    };
  }
}
 
auto main() -> int {
  ptr<object> obj1 = new_ptr<examples::object_test::object1>();
  console::write_line(obj1->to_string());
 
  ptr<object> obj2 = new_ptr<date_time>(1971, 1, 5, 23, 5, 0);
  console::write_line(obj2->to_string());
 
  ptr<object> obj3 = new_ptr<boolean_object>();
  console::write_line(obj3->to_string());
}
 
// This code produces the following output :
//
// examples::object_test::object1
// Tue Jan  5 23:05:00 1971
// false

Reimplemented from xtd::object.

trim_excess()

template<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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.

operator=() [1/3]

template<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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

other

Another container to use as data source.

Returns

This current instance.

operator=() [2/3]

template<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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

other

Another base type container to use as data source.

Returns

This current instance.

operator=() [3/3]

template<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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

items

Initializer list to use as data source

Returns

This current instance.

operator[]() [1/2]

template<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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

index

The position of the element to return.

Returns

Reference to the requested element.

Exceptions

std::out_of_range

If pos is not within the range of the container.

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

operator[]() [2/2]

template<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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

index

The position of the element to return.

Returns

Reference to the requested element.

Exceptions

std::out_of_range

If `index` is not within the range of the container.

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

operator const base_type &()

template<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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<typename type_t , typename allocator_t = xtd::collections::generic::helpers::allocator<typename std::conditional<std::is_same<bool, type_t>::value, char, type_t>::type>>

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:

• xtd.core/include/xtd/collections/generic/list.h