xtd 0.2.0
Loading...
Searching...
No Matches

◆ 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
Represents a strongly typed list of objects that can be accessed by index. Provides methods to search...
Definition list.h:72
Represents the standard input, output, and error streams for console applications.
Definition console.h:36
Defines a generalized method that a value type or class implements to create a type-specific method f...
Definition iequatable.h:22
Supports all classes in the xtd class hierarchy and provides low-level services to derived classes....
Definition object.h:42
#define startup_(main_method)
Defines the entry point to be called when the application loads. Generally this is set either to the ...
Definition startup.h:175
size_t size
Represents a size of any object in bytes.
Definition size.h:23
@ other
The operating system is other.
std::string to_string(const value_t &value, const std::string &fmt, const std::locale &loc)
Convert a specified value into a string with specified format and locale.
Definition to_string.h:41
The xtd::collections::generic namespace contains interfaces and classes that define generic collectio...
Definition comparer.h:15
The xtd namespace contains all fundamental classes to access Hardware, Os, System,...
Definition xtd_about_box.h:10
The following example demonstrates several properties and methods of the xtd::collections::generic::list <type_t> generic class of type string. (For an example of a xtd::collections::generic::list <type_t> of complex types, see the xtd::collections::generic::list::contains method.)

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

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

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

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

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

#include <xtd/xtd>
using namespace xtd;
using namespace xtd::collections::generic;
class example {
public:
static auto main() -> void {
auto dinosaurs = list<string> {};
console::write_line("\ncapacity: {0}", dinosaurs.capacity());
dinosaurs.add("Tyrannosaurus");
dinosaurs.add("Amargasaurus");
dinosaurs.add("Mamenchisaurus");
dinosaurs.add("Deinonychus");
dinosaurs.add("Compsognathus");
console::write_line();
for (auto dinosaur : dinosaurs)
console::write_line(dinosaur);
console::write_line("\ncapacity: {0}", dinosaurs.capacity());
console::write_line("count: {0}", dinosaurs.count());
console::write_line("\ncontains(\"Deinonychus\"): {0}", dinosaurs.contains("Deinonychus"));
console::write_line("\ninsert(2, \"Compsognathus\")");
dinosaurs.insert(2, "Compsognathus");
console::write_line();
for (auto dinosaur : dinosaurs)
console::write_line(dinosaur);
// Shows accessing the list using the Item property.
console::write_line("\ndinosaurs[3]: {0}", dinosaurs[3]);
console::write_line("\nremove(\"Compsognathus\")");
dinosaurs.remove("Compsognathus");
console::write_line();
for (auto dinosaur : dinosaurs)
console::write_line(dinosaur);
dinosaurs.trim_excess();
console::write_line("\ntrim_excess()");
console::write_line("capacity: {0}", dinosaurs.capacity());
console::write_line("count: {0}", dinosaurs.count());
dinosaurs.clear();
console::write_line("\nclear()");
console::write_line("capacity: {0}", dinosaurs.capacity());
console::write_line("count: {0}", dinosaurs.count());
}
};
startup_(example::main);
// This code produces the following output :
//
// capacity: 0
//
// Tyrannosaurus
// Amargasaurus
// Mamenchisaurus
// Deinonychus
// Compsognathus
//
// capacity: 8
// count: 5
//
// contains("Deinonychus"): true
//
// insert(2, "Compsognathus")
//
// Tyrannosaurus
// Amargasaurus
// Compsognathus
// Mamenchisaurus
// Deinonychus
// Compsognathus
//
// dinosaurs[3]: Mamenchisaurus
//
// remove("Compsognathus")
//
// Tyrannosaurus
// Amargasaurus
// Mamenchisaurus
// Deinonychus
// Compsognathus
//
// trim_excess()
// capacity: 5
// count: 5
// clear()
// capacity: 5
// count: 0
Remarks
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.