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

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