New and Noteworthy in 0.5

Here are some of the more noteworthy things about release 0.5 of libgee (September 28, 2009) which is now available for download. See the git-generated ChangeLog for details about bugs fixed and other changes.

Libgee 0.5 introduces lots of API changes and thus a migration guide is provided.

API changes

• Introduction of a Functions factory:

  • Functions.get_hash_function_for (Type t) returns a hash function for type t.

  • Functions.get_equal_function_for (Type t) returns a equal function for type t.

  • Functions.get_compare_function_for (Type t) returns a compare function for type t.

• Introduction of the Comparable<G> interface:

  • Comparable<G>.compare_to (G comparable) defines an natural ordering for instance of the G class.

  • Functions.get_compare_function_for (Type t) returns a dedicated compare function for types inheriting from Comparable.

• All implementations now provides sane defaults when constructed without any function arguments, using Functions.

• ReadOnly* implementations made internal in favor of a read_only_view properties on Collection, List, Set and Map. Those are guaranteed to always return the same instance, if existing, using weak references. (Thanks to Tomaž Vajngerl and Julien Peters)

• Iterator<G> is now mutable and resettable:

  • Iterator<G>.remove () removes the current element in the iteration.

  • Iterator<G>.first () rewinds the iterator to the first element in the iteration.

  • Iterator<G>.has_next () tests whether a next element exists in the iteration without actually moving.

• Introduction of BidirIterator<G> bidirectional iterators:

  • All the methods of Iterator<G>.

  • BidirIterator<G>.last () advances the iterator to the last element in the iteration.

  • BidirIterator<G>.previous () rewinds to the previous element in the iteration if it exists.

  • BidirIterator<G>.has_previous () tests whether a previous element exists in the iteration without actually moving.

• List<G>.list_iterator () returns a specialized ListIterator<G>:

  • All the methods of BidirIterator<G>

  • ListIterator<G>.index () returns the current index in the iteration.

  • ListIterator<G>.set (G element) replaces the current element in the iteration.

  • ListIterator<G>.insert (G element) insert the specified element before the current element in the iteration.

  • ListIterator<G>.add (G element) insert the specified element after the current element in the iteration.

• Contracts clarifications and enhancements:

  • List<G>.get () is now undefined if list is empty.

  • List<G>.remove_all (coll) and List<G>.retain_all (coll) now removes and retains the exact occurrences of elements in coll.

  • List<G>.remove_at (index) now returns the the removed element.

  • List<G>.first () and List<G>.last () are now undefined if list is empty.

• New List<G> API:

  • List<G>.sort (CompareFunc? compare = null) sorts the collection. This uses TimSort.

• Map API rework:

  • Method renaming (old versions made deprecated):

    • Map<K,V>.remove (key) becomes Map<K,V>.unset (key)

    • Map<K,V>.remove_all (map) becomes Map<K,V>.unset_all (map)

    • Map<K,V>.contains (key) becomes Map<K,V>.has_key (key)

    • Map<K,V>.contains_all (key) becomes Map<K,V>.has_all (map)

  • get_keys () and get_values () methods transformed into properties. Those are guaranteed to always return the same instances, if existing, using weak references.

    • Map<K,V>.get_keys () becomes Map<K,V>.keys

    • Map<K,V>.get_values () becomes Map<K,V>.values

  • Contract changes:

    • Map<K,V>.has_all (map) now checks for Map.has (key, value) for every (key,value) entries in map. (instead of Map.has_key (key))

  • New members:

    • Map<K,V>.has (key, value) checks for the presence of such entry in the map

    • Map.Entry<K,V> represents a map entry

    • Map<K,V>.entries is the set of entries. This is guaranteed to always return the same instance, if existing, using weak references.

  • Map<K,V> now derives from Iterable<Map.Entry<K,V>>.

    • Note that the iterator returned by Map<K,V>.iterator () is mutable.

  • Map<K,V>.map_iterator () returns a specialized mutable MapIterator<K,V>:

    • MapIterator<K,V>.next () advances to the next entry in the iteration if it exists.

    • MapIterator<K,V>.has_next () tests whether a next entry exists in the iteration without actually moving.

    • MapIterator<K,V>.first () rewinds the iterator to the first entry in the iteration if it exists.

    • MapIterator<K,V>.get_key () returns the key of the current entry in the iteration.

    • MapIterator<K,V>.get_value () returns the value of the current entry in the iteration.

    • MapIterator<K,V>.set_value (V value) sets the value of the current entry in the iteration.

    • MapIterator<K,V>.unset () unsets the current entry in the iteration.

• New Queue and Deque interfaces, that provides LIFO of FIFO (aka stack) queue and double-ended queue services and features optional capacity bound.

• New MultiSet and MultiMap interfaces, that provides multi-set (aka bags) and multi-map services. (Code donation from libcore thanks to Ali Sabil)

• New SortedSet interface, which you can navigate over and get sub-sets of. (Thanks to Maciej Piechotka)

New implementations

• HashMultiSet and HashMultiMap. (Code donation from libcore thanks to Ali Sabil)

• TreeMultiSet, and TreeMultiMap.

• PriorityQueue.

• LinkedList now implements Deque.

• TreeSet now implements SortedSet. (Thanks to Maciej Piechotka)

Infrastructure

• New test framework and complete tests refactoring (Thanks to Julien Peters)

• New doc/ documentation directory. The documentation is generated in place when configured with --enable-doc.

• Test coverage analysis using gcov/lcov. The coverage report is generated in place when configured with --enable-coverage.

• Basic benchmark framework and sort algorithms benchmark. Triggered when configured with --enable-benchmark.

• Use silent rules by default for users of automake 1.11. (Backward compatibility is ensured for now but gee-1.0 may force automake 1.11)

Code Quality

• Many bug fixes.
• Many optimizations.

• Lots of additional documentation. (c.f. gee-1.0 on valadoc.org)

• Better overall encapsulation. Dangerous public setters have been removed.

• Better test coverage. More than 90% of gee's code is covered by tests now, and some more is not reported by lcov (c.f. above) due to failure to collect data for fork child processes (which are used in the GTest framework by Trap.fork ()).