diff options
author | Maciej Piechotka <uzytkownik2@gmail.com> | 2014-09-13 14:25:29 +0200 |
---|---|---|
committer | Maciej Piechotka <uzytkownik2@gmail.com> | 2014-09-13 14:26:01 +0200 |
commit | b12c25fac688138779477c7ff010d7cbb72c6516 (patch) | |
tree | 288d3631a27dd5e7bdb142395b057fcf212e85ee | |
parent | ba9894127c4f18955f7d080da71a5a7500c92889 (diff) | |
download | libgee-b12c25fac688138779477c7ff010d7cbb72c6516.tar.gz |
Explicitly make the hashes, equality and comparation immutable
-rw-r--r-- | gee/comparable.vala | 12 | ||||
-rw-r--r-- | gee/hashable.vala | 21 | ||||
-rw-r--r-- | gee/hashset.vala | 33 |
3 files changed, 63 insertions, 3 deletions
diff --git a/gee/comparable.vala b/gee/comparable.vala index 9639483..6ee158e 100644 --- a/gee/comparable.vala +++ b/gee/comparable.vala @@ -24,6 +24,18 @@ * This interface defines a total ordering among instances of each class * implementing it. * + * In other words: + * + * * It's irreflexive: For all `a` it holds that `a.compare_to(a) == 0` + * * It's transitive: For all `a`, `b` and `c` if `a.compare_to(b) < 0` and + * `b.compare_to(c) < 0` then `a.compare_to(c) < 0`. + * * It's trichotomous: For all `a` and `b` it holds that + * `a.compare_to(b) = -b.compare_to(a)`. + * + * Note: The relationship must be immutable. In other words if at one point of + * program `a.compare_to(b)` had certain value then call `a.compare_to(b)` + * //must always// return the original value until end of `a` and `b` lifetime. + * * @see Hashable */ public interface Gee.Comparable<G> : Object { diff --git a/gee/hashable.vala b/gee/hashable.vala index 8a2c785..dd5f3c0 100644 --- a/gee/hashable.vala +++ b/gee/hashable.vala @@ -23,21 +23,36 @@ /** * This interface defines a hash function amongs instances of each class * implementing it. - * + * * @see Comparable */ public interface Gee.Hashable<G> : Object { /** * Computes hash for an objects. Two hashes of equal objects have to be - * equal. Hash have to not change during lifetime of object. + * equal. + * + * Note: Hash //must not// change during lifetime of an object. * * @return hash of an object */ public abstract uint hash (); /** - * Compares this object with the specifed object. + * Compares this object with the specifed object. This defines the + * equivalence relation between them. + * + * In other words: + * + * * It must be reflexive: for all objects `a` it holds that + * `a.equal_to(a)`. + * * It must be symmetric: for all objects `a` and `b` if + * `a.equal_to(b)` then `b.equal_to(a)`. + * * It must be transitive: if `a.equal_to(b)` and `b.equal_to(c)` then + * `a.equal_to(c)`. + * + * Note: Relationship //must not// change during lifetime of an object. * + * @param object Object this objest is compared with * @return true if objects are equal */ public abstract bool equal_to (G object); diff --git a/gee/hashset.vala b/gee/hashset.vala index 2736554..959d592 100644 --- a/gee/hashset.vala +++ b/gee/hashset.vala @@ -26,7 +26,40 @@ using GLib; namespace Gee { + /** + * A function producing a hash for an object. Two hashes of equal + * objects (as specified by corresponding {@link EqualDataFunc}) have to + * be equal. + * + * Note: Hash for a given object //must not// change during the lifetime + * of delegate. + * + * @param v Hashed value + * @return Hash for given value + * + * @see Hashable + */ public delegate uint HashDataFunc<T> (T v); + /** + * A function comparing two object defining equivalence relationship. + * + * In other words if `equal_to` is `EqualDataFunc` then: + * + * * It must be reflexive: for all objects `a` it holds that + * `equal_to(a, a)`. + * * It must be symmetric: for all objects `a` and `b` if + * `equal_to(a, b)` then `equal_to(b, a)`. + * * It must be transitive: if `equal_to(a, b)` and `equal_to(b, c)` + * then `equal_to(a, c)` + * + * Note: The relationship //must not// change during lifetime of the + * delegate. + * + * @param v Hashed value + * @return Hash for given value + * + * @see Hashable + */ public delegate bool EqualDataFunc<T> (T a, T b); } |