src/xmlpatterns/expr/qcomparisonplatform_p.h

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
   4 ** Contact: http://www.qt-project.org/legal
   5 **
   6 ** This file is part of the QtXmlPatterns module of the Qt Toolkit.
   7 **
   8 ** $QT_BEGIN_LICENSE:LGPL$
   9 ** Commercial License Usage
  10 ** Licensees holding valid commercial Qt licenses may use this file in
  11 ** accordance with the commercial license agreement provided with the
  12 ** Software or, alternatively, in accordance with the terms contained in
  13 ** a written agreement between you and Digia.  For licensing terms and
  14 ** conditions see http://qt.digia.com/licensing.  For further information
  15 ** use the contact form at http://qt.digia.com/contact-us.
  16 **
  17 ** GNU Lesser General Public License Usage
  18 ** Alternatively, this file may be used under the terms of the GNU Lesser
  19 ** General Public License version 2.1 as published by the Free Software
  20 ** Foundation and appearing in the file LICENSE.LGPL included in the
  21 ** packaging of this file.  Please review the following information to
  22 ** ensure the GNU Lesser General Public License version 2.1 requirements
  23 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
  24 **
  25 ** In addition, as a special exception, Digia gives you certain additional
  26 ** rights.  These rights are described in the Digia Qt LGPL Exception
  27 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
  28 **
  29 ** GNU General Public License Usage
  30 ** Alternatively, this file may be used under the terms of the GNU
  31 ** General Public License version 3.0 as published by the Free Software
  32 ** Foundation and appearing in the file LICENSE.GPL included in the
  33 ** packaging of this file.  Please review the following information to
  34 ** ensure the GNU General Public License version 3.0 requirements will be
  35 ** met: http://www.gnu.org/copyleft/gpl.html.
  36 **
  37 **
  38 ** $QT_END_LICENSE$
  39 **
  40 ****************************************************************************/
  41
  42 //
  43 //  W A R N I N G
  44 //  -------------
  45 //
  46 // This file is not part of the Qt API.  It exists purely as an
  47 // implementation detail.  This header file may change from version to
  48 // version without notice, or even be removed.
  49 //
  50 // We mean it.
  51
  52 #ifndef Patternist_ComparisonPlatform_H
  53 #define Patternist_ComparisonPlatform_H
  54
  55 #include <private/qatomiccomparators_p.h>
  56 #include <private/qitem_p.h>
  57 #include <private/qcommonsequencetypes_p.h>
  58 #include <private/qdynamiccontext_p.h>
  59 #include <private/qbuiltintypes_p.h>
  60 #include <private/qitemtype_p.h>
  61 #include <private/qpatternistlocale_p.h>
  62
  63 QT_BEGIN_HEADER
  64
  65 QT_BEGIN_NAMESPACE
  66
  67 namespace QPatternist
  68 {
  69     /**
  70      * @short Provides comparison functionality for classes that compare Items,
  71      * such as ValueComparison or MaxFN.
  72      *
  73      * Classes which need comparison functionalities should inherit from this class.
  74      *
  75      * The parameter of this template class is the class inheriting from ComparisonPlatform.
  76      *
  77      * The class inheriting ComparisonPlatform must implement the following function:
  78      * @code
  79      * AtomicComparator::Operator operatorID() const
  80      * @endcode
  81      *
  82      * @author Vincent Ricard <magic@magicninja.org>
  83      * @ingroup Patternist_expressions
  84      */
  85     template <typename TSubClass,
  86               bool issueError,
  87               AtomicComparator::ComparisonType comparisonType = AtomicComparator::AsValueComparison,
  88               ReportContext::ErrorCode errorCode = ReportContext::XPTY0004>
  89     class ComparisonPlatform
  90     {
  91     protected:
  92         /**
  93          * Makes ComparisonPlatform use the AtomicComparator @p comparator.
  94          */
  95         void prepareComparison(const AtomicComparator::Ptr &comparator);
  96
  97         /**
  98          * Default constructor. Does nothing. It is implemented in order make template
  99          * instantiation easier.
 100          */
 101         inline ComparisonPlatform()
 102         {
 103         }
 104
 105         /**
 106          * Utility function for fetching the appropriate AtomicComparator
 107          * for two atomic values of type @p type1 and @p type2, for the operator @p op.
 108          *
 109          * This function is used throughout the implementation, ranging from the ValueComparison
 110          * itself, to for example the aggregate functions.
 111          *
 112          * @param context the ordinary ReportContext, used for issuing errors.
 113          * @param type1 the type of the first operand value in a comparison for which the
 114          * returned AtomicComparator is intended for
 115          * @param type2 the type of the second operand value in a comparison for which the
 116          * returned AtomicComparator is intended for. Whether @p type1 and @p type2 corresponds
 117          * to what is the first second operand type does not have significance, the order
 118          * can be arbitrary
 119          */
 120         AtomicComparator::Ptr
 121         fetchComparator(const ItemType::Ptr &type1,
 122                         const ItemType::Ptr &type2,
 123                         const ReportContext::Ptr &context) const;
 124
 125         /**
 126          * @short Compares @p i1 and @p i2 with operator @p op, using comparator @p
 127          * comp. All input arguments must be valid, and not @c null.
 128          *
 129          * This is a fast, raw function which has the requirement that the
 130          * caller knows what to compare and with what.
 131          */
 132         bool compare(const Item &i1,
 133                      const Item &i2,
 134                      const AtomicComparator::Ptr &comp,
 135                      const AtomicComparator::Operator op) const;
 136
 137         /**
 138          * @short Compares @p it1 against @p it2, using comparator() and operatorID().
 139          *
 140          * If the comparator wasn't looked up at compile time, it will be
 141          * attempted before comparing. If this fails, errors are reported via
 142          * @p context.
 143          */
 144         bool
 145         flexibleCompare(const Item &it1,
 146                         const Item &it2,
 147                         const DynamicContext::Ptr &context) const;
 148
 149         /**
 150          * @short like flexibleCompare(), but returns the result
 151          * as an AtomicComparator::Operator instead of @c bool.
 152          *
 153          * This is useful when it is significant how a less than comparison
 154          * fails; whether the two values are equal or greater than.
 155          */
 156         AtomicComparator::ComparisonResult
 157         detailedFlexibleCompare(const Item &it1,
 158                                 const Item &it2,
 159                                 const DynamicContext::Ptr &context) const;
 160
 161         /**
 162          * @returns the AtomicComparator that has been allocated at compile time,
 163          * with prepareComparison(). If no AtomicComparator has been allocated
 164          * for some reason, this function returns @c null.
 165          */
 166         inline const AtomicComparator::Ptr &comparator() const
 167         {
 168             return m_comparator;
 169         }
 170
 171         /**
 172          * Calling this function makes ComparisonPlatform use a comparator that
 173          * compares strings case insensitively.
 174          *
 175          * @see ValueComparison::isCaseInsensitiveCompare()
 176          */
 177         inline void useCaseInsensitiveComparator()
 178         {
 179             m_comparator = AtomicComparator::Ptr(new CaseInsensitiveStringComparator());
 180         }
 181
 182     private:
 183         /**
 184          * @returns the operator that is used.
 185          */
 186         inline AtomicComparator::Operator operatorID() const
 187         {
 188             Q_ASSERT(static_cast<const TSubClass *>(this)->operatorID());
 189             return static_cast<const TSubClass *>(this)->operatorID();
 190         }
 191
 192         /**
 193          * The comparator that is used for comparing atomic values. The AtomicComparator
 194          * that is used, depends on the static type of the operands. m_comparator can be
 195          * @c null if it wasn't possible to determine what comparator to use at compile time.
 196          */
 197         AtomicComparator::Ptr m_comparator;
 198     };
 199
 200 #include "qcomparisonplatform_tpl_p.h"
 201
 202 }
 203
 204 QT_END_NAMESPACE
 205
 206 QT_END_HEADER
 207
 208 #endif