docs: add libgee collection samples (#71)

* docs: add vala collections libgee

* correct equality function name; remove iterable

* remove iterable.vala

Author: JuanGarcia1177

source/developer-guides/documentation/vala-for-csharp-devs/33-collections.rst

@@ -29,7 +29,7 @@ IList                      List
                            Deque
 ========================== ===
 
-See `Gee Examples <https://wiki.gnome.org/Projects/Vala/GeeSamples>`_
+See :doc:`Gee Examples </developer-guides/gee-samples>`
 
 You can access and assign Gee collection items via indexers (e.g.
 ``my_map[key]`` is equivalent to ``my_map.get (key)``). Vala supports an ``in``

source/developer-guides/gee-samples.rst

@@ -0,0 +1,14 @@
+Vala Collections: libgee
+========================
+
+You should install the Vala collection library, libgee, from your distribution.
+More information about libgee is available from
+`https://wiki.gnome.org/Projects/Libgee <https://wiki.gnome.org/Projects/Libgee>`_
+
+`Gee API Documentation <https://valadoc.org/gee-0.8/index.htm>`_
+
+.. toctree::
+   :glob:
+   :maxdepth: 1
+
+   gee-samples/*

source/developer-guides/gee-samples/01-list-sample.rst

@@ -0,0 +1,36 @@
+List Sample
+===========
+
+A dynamic length `ArrayList <https://valadoc.org/gee-0.8/Gee.ArrayList.html>`_
+
+.. code-block:: vala
+
+   using Gee;
+
+   void main () {
+       var list = new ArrayList<int> ();
+       list.add (1);
+       list.add (2);
+       list.add (5);
+       list.add (4);
+       list.insert (2, 3);
+       list.remove_at (3);
+       foreach (int i in list) {
+           stdout.printf ("%d\n", i);
+       }
+       list[2] = 10;                       // same as list.set (2, 10)
+       stdout.printf ("%d\n", list[2]);    // same as list.get (2)
+   }
+
+Compile and Run
+---------------
+
+.. code-block:: bash
+
+   $ valac --pkg gee-0.8 gee-list.vala
+   $ ./gee-list
+
+You can use any type fitting into the size of a pointer (e.g. int, bool,
+reference types) directly as generic type argument: ``bool``, ``int``, ``string``,
+``MyObject``. Other types must be "boxed" by appending a question mark: ``float?``,
+``double?``, ``MyStruct?``. The compiler will tell you this if necessary.

source/developer-guides/gee-samples/02-set-sample.rst

@@ -0,0 +1,28 @@
+Set Sample
+==========
+
+`Sets <https://valadoc.org/gee-0.8/Gee.HashSet.html>`_ are unordered and do not
+contain duplicate elements.
+
+.. code-block:: vala
+
+   using Gee;
+
+   void main () {
+       var my_set = new HashSet<string> ();
+       my_set.add ("one");
+       my_set.add ("two");
+       my_set.add ("three");
+       my_set.add ("two");         // will not be added because it's a duplicate
+       foreach (string s in my_set) {
+           stdout.printf ("%s\n", s);
+       }
+   }
+
+Compile and Run
+---------------
+
+.. code-block:: bash
+
+   $ valac --pkg gee-0.8 gee-set.vala
+   $ ./gee-set

source/developer-guides/gee-samples/03-map-sample.rst

@@ -0,0 +1,57 @@
+Map Example
+===========
+
+`Maps <https://valadoc.org/gee-0.8/Gee.HashMap.html>`_ work like a dictionary.
+They store key - value pairs.
+
+.. code-block:: vala
+
+   using Gee;
+
+   void main () {
+
+       var map = new HashMap<string, int> ();
+
+       // Setting values
+       map.set ("one", 1);
+       map.set ("two", 2);
+       map.set ("three", 3);
+       map["four"] = 4;            // same as map.set ("four", 4)
+       map["five"] = 5;
+
+       // Getting values
+       int a = map.get ("four");
+       int b = map["four"];        // same as map.get ("four")
+       assert (a == b);
+
+       // Iteration
+
+       stdout.printf ("Iterating over entries\n");
+       foreach (var entry in map.entries) {
+           stdout.printf ("%s => %d\n", entry.key, entry.value);
+       }
+
+       stdout.printf ("Iterating over keys only\n");
+       foreach (string key in map.keys) {
+           stdout.printf ("%s\n", key);
+       }
+
+       stdout.printf ("Iterating over values only\n");
+       foreach (int value in map.values) {
+           stdout.printf ("%d\n", value);
+       }
+
+       stdout.printf ("Iterating via 'for' statement\n");
+       var it = map.map_iterator ();
+       for (var has_next = it.next (); has_next; has_next = it.next ()) {
+           stdout.printf ("%d\n", it.get_value ());
+       }
+   }
+
+Compile and Run
+---------------
+
+.. code-block:: bash
+
+   $ valac --pkg gee-0.8 gee-map.vala
+   $ ./gee-map

source/developer-guides/gee-samples/04-syntactic-sugar.rst

@@ -0,0 +1,10 @@
+Syntactic Sugar
+===============
+
+There's syntactic sugar for testing if a collection contains an element:
+
+.. code-block:: vala
+
+   if ("three" in my_set) {    // same as my_set.contains ("three")
+       stdout.printf ("heureka\n");
+   }

source/developer-guides/gee-samples/05-custom-equality.rst

@@ -0,0 +1,17 @@
+Customizing the equality function
+=================================
+
+`ArrayList <https://valadoc.org/gee-0.8/Gee.ArrayList.html>`_ supports the
+``contains (G item)`` its equality function can be customized by providing an
+implementation of ``EqualDataFunc``.
+
+.. code-block:: vala
+
+   bool same_book (Book a, Book b) {
+       return a.isbn == b.isbn;
+   }
+
+   var books = new Gee.ArrayList<Book> ((EqualDataFunc) same_book);
+
+Other `delegates <https://valadoc.org/gee-0.8/Gee.Functions.html>`_ such as
+``CompareDataFunc`` and ``HashDataFunc`` apply to other Collections.

source/tutorials/programming-language/main/04-00-advanced-features/04-04-collections.rst

@@ -17,7 +17,7 @@ Also common to every *Collection* type is the *Iterable* interface. This means t
 
 All classes and interfaces use the generics system. This means that they must be instantiated with a particular type or set of types that they will contain.  The system will ensure that only the intended types can be put into the collections, and that when objects are retrieved they are returned as the correct type.
 
-`Gee API documentation <http://valadoc.org/gee-0.8/index.htm>`_, `Gee Examples <https://wiki.gnome.org/Projects/Vala/GeeSamples>`_.
+`Gee API documentation <http://valadoc.org/gee-0.8/index.htm>`_, :doc:`Gee Examples </developer-guides/gee-samples>`.
 
 Some important Gee classes are: