C++ Client API Reference for Oracle Coherence
14c (14.1.2.0.0)

F79659-03

coherence/util/Comparator.hpp

00001 /*
00002  * Copyright (c) 2000, 2020, Oracle and/or its affiliates.
00003  *
00004  * Licensed under the Universal Permissive License v 1.0 as shown at
00005  * http://oss.oracle.com/licenses/upl.
00006  */
00007 #ifndef COH_COMPARATOR_HPP
00008 #define COH_COMPARATOR_HPP
00009 
00010 #include "coherence/lang.ns"
00011 
00012 COH_OPEN_NAMESPACE2(coherence,util)
00013 
00014 
00015 /**
00016 * The Comparator defines a partial order on the collection of Objects.
00017 *
00018 * Such ordering is required, for example, for tree-based collections like
00019 * HashMap or TreeSet. As there are no "natural" ordering defined for Objects,
00020 * the tree-based collections require some Comparator at creation time, and
00021 * further can contain only Objects that are comparable with that Comparator.
00022 *
00023 * The implementations of the Comparator shall take care to keep "less-than"
00024 * and "equals" relations impiled by them to satisfy the natural rules for
00025 * the corresponding mathematical relations. See the comments for method
00026 * {@link Comparator::compare compare(Object::View v1, Object::View v2)}
00027 * for more details.
00028 */
00029 class COH_EXPORT Comparator
00030     : public interface_spec<Comparator>
00031     {
00032     // ----- Comparator interface -------------------------------------------
00033 
00034     public:
00035         /**
00036         * Compare two {@link coherence::lang::Object Objects}. If both
00037         * Objects are comparable with this
00038         * Comparator, return < 0, 0 or > 0 if the first Object is less than,
00039         * equal to, or greater than the second Object.
00040         *
00041         * The general contract for this method is:
00042         * <ol>
00043         * <li> If either of two handles are <tt>NULL</tt>, a
00044         *      coherence::lang::NullPointerException shall be thrown;
00045         * </li>
00046         * <li> If either of two Objects are not comparable with this
00047         *      Comparator, a coherence::lang::IllegalArgumentException
00048         *      shall be thrown;
00049         * </li>
00050         * <li> It shall be consistent with the {@link
00051         *      coherence::lang::Object::equals() Object::equals()}
00052         *      relation, i.e. <code>compare(v1, v2) == 0</code> if and only
00053         *      if <code>Object::equals(v1, v2) == true</code>
00054         * </li>
00055         * <li> The subsequent calls to this method shall return the same
00056         *      value until either of arguments changed</li>
00057         * </li>
00058         * <li> It shall be <i>anti-symmetric</i>, i.e.
00059         *      <code>compare(v1, v2) == -compare(v2, v1)</code>
00060         * </li>
00061         * </ol>
00062         *
00063         * A typical implementation of Comparator may look as follows:
00064         * <pre>
00065         * int32_t MyTypeComparator::compare(Object::View v1,
00066         *                                   Object::View v2) const
00067         *     {
00068         *     // compares instances of class MyType only
00069         *     if (!v1 || !v2)
00070         *         {
00071         *         COH_THROW(NullPointerException());
00072         *         }
00073         *     MyType::View vTypedObj1 = cast<MyType::View>(v1);
00074         *     MyType::View vTypedObj2 = cast<MyType::View>(v2);
00075         *     if (!vTypedObj1 || !vTypedObj1)
00076         *         {
00077         *         COH_THROW(IllegalArgumentException("Instances of MyType expected"));
00078         *         }
00079         *     // here we suppose that the state of the MyType is defined by
00080         *     // single field of integer type
00081         *     if (vTypedObj1->m_intField == vTypedObj2->m_intField)
00082         *         {
00083         *         return 0;
00084         *         }
00085         *     else if (vTypedObj1->m_intField < vTypedObj2->m_intField)
00086         *         {
00087         *         return -1;
00088         *         }
00089         *     else
00090         *         {
00091         *         return 1;
00092         *         }
00093         *     }
00094         * </pre>
00095         */
00096         virtual int32_t compare(Object::View v1, Object::View v2) const = 0;
00097     };
00098 
00099 COH_CLOSE_NAMESPACE2
00100 
00101 #endif // COH_COMPARATOR_HPP
Copyright © 2000, 2025, Oracle and/or its affiliates. Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl.