Add generic_dictionary example

Author: gammasoft71

examples/xtd.core.examples/README.md

@@ -197,6 +197,7 @@
 
 ## [generic_Collections](generic_Collections/README.md)
 
+* [generic_dictionary](generic_Collections/generic_dictionary/README.md) shows how to use [xtd::collections::generic::dictionary](https://gammasoft71.github.io/xtd/reference_guides/latest/classxtd_1_1collections_1_1generic_1_1dictionary.html) class.
 * [generic_icollection](generic_Collections/generic_icollection/README.md) shows how to use [xtd::collections::generic::icollection](https://gammasoft71.github.io/xtd/reference_guides/latest/classxtd_1_1collections_1_1generic_1_1icollection.html) interface.
 * [generic_ienumerable](generic_Collections/generic_ienumerable/README.md) shows how to use [xtd::collections::generic::ienumerable](https://gammasoft71.github.io/xtd/reference_guides/latest/classxtd_1_1collections_1_1generic_1_1ienumerable.html) interface.
 * [generic_ienumerable2](generic_Collections/generic_ienumerable2/README.md) shows how to use [xtd::collections::generic::ienumerable](https://gammasoft71.github.io/xtd/reference_guides/latest/classxtd_1_1collections_1_1generic_1_1ienumerable.html) interface.

examples/xtd.core.examples/generic_collections/CMakeLists.txt

@@ -4,6 +4,7 @@ project(generic_collections)
 find_package(xtd REQUIRED)
 
 add_projects(
+  generic_dictionary
   generic_icollection
   generic_ienumerable
   generic_ienumerable2

examples/xtd.core.examples/generic_collections/README.md

@@ -2,6 +2,7 @@
 
 [This folder](.) contains collections examples used by [Reference Guide](https://gammasoft71.github.io/xtd/reference_guides/latest/) and more.
 
+* [generic_dictionary](generic_dictionary/README.md) shows how to use [xtd::collections::generic::dictionary](https://gammasoft71.github.io/xtd/reference_guides/latest/classxtd_1_1collections_1_1generic_1_1dictionary.html) class.
 * [generic_icollection](generic_icollection/README.md) shows how to use [xtd::collections::generic::icollection](https://gammasoft71.github.io/xtd/reference_guides/latest/classxtd_1_1collections_1_1generic_1_1icollection.html) interface.
 * [generic_ienumerable](generic_ienumerable/README.md) shows how to use [xtd::collections::generic::ienumerable](https://gammasoft71.github.io/xtd/reference_guides/latest/classxtd_1_1collections_1_1generic_1_1ienumerable.html) interface.
 * [generic_ienumerable2](generic_ienumerable2/README.md) shows how to use [xtd::collections::generic::ienumerable](https://gammasoft71.github.io/xtd/reference_guides/latest/classxtd_1_1collections_1_1generic_1_1ienumerable.html) interface.

examples/xtd.core.examples/generic_collections/generic_dictionary/CMakeLists.txt

@@ -0,0 +1,6 @@
+cmake_minimum_required(VERSION 3.20)
+
+project(generic_dictionary)
+find_package(xtd REQUIRED)
+add_sources(README.md src/generic_dictionary.cpp)
+target_type(CONSOLE_APPLICATION)

examples/xtd.core.examples/generic_collections/generic_dictionary/README.md

@@ -0,0 +1,52 @@
+# generic_dictionary
+
+Shows how to use [xtd::collections::generic::dictionary](https://gammasoft71.github.io/xtd/reference_guides/latest/classxtd_1_1collections_1_1generic_1_1dictionary.html) class.
+
+## Sources
+
+[src/generic_dictionary.cpp](src/generic_dictionary.cpp)
+
+[CMakeLists.txt](CMakeLists.txt)
+
+## Build and run
+
+Open "Command Prompt" or "Terminal". Navigate to the folder that contains the project and type the following:
+
+```cmake
+xtdc run
+```
+
+## 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.
+```

examples/xtd.core.examples/generic_collections/generic_dictionary/src/generic_dictionary.cpp

@@ -0,0 +1,130 @@
+#include <xtd/xtd>
+
+using namespace xtd;
+using namespace xtd::collections::generic;
+
+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 Item property is another name for the indexer, so you
+    // can omit its name when accessing elements.
+    console::write_line("For key = \"rtf\", value = {0}.", xtd::as_const(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}.", xtd::as_const(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}.", xtd::as_const(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, TryGetValue 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.");
+    
+    // ContainsKey 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}", xtd::as_const(open_with)["ht"]);
+    }
+    
+    // When you use foreach to enumerate dictionary elements,
+    // the elements are retrieved as KeyValuePair 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 ValueCollection are strongly typed
+    // with the type that was specified for dictionary values.
+    console::write_line();
+    for(const string& 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 KeyCollection 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.

src/xtd.core/CMakeLists.txt

@@ -44,6 +44,8 @@ add_sources(
   include/xtd/array_abstract_object.hpp
   include/xtd/as.hpp
   include/xtd/as
+  include/xtd/as_const.hpp
+  include/xtd/as_const
   include/xtd/async_callback.hpp
   include/xtd/async_callback
   include/xtd/async_result.hpp

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

@@ -56,10 +56,17 @@ namespace xtd {
       /// @par Library
       /// xtd.core
       /// @ingroup xtd_core generic_collections
-      /// @remarks The xtd::collections::generic::dictionary class is same as [std::unordered_map](https://en.cppreference.com/w/cpp/container/unordered_map).
       /// @par Examples
-      /// The following shows how to use xtd::collections::generic::dictionary.
-      /// @include dictionary.cpp
+      /// 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 generic_dictionary.cpp
       /// @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.
@@ -1542,7 +1549,9 @@ namespace xtd {
         /// @exception 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]`.
         /// @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.
-        value_t& operator [](const key_t& key) override {return data_->items[key];}
+        value_t& operator [](const key_t& key) override {
+          ++data_->version;
+          return data_->items[key];}
 
         /// @brief Returns a reference to the underlying base type.
         /// @return Reference to the underlying base type.