From 9ba500a1ea54d4fa73e831dc98d96802d3c94ef3 Mon Sep 17 00:00:00 2001 From: Julien Peeters Date: Sat, 5 Sep 2009 11:21:29 +0200 Subject: [PATCH] Adding a short descriptive introduction for each implementation class. Generally this introduction consists of a implementation description and few word about comparison with other structures. --- gee/abstractcollection.vala | 6 ++++- gee/abstractlist.vala | 7 +++++- gee/abstractmap.vala | 12 +++++++--- gee/arraylist.vala | 18 +++++++++++++-- gee/collection.vala | 3 +-- gee/functions.vala | 8 ++++++- gee/hashmap.vala | 48 +++++++++++++++++++++++++++++++++++++++- gee/hashset.vala | 17 +++++++++++---- gee/iterable.vala | 3 +-- gee/iterator.vala | 3 +-- gee/linkedlist.vala | 11 +++++++--- gee/list.vala | 2 +- gee/map.vala | 2 +- gee/readonlycollection.vala | 13 ++++++++--- gee/readonlylist.vala | 13 ++++++++--- gee/readonlymap.vala | 53 ++++++++++++++++++++++++++++++++++++++++++++- gee/readonlyset.vala | 12 +++++++--- gee/set.vala | 2 +- gee/treemap.vala | 18 +++++++++++---- gee/treeset.vala | 17 ++++++++++++--- 20 files changed, 226 insertions(+), 42 deletions(-) diff --git a/gee/abstractcollection.vala b/gee/abstractcollection.vala index 9a1f412..9ca2988 100644 --- a/gee/abstractcollection.vala +++ b/gee/abstractcollection.vala @@ -22,7 +22,11 @@ */ /** - * Serves as the base class for implementing collection classes. + * Skeletal implementation of the {@link Gee.Collection} interface. + * + * Contains common code shared by all collection implementations. + * + * @see Gee.AbstractList */ public abstract class Gee.AbstractCollection : Object, Iterable, Collection { diff --git a/gee/abstractlist.vala b/gee/abstractlist.vala index 6f4af8b..3e06fd9 100644 --- a/gee/abstractlist.vala +++ b/gee/abstractlist.vala @@ -22,7 +22,12 @@ */ /** - * Serves as the base class for implementing list classes. + * Skeletal implementation of the {@link Gee.List} interface. + * + * Contains common code shared by all list implementations. + * + * @see Gee.ArrayList + * @see Gee.LinkedList */ public abstract class Gee.AbstractList : Gee.AbstractCollection, List { diff --git a/gee/abstractmap.vala b/gee/abstractmap.vala index a0192f5..e276ce4 100644 --- a/gee/abstractmap.vala +++ b/gee/abstractmap.vala @@ -20,9 +20,15 @@ * Author: * Tomaž Vajngerl */ - - /** - * Serves as the base class for implementing map classes. + +/** + * Skeletal implementation of the {@link Gee.Map} interface. + * + * Contains common code shared by all map implementations. + * + * @see Gee.Map + * @see Gee.TreeMap + * @see Gee.HashMap */ public abstract class Gee.AbstractMap : Object, Map { diff --git a/gee/arraylist.vala b/gee/arraylist.vala index 8eae29b..54c777d 100644 --- a/gee/arraylist.vala +++ b/gee/arraylist.vala @@ -25,13 +25,27 @@ using GLib; /** - * Arrays of arbitrary elements which grow automatically as elements are added. + * Resizable array implementation of the {@link Gee.List} interface. + * + * The storage array grows automatically when needed. + * + * This implementation is pretty good for rarely modified data. Because they are + * stored in an array this structure does not fit for highly mutable data. For an + * alternative implementation see {@link Gee.LinkedList}. + * + * @see Gee.LinkedList */ public class Gee.ArrayList : AbstractList { + /** + * @inheritDoc + */ public override int size { get { return _size; } } + /** + * The elements' equality testing function. + */ public EqualFunc equal_func { private set; get; } private G[] _items = new G[4]; @@ -41,7 +55,7 @@ public class Gee.ArrayList : AbstractList { private int _stamp = 0; /** - * Array list implementation constructor. + * Constructs a new, empty array list. * * @param equal_func an optional elements equality testing function. */ diff --git a/gee/collection.vala b/gee/collection.vala index 2dca0ed..7827a86 100644 --- a/gee/collection.vala +++ b/gee/collection.vala @@ -21,8 +21,7 @@ */ /** - * Serves as the base interface for implementing collection classes. Defines - * size, iteration, and modification methods. + * A generic collection of objects. */ public interface Gee.Collection : Iterable { /** diff --git a/gee/functions.vala b/gee/functions.vala index 9303e0d..7ca0c6c 100644 --- a/gee/functions.vala +++ b/gee/functions.vala @@ -24,8 +24,14 @@ using GLib; namespace Gee { + /** + * Helper class for equal, hash and compare functions. + */ public class Functions { + private Functions () { + } + /** * Get a equality testing function for a given type. * @@ -73,7 +79,7 @@ namespace Gee { } /** - * Compares to arbitrary elements together. + * Compares two arbitrary elements together. * * The comparison is done on pointers and not on values behind. * diff --git a/gee/hashmap.vala b/gee/hashmap.vala index 14cdb7b..9d0591f 100644 --- a/gee/hashmap.vala +++ b/gee/hashmap.vala @@ -25,17 +25,35 @@ using GLib; /** - * Hashtable implementation of the Map interface. + * Hash table implementation of the {@link Gee.Map} interface. + * + * This implementation is better fit for highly heterogenous key values. + * In case of high key hashes redundancy or higher amount of data prefer using + * tree implementation like {@link Gee.TreeMap}. + * + * @see Gee.TreeMap */ public class Gee.HashMap : Gee.AbstractMap { + /** + * @inheritDoc + */ public override int size { get { return _nnodes; } } + /** + * The keys' hash function. + */ public HashFunc key_hash_func { private set; get; } + /** + * The keys' equality testing function. + */ public EqualFunc key_equal_func { private set; get; } + /** + * The values' equality testing function. + */ public EqualFunc value_equal_func { private set; get; } private int _array_size; @@ -48,6 +66,13 @@ public class Gee.HashMap : Gee.AbstractMap { private const int MIN_SIZE = 11; private const int MAX_SIZE = 13845163; + /** + * Constructs a new, empty hash map. + * + * @param key_hash_func a key hash function. + * @param key_equal_func a key equality testing function. + * @param value_equal_func a value equallity testing function. + */ public HashMap (HashFunc? key_hash_func = null, EqualFunc? key_equal_func = null, EqualFunc? value_equal_func = null) { if (key_hash_func == null) { key_hash_func = Functions.get_hash_func_for (typeof (K)); @@ -68,10 +93,16 @@ public class Gee.HashMap : Gee.AbstractMap { _nodes = new Node[_array_size]; } + /** + * @inheritDoc + */ public override Set get_keys () { return new KeySet (this); } + /** + * @inheritDoc + */ public override Collection get_values () { return new ValueCollection (this); } @@ -85,11 +116,17 @@ public class Gee.HashMap : Gee.AbstractMap { return node; } + /** + * @inheritDoc + */ public override bool contains (K key) { Node** node = lookup_node (key); return (*node != null); } + /** + * @inheritDoc + */ public override V? get (K key) { Node* node = (*lookup_node (key)); if (node != null) { @@ -99,6 +136,9 @@ public class Gee.HashMap : Gee.AbstractMap { } } + /** + * @inheritDoc + */ public override void set (K key, V value) { Node** node = lookup_node (key); if (*node != null) { @@ -112,6 +152,9 @@ public class Gee.HashMap : Gee.AbstractMap { _stamp++; } + /** + * @inheritDoc + */ public override bool remove (K key, out V? value = null) { Node** node = lookup_node (key); if (*node != null) { @@ -135,6 +178,9 @@ public class Gee.HashMap : Gee.AbstractMap { return false; } + /** + * @inheritDoc + */ public override void clear () { for (int i = 0; i < _array_size; i++) { Node node = (owned) _nodes[i]; diff --git a/gee/hashset.vala b/gee/hashset.vala index 17e07c4..d680c45 100644 --- a/gee/hashset.vala +++ b/gee/hashset.vala @@ -25,20 +25,29 @@ using GLib; /** - * Hashtable implementation of the Set interface. + * Hash table implementation of the {@link Gee.Set} interface. + * + * This implementation is better fit for highly heterogenous values. + * In case of high value hashes redundancy or higher amount of data prefer using + * tree implementation like {@link Gee.TreeSet}. + * + * @see Gee.TreeSet */ public class Gee.HashSet : AbstractCollection, Set { + /** + * @inheritDoc + */ public override int size { get { return _nnodes; } } /** - * Hash function. + * The elements' hash function. */ public HashFunc hash_func { private set; get; } /** - * Equality testing function. + * The elements' equality testing function. */ public EqualFunc equal_func { private set; get; } @@ -53,7 +62,7 @@ public class Gee.HashSet : AbstractCollection, Set { private const int MAX_SIZE = 13845163; /** - * Hash set implementation constructor. + * Constructs a new, empty hash set. * * @param hash_func an optional hash function. * @param equal_func an optional equality testing function. diff --git a/gee/iterable.vala b/gee/iterable.vala index 2726325..a59defe 100644 --- a/gee/iterable.vala +++ b/gee/iterable.vala @@ -23,8 +23,7 @@ using GLib; /** - * Implemented by classes that support a simple iteration over instances of the - * collection. + * An object that can provide an {@link Gee.Iterator}. */ public interface Gee.Iterable : GLib.Object { /** diff --git a/gee/iterator.vala b/gee/iterator.vala index 6642a90..4f05b5c 100644 --- a/gee/iterator.vala +++ b/gee/iterator.vala @@ -21,8 +21,7 @@ */ /** - * Implemented by classes that support a simple iteration over instances of the - * collection. + * An iterator over a collection. */ public interface Gee.Iterator : GLib.Object { /** diff --git a/gee/linkedlist.vala b/gee/linkedlist.vala index c3adc20..6ca470b 100644 --- a/gee/linkedlist.vala +++ b/gee/linkedlist.vala @@ -25,7 +25,12 @@ */ /** - * A Gee.List implementation, using a doubly-linked list. + * Doubly-linked list implementation of the {@link Gee.List} interface. + * + * This implementation is pretty well designed for highly mutable data. When + * indexed access is privileged prefer using {@link Gee.ArrayList}. + * + * @see Gee.ArrayList */ public class Gee.LinkedList : AbstractList { private int _size = 0; @@ -34,12 +39,12 @@ public class Gee.LinkedList : AbstractList { private Node? _tail = null; /** - * Equality testing between elements function. + * The elements' equality testing function. */ public EqualFunc equal_func { private set; get; } /** - * Linked list implementation constructor. + * Constructs a new, empty linked list. * * @param equal_func an optional equality testing function. */ diff --git a/gee/list.vala b/gee/list.vala index 479cf4c..259ea80 100644 --- a/gee/list.vala +++ b/gee/list.vala @@ -21,7 +21,7 @@ */ /** - * Represents a collection of items in a well-defined order. + * An ordered collection. */ public interface Gee.List : Collection { /** diff --git a/gee/map.vala b/gee/map.vala index f4a1983..b3f713a 100644 --- a/gee/map.vala +++ b/gee/map.vala @@ -21,7 +21,7 @@ */ /** - * A map is a generic collection of key/value pairs. + * An object that maps keys to values. */ public interface Gee.Map : GLib.Object { /** diff --git a/gee/readonlycollection.vala b/gee/readonlycollection.vala index c3496e5..8ef8c69 100644 --- a/gee/readonlycollection.vala +++ b/gee/readonlycollection.vala @@ -23,7 +23,13 @@ using GLib; /** - * Represents a read-only collection of items. + * Read-only view for {@link Gee.Collection} collections. + * + * This class decorates any class which implements the {@link Gee.Collection} + * interface by making it read only. Any method which normally modify data will + * throw an error. + * + * @see Gee.Collection */ public class Gee.ReadOnlyCollection : Object, Iterable, Collection { @@ -42,7 +48,7 @@ public class Gee.ReadOnlyCollection : Object, Iterable, Collection { } /** - * Generic collection property. + * The decorated collection. */ public Collection collection { construct { _collection = value; } @@ -51,7 +57,8 @@ public class Gee.ReadOnlyCollection : Object, Iterable, Collection { private Collection _collection; /** - * Read only collection constructor. + * Constructs a read-only collection that mirrors the content of the + * specified collection. * * @param collection the collection to decorate (may be null). */ diff --git a/gee/readonlylist.vala b/gee/readonlylist.vala index fdedc26..23db056 100644 --- a/gee/readonlylist.vala +++ b/gee/readonlylist.vala @@ -23,7 +23,13 @@ using GLib; /** - * Represents a read-only collection of items in a well-defined order. + * Read-only view for {@link Gee.List} collections. + * + * This class decorates any class which implements the {@link Gee.List} + * interface by making it read only. Any method which normally modify data will + * throw an error. + * + * @see Gee.List */ public class Gee.ReadOnlyList : Object, Iterable, Collection, List { @@ -42,7 +48,7 @@ public class Gee.ReadOnlyList : Object, Iterable, Collection, List { } /** - * @inheritDoc + * The decorated list. */ public List list { construct { _list = value; } @@ -51,7 +57,8 @@ public class Gee.ReadOnlyList : Object, Iterable, Collection, List { private List _list; /** - * Read only list implementation constrcutor. + * Constructs a read-only set that mirrors the content of the specified + * list. * * @param list the list to decorate (may be null). */ diff --git a/gee/readonlymap.vala b/gee/readonlymap.vala index e38fb01..d9d7042 100644 --- a/gee/readonlymap.vala +++ b/gee/readonlymap.vala @@ -23,27 +23,51 @@ using GLib; /** - * Represents a read-only collection of key/value pairs. + * Read-only view for {@link Gee.Map} collections. + * + * This class decorates any class which implements the {@link Gee.Map} interface + * by making it read only. Any method which normally modify data will throw an + * error. + * + * @see Gee.Map */ public class Gee.ReadOnlyMap : Object, Map { + + /** + * @inheritDoc + */ public int size { get { return _map.size; } } + /** + * @inheritDoc + */ public bool is_empty { get { return _map.is_empty; } } + /** + * The decorated map. + */ public Map map { construct { _map = value; } } private Map _map; + /** + * Constructs a read-only map that mirrors the content of the specified map. + * + * @param map the map to decorate (may be null). + */ public ReadOnlyMap (Map? map = null) { this.map = map; } + /** + * @inheritDoc + */ public Set get_keys () { if (_map == null) { return new ReadOnlySet (); @@ -52,6 +76,9 @@ public class Gee.ReadOnlyMap : Object, Map { return _map.get_keys (); } + /** + * @inheritDoc + */ public Collection get_values () { if (_map == null) { return new ReadOnlyCollection (); @@ -60,6 +87,9 @@ public class Gee.ReadOnlyMap : Object, Map { return _map.get_values (); } + /** + * @inheritDoc + */ public bool contains (K key) { if (_map == null) { return false; @@ -68,6 +98,9 @@ public class Gee.ReadOnlyMap : Object, Map { return _map.contains (key); } + /** + * @inheritDoc + */ public new V? get (K key) { if (_map == null) { return null; @@ -76,26 +109,44 @@ public class Gee.ReadOnlyMap : Object, Map { return _map.get (key); } + /** + * Unimplemented method (read only map). + */ public new void set (K key, V value) { assert_not_reached (); } + /** + * Unimplemented method (read only map). + */ public bool remove (K key, out V? value = null) { assert_not_reached (); } + /** + * Unimplemented method (read only map). + */ public void clear () { assert_not_reached (); } + /** + * Unimplemented method (read only map). + */ public void set_all (Map map) { assert_not_reached (); } + /** + * Unimplemented method (read only map). + */ public bool remove_all (Map map) { assert_not_reached (); } + /** + * @inheritDoc + */ public bool contains_all (Map map) { if (_map == null) { return false; diff --git a/gee/readonlyset.vala b/gee/readonlyset.vala index 828d0d0..ffe7f60 100644 --- a/gee/readonlyset.vala +++ b/gee/readonlyset.vala @@ -23,7 +23,13 @@ using GLib; /** - * Represents a read-only collection of items without duplicates. + * Read-only view for {@link Gee.Set} collections. + * + * This class decorates any class which implements the {@link Gee.Set} interface + * by making it read only. Any method which normally modify data will throw an + * error. + * + * @see Gee.Set */ public class Gee.ReadOnlySet : Object, Iterable, Collection, Set { @@ -42,7 +48,7 @@ public class Gee.ReadOnlySet : Object, Iterable, Collection, Set { } /** - * @inheritDoc + * The decorated set. */ public new Set set { construct { _set = value; } @@ -51,7 +57,7 @@ public class Gee.ReadOnlySet : Object, Iterable, Collection, Set { private Set _set; /** - * Read only set implementation constructor. + * Constructs a read-only set that mirrors the content of the specified set. * * @param set the set to decorate. */ diff --git a/gee/set.vala b/gee/set.vala index 57b69e3..765db0b 100644 --- a/gee/set.vala +++ b/gee/set.vala @@ -21,7 +21,7 @@ */ /** - * A set is a collection without duplicates. + * A collection without duplicate elements. */ public interface Gee.Set : Collection { } diff --git a/gee/treemap.vala b/gee/treemap.vala index 25111aa..6bbea61 100644 --- a/gee/treemap.vala +++ b/gee/treemap.vala @@ -23,27 +23,37 @@ using GLib; /** - * Left-leaning red-black tree implementation of the Map interface. + * Left-leaning red-black tree implementation of the {@link Gee.Map} interface. + * + * This implementation is especially well designed for large quantity of + * data. The (balanced) tree implementation insure that the set and get + * methods are in logarithmic complexity. + * + * @see Gee.HashMap */ public class Gee.TreeMap : Gee.AbstractMap { + /** + * @inheritDoc + */ public override int size { get { return _size; } } /** - * The keys comparator function. + * The keys' comparator function. */ public CompareFunc key_compare_func { private set; get; } /** - * The values equality testing function. + * The values' equality testing function. */ public EqualFunc value_equal_func { private set; get; } private int _size = 0; /** - * Tree map implementation constructor. + * Constructs a new, empty tree map sorted according to the specified + * comparator function. * * @param key_compare_func an optional key comparator function. * @param value_equal_func an optional values equality testing function. diff --git a/gee/treeset.vala b/gee/treeset.vala index 61537ff..5af2462 100644 --- a/gee/treeset.vala +++ b/gee/treeset.vala @@ -23,22 +23,33 @@ using GLib; /** - * Left-leaning red-black tree implementation of the Set interface. + * Left-leaning red-black tree implementation of the {@link Gee.Set} interface. + * + * This implementation is especially well designed for large quantity of + * data. The (balanced) tree implementation insure that the set and get + * methods are in logarithmic complexity. For a linear implementation see + * {@link Gee.HashSet}. + * + * @see Gee.HashSet */ public class Gee.TreeSet : AbstractCollection, Set { + /** + * @inheritDoc + */ public override int size { get {return _size;} } /** - * The elements comparator function. + * The elements' comparator function. */ public CompareFunc compare_func { private set; get; } private int _size = 0; /** - * Tree set implementation constructor. + * Constructs a new, empty tree set sorted according to the specified + * comparator function. * * @param compare_func an optional elements comparator function. */ -- 2.7.4