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.