src/xmlpatterns/expr/qcastingplatform_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_CastingPlatform_H
  53 #define Patternist_CastingPlatform_H
  54
  55 #include <private/qatomiccasterlocator_p.h>
  56 #include <private/qatomiccaster_p.h>
  57 #include <private/qatomicstring_p.h>
  58 #include <private/qatomictype_p.h>
  59 #include <private/qbuiltintypes_p.h>
  60 #include <private/qcommonsequencetypes_p.h>
  61 #include <private/qpatternistlocale_p.h>
  62 #include <private/qqnamevalue_p.h>
  63 #include <private/qschematypefactory_p.h>
  64 #include <private/qstaticcontext_p.h>
  65 #include <private/qvalidationerror_p.h>
  66
  67 QT_BEGIN_HEADER
  68
  69 QT_BEGIN_NAMESPACE
  70
  71 namespace QPatternist
  72 {
  73     /**
  74      * @short Provides casting functionality for classes, such as CastAs or NumberFN, which
  75      * needs to perform casting.
  76      *
  77      * Classes which need to perform casting can simply from this class and gain
  78      * access to casting functinality wrapped in a convenient way. At the center of this
  79      * class is the cast() function, which is used at runtime to perform the actual cast.
  80      *
  81      * The actual circumstances where casting is used, such as in the 'castable as'
  82      * expression or the <tt>fn:number()</tt> function, often have other things to handle as well,
  83      * error handling and cardinality checks for example. This class handles only casting
  84      * and leaves the other case-specific details to the sub-class such that this class only
  85      * do one thing well.
  86      *
  87      * This template class takes two parameters:
  88      * - TSubClass This should be the class inheriting from CastingPlatform.
  89      * - issueError if true, errors are issued via ReportContext, otherwise
  90      *   ValidationError instances are returned appropriately.
  91      *
  92      * The class inheriting CastingPlatform must implement the following function:
  93      * @code
  94      * ItemType::Ptr targetType() const
  95      * @endcode
  96      *
  97      * that returns the type that should be cast to. The type must be an AtomicType.
  98      * Typically, it is appropriate to declare this function @c inline.
  99      *
 100      * A sub-class calls prepareCasting() at compile time(such that CastingPlatform can attempt
 101      * to lookup the proper AtomicCaster) and then it simply uses the cast() function at runtime. The
 102      * function targetType() must be implemented such that CastingPlatform knows
 103      * what type it shall cast to.
 104      *
 105      * @see ValueFactory
 106      * @author Frans Englich <frans.englich@nokia.com>
 107      * @ingroup Patternist_expressions
 108      */
 109     template<typename TSubClass, const bool issueError>
 110     class CastingPlatform
 111     {
 112     protected:
 113         /**
 114          * @note issueCastError() depends on the default value.
 115          */
 116         inline CastingPlatform(const ReportContext::ErrorCode code = ReportContext::FORG0001) : m_errorCode(code)
 117         {
 118         }
 119
 120         /**
 121          * Attempts to cast @p sourceValue to targetType(), and returns
 122          * the created value. Remember that prepareCasting() should have been
 123          * called at compile time, otherwise this function will be slow.
 124          *
 125          * Error reporting is done in two ways. If a cast fails because
 126          * of an error in lexical representation a ValidationError is returned.
 127          * If the cause of failure is that the casting combination is invalid(such as
 128          * when attempting to cast @c xs:date to @c xs:integer), a ValidationError
 129          * is returned if @c false was passed in the template instantiation,
 130          * an error is issued via @p context.
 131          *
 132          * @param sourceValue the value to cast. Must be non @c null.
 133          * @param context the usual ReportContext, used for error reporting.
 134          * @returns the new value which was the result of the cast. If the
 135          * cast failed, an ValidationError is returned.
 136          */
 137         Item cast(const Item &sourceValue,
 138                   const ReportContext::Ptr &context) const;
 139
 140         /**
 141          * This function should be called at compiled time, it attempts to determine
 142          * what AtomicCaster that should be used when casting from @p sourceType to
 143          * targetType(). If that is not possible, because the @p sourceType is
 144          * @c xs:anyAtomicType for instance, the AtomicCaster lookup will done at
 145          * runtime on a case-per-case basis.
 146          *
 147          * @returns @c true if the requested casting combination is valid or might be valid.
 148          * If it is guranteed to be invalid, @c false is returned.
 149          */
 150         bool prepareCasting(const ReportContext::Ptr &context,
 151                             const ItemType::Ptr &sourceType);
 152
 153         /**
 154          * Checks that the targetType() is a valid target type for <tt>castable as</tt>
 155          * and <tt>cast as</tt>. For example, that it is not abstract. If the type is
 156          * invalid, an error is raised via the @p context. Note that it is assumed the type
 157          * is atomic.
 158          */
 159         void checkTargetType(const ReportContext::Ptr &context) const;
 160
 161     private:
 162         inline Item castWithCaster(const Item &sourceValue,
 163                                    const AtomicCaster::Ptr &caster,
 164                                    const ReportContext::Ptr &context) const;
 165
 166         /**
 167          * Locates the caster for casting values of type @p sourceType to targetType(), if
 168          * possible.
 169          *
 170          * @p castImpossible is not initialized. Initialize it to @c false.
 171          */
 172         static AtomicCaster::Ptr locateCaster(const ItemType::Ptr &sourceType,
 173                                               const ReportContext::Ptr &context,
 174                                               bool &castImpossible,
 175                                               const SourceLocationReflection *const location,
 176                                               const ItemType::Ptr &targetType);
 177     private:
 178         inline Item castWithCaster(const Item &sourceValue,
 179                                    const AtomicCaster::Ptr &caster,
 180                                    const DynamicContext::Ptr &context) const;
 181
 182
 183         inline ItemType::Ptr targetType() const
 184         {
 185             Q_ASSERT(static_cast<const TSubClass *>(this)->targetType());
 186             return static_cast<const TSubClass *>(this)->targetType();
 187         }
 188
 189         void issueCastError(const Item &validationError,
 190                             const Item &sourceValue,
 191                             const ReportContext::Ptr &context) const;
 192
 193         Q_DISABLE_COPY(CastingPlatform)
 194         AtomicCaster::Ptr m_caster;
 195         const ReportContext::ErrorCode m_errorCode;
 196     };
 197
 198 #include "qcastingplatform_tpl_p.h"
 199
 200 }
 201
 202 QT_END_NAMESPACE
 203
 204 QT_END_HEADER
 205
 206 #endif