* 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 {
/**
* 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);
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);
}