7fe11185dd0c6f9570cb43b4bd9ef3152aa318a9
[profile/ivi/qtxmlpatterns.git] / src / xmlpatterns / utils / qcppcastinghelper_p.h
1 /****************************************************************************
2 **
3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
4 ** Contact: http://www.qt-project.org/
5 **
6 ** This file is part of the QtXmlPatterns module of the Qt Toolkit.
7 **
8 ** $QT_BEGIN_LICENSE:LGPL$
9 ** GNU Lesser General Public License Usage
10 ** This file may be used under the terms of the GNU Lesser General Public
11 ** License version 2.1 as published by the Free Software Foundation and
12 ** appearing in the file LICENSE.LGPL included in the packaging of this
13 ** file. Please review the following information to ensure the GNU Lesser
14 ** General Public License version 2.1 requirements will be met:
15 ** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
16 **
17 ** In addition, as a special exception, Nokia gives you certain additional
18 ** rights. These rights are described in the Nokia Qt LGPL Exception
19 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
20 **
21 ** GNU General Public License Usage
22 ** Alternatively, this file may be used under the terms of the GNU General
23 ** Public License version 3.0 as published by the Free Software Foundation
24 ** and appearing in the file LICENSE.GPL included in the packaging of this
25 ** file. Please review the following information to ensure the GNU General
26 ** Public License version 3.0 requirements will be met:
27 ** http://www.gnu.org/copyleft/gpl.html.
28 **
29 ** Other Usage
30 ** Alternatively, this file may be used in accordance with the terms and
31 ** conditions contained in a signed written agreement between you and Nokia.
32 **
33 **
34 **
35 **
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_CppCastingHelper_H
53 #define Patternist_CppCastingHelper_H
54
55 #include <QtCore/QtGlobal>
56
57 QT_BEGIN_HEADER
58
59 QT_BEGIN_NAMESPACE
60
61 namespace QPatternist
62 {
63     /**
64      * @short Provides convenience methods for performing static casts between C++ classes.
65      *
66      * In Patternist, it is very common to do up-casts from Expression or Item, which typically
67      * involves writing messy code. Such an old-way cast looks like this:
68      *
69      * @code
70      * static_cast<const MyClass *>(myInstance.data())->myClassMember()
71      * @endcode
72      *
73      * CppCastingHelper provides the convenience method as() for this, which is functionally
74      * equivalent to the above code, but simpler:
75      *
76      * @code
77      * myInstance->as<MyClass>()->myClassMember()
78      * @endcode
79      *
80      * The as() function performs a static cast.
81      *
82      * By using CppCastingHelper, this is achieved:
83      *
84      * - Const correctness is automatically taken care of
85      * - Less code to write
86      * - When compiling in debug mode, the as() functions uses a @c dynamic_cast to verify that the
87      *   static casts are properly done, such that sensible error messages are given when the casts
88      *   are invalid. It also traps invalid casts which nevertheless happen to work on a particular
89      *   platform/compiler/hardware architecture.
90      *
91      * CppCastingHelper is a template class where the TSubClass parameter must be the class
92      * inheriting CppCastingHelper. See Item or Expression for demonstration.
93      *
94      * @author Frans Englich <frans.englich@nokia.com>
95      */
96     template<typename TSubClass>
97     class CppCastingHelper
98     {
99     public:
100
101         /**
102          * Casts this instance to:
103          *
104          * @code
105          * const TCastTarget *
106          * @endcode
107          *
108          * and returns the result.
109          *
110          * When compiled in debug mode, this function perform a @c dynamic_cast, in order to
111          * check the correctness of the cast.
112          */
113         template<typename TCastTarget>
114         inline const TCastTarget *as() const
115         {
116 #if defined(Patternist_DEBUG) && !defined(Q_CC_XLC)
117 /* At least on aix-xlc-64, the compiler cries when it sees dynamic_cast. */
118             Q_ASSERT_X(dynamic_cast<const TCastTarget *>(static_cast<const TSubClass *>(this)),
119                        Q_FUNC_INFO,
120                        "The cast is invalid. This class does not inherit the cast target.");
121 #endif
122             return static_cast<const TCastTarget *>(static_cast<const TSubClass *>(this));
123         }
124
125         /**
126          * Casts this instance to:
127          *
128          * @code
129          * TCastTarget *
130          * @endcode
131          *
132          * and returns the result.
133          *
134          * When compiled in debug mode, a @c dynamic_cast is attempted, in order to
135          * check the correctness of the cast.
136          */
137         template<typename TCastTarget>
138         inline TCastTarget *as()
139         {
140 #if defined(Patternist_DEBUG) && !defined(Q_CC_XLC)
141 /* At least on aix-xlc-64, the compiler cries when it sees dynamic_cast. */
142             Q_ASSERT_X(dynamic_cast<TCastTarget *>(static_cast<TSubClass *>(this)),
143                        Q_FUNC_INFO,
144                        "The cast is invalid. This class does not inherit the cast target.");
145 #endif
146             return static_cast<TCastTarget *>(static_cast<TSubClass *>(this));
147         }
148
149     protected:
150         /**
151          * This constructor is protected because this class must be sub-classed.
152          */
153         inline CppCastingHelper() {}
154     };
155 }
156
157 QT_END_NAMESPACE
158
159 QT_END_HEADER
160
161 #endif