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.