xtd::collections::generic::dictionary< key_t, value_t, hasher_t, equator_t, allocator_t > Class Template Reference

Inheritance diagram for xtd::collections::generic::dictionary< key_t, value_t, hasher_t, equator_t, allocator_t >:

Definition

template<class key_t, class value_t, class hasher_t = xtd::collections::generic::helpers::hasher<key_t>, class equator_t = xtd::collections::generic::helpers::equator<key_t>, class allocator_t = xtd::collections::generic::helpers::allocator<std::pair<const key_t, value_t >>>
class xtd::collections::generic::dictionary< key_t, value_t, hasher_t, equator_t, allocator_t >

Represents a collection of keys and values.

Definition

template<class key_t, class value_t, class hasher_t = xtd::collections::generic::helpers::hasher<key_t>, class equator_t = xtd::collections::generic::helpers::equator<key_t>, class allocator_t = xtd::collections::generic::helpers::allocator<std::pair<const key_t, value_t>>>
class dictionary : public xtd::object, public xtd::collections::generic::idictionary<key_t, value_t>;

Header

#include <xtd/collections/generic/dictionary>

Namespace

xtd::collections::generic

Library

xtd.core

Examples

The following code example creates an empty xtd::collections::generic::dictionary <key_t, value_t> of strings with string keys and uses the Add method to add some elements. The example demonstrates that the xtd::collections::generic::dictionary::add method throws an xtd::argument_exception when attempting to add a duplicate key.

The example uses the xtd::collections::generic::dictionary::operator [] to retrieve values, demonstrating that a xtd::collections::generic::key_not_found_exception is thrown when a requested key is not present, and showing that the value associated with a key can be replaced.

The example shows how to use the xtd::collections::generic::dictionary::try_get_vValue method as a more efficient way to retrieve values if a program often must try key values that are not in the dictionary, and it shows how to use the xtd::collections::generic::dictionary::contains_key method to test whether a key exists before calling the xtd::collections::generic::dictionary::add method.

The example shows how to enumerate the keys and values in the dictionary and how to enumerate the keys and values alone using the xtd::collections::generic::dictionary::keys property and the xtd::collections::generic::dictionary::values property.

Finally, the example demonstrates the xtd::collections::generic::dictionary::remove method.

#include <xtd/xtd>
 
class example {
public:
  static auto main() -> void {
    // Create a new dictionary of strings, with string keys.
    //
    auto open_with = dictionary<string, string> {};
    
    // Add some elements to the dictionary. There are no
    // duplicate keys, but some of the values are duplicates.
    open_with.add("txt", "notepad.exe");
    open_with.add("bmp", "paint.exe");
    open_with.add("dib", "paint.exe");
    open_with.add("rtf", "wordpad.exe");
    
    // The Add method throws an exception if the new key is
    // already in the dictionary.
    try {
      open_with.add("txt", "winword.exe");
    } catch (const argument_exception&) {
      console::write_line("An element with key = \"txt\" already exists.");
    }
    
    // The operator [] is another name for the indexer, so you
    // can omit its name when accessing elements.
    console::write_line("For key = \"rtf\", value = {0}.", open_with["rtf"]);
    
    // The indexer can be used to change the value associated with a key.
    open_with["rtf"] = "winword.exe";
    console::write_line("For key = \"rtf\", value = {0}.", open_with["rtf"]);
    
    // If a key does not exist, setting the indexer for that key
    // adds a new key/value pair.
    open_with["doc"] = "winword.exe";
    
    // The indexer throws an exception if the requested key is not in the dictionary.
    try {
      console::write_line("For key = \"tif\", value = {0}.", open_with["tif"]);
    } catch (const key_not_found_exception&) {
      console::write_line("key = \"tif\" is not found.");
    }
    
    // When a program often has to try keys that turn out not to
    // be in the dictionary, try_get_value can be a more efficient
    // way to retrieve values.
    auto value = ""_s;
    if (open_with.try_get_value("tif", value))
      console::write_line("For key = \"tif\", value = {0}.", value);
    else
      console::write_line("key = \"tif\" is not found.");
    
    // contains_key can be used to test keys before inserting them.
    if (!open_with.contains_key("ht")) {
      open_with.add("ht", "hypertrm.exe");
      console::write_line("value added for key = \"ht\": {0}", open_with["ht"]);
    }
    
    // When you use for each to enumerate dictionary elements,
    // the elements are retrieved as key_value_pair objects.
    console::write_line();
    for (const key_value_pair<string, string>& kvp : open_with)
      console::write_line("key = {0}, value = {1}", kvp.key(), kvp.value());
    
    // To get the values alone, use the values property.
    dictionary<string, string>::value_collection values = open_with.values();
    
    // The elements of the value_collection are strongly typed
    // with the type that was specified for dictionary values.
    console::write_line();
    for(const auto& s : values)
      console::write_line("value = {0}", s);
    
    // To get the keys alone, use the keys property.
    dictionary<string, string>::key_collection keys = open_with.keys();
    
    // The elements of the key_collection are strongly typed
    // with the type that was specified for dictionary keys.
    console::write_line();
    for(const string& s : keys)
      console::write_line("key = {0}", s);
    
    // Use the remove method to remove a key/value pair.
    console::write_line("\nRemove(\"doc\")");
    open_with.remove("doc");
    
    if (!open_with.contains_key("doc"))
      console::write_line("key \"doc\" is not found.");
  }
};
 
startup_(example::main);
 
// This code produces the following output :
//
// An element with key = "txt" already exists.
// For key = "rtf", value = wordpad.exe.
// For key = "rtf", value = winword.exe.
// key = "tif" is not found.
// key = "tif" is not found.
// value added for key = "ht": hypertrm.exe
//
// key = doc, value = winword.exe
// key = rtf, value = winword.exe
// key = bmp, value = paint.exe
// key = ht, value = hypertrm.exe
// key = dib, value = paint.exe
// key = txt, value = notepad.exe
//
// value = winword.exe
// value = winword.exe
// value = paint.exe
// value = hypertrm.exe
// value = paint.exe
// value = notepad.exe
//
// key = doc
// key = rtf
// key = bmp
// key = ht
// key = dib
// key = txt
//
// Remove("doc")
// key "doc" is not found.

Remarks

The xtd::collections::generic::dictionary <key_t, value_t> generic class provides a mapping from a set of keys to a set of values. Each addition to the dictionary consists of a value and its associated key. Retrieving a value by using its key is very fast, close to O(1), because the xtd::collections::generic::dictionary <key_t, value_t> class is implemented as a hash table.

Note

The speed of retrieval depends on the quality of the hashing algorithm of the type specified for key_t.

Remarks

As long as an object is used as a key in the xtd::collections::generic::dictionary <key_t, value_t>, it must not change in any way that affects its hash value. Every key in a xtd::collections::generic::dictionary <key_t, value_t> must be unique according to the dictionary's equality comparer.

xtd::collections::generic::dictionary <key_t, value_t> requires an equality implementation to determine whether keys are equal. You can specify an implementation of the xtd::collections::generic::iequality_comparer <type_t> generic interface by using a constructor that accepts a comparer parameter; if you do not specify an implementation, the default generic equality comparer xtd::collections::generic::equality_comparer<type_t>::default_equality_comparer is used. If type key_t implements the xtd::iequatable <type_t> generic interface, the default equality comparer uses that implementation.

Note

For example, you can use the case-insensitive string comparers provided by the xtd::string_comparer class to create dictionaries with case-insensitive string keys.

Remarks

The capacity of a xtd::collections::generic::dictionary <key_t, value_t> is the number of elements the xtd::collections::generic::dictionary <key_t, value_t> can hold. As elements are added to a xtd::collections::generic::dictionary <key_t, value_t>, the capacity is automatically increased as required by reallocating the internal array.

For purposes of enumeration, each item in the dictionary is treated as a xtd::collections::generic::key_value_pair <key_t, value_t> structure representing a value and its key. The order in which the items are returned is undefined.

The for each statement returns an object of the type of the elements in the collection. Since the xtd::collections::generic::dictionary <key_t, value_t> is a collection of keys and values, the element type is not the type of the key or the type of the value. Instead, the element type is a xtd::collections::generic::key_value_pair <key_t, value_t> of the key type and the value type. For example:

for (const key_value_pair<string, string>& kvp : my_dictionary)
  console::write_line("key = {}, value = {}", kvp.key(), kvp.value());

Or with auto key type and the value type. For example:

for (const auto& [key, value] : my_dictionary)
  console::write_line("key = {}, value = {}", key, value);

Public Aliases
using	key_type
	Represents the dictionary key type.
using	mapped_type
	Represents the dictionary mapped type.
using	value_type
	Represents the dictionary value type.
using	size_type
	Represents the dictionary size type.
using	base_value_type
	Represents the dictionary base value type.
using	base_type
	Represents the dictionary base type.
using	key_collection
	Represents the idictionary key collection type.
using	value_collection
	Represents the idictionary value collection type.
using	equator
	Represents the dictionary equator type.
using	hasher
	Represents the dictionary hasher type.

Public Constructors
	dictionary () noexcept=default
	Initializes a new instance of the xtd::collections::generic::dictionary <key_t, value_t> class that is empty, has the default initial capacity, and uses the default equality comparer for the key type.
	dictionary (const xtd::collections::generic::idictionary< key_t, value_t > &dictionary)
	Initializes a new instance of the xtd::collections::generic::dictionary <key_t, value_t> class that contains elements copied from the specified xtd::collections::generic::idictionary <key_t, value_t> and uses the default equality comparer for the key type.
	dictionary (const xtd::collections::generic::ienumerable< value_type > &collection)
	Initializes a new instance of the xtd::collections::generic::dictionary <key_t, value_t> class that contains elements copied from the specified xtd::collections::generic::ienumerable <type_t>.
	dictionary (const xtd::collections::generic::iequality_comparer< key_type > &comparer)
	Initializes a new instance of the xtd::collections::generic::dictionary <key_t, value_t> class that is empty, has the default initial capacity, and uses the specified xtd::collections::generic::iequality_comparer<type_t>.
	dictionary (xtd::size capacity)
	Initializes a new instance of the xtd::collections::generic::dictionary <key_t, value_t> class that is empty, has the specified initial capacit.
	dictionary (xtd::size capacity, const xtd::collections::generic::iequality_comparer< key_type > &comparer)
	Initializes a new instance of the xtd::collections::generic::dictionary <key_t, value_t> class that is empty, has the specified initial capacity, and uses the specified xtd::collections::generic::iequality_comparer <type_t>.
	dictionary (const xtd::collections::generic::idictionary< key_t, value_t > &dictionary, const xtd::collections::generic::iequality_comparer< key_type > &comparer)
	Initializes a new instance of the xtd::collections::generic::dictionary <key_t, value_t> class that contains elements copied from the specified xtd::collections::generic::dictionary <key_t, value_t> and uses the specified xtd::collections::generic::iequality_comparer <type_t>.
	dictionary (const xtd::collections::generic::ienumerable< value_type > &collection, const xtd::collections::generic::iequality_comparer< key_type > &comparer)
	Initializes a new instance of the xtd::collections::generic::dictionary <key_t, value_t> class that contains elements copied from the specified xtd::collections::generic::ienumerable <type_t> and uses the specified xtd::collections::generic::iequality_comparer <type_t>.
	dictionary (dictionary &&other) noexcept=default
	Initializes instance of the xtd::collections::generic::dictionary <key_t, value_t> class from a variety of data sources. Optionally uses user supplied bucket_count as a minimal number of buckets to create, hash as the hash function, equal as the function to compare keys and alloc as the allocator.
	dictionary (const dictionary &other)
	Initializes instance of the xtd::collections::generic::dictionary <key_t, value_t> class from a variety of data sources. Optionally uses user supplied bucket_count as a minimal number of buckets to create, hash as the hash function, equal as the function to compare keys and alloc as the allocator.
	dictionary (std::unordered_map< key_t, value_t > &&other)
	Initializes instance of the xtd::collections::generic::dictionary <key_t, value_t> class from a variety of data sources. Optionally uses user supplied bucket_count as a minimal number of buckets to create, hash as the hash function, equal as the function to compare keys and alloc as the allocator.
	dictionary (const std::unordered_map< key_t, value_t > &other)
	Initializes instance of the xtd::collections::generic::dictionary <key_t, value_t> class from a variety of data sources. Optionally uses user supplied bucket_count as a minimal number of buckets to create, hash as the hash function, equal as the function to compare keys and alloc as the allocator.
	dictionary (std::initializer_list< base_value_type > init)
	Initializes instance of the xtd::collections::generic::dictionary <key_t, value_t> class from a variety of data sources.
template<class init_key_t, class init_value_t>
	dictionary (std::initializer_list< key_value_pair< init_key_t, init_value_t > > init)
	Initializes instance of the xtd::collections::generic::dictionary <key_t, value_t> class from a variety of data sources.
template<class input_iterator_t>
	dictionary (input_iterator_t first, input_iterator_t last)
	Initializes instance of the xtd::collections::generic::dictionary <key_t, value_t> class from a variety of data sources.

Public Properties
auto	capacity () const noexcept -> size_type
	Gets the total numbers of elements the internal data structure can hold without resizing.
auto	comparer () const noexcept -> const iequality_comparer< key_t > &
	Gets the xtd::collections::generic::iequality_comparer <type_t> that is used to determine equality of keys for the dictionary.
auto	count () const noexcept -> size_type override
	Gets the number of key/value pairs contained in the xtd::collections::generic::dictionary <key_t, value_t>.
virtual auto	items () const noexcept -> const base_type &
	Returns the underlying base type items.
virtual auto	items () noexcept -> base_type &
	Returns the underlying base type items.
auto	keys () const noexcept -> key_collection override
	Gets a collection containing the keys in the xtd::collections::generic::dictionary <key_t, value_t>.
auto	values () const noexcept -> value_collection override
	Gets a collection containing the values in the xtd::collections::generic::dictionary <key_t, value_t>.

Public Methods
auto	add (const key_t &key, const value_t &value) -> void override
	Adds an element with the provided key and value to the xtd::collections::generic::dictionary <key_t, value_t>.
auto	add (const value_type &item) -> void override
	Adds an item to the xtd::collections::generic::icollection <type_t>.
auto	clear () noexcept -> void override
	Removes all keys and values from the xtd::collections::generic::dictionary <key_t, value_t>.
auto	contains (const value_type &item) const noexcept -> bool override
	Determines whether an element is in the xtd::collections::generic::dictionary <key_t, value_t>.
auto	contains_key (const key_t &key) const noexcept -> bool override
	Determines whether the xtd::collections::generic::dictionary <key_t, value_t> contains the specified key.
auto	contains_value (const value_t &value) const noexcept -> bool
	Determines whether the xtd::collections::generic::dictionary <key_t, value_t> contains the specified value.
auto	copy_to (xtd::array< value_type > &array, xtd::size array_index) const -> void override
	Copies the elements of the xtd::collections::generic::icollection <type_t> to an xtd::array, starting at a particular xtd::array index.
auto	ensure_capacity (xtd::size capacity) noexcept -> size_type
	Ensures that the dictionary can hold up to a specified number of entries without any further expansion of its backing storage.
enumerator< value_type >	get_enumerator () const noexcept override
	Returns an enumerator that iterates through the xtd::collections::generic::dictionary <key_t, value_t>.
auto	remove (const key_t &key) noexcept -> bool override
	Removes the value with the specified key from the xtd::collections::generic::dictionary <key_t, value_t>.
auto	remove (const value_type &item) noexcept -> bool override
	Removes the first occurrence of a specific object from the xtd::collections::generic::dictionary <key_t, value_t>.
auto	remove (const key_t &key, value_t &value) noexcept -> bool
	Removes the value with the specified key from the xtd::collections::generic::dictionary <key_t, value_t>, and copies the element to the value parameter.
auto	to_string () const noexcept -> xtd::string override
	Gets a string that represents the current object.
auto	trim_excess (size_type capacity) -> void
	Sets the capacity of this dictionary to hold up a specified number of entries without any further expansion of its backing storage.
auto	trim_excess () -> void
	Sets the capacity of this dictionary to what it would be if it had been originally initialized with all its entries.
auto	try_add (const key_t &key, const value_t value) noexcept -> bool
	Attempts to add the specified key and value to the dictionary.
auto	try_get_value (const key_t &key, value_t &value) const -> bool override
	Gets the value associated with the specified key.

Public Operators
auto	operator= (dictionary &&other) noexcept -> dictionary &
	Move assignment operator. Replaces the contents with a copy of the contents of other.
auto	operator= (std::unordered_map< key_t, value_t > &&other) noexcept -> dictionary &
	Move assignment operator. Replaces the contents with a copy of the contents of other.
auto	operator= (const dictionary &other) noexcept -> dictionary &=default
	Copy assignment operator. Replaces the contents with a copy of the contents of other.
auto	operator= (const std::unordered_map< key_t, value_t > &other) noexcept -> dictionary &
	Copy assignment operator. Replaces the contents with a copy of the contents of other.
auto	operator= (std::initializer_list< base_value_type > ilist) -> dictionary &
	Copy assignment operator. Replaces the contents with a copy of the contents of other.
template<class init_key_t, class init_value_t>
auto	operator= (std::initializer_list< key_value_pair< init_key_t, init_value_t > > ilist) -> dictionary &
	Copy assignment operator. Replaces the contents with a copy of the contents of other.
const value_t &	operator[] (const key_t &key) const override
	Gets the element with the specified key.
value_t &	operator[] (const key_t &key) override
	Sets the element with the specified key.
	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.
	operator std::unordered_map< key_t, value_t > () const noexcept
	Gets a std::unordered_map<key_t, value_t>.

Additional Inherited Members
using	key_type
	Represents the dictionary key type.
using	mapped_type
	Represents the dictionary mapped type.
using	value_type
	Represents the xtd::collections::generic::idictionary value type.
using	iterator
	Represents the iterator of xtd::collections::generic::ienumerable value type.
using	const_iterator
	Represents the const iterator of xtd::collections::generic::ienumerable value type.
using	key_collection
	Represents the idictionary key collection type.
using	value_collection
	Represents the idictionary value collection type.
	object ()=default
	Create a new instance of the ultimate base class object.
virtual bool	equals (const object &obj) const noexcept
	Determines whether the specified object is equal to the current object.
virtual xtd::size	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<class object_t>
xtd::unique_ptr_object< object_t >	memberwise_clone () const
	Creates a shallow copy of the current object.
template<class object_a_t, class 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<class object_a_t, class 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

key_type

template<class key_t, class value_t, class hasher_t = xtd::collections::generic::helpers::hasher<key_t>, class equator_t = xtd::collections::generic::helpers::equator<key_t>, class allocator_t = xtd::collections::generic::helpers::allocator<std::pair<const key_t, value_t >>>

using xtd::collections::generic::dictionary< key_t, value_t, hasher_t, equator_t, allocator_t >::key_type

Represents the dictionary key type.

mapped_type

template<class key_t, class value_t, class hasher_t = xtd::collections::generic::helpers::hasher<key_t>, class equator_t = xtd::collections::generic::helpers::equator<key_t>, class allocator_t = xtd::collections::generic::helpers::allocator<std::pair<const key_t, value_t >>>

using xtd::collections::generic::dictionary< key_t, value_t, hasher_t, equator_t, allocator_t >::mapped_type

Represents the dictionary mapped type.

value_type

template<class key_t, class value_t, class hasher_t = xtd::collections::generic::helpers::hasher<key_t>, class equator_t = xtd::collections::generic::helpers::equator<key_t>, class allocator_t = xtd::collections::generic::helpers::allocator<std::pair<const key_t, value_t >>>

using xtd::collections::generic::dictionary< key_t, value_t, hasher_t, equator_t, allocator_t >::value_type

Represents the dictionary value type.

size_type

template<class key_t, class value_t, class hasher_t = xtd::collections::generic::helpers::hasher<key_t>, class equator_t = xtd::collections::generic::helpers::equator<key_t>, class allocator_t = xtd::collections::generic::helpers::allocator<std::pair<const key_t, value_t >>>

using xtd::collections::generic::dictionary< key_t, value_t, hasher_t, equator_t, allocator_t >::size_type

Represents the dictionary size type.

base_value_type

template<class key_t, class value_t, class hasher_t = xtd::collections::generic::helpers::hasher<key_t>, class equator_t = xtd::collections::generic::helpers::equator<key_t>, class allocator_t = xtd::collections::generic::helpers::allocator<std::pair<const key_t, value_t >>>

using xtd::collections::generic::dictionary< key_t, value_t, hasher_t, equator_t, allocator_t >::base_value_type

Represents the dictionary base value type.

base_type

template<class key_t, class value_t, class hasher_t = xtd::collections::generic::helpers::hasher<key_t>, class equator_t = xtd::collections::generic::helpers::equator<key_t>, class allocator_t = xtd::collections::generic::helpers::allocator<std::pair<const key_t, value_t >>>

using xtd::collections::generic::dictionary< key_t, value_t, hasher_t, equator_t, allocator_t >::base_type

Represents the dictionary base type.

key_collection

template<class key_t, class value_t, class hasher_t = xtd::collections::generic::helpers::hasher<key_t>, class equator_t = xtd::collections::generic::helpers::equator<key_t>, class allocator_t = xtd::collections::generic::helpers::allocator<std::pair<const key_t, value_t >>>

using xtd::collections::generic::dictionary< key_t, value_t, hasher_t, equator_t, allocator_t >::key_collection

Represents the idictionary key collection type.

value_collection

template<class key_t, class value_t, class hasher_t = xtd::collections::generic::helpers::hasher<key_t>, class equator_t = xtd::collections::generic::helpers::equator<key_t>, class allocator_t = xtd::collections::generic::helpers::allocator<std::pair<const key_t, value_t >>>

using xtd::collections::generic::dictionary< key_t, value_t, hasher_t, equator_t, allocator_t >::value_collection

Represents the idictionary value collection type.

equator

template<class key_t, class value_t, class hasher_t = xtd::collections::generic::helpers::hasher<key_t>, class equator_t = xtd::collections::generic::helpers::equator<key_t>, class allocator_t = xtd::collections::generic::helpers::allocator<std::pair<const key_t, value_t >>>

using xtd::collections::generic::dictionary< key_t, value_t, hasher_t, equator_t, allocator_t >::equator

Represents the dictionary equator type.

hasher

template<class key_t, class value_t, class hasher_t = xtd::collections::generic::helpers::hasher<key_t>, class equator_t = xtd::collections::generic::helpers::equator<key_t>, class allocator_t = xtd::collections::generic::helpers::allocator<std::pair<const key_t, value_t >>>

using xtd::collections::generic::dictionary< key_t, value_t, hasher_t, equator_t, allocator_t >::hasher

Represents the dictionary hasher type.

Constructor & Destructor Documentation

dictionary() [1/15]

template<class key_t, class value_t, class hasher_t = xtd::collections::generic::helpers::hasher<key_t>, class equator_t = xtd::collections::generic::helpers::equator<key_t>, class allocator_t = xtd::collections::generic::helpers::allocator<std::pair<const key_t, value_t >>>

xtd::collections::generic::dictionary< key_t, value_t, hasher_t, equator_t, allocator_t >::dictionary ( )

defaultnoexcept

Initializes a new instance of the xtd::collections::generic::dictionary <key_t, value_t> class that is empty, has the default initial capacity, and uses the default equality comparer for the key type.

Remarks

Every key in a xtd::collections::generic::dictionary <key_t, value_t> must be unique according to the default equality comparer.

xtd::collections::generic::dictionary <key_t, value_t> requires an equality implementation to determine whether keys are equal. This constructor uses the default generic equality comparer, equality_comparer::default. If type key_t implements the xtd::equatable <type_t> generic interface, the default equality comparer uses that implementation. Alternatively, you can specify an implementation of the iequality_comparer <typer_t> generic interface by using a constructor that accepts a comparer parameter.

Note

If you can estimate the size of the collection, using a constructor that specifies the initial capacity eliminates the need to perform a number of resizing operations while adding elements to the xtd::collections::generic::dictionary <key_t, value_t>.

Remarks

Constructs empty container. Sets xtd::collections::generic::dictionary::max_load_factor() to 1.0. For the default constructor, the number of buckets is implementation-defined.

This constructor is an O(1) operation.

Examples

The following code example creates an empty xtd::collections::generic::dictionary <key_t, value_t> of strings with string keys and uses the Add method to add some elements. The example demonstrates that the dictionary::add method throws an xtd::argument_exception when attempting to add a duplicate key.

This code example is part of a larger example provided for the xtd::collections::generic::dictionary <key_t, value_t> class.

// Create a new dictionary of strings, with string keys.
//
auto open_with = dictionary<string, string> {};
 
// Add some elements to the dictionary. There are no
// duplicate keys, but some of the values are duplicates.
open_with.add("txt", "notepad.exe");
open_with.add("bmp", "paint.exe");
open_with.add("dib", "paint.exe");
open_with.add("rtf", "wordpad.exe");
 
// The add method throws an exception if the new key is
// already in the dictionary.
try {
  open_with.add("txt", "winword.exe");
} catch (const argument_exception&) {
  console::write_line("An element with key = \"txt\" already exists.");
}

dictionary() [2/15]

template<class key_t, class value_t, class hasher_t = xtd::collections::generic::helpers::hasher<key_t>, class equator_t = xtd::collections::generic::helpers::equator<key_t>, class allocator_t = xtd::collections::generic::helpers::allocator<std::pair<const key_t, value_t >>>

xtd::collections::generic::dictionary< key_t, value_t, hasher_t, equator_t, allocator_t >::dictionary ( const xtd::collections::generic::idictionary< key_t, value_t > & dictionary )

inline

Initializes a new instance of the xtd::collections::generic::dictionary <key_t, value_t> class that contains elements copied from the specified xtd::collections::generic::idictionary <key_t, value_t> and uses the default equality comparer for the key type.

Parameters

dictionary

The xtd::collections::generic::idictionary <key_t, value_t> whose elements are copied to the new xtd::collections::generic::dictionary <key_t, value_t>.

Exceptions

xtd::argument_exception

`dictionary` contains one or more duplicate keys.

Remarks

Every key in a xtd::collections::generic::dictionary <key_t, value_t> must be unique according to the default equality comparer; likewise, every key in the source dictionary must also be unique according to the default equality comparer.

The initial capacity of the new xtd::collections::generic::dictionary <key_t, value_t> is large enough to contain all the elements in dictionary.

xtd::collections::generic::dictionary <key_t, value_t> requires an equality implementation to determine whether keys are equal. This constructor uses the default generic equality comparer, xtd::collections::generic::equality_comparer::default_equality_comparer. If type key_t implements the xtd::iequatable <type_t> generic interface, the default equality comparer uses that implementation. Alternatively, you can specify an implementation of the xtd::collections::generic::iequality_comparer <type_t> generic interface by using a constructor that accepts a comparer parameter.

This constructor is an O(n) operation, where n is the number of elements in dictionary.

Examples

The following code example shows how to use the xtd::collections::generic::dictionary <key_t, value_t>(xtd::collections::generic::iequality_comparer <key_t>) constructor to initialize a xtd::collections::generic::dictionary <key_t, value_t> with sorted content from another dictionary. The code example creates a xtd::collections::generic::sorted_dictionary <key_t, value_t> and populates it with data in random order, then passes the xtd::collections::generic::sorted_dictionary <key_t, value_t> to the xtd::collections::generic::dictionary <key_t, value_t>(xtd::collections::generic::iequality_comparer <key_t>) constructor, creating a xtd::collections::generic::dictionary <key_t, value_t> that is sorted. This is useful if you need to build a sorted dictionary that at some point becomes static; copying the data from a xtd::collections::generic::sorted_dictionary <key_t, value_t> to a xtd::collections::generic::dictionary <key_t, value_t> improves retrieval speed.

#include <xtd/xtd>
 
class example {
public:
  static auto main() -> void {
    // Create a new sorted dictionary of strings, with string keys.
    auto open_with = sorted_dictionary<string, string> {};
    
    // Add some elements to the dictionary.
    open_with.insert({"txt", "notepad.exe"});
    open_with.insert({"bmp", "paint.exe"});
    open_with.insert({"dib", "paint.exe"});
    open_with.insert({"rtf", "wordpad.exe"});
    
    // Create a dictionary of strings with string keys, and
    // initialize it with the contents of the sorted dictionary.
    auto copy = dictionary<string, string>(open_with.begin(), open_with.end());
    
    // List the contents of the copy.
    console::write_line();
    for(const key_value_pair<string, string>& kvp : copy)
      console::write_line("key = {0}, value = {1}", kvp.key(), kvp.value());
  }
};
 
startup_(example::main);
 
// This code can produce the following output :
//
// key = txt, value = notepad.exe
// key = bmp, value = paint.exe
// key = dib, value = paint.exe
// key = rtf, value = wordpad.exe

dictionary() [3/15]

template<class key_t, class value_t, class hasher_t = xtd::collections::generic::helpers::hasher<key_t>, class equator_t = xtd::collections::generic::helpers::equator<key_t>, class allocator_t = xtd::collections::generic::helpers::allocator<std::pair<const key_t, value_t >>>

xtd::collections::generic::dictionary< key_t, value_t, hasher_t, equator_t, allocator_t >::dictionary ( const xtd::collections::generic::ienumerable< value_type > & collection )

inline

Initializes a new instance of the xtd::collections::generic::dictionary <key_t, value_t> class that contains elements copied from the specified xtd::collections::generic::ienumerable <type_t>.

Parameters

collection

The xtd::collections::generic::ienumerable <type_t> whose elements are copied to the new xtd::collections::generic::dictionary <key_t, value_t>

Exceptions

xtd::argument_exception

`dictionary` contains one or more duplicate keys.

dictionary() [4/15]

template<class key_t, class value_t, class hasher_t = xtd::collections::generic::helpers::hasher<key_t>, class equator_t = xtd::collections::generic::helpers::equator<key_t>, class allocator_t = xtd::collections::generic::helpers::allocator<std::pair<const key_t, value_t >>>

xtd::collections::generic::dictionary< key_t, value_t, hasher_t, equator_t, allocator_t >::dictionary ( const xtd::collections::generic::iequality_comparer< key_type > & comparer )

inline

Initializes a new instance of the xtd::collections::generic::dictionary <key_t, value_t> class that is empty, has the default initial capacity, and uses the specified xtd::collections::generic::iequality_comparer<type_t>.

Parameters

comparer

The xtd::collections::generic::iequality_comparer<type_t> implementation to use when comparing keys.

Remarks

Use this constructor with the case-insensitive string comparers provided by the xtd::string_comparer class to create dictionaries with case-insensitive string keys.

Every key in a xtd::collections::generic::dictionary <key_t, value_t> must be unique according to the specified comparer.

xtd::collections::generic::dictionary <key_t, value_t> requires an equality implementation to determine whether keys are equal. If type key_t implements the xtd::iequatable <type_t> generic interface, the default equality comparer uses that implementation.

dictionary() [5/15]

template<class key_t, class value_t, class hasher_t = xtd::collections::generic::helpers::hasher<key_t>, class equator_t = xtd::collections::generic::helpers::equator<key_t>, class allocator_t = xtd::collections::generic::helpers::allocator<std::pair<const key_t, value_t >>>

xtd::collections::generic::dictionary< key_t, value_t, hasher_t, equator_t, allocator_t >::dictionary ( xtd::size capacity )

inline

Initializes a new instance of the xtd::collections::generic::dictionary <key_t, value_t> class that is empty, has the specified initial capacit.

Parameters

capacity

The initial number of elements that the xtd::collections::generic::dictionary <key_t, value_t> can contain.

Remarks

Every key in a xtd::collections::generic::dictionary <key_t, value_t> must be unique according to the specified comparer; likewise, every key in the source dictionary must also be unique according to the specified comparer.

The capacity of a xtd::collections::generic::dictionary <key_t, value_t> is the number of elements that can be added to the xtd::collections::generic::dictionary <key_t, value_t> before resizing is necessary. As elements are added to a xtd::collections::generic::dictionary <key_t, value_t>, the capacity is automatically increased as required by reallocating the internal array.

If the size of the collection can be estimated, specifying the initial capacity eliminates the need to perform a number of resizing operations while adding elements to the xtd::collections::generic::dictionary <key_t, value_t>.

xtd::collections::generic::dictionary <key_t, value_t> requires an equality implementation to determine whether keys are equal. If type TKey implements the xtd::iequatable <type_t> generic interface, the default equality comparer uses that implementation.

This constructor is an O(1) operation.

xtd::collections::generic::dictionary::capacity and xtd::collections::generic::dictionary::bucket_count are equivalent properties.

dictionary() [6/15]

template<class key_t, class value_t, class hasher_t = xtd::collections::generic::helpers::hasher<key_t>, class equator_t = xtd::collections::generic::helpers::equator<key_t>, class allocator_t = xtd::collections::generic::helpers::allocator<std::pair<const key_t, value_t >>>

xtd::collections::generic::dictionary< key_t, value_t, hasher_t, equator_t, allocator_t >::dictionary ( xtd::size capacity, const xtd::collections::generic::iequality_comparer< key_type > & comparer )

inline

Initializes a new instance of the xtd::collections::generic::dictionary <key_t, value_t> class that is empty, has the specified initial capacity, and uses the specified xtd::collections::generic::iequality_comparer <type_t>.

Parameters

capacity	The initial number of elements that the xtd::collections::generic::dictionary <key_t, value_t> can contain.
comparer	The xtd::collections::generic::iequality_comparer <type_t> implementation to use when comparing keys.

Remarks

Use this constructor with the case-insensitive string comparers provided by the xtd::string_comparer class to create dictionaries with case-insensitive string keys.

Every key in a xtd::collections::generic::dictionary <key_t, value_t> must be unique according to the specified comparer; likewise, every key in the source dictionary must also be unique according to the specified comparer.

The capacity of a xtd::collections::generic::dictionary <key_t, value_t> is the number of elements that can be added to the xtd::collections::generic::dictionary <key_t, value_t> before resizing is necessary. As elements are added to a xtd::collections::generic::dictionary <key_t, value_t>, the capacity is automatically increased as required by reallocating the internal array.

If the size of the collection can be estimated, specifying the initial capacity eliminates the need to perform a number of resizing operations while adding elements to the xtd::collections::generic::dictionary <key_t, value_t>.

xtd::collections::generic::dictionary <key_t, value_t> requires an equality implementation to determine whether keys are equal. If type TKey implements the xtd::iequatable <type_t> generic interface, the default equality comparer uses that implementation.

This constructor is an O(1) operation.

xtd::collections::generic::dictionary::capacity and xtd::collections::generic::dictionary::bucket_count are equivalent properties.

dictionary() [7/15]

template<class key_t, class value_t, class hasher_t = xtd::collections::generic::helpers::hasher<key_t>, class equator_t = xtd::collections::generic::helpers::equator<key_t>, class allocator_t = xtd::collections::generic::helpers::allocator<std::pair<const key_t, value_t >>>

xtd::collections::generic::dictionary< key_t, value_t, hasher_t, equator_t, allocator_t >::dictionary ( const xtd::collections::generic::idictionary< key_t, value_t > & dictionary, const xtd::collections::generic::iequality_comparer< key_type > & comparer )

inline

Initializes a new instance of the xtd::collections::generic::dictionary <key_t, value_t> class that contains elements copied from the specified xtd::collections::generic::dictionary <key_t, value_t> and uses the specified xtd::collections::generic::iequality_comparer <type_t>.

Parameters

dictionary	The xtd::collections::generic::dictionary <key_t, value_t> whose elements are copied to the new xtd::collections::generic::dictionary <key_t, value_t>.
comparer	The xtd::collections::generic::iequality_comparer <type_t> implementation to use when comparing keys.

Exceptions

xtd::argument_exception

`dictionary` contains one or more duplicate keys.

Remarks

Use this constructor with the case-insensitive string comparers provided by the xtd::string_comparer class to create dictionaries with case-insensitive string keys.

Every key in a xtd::collections::generic::dictionary <key_t, value_t> must be unique according to the specified comparer; likewise, every key in the source dictionary must also be unique according to the specified comparer.

Note

For example, duplicate keys can occur if comparer is one of the case-insensitive string comparers provided by the xtd::string_comparer class and dictionary does not use a case-insensitive comparer key.

Remarks

The initial capacity of the new xtd::collections::generic::dictionary <key_t, value_t> is large enough to contain all the elements in dictionary.

xtd::collections::generic::dictionary <key_t, value_t> requires an equality implementation to determine whether keys are equal. If type key_t implements the xtd::iequatable <type_t> generic interface, the default equality comparer uses that implementation.

This constructor is an O(n) operation, where n is the number of elements in dictionary.

dictionary() [8/15]

template<class key_t, class value_t, class hasher_t = xtd::collections::generic::helpers::hasher<key_t>, class equator_t = xtd::collections::generic::helpers::equator<key_t>, class allocator_t = xtd::collections::generic::helpers::allocator<std::pair<const key_t, value_t >>>

xtd::collections::generic::dictionary< key_t, value_t, hasher_t, equator_t, allocator_t >::dictionary ( const xtd::collections::generic::ienumerable< value_type > & collection, const xtd::collections::generic::iequality_comparer< key_type > & comparer )

inline

Initializes a new instance of the xtd::collections::generic::dictionary <key_t, value_t> class that contains elements copied from the specified xtd::collections::generic::ienumerable <type_t> and uses the specified xtd::collections::generic::iequality_comparer <type_t>.

Parameters

collection	The xtd::collections::generic::ienumerable <type_t> whose elements are copied to the new xtd::collections::generic::dictionary <key_t, value_t>.
comparer	The xtd::collections::generic::iequality_comparer <type_t> implementation to use when comparing keys.

Exceptions

xtd::argument_exception

`dictionary` contains one or more duplicate keys.

dictionary() [9/15]

template<class key_t, class value_t, class hasher_t = xtd::collections::generic::helpers::hasher<key_t>, class equator_t = xtd::collections::generic::helpers::equator<key_t>, class allocator_t = xtd::collections::generic::helpers::allocator<std::pair<const key_t, value_t >>>

xtd::collections::generic::dictionary< key_t, value_t, hasher_t, equator_t, allocator_t >::dictionary ( dictionary< key_t, value_t, hasher_t, equator_t, allocator_t > && other )

defaultnoexcept

Initializes instance of the xtd::collections::generic::dictionary <key_t, value_t> class from a variety of data sources. Optionally uses user supplied bucket_count as a minimal number of buckets to create, hash as the hash function, equal as the function to compare keys and alloc as the allocator.

Parameters

other

Another container to be used as source to initialize the elements of the container with.

Remarks

Move constructor. Constructs the container with the contents of other using move semantics. If alloc is not provided, allocator is obtained by move-construction from the allocator belonging to other.

dictionary() [10/15]

template<class key_t, class value_t, class hasher_t = xtd::collections::generic::helpers::hasher<key_t>, class equator_t = xtd::collections::generic::helpers::equator<key_t>, class allocator_t = xtd::collections::generic::helpers::allocator<std::pair<const key_t, value_t >>>

xtd::collections::generic::dictionary< key_t, value_t, hasher_t, equator_t, allocator_t >::dictionary ( const dictionary< key_t, value_t, hasher_t, equator_t, allocator_t > & other )

inline

Initializes instance of the xtd::collections::generic::dictionary <key_t, value_t> class from a variety of data sources. Optionally uses user supplied bucket_count as a minimal number of buckets to create, hash as the hash function, equal as the function to compare keys and alloc as the allocator.

Parameters

other

Another container to be used as source to initialize the elements of the container with.

Remarks

Copy constructor. Constructs the container with the copy of the contents of other, copies the load factor, the predicate, and the hash function as well. If alloc is not provided, allocator is obtained by calling

dictionary() [11/15]

template<class key_t, class value_t, class hasher_t = xtd::collections::generic::helpers::hasher<key_t>, class equator_t = xtd::collections::generic::helpers::equator<key_t>, class allocator_t = xtd::collections::generic::helpers::allocator<std::pair<const key_t, value_t >>>

xtd::collections::generic::dictionary< key_t, value_t, hasher_t, equator_t, allocator_t >::dictionary ( std::unordered_map< key_t, value_t > && other )

inline

Initializes instance of the xtd::collections::generic::dictionary <key_t, value_t> class from a variety of data sources. Optionally uses user supplied bucket_count as a minimal number of buckets to create, hash as the hash function, equal as the function to compare keys and alloc as the allocator.

Parameters

other

Another container to be used as source to initialize the elements of the container with.

Remarks

Move constructor. Constructs the container with the contents of other using move semantics. If alloc is not provided, allocator is obtained by move-construction from the allocator belonging to other.

dictionary() [12/15]

template<class key_t, class value_t, class hasher_t = xtd::collections::generic::helpers::hasher<key_t>, class equator_t = xtd::collections::generic::helpers::equator<key_t>, class allocator_t = xtd::collections::generic::helpers::allocator<std::pair<const key_t, value_t >>>

xtd::collections::generic::dictionary< key_t, value_t, hasher_t, equator_t, allocator_t >::dictionary ( const std::unordered_map< key_t, value_t > & other )

inline

Initializes instance of the xtd::collections::generic::dictionary <key_t, value_t> class from a variety of data sources. Optionally uses user supplied bucket_count as a minimal number of buckets to create, hash as the hash function, equal as the function to compare keys and alloc as the allocator.

Parameters

other

Another container to be used as source to initialize the elements of the container with.

Exceptions

xtd::argument_exception

`dictionary` contains one or more duplicate keys.

Remarks

Copy constructor. Constructs the container with the copy of the contents of other, copies the load factor, the predicate, and the hash function as well. If alloc is not provided, allocator is obtained by calling

dictionary() [13/15]

template<class key_t, class value_t, class hasher_t = xtd::collections::generic::helpers::hasher<key_t>, class equator_t = xtd::collections::generic::helpers::equator<key_t>, class allocator_t = xtd::collections::generic::helpers::allocator<std::pair<const key_t, value_t >>>

xtd::collections::generic::dictionary< key_t, value_t, hasher_t, equator_t, allocator_t >::dictionary ( std::initializer_list< base_value_type > init )

inline

Initializes instance of the xtd::collections::generic::dictionary <key_t, value_t> class from a variety of data sources.

Parameters

init	Initializer list to initialize the elements of the container with.

Exceptions

xtd::argument_exception

`dictionary` contains one or more duplicate keys.

Remarks

Initializer-list constructor. Constructs the container with the contents of the initializer list init, same as

dictionary(init.begin(), init.end())

dictionary() [14/15]

template<class key_t, class value_t, class hasher_t = xtd::collections::generic::helpers::hasher<key_t>, class equator_t = xtd::collections::generic::helpers::equator<key_t>, class allocator_t = xtd::collections::generic::helpers::allocator<std::pair<const key_t, value_t >>>

template<class init_key_t, class init_value_t>

xtd::collections::generic::dictionary< key_t, value_t, hasher_t, equator_t, allocator_t >::dictionary ( std::initializer_list< key_value_pair< init_key_t, init_value_t > > init )

inlineexplicit

Initializes instance of the xtd::collections::generic::dictionary <key_t, value_t> class from a variety of data sources.

Parameters

init	Initializer list to initialize the elements of the container with.

Exceptions

xtd::argument_exception

`dictionary` contains one or more duplicate keys.

Remarks

Initializer-list constructor. Constructs the container with the contents of the initializer list init, same as

dictionary(init.begin(), init.end())

xtd::collections::generic::dictionary::bucket_count and xtd::collections::generic::dictionary::capacity are equivalent properties.

dictionary() [15/15]

template<class key_t, class value_t, class hasher_t = xtd::collections::generic::helpers::hasher<key_t>, class equator_t = xtd::collections::generic::helpers::equator<key_t>, class allocator_t = xtd::collections::generic::helpers::allocator<std::pair<const key_t, value_t >>>

template<class input_iterator_t>

xtd::collections::generic::dictionary< key_t, value_t, hasher_t, equator_t, allocator_t >::dictionary ( input_iterator_t first, input_iterator_t last )

inlineexplicit

Initializes instance of the xtd::collections::generic::dictionary <key_t, value_t> class from a variety of data sources.

Parameters

first	The fist iterator of the range [first, last) to copy the elements from.
last	Thaae last itezrator of the range [first, last) to copy the elements from.

Exceptions

xtd::argument_exception

`dictionary` contains one or more duplicate keys.

Remarks

Constructs the container with the contents of the range [first, last). Sets xtd::collections::generic::dictionary::max_load_factor() to 1.0. If multiple elements in the range have keys that compare equivalent, it is unspecified which element is inserted (pending LWG2844.

xtd::collections::generic::dictionary::bucket_count and xtd::collections::generic::dictionary::capacity are equivalent properties.

Member Function Documentation

capacity()

template<class key_t, class value_t, class hasher_t = xtd::collections::generic::helpers::hasher<key_t>, class equator_t = xtd::collections::generic::helpers::equator<key_t>, class allocator_t = xtd::collections::generic::helpers::allocator<std::pair<const key_t, value_t >>>

auto xtd::collections::generic::dictionary< key_t, value_t, hasher_t, equator_t, allocator_t >::capacity ( ) const -> size_type

inlinenodiscardnoexcept

Gets the total numbers of elements the internal data structure can hold without resizing.

Returns

The total numbers of elements the internal data structure can hold without resizing.

Remarks

xtd::collections::generic::dictionary::capacity and xtd::collections::generic::dictionary::bucket_count are equivalent properties.

comparer()

template<class key_t, class value_t, class hasher_t = xtd::collections::generic::helpers::hasher<key_t>, class equator_t = xtd::collections::generic::helpers::equator<key_t>, class allocator_t = xtd::collections::generic::helpers::allocator<std::pair<const key_t, value_t >>>

auto xtd::collections::generic::dictionary< key_t, value_t, hasher_t, equator_t, allocator_t >::comparer ( ) const -> const iequality_comparer< key_t > &

inlinenodiscardnoexcept

Gets the xtd::collections::generic::iequality_comparer <type_t> that is used to determine equality of keys for the dictionary.

Returns

The xtd::collections::generic::iequality_comparer <type_t> generic interface implementation that is used to determine equality of keys for the current xtd::collections::generic::dictionary <key_t, value_t> and to provide hash values for the keys.

Remarks

xtd::collections::generic::dictionary <key_t, value_t> requires an equality implementation to determine whether keys are equal. You can specify an implementation of the xtd::collections::generic::iequality_comparer <type_t> generic interface by using a constructor that accepts a comparer parameter; if you do not specify one, the default generic equality comparer td::collections::generic::equality_comparer::default_equality_comparer is used.

count()

template<class key_t, class value_t, class hasher_t = xtd::collections::generic::helpers::hasher<key_t>, class equator_t = xtd::collections::generic::helpers::equator<key_t>, class allocator_t = xtd::collections::generic::helpers::allocator<std::pair<const key_t, value_t >>>

auto xtd::collections::generic::dictionary< key_t, value_t, hasher_t, equator_t, allocator_t >::count ( ) const -> size_type

inlinenodiscardoverridenoexcept

Gets the number of key/value pairs contained in the xtd::collections::generic::dictionary <key_t, value_t>.

Returns

the number of key/value pairs contained in the xtd::collections::generic::dictionary <key_t, value_t>.

Remarks

The capacity of a xtd::collections::generic::dictionary <key_t, value_t> is the number of elements that the xtd::collections::generic::dictionary <key_t, value_t> can store. The xtd::collections::generic::dictionary::count property is the number of elements that are actually in the xtd::collections::generic::dictionary <key_t, value_t>.

The capacity is always greater than or equal to xtd::collections::generic::dictionary::count. If xtd::collections::generic::dictionary::count exceeds the capacity while adding elements, the capacity is increased by automatically reallocating the internal array before copying the old elements and adding the new elements.

Getting the value of this property is an O(1) operation.

items() [1/2]

template<class key_t, class value_t, class hasher_t = xtd::collections::generic::helpers::hasher<key_t>, class equator_t = xtd::collections::generic::helpers::equator<key_t>, class allocator_t = xtd::collections::generic::helpers::allocator<std::pair<const key_t, value_t >>>

virtual auto xtd::collections::generic::dictionary< key_t, value_t, hasher_t, equator_t, allocator_t >::items ( ) const -> const base_type &

inlinenodiscardvirtualnoexcept

Returns the underlying base type items.

Returns

The underlying base type items.

items() [2/2]

template<class key_t, class value_t, class hasher_t = xtd::collections::generic::helpers::hasher<key_t>, class equator_t = xtd::collections::generic::helpers::equator<key_t>, class allocator_t = xtd::collections::generic::helpers::allocator<std::pair<const key_t, value_t >>>

virtual auto xtd::collections::generic::dictionary< key_t, value_t, hasher_t, equator_t, allocator_t >::items ( ) -> base_type &

inlinenodiscardvirtualnoexcept

Returns the underlying base type items.

Returns

The underlying base type items.

keys()

template<class key_t, class value_t, class hasher_t = xtd::collections::generic::helpers::hasher<key_t>, class equator_t = xtd::collections::generic::helpers::equator<key_t>, class allocator_t = xtd::collections::generic::helpers::allocator<std::pair<const key_t, value_t >>>

auto xtd::collections::generic::dictionary< key_t, value_t, hasher_t, equator_t, allocator_t >::keys ( ) const -> key_collection

inlinenodiscardoverridevirtualnoexcept

Gets a collection containing the keys in the xtd::collections::generic::dictionary <key_t, value_t>.

Returns

A xtd::collections::generic::dictionary::key_collection containing the keys in the xtd::collections::generic::dictionary <key_t, value_t>.

Remarks

The order of the keys in the xtd::collections::generic::dictionary::key_collection is unspecified, but it is the same order as the associated values in the xtd::collections::generic::dictionary::value_collection returned by the xtd::collections::generic::dictionary::values property.

Getting the value of this property is an O(1) operation.

Implements xtd::collections::generic::idictionary< key_t, value_t >.

values()

template<class key_t, class value_t, class hasher_t = xtd::collections::generic::helpers::hasher<key_t>, class equator_t = xtd::collections::generic::helpers::equator<key_t>, class allocator_t = xtd::collections::generic::helpers::allocator<std::pair<const key_t, value_t >>>

auto xtd::collections::generic::dictionary< key_t, value_t, hasher_t, equator_t, allocator_t >::values ( ) const -> value_collection

inlinenodiscardoverridevirtualnoexcept

Gets a collection containing the values in the xtd::collections::generic::dictionary <key_t, value_t>.

Returns

A xtd::collections::generic::dictionary::value_collection containing the values in the xtd::collections::generic::dictionary <key_t, value_t>.

Remarks

The order of the values in the xtd::collections::generic::dictionary::value_collection is unspecified, but it is the same order as the associated keys in the xtd::collections::generic::dictionary::key_collection returned by the xtd::collections::generic::dictionary::keys property.

Getting the value of this property is an O(1) operation.

Implements xtd::collections::generic::idictionary< key_t, value_t >.

add() [1/2]

template<class key_t, class value_t, class hasher_t = xtd::collections::generic::helpers::hasher<key_t>, class equator_t = xtd::collections::generic::helpers::equator<key_t>, class allocator_t = xtd::collections::generic::helpers::allocator<std::pair<const key_t, value_t >>>

auto xtd::collections::generic::dictionary< key_t, value_t, hasher_t, equator_t, allocator_t >::add ( const key_t & key, const value_t & value ) -> void

inlineoverridevirtual

Adds an element with the provided key and value to the xtd::collections::generic::dictionary <key_t, value_t>.

Parameters

key	The object to use as the key of the element to add.
value	The object to use as the value of the element to add.

Exceptions

xtd::argument_exception	An element with the same key already exists in the xtd::collections::generic::dictionary <key_t, value_t>.
xtd::not_supported_exception	The xtd::collections::generic::dictionary <key_t, value_t> is read-only.

Remarks

You can also use the operator [] to add new elements by setting the value of a key that does not exist in the dictionary; for example, my_collection["my_nonexistent_key"] = my_value. However, if the specified key already exists in the dictionary, setting the operator [] overwrites the old value. In contrast, the xtd::collections::generic::dictionary::add method does not modify existing elements.

Implements xtd::collections::generic::idictionary< key_t, value_t >.

add() [2/2]

template<class key_t, class value_t, class hasher_t = xtd::collections::generic::helpers::hasher<key_t>, class equator_t = xtd::collections::generic::helpers::equator<key_t>, class allocator_t = xtd::collections::generic::helpers::allocator<std::pair<const key_t, value_t >>>

auto xtd::collections::generic::dictionary< key_t, value_t, hasher_t, equator_t, allocator_t >::add ( const value_type & item ) -> void

inlineoverride

Adds an item to the xtd::collections::generic::icollection <type_t>.

Parameters

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

Exceptions

xtd::not_supported_exception

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

clear()

template<class key_t, class value_t, class hasher_t = xtd::collections::generic::helpers::hasher<key_t>, class equator_t = xtd::collections::generic::helpers::equator<key_t>, class allocator_t = xtd::collections::generic::helpers::allocator<std::pair<const key_t, value_t >>>

auto xtd::collections::generic::dictionary< key_t, value_t, hasher_t, equator_t, allocator_t >::clear ( ) -> void

inlineoverridenoexcept

Removes all keys and values from the xtd::collections::generic::dictionary <key_t, value_t>.

Remarks

The xtd::collections::generic::dictionary::count property is set to 0, and references to other objects from elements of the collection are also released. The capacity remains unchanged.

contains()

template<class key_t, class value_t, class hasher_t = xtd::collections::generic::helpers::hasher<key_t>, class equator_t = xtd::collections::generic::helpers::equator<key_t>, class allocator_t = xtd::collections::generic::helpers::allocator<std::pair<const key_t, value_t >>>

auto xtd::collections::generic::dictionary< key_t, value_t, hasher_t, equator_t, allocator_t >::contains ( const value_type & item ) const -> bool

inlinenodiscardoverridenoexcept

Determines whether an element is in the xtd::collections::generic::dictionary <key_t, value_t>.

Parameters

item	The object to be added to the end of the xtd::collections::generic::dictionary <key_t, value_t>.

Returns

true if the xtd::collections::generic::dictionary <key_t, value_t> contains an element with the specified item ; otherwise, false.

contains_key()

template<class key_t, class value_t, class hasher_t = xtd::collections::generic::helpers::hasher<key_t>, class equator_t = xtd::collections::generic::helpers::equator<key_t>, class allocator_t = xtd::collections::generic::helpers::allocator<std::pair<const key_t, value_t >>>

auto xtd::collections::generic::dictionary< key_t, value_t, hasher_t, equator_t, allocator_t >::contains_key ( const key_t & key ) const -> bool

inlinenodiscardoverridevirtualnoexcept

Determines whether the xtd::collections::generic::dictionary <key_t, value_t> contains the specified key.

Parameters

The	key to locate in the xtd::collections::generic::dictionary <key_t, value_t>.

Returns

true if the xtd::collections::generic::dictionary <key_t, value_t> contains an element with the specified key ; otherwise, false.

Remarks

This method approaches an O(1) operation.

Implements xtd::collections::generic::idictionary< key_t, value_t >.

contains_value()

template<class key_t, class value_t, class hasher_t = xtd::collections::generic::helpers::hasher<key_t>, class equator_t = xtd::collections::generic::helpers::equator<key_t>, class allocator_t = xtd::collections::generic::helpers::allocator<std::pair<const key_t, value_t >>>

auto xtd::collections::generic::dictionary< key_t, value_t, hasher_t, equator_t, allocator_t >::contains_value ( const value_t & value ) const -> bool

inlinenodiscardnoexcept

Determines whether the xtd::collections::generic::dictionary <key_t, value_t> contains the specified value.

Parameters

The	value to locate in the xtd::collections::generic::dictionary <key_t, value_t>.

Returns

true if the xtd::collections::generic::dictionary <key_t, value_t> contains an element with the specified key ; otherwise, false.

Remarks

This method performs a linear search; therefore, the average execution time is proportional to xtd::collections::generic::dictionary::count. That is, this method is an O(n) operation, where n is xtd::collections::generic::dictionary::count.

copy_to()

template<class key_t, class value_t, class hasher_t = xtd::collections::generic::helpers::hasher<key_t>, class equator_t = xtd::collections::generic::helpers::equator<key_t>, class allocator_t = xtd::collections::generic::helpers::allocator<std::pair<const key_t, value_t >>>

auto xtd::collections::generic::dictionary< key_t, value_t, hasher_t, equator_t, allocator_t >::copy_to ( xtd::array< value_type > & array, xtd::size array_index ) const -> void

inlineoverride

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

ensure_capacity()

template<class key_t, class value_t, class hasher_t = xtd::collections::generic::helpers::hasher<key_t>, class equator_t = xtd::collections::generic::helpers::equator<key_t>, class allocator_t = xtd::collections::generic::helpers::allocator<std::pair<const key_t, value_t >>>

auto xtd::collections::generic::dictionary< key_t, value_t, hasher_t, equator_t, allocator_t >::ensure_capacity ( xtd::size capacity ) -> size_type

inlinenoexcept

Ensures that the dictionary can hold up to a specified number of entries without any further expansion of its backing storage.

Parameters

capacity

The number of entries.

Returns

The current capacity of the xtd::collections::generic::dictionary <key_t, value_t>.

get_enumerator()

template<class key_t, class value_t, class hasher_t = xtd::collections::generic::helpers::hasher<key_t>, class equator_t = xtd::collections::generic::helpers::equator<key_t>, class allocator_t = xtd::collections::generic::helpers::allocator<std::pair<const key_t, value_t >>>

enumerator< value_type > xtd::collections::generic::dictionary< key_t, value_t, hasher_t, equator_t, allocator_t >::get_enumerator ( ) const

inlinenodiscardoverridenoexcept

Returns an enumerator that iterates through the xtd::collections::generic::dictionary <key_t, value_t>.

Returns

A xtd::collections::enumerator structure for the xtd::collections::generic::dictionary <key_t, value_t>.

remove() [1/3]

template<class key_t, class value_t, class hasher_t = xtd::collections::generic::helpers::hasher<key_t>, class equator_t = xtd::collections::generic::helpers::equator<key_t>, class allocator_t = xtd::collections::generic::helpers::allocator<std::pair<const key_t, value_t >>>

auto xtd::collections::generic::dictionary< key_t, value_t, hasher_t, equator_t, allocator_t >::remove ( const key_t & key ) -> bool

inlineoverridevirtualnoexcept

Removes the value with the specified key from the xtd::collections::generic::dictionary <key_t, value_t>.

Parameters

key	The key of the element to remove.

Returns

true if the element is successfully found and removed; otherwise, false. This method returns false if key is not found in the xtd::collections::generic::dictionary <key_t, value_t>.

Remarks

If the xtd::collections::generic::dictionary <key_t, value_t> does not contain an element with the specified key, the xtd::collections::generic::dictionary <key_t, value_t> remains unchanged. No exception is thrown.

Implements xtd::collections::generic::idictionary< key_t, value_t >.

remove() [2/3]

template<class key_t, class value_t, class hasher_t = xtd::collections::generic::helpers::hasher<key_t>, class equator_t = xtd::collections::generic::helpers::equator<key_t>, class allocator_t = xtd::collections::generic::helpers::allocator<std::pair<const key_t, value_t >>>

auto xtd::collections::generic::dictionary< key_t, value_t, hasher_t, equator_t, allocator_t >::remove ( const value_type & item ) -> bool

inlineoverridenoexcept

Removes the first occurrence of a specific object from the xtd::collections::generic::dictionary <key_t, value_t>.

Parameters

item	The object to remove from the xtd::collections::generic::dictionary <key_t, value_t>.

Returns

true if item is successfully removed; otherwise, false. This method also returns false if item value was not found in the xtd::collections::generic::dictionary <key_t, value_t>.

remove() [3/3]

template<class key_t, class value_t, class hasher_t = xtd::collections::generic::helpers::hasher<key_t>, class equator_t = xtd::collections::generic::helpers::equator<key_t>, class allocator_t = xtd::collections::generic::helpers::allocator<std::pair<const key_t, value_t >>>

auto xtd::collections::generic::dictionary< key_t, value_t, hasher_t, equator_t, allocator_t >::remove ( const key_t & key, value_t & value ) -> bool

inlinenoexcept

Removes the value with the specified key from the xtd::collections::generic::dictionary <key_t, value_t>, and copies the element to the value parameter.

Parameters

key	The key of the element to remove.
value	The removed element.

to_string()

template<class key_t, class value_t, class hasher_t = xtd::collections::generic::helpers::hasher<key_t>, class equator_t = xtd::collections::generic::helpers::equator<key_t>, class allocator_t = xtd::collections::generic::helpers::allocator<std::pair<const key_t, value_t >>>

auto xtd::collections::generic::dictionary< key_t, value_t, hasher_t, equator_t, allocator_t >::to_string ( ) const -> xtd::string

inlinenodiscardoverridevirtualnoexcept

Gets a string that represents the current object.

Returns

A string that represents the current object.

Reimplemented from xtd::object.

trim_excess() [1/2]

template<class key_t, class value_t, class hasher_t = xtd::collections::generic::helpers::hasher<key_t>, class equator_t = xtd::collections::generic::helpers::equator<key_t>, class allocator_t = xtd::collections::generic::helpers::allocator<std::pair<const key_t, value_t >>>

auto xtd::collections::generic::dictionary< key_t, value_t, hasher_t, equator_t, allocator_t >::trim_excess ( size_type capacity ) -> void

inline

Sets the capacity of this dictionary to hold up a specified number of entries without any further expansion of its backing storage.

Parameters

capacity

The new capacity.

Exceptions

xtd::argument_out_of_range_exception

`capacity` is less than xtd::collections::generic::dictionary::count.

Remarks

This method can be used to minimize the memory overhead once it is known that no new elements will be added.

trim_excess() [2/2]

template<class key_t, class value_t, class hasher_t = xtd::collections::generic::helpers::hasher<key_t>, class equator_t = xtd::collections::generic::helpers::equator<key_t>, class allocator_t = xtd::collections::generic::helpers::allocator<std::pair<const key_t, value_t >>>

auto xtd::collections::generic::dictionary< key_t, value_t, hasher_t, equator_t, allocator_t >::trim_excess ( ) -> void

inline

Sets the capacity of this dictionary to what it would be if it had been originally initialized with all its entries.

Remarks

This method can be used to minimize memory overhead once it is known that no new elements will be added to the dictionary. To allocate a minimum size storage array, execute the following statements:

dictionary.clear();
dictionary.trim_excess();

try_add()

template<class key_t, class value_t, class hasher_t = xtd::collections::generic::helpers::hasher<key_t>, class equator_t = xtd::collections::generic::helpers::equator<key_t>, class allocator_t = xtd::collections::generic::helpers::allocator<std::pair<const key_t, value_t >>>

auto xtd::collections::generic::dictionary< key_t, value_t, hasher_t, equator_t, allocator_t >::try_add ( const key_t & key, const value_t value ) -> bool

inlinenodiscardnoexcept

Attempts to add the specified key and value to the dictionary.

Parameters

key	The key of the element to add.
value	The value of the element to add.

Returns

true if the key/value pair was added to the dictionary successfully; otherwise, false.

Remarks

Unlike the xtd::collections::generic::dictionary::add method, this method doesn't throw an exception if the element with the given key exists in the dictionary. Unlike the xtd::collections::generic::dictionary indexer (operator []), xtd::collections::generic::dictionary::try_add doesn't override the element if the element with the given key exists in the dictionary. If the key already exists, xtd::collections::generic::dictionary::try_add does nothing and returns false.

try_get_value()

template<class key_t, class value_t, class hasher_t = xtd::collections::generic::helpers::hasher<key_t>, class equator_t = xtd::collections::generic::helpers::equator<key_t>, class allocator_t = xtd::collections::generic::helpers::allocator<std::pair<const key_t, value_t >>>

auto xtd::collections::generic::dictionary< key_t, value_t, hasher_t, equator_t, allocator_t >::try_get_value ( const key_t & key, value_t & value ) const -> bool

inlinenodiscardoverridevirtual

Gets the value associated with the specified key.

Parameters

key	The key of the value to get.
value	When this method returns, contains the value associated with the specified key, if the key is found; otherwise, the default value for the type of the value parameter.

Returns

true if the xtd::collections::generic::dictionary <key_t, value_t> contains an element with the specified key; otherwise, false.

Implements xtd::collections::generic::idictionary< key_t, value_t >.

operator=() [1/6]

template<class key_t, class value_t, class hasher_t = xtd::collections::generic::helpers::hasher<key_t>, class equator_t = xtd::collections::generic::helpers::equator<key_t>, class allocator_t = xtd::collections::generic::helpers::allocator<std::pair<const key_t, value_t >>>

auto xtd::collections::generic::dictionary< key_t, value_t, hasher_t, equator_t, allocator_t >::operator= ( dictionary< key_t, value_t, hasher_t, equator_t, allocator_t > && other ) -> dictionary &

inlinenoexcept

Move 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/6]

template<class key_t, class value_t, class hasher_t = xtd::collections::generic::helpers::hasher<key_t>, class equator_t = xtd::collections::generic::helpers::equator<key_t>, class allocator_t = xtd::collections::generic::helpers::allocator<std::pair<const key_t, value_t >>>

auto xtd::collections::generic::dictionary< key_t, value_t, hasher_t, equator_t, allocator_t >::operator= ( std::unordered_map< key_t, value_t > && other ) -> dictionary &

inlinenoexcept

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

template<class key_t, class value_t, class hasher_t = xtd::collections::generic::helpers::hasher<key_t>, class equator_t = xtd::collections::generic::helpers::equator<key_t>, class allocator_t = xtd::collections::generic::helpers::allocator<std::pair<const key_t, value_t >>>

auto xtd::collections::generic::dictionary< key_t, value_t, hasher_t, equator_t, allocator_t >::operator= ( const dictionary< key_t, value_t, hasher_t, equator_t, allocator_t > & other ) -> dictionary &=default

defaultnoexcept

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=() [4/6]

template<class key_t, class value_t, class hasher_t = xtd::collections::generic::helpers::hasher<key_t>, class equator_t = xtd::collections::generic::helpers::equator<key_t>, class allocator_t = xtd::collections::generic::helpers::allocator<std::pair<const key_t, value_t >>>

auto xtd::collections::generic::dictionary< key_t, value_t, hasher_t, equator_t, allocator_t >::operator= ( const std::unordered_map< key_t, value_t > & other ) -> dictionary &

inlinenoexcept

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=() [5/6]

template<class key_t, class value_t, class hasher_t = xtd::collections::generic::helpers::hasher<key_t>, class equator_t = xtd::collections::generic::helpers::equator<key_t>, class allocator_t = xtd::collections::generic::helpers::allocator<std::pair<const key_t, value_t >>>

auto xtd::collections::generic::dictionary< key_t, value_t, hasher_t, equator_t, allocator_t >::operator= ( std::initializer_list< base_value_type > ilist ) -> dictionary &

inline

Copy assignment operator. Replaces the contents with a copy of the contents of other.

Parameters

ilist

The initializer list to use as data source.

Returns

This current instance.

operator=() [6/6]

template<class key_t, class value_t, class hasher_t = xtd::collections::generic::helpers::hasher<key_t>, class equator_t = xtd::collections::generic::helpers::equator<key_t>, class allocator_t = xtd::collections::generic::helpers::allocator<std::pair<const key_t, value_t >>>

template<class init_key_t, class init_value_t>

auto xtd::collections::generic::dictionary< key_t, value_t, hasher_t, equator_t, allocator_t >::operator= ( std::initializer_list< key_value_pair< init_key_t, init_value_t > > ilist ) -> dictionary &

inline

Copy assignment operator. Replaces the contents with a copy of the contents of other.

Parameters

ilist

The initializer list to use as data source.

Returns

This current instance.

operator[]() [1/2]

template<class key_t, class value_t, class hasher_t = xtd::collections::generic::helpers::hasher<key_t>, class equator_t = xtd::collections::generic::helpers::equator<key_t>, class allocator_t = xtd::collections::generic::helpers::allocator<std::pair<const key_t, value_t >>>

const value_t & xtd::collections::generic::dictionary< key_t, value_t, hasher_t, equator_t, allocator_t >::operator[] ( const key_t & key ) const

inlinenodiscardoverride

Gets the element with the specified key.

Parameters

key	The key of the element to get.

Returns

The element with the specified key.

Exceptions

xtd::collections::generic::key_not_found_exception	The property is retrieved and key is not found.
xtd::not_supported_exception	The property is set and the xtd::collections::generic::dictionary <key_t, value_t> is read-only.

Remarks

This property provides the ability to access a specific element in the collection by using the following syntax: my_collection[key].

You can also use the operator [] to add new elements by setting the value of a key that does not exist in the dictionary; for example, my_collection["my_nonexistent_key"] = my_value. However, if the specified key already exists in the dictionary, setting the operator [] overwrites the old value. In contrast, the xtd::collections::generic::dictionary::add method does not modify existing elements.

operator[]() [2/2]

template<class key_t, class value_t, class hasher_t = xtd::collections::generic::helpers::hasher<key_t>, class equator_t = xtd::collections::generic::helpers::equator<key_t>, class allocator_t = xtd::collections::generic::helpers::allocator<std::pair<const key_t, value_t >>>

value_t & xtd::collections::generic::dictionary< key_t, value_t, hasher_t, equator_t, allocator_t >::operator[] ( const key_t & key )

inlinenodiscardoverridevirtual

Sets the element with the specified key.

Parameters

key	The key of the element to set.

Returns

The element with the specified key.

Exceptions

xtd::not_supported_exception

The property is set and the xtd::collections::generic::dictionary <key_t, value_t> is read-only.

Remarks

This property provides the ability to access a specific element in the collection by using the following syntax: my_collection[key].

You can also use the operator [] to add new elements by setting the value of a key that does not exist in the dictionary; for example, my_collection["my_nonexistent_key"] = my_value. However, if the specified key already exists in the dictionary, setting the operator [] overwrites the old value. In contrast, the xtd::collections::generic::dictionary::add method does not modify existing elements.

Implements xtd::collections::generic::idictionary< key_t, value_t >.

operator const base_type &()

template<class key_t, class value_t, class hasher_t = xtd::collections::generic::helpers::hasher<key_t>, class equator_t = xtd::collections::generic::helpers::equator<key_t>, class allocator_t = xtd::collections::generic::helpers::allocator<std::pair<const key_t, value_t >>>

xtd::collections::generic::dictionary< key_t, value_t, hasher_t, equator_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<class key_t, class value_t, class hasher_t = xtd::collections::generic::helpers::hasher<key_t>, class equator_t = xtd::collections::generic::helpers::equator<key_t>, class allocator_t = xtd::collections::generic::helpers::allocator<std::pair<const key_t, value_t >>>

xtd::collections::generic::dictionary< key_t, value_t, hasher_t, equator_t, allocator_t >::operator base_type & ( )

inlinenoexcept

Returns a reference to the underlying base type.

Returns

Reference to the underlying base type.

operator std::unordered_map< key_t, value_t >()

template<class key_t, class value_t, class hasher_t = xtd::collections::generic::helpers::hasher<key_t>, class equator_t = xtd::collections::generic::helpers::equator<key_t>, class allocator_t = xtd::collections::generic::helpers::allocator<std::pair<const key_t, value_t >>>

xtd::collections::generic::dictionary< key_t, value_t, hasher_t, equator_t, allocator_t >::operator std::unordered_map< key_t, value_t > ( ) const

inlinenoexcept

Gets a std::unordered_map<key_t, value_t>.

Returns

A std::unordered_map<key_t, value_t>.

---

The documentation for this class was generated from the following file:

• xtd.core/include/xtd/collections/generic/dictionary.hpp