Oracle Coherence for C++ API
Release 3.6.0.0

E15728-01

Comparator Class Reference

#include <coherence/util/Comparator.hpp>

Inherits Object.

Inherited by ChainedComparator [virtual], EntryAwareComparator [virtual], QueryMapComparator [virtual], and SafeComparator [virtual].

List of all members.


Detailed Description

The Comparator defines a partial order on the collection of Objects.

Such ordering is required, for example, for tree-based collections like HashMap or TreeSet. As there are no "natural" ordering defined for Objects, the tree-based collections require some Comparator at creation time, and further can contain only Objects that are comparable with that Comparator.

The implementations of the Comparator shall take care to keep "less-than" and "equals" relations impiled by them to satisfy the natural rules for the corresponding mathematical relations. See the comments for method compare(Object::View v1, Object::View v2) for more details.

Public Types

typedef spec::Handle Handle
 Comparator Handle definition.
typedef spec::View View
 Comparator View definition.
typedef spec::Holder Holder
 Comparator Holder definition.

Public Member Functions

virtual int32_t compare (Object::View v1, Object::View v2) const =0
 Compare two Objects.


Member Function Documentation

virtual int32_t compare ( Object::View  v1,
Object::View  v2 
) const [pure virtual]

Compare two Objects.

If both Objects are comparable with this Comparator, return < 0, 0 or > 0 if the first Object is less than, equal to, or greater than the second Object.

The general contract for this method is:

  1. If either of two handles are NULL, a coherence::lang::NullPointerException shall be thrown;
  2. If either of two Objects are not comparable with this Comparator, a coherence::lang::IllegalArgumentException shall be thrown;
  3. It shall be consistent with the Object::equals() relation, i.e. compare(v1, v2) == 0 if and only if Object::equals(v1, v2) == true
  4. The subsequent calls to this method shall return the same value until either of arguments changed
  5. It shall be anti-symmetric, i.e. compare(v1, v2) == -compare(v2, v1)

A typical implementation of Comparator may look as follows:

 int32_t MyTypeComparator::compare(Object::View v1,
                                   Object::View v2) const
     {
     // compares instances of class MyType only
     if (!v1 || !v2)
         {
         COH_THROW(NullPointerException());
         }
     MyType::View vTypedObj1 = cast<MyType::View>(v1);
     MyType::View vTypedObj2 = cast<MyType::View>(v2);
     if (!vTypedObj1 || !vTypedObj1)
         {
         COH_THROW(IllegalArgumentException("Instances of MyType expected"));
         }
     // here we suppose that the state of the MyType is defined by
     // single field of integer type
     if (vTypedObj1->m_intField == vTypedObj2->m_intField)
         {
         return 0;
         }
     else if (vTypedObj1->m_intField < vTypedObj2->m_intField)
         {
         return -1;
         }
     else
         {
         return 1;
         }
     }
 

Implemented in ChainedComparator, EntryComparator, InverseComparator, SafeComparator, and AbstractExtractor.


The documentation for this class was generated from the following file:
Copyright © 2000, 2010, Oracle and/or its affiliates. All rights reserved.