// slbRCComp.h -- Comparator helpers for reference counting smart pointer.

// (c) Copyright Schlumberger Technology Corp., unpublished work, created
// 1999. This computer program includes Confidential, Proprietary
// Information and is a Trade Secret of Schlumberger Technology Corp. All
// use, disclosure, and/or reproduction is prohibited unless authorized
// in writing.  All Rights Reserved.

#if !defined(SLB_RCCOMP_H)
#define SLB_RCCOMP_H

#include <functional>                             // for binary_function

namespace slbRefCnt {

// slbRCComp.h declares several helpers to deal with smart pointer
// testing and comparisons as if they were real pointers.
//
// Testing and comparing pointer smart pointers to one another is
// problematic.  A smart pointer (reference couting pointer)
// represents a handle to the actual (dumb) pointer of interest.
// There is no straight-forward way to compare the dumb pointers
// without allowing the clients direct access to the dump pointer and
// bypassing all the features the smart pointer is trying keep intact.
// There are solutions but they usually require constructs that aren't
// natural for pointers.
//
// The facilities defined in this header provide the primitives for
// the smart pointers to be compared in a syntactically natural way
// without allowing heterogeneous comparisons and that won't violate
// the protections the smart pointers provide.
//
// Meyers describes some of these peculiar pointer comparisons in
// Item #28 found in the book "More Effective C++," Scott Meyers,
// Addison-Wesley, 1996.

// Problem: Comparing pointer values of the smart pointers to one
// another is problematic.  A smart pointer (reference couting
// pointer) represents a handle to the actual (dumb) pointer of
// interest.  There is no straight-forward way to compare the dumb
// pointers without allowing the clients direct access to the dump
// pointer and bypassing all the features the smart pointer is trying
// keep intact.

// Solution: Provide a set of comparators, or comparison functors
// (function objects), that perform the appropriate comparisons.
// These comparators are referenced by the RCPtr and GRCPtr classes to
// carryout the pointer comparisons.
//
// An abstract Predicate struct is defined to establish the functor
// interface.  All predicates used by Comparators must be derived from
// this class.  These predicate functors are passed const versions of
// the dumb pointers the smart pointer represents.  The functor
// performs the comparison returning the bool result.  Since const
// versions of the dumb pointers are used, then exposure of the dumb
// pointer is limited.
//
// Two sets of comparators are defined which should handle most of the
// cases.  The first is a shallow comparator which compares the two
// dumb pointer values using ==.  The second is deep comparator which
// compares the objects the dumb pointers reference, testing for
// equivalence.
//
// WARNING: Using the DeepComparator, any complex object being being
// compared to another will have to define either an operator==,
// operator< or both to carry out the comparison.

// template struct Predicate -- abstract functor definition for
// elements of Comparator.
template<class T>
struct Predicate : public std::binary_function<T const *, T const *, bool>
{
public:
    result_type operator()(first_argument_type lhs,
                           second_argument_type rhs) const;
};

template<class T>
struct ShallowEquatesTester : public Predicate<T>
{
public:
    result_type operator()(first_argument_type lhs, second_argument_type rhs)
    const { return lhs == rhs; };
};

template<class T>
struct DeepEquatesTester : public Predicate<T>
{
public:
    result_type operator()(first_argument_type lhs, second_argument_type rhs)
    const { return *lhs == *rhs; };
};

template<class T>
struct ShallowLessTester : public Predicate<T>
{
public:
    result_type operator()(first_argument_type lhs, second_argument_type rhs)
    const { return lhs < rhs; };
};

template<class T>
struct DeepLessTester : public Predicate<T>
{
public:
    result_type operator()(first_argument_type lhs, second_argument_type rhs)
    const { return *lhs < *rhs; };
};

// template struct Comparator -- Aggregation of comparison predicate
// functors
//
// Comparator is a template defining the aggregation of the comparison
// functors (function objects) used by the pointer comparison
// operators ==, !=, <, >, <= and >= in the RCPtr and GRCPtr classes
// (see slbRCPtr.h and slbGRCPtr.h).  The RCPtr and GRCPtr reference
// the specified comparator to access the appropriate predicate
// functor to compare the pointer values these reference counting
// (smart) pointers represent.
//
// Two comparators are predefined.  First is ShallowComparator for
// testing relative equality.  Second is DeepComparator for testing
// relative equivalency of the pointers by calling operator== of the
// object being reference counted.
//
// The DeepComparator is provided since smart pointers can be used as
// "handles" to other "body" objects.  As such, one needs to be able
// to compare their bodies as if there was a direct reference to the
// body while maintaining syntactic integrity without exposing the
// body to the client code.
//
// CONSTRAINTS: When using DeepComparator, the body class (the
// derivation of RCObject) must have the corresponding comparison operator
// defined for that class, operator== and/or operator<.
//
// Clients may define their own comparator by deriving from Comparator
// and specifying derived class when instantiating an RCPtr or GRCPtr
// template.
template<class EquatesTester, class LessTester>
struct Comparator
{
public:
                                                  // Predicates
    EquatesTester Equates;
    LessTester IsLess;
};

// template struct ShallowComparator -- minimal set of comparison
// functors for testing equality.
template<class T>
struct ShallowComparator : public Comparator<ShallowEquatesTester<T>,
                                             ShallowLessTester<T> >
{
};

// template struct DeepComparator -- minimal set of comparison
// functors for testing equivalency.
template<class T>
struct DeepComparator : public Comparator<DeepEquatesTester<T>,
                                          DeepLessTester<T> >
{
};

} // namespace

#endif // SLB_RCCOMP_H