Skip to content

Commit 7f3941e

Browse files
m-kuhnm-kuhn
committedApr 30, 2017
Doxymentation
·
ltr-3_40final-3_0_0
1 parent 9e14344 commit 7f3941e

File tree

3 files changed

+268
-112
lines changed

3 files changed

+268
-112
lines changed
 

‎python/core/qgsexpression.sip

Lines changed: 163 additions & 77 deletions
Original file line numberDiff line numberDiff line change
@@ -161,7 +161,7 @@ Returns root node of the expression. Root node is null is parsing has failed
161161
all attributes from the layer are required for evaluation of the expression.
162162
QgsFeatureRequest.setSubsetOfAttributes automatically handles this case.
163163

164-
\see referencedAttributeIndexes()
164+
.. seealso:: referencedAttributeIndexes()
165165
:rtype: set of str
166166
%End
167167

@@ -267,9 +267,9 @@ expression() instead.
267267
%Docstring
268268
Return calculator used for distance and area calculations
269269
(used by $length, $area and $perimeter functions only)
270-
\see setGeomCalculator()
271-
\see distanceUnits()
272-
\see areaUnits()
270+
.. seealso:: setGeomCalculator()
271+
.. seealso:: distanceUnits()
272+
.. seealso:: areaUnits()
273273
:rtype: QgsDistanceArea
274274
%End
275275

@@ -281,7 +281,7 @@ expression() instead.
281281
cartesian methods (ie no ellipsoidal calculations).
282282
\param calc geometry calculator. Ownership is not transferred. Set to a None to force
283283
cartesian calculations.
284-
\see geomCalculator()
284+
.. seealso:: geomCalculator()
285285
%End
286286

287287
QgsUnitTypes::DistanceUnit distanceUnits() const;
@@ -291,8 +291,8 @@ expression() instead.
291291

292292
distances are only converted when a geomCalculator() has been set
293293
.. versionadded:: 2.14
294-
\see setDistanceUnits()
295-
\see areaUnits()
294+
.. seealso:: setDistanceUnits()
295+
.. seealso:: areaUnits()
296296
:rtype: QgsUnitTypes.DistanceUnit
297297
%End
298298

@@ -303,8 +303,8 @@ expression() instead.
303303

304304
distances are only converted when a geomCalculator() has been set
305305
.. versionadded:: 2.14
306-
\see distanceUnits()
307-
\see setAreaUnits()
306+
.. seealso:: distanceUnits()
307+
.. seealso:: setAreaUnits()
308308
%End
309309

310310
QgsUnitTypes::AreaUnit areaUnits() const;
@@ -314,8 +314,8 @@ expression() instead.
314314

315315
areas are only converted when a geomCalculator() has been set
316316
.. versionadded:: 2.14
317-
\see setAreaUnits()
318-
\see distanceUnits()
317+
.. seealso:: setAreaUnits()
318+
.. seealso:: distanceUnits()
319319
:rtype: QgsUnitTypes.AreaUnit
320320
%End
321321

@@ -326,8 +326,8 @@ expression() instead.
326326

327327
areas are only converted when a geomCalculator() has been set
328328
.. versionadded:: 2.14
329-
\see areaUnits()
330-
\see setDistanceUnits()
329+
.. seealso:: areaUnits()
330+
.. seealso:: setDistanceUnits()
331331
%End
332332

333333
static QString replaceExpressionText( const QString &action, const QgsExpressionContext *context,
@@ -613,7 +613,7 @@ Does this function use a geometry object.
613613
%Docstring
614614
Returns a list of the groups the function belongs to.
615615
.. versionadded:: 3.0
616-
\see group()
616+
.. seealso:: group()
617617
:rtype: list of str
618618
%End
619619

@@ -662,15 +662,15 @@ The help text for the function.
662662
\param function function to register
663663
\param transferOwnership set to true to transfer ownership of function to expression engine
664664
:return: true on successful registration
665-
\see unregisterFunction
665+
.. seealso:: unregisterFunction
666666
:rtype: bool
667667
%End
668668

669669
static bool unregisterFunction( const QString &name );
670670
%Docstring
671671
Unregisters a function from the expression engine. The function will no longer be usable in expressions.
672672
\param name function name
673-
\see registerFunction
673+
.. seealso:: registerFunction
674674
:rtype: bool
675675
%End
676676

@@ -703,16 +703,16 @@ return index of the function in Functions array
703703
static QString quotedColumnRef( QString name );
704704
%Docstring
705705
Returns a quoted column reference (in double quotes)
706-
\see quotedString()
707-
\see quotedValue()
706+
.. seealso:: quotedString()
707+
.. seealso:: quotedValue()
708708
:rtype: str
709709
%End
710710

711711
static QString quotedString( QString text );
712712
%Docstring
713713
Returns a quoted version of a string (in single quotes)
714-
\see quotedValue()
715-
\see quotedColumnRef()
714+
.. seealso:: quotedValue()
715+
.. seealso:: quotedColumnRef()
716716
:rtype: str
717717
%End
718718

@@ -722,8 +722,8 @@ return index of the function in Functions array
722722
quotations where required.
723723
\param value value to convert to a string representation
724724
.. versionadded:: 2.14
725-
\see quotedString()
726-
\see quotedColumnRef()
725+
.. seealso:: quotedString()
726+
.. seealso:: quotedColumnRef()
727727
:rtype: str
728728
%End
729729

@@ -734,8 +734,8 @@ return index of the function in Functions array
734734
\param value value to convert to a string representation
735735
\param type value type
736736
.. versionadded:: 2.14
737-
\see quotedString()
738-
\see quotedColumnRef()
737+
.. seealso:: quotedString()
738+
.. seealso:: quotedColumnRef()
739739
:rtype: str
740740
%End
741741

@@ -753,6 +753,10 @@ return index of the function in Functions array
753753

754754
class Node
755755
{
756+
%Docstring
757+
758+
Abstract base class for all nodes that can appear in an expression.
759+
%End
756760

757761
%TypeHeaderCode
758762
#include "qgsexpression.h"
@@ -761,49 +765,59 @@ return index of the function in Functions array
761765
%ConvertToSubClassCode
762766
switch ( sipCpp->nodeType() )
763767
{
764-
case QgsExpression::ntUnaryOperator: sipType = sipType_QgsExpression_NodeUnaryOperator; break;
765-
case QgsExpression::ntBinaryOperator: sipType = sipType_QgsExpression_NodeBinaryOperator; break;
766-
case QgsExpression::ntInOperator: sipType = sipType_QgsExpression_NodeInOperator; break;
767-
case QgsExpression::ntFunction: sipType = sipType_QgsExpression_NodeFunction; break;
768-
case QgsExpression::ntLiteral: sipType = sipType_QgsExpression_NodeLiteral; break;
769-
case QgsExpression::ntColumnRef: sipType = sipType_QgsExpression_NodeColumnRef; break;
770-
case QgsExpression::ntCondition: sipType = sipType_QgsExpression_NodeCondition; break;
771-
default: sipType = 0; break;
768+
case QgsExpression::ntUnaryOperator:
769+
sipType = sipType_QgsExpression_NodeUnaryOperator;
770+
break;
771+
case QgsExpression::ntBinaryOperator:
772+
sipType = sipType_QgsExpression_NodeBinaryOperator;
773+
break;
774+
case QgsExpression::ntInOperator:
775+
sipType = sipType_QgsExpression_NodeInOperator;
776+
break;
777+
case QgsExpression::ntFunction:
778+
sipType = sipType_QgsExpression_NodeFunction;
779+
break;
780+
case QgsExpression::ntLiteral:
781+
sipType = sipType_QgsExpression_NodeLiteral;
782+
break;
783+
case QgsExpression::ntColumnRef:
784+
sipType = sipType_QgsExpression_NodeColumnRef;
785+
break;
786+
case QgsExpression::ntCondition:
787+
sipType = sipType_QgsExpression_NodeCondition;
788+
break;
789+
default:
790+
sipType = 0;
791+
break;
772792
}
773793
%End
774794
public:
775795
virtual ~Node();
776796

777797
virtual QgsExpression::NodeType nodeType() const = 0;
778798
%Docstring
779-
Abstract virtual that returns the type of this node.
799+
Get the type of this node.
780800

781801
:return: The type of this node
782802
:rtype: QgsExpression.NodeType
783803
%End
784804

785-
virtual QVariant eval( QgsExpression *parent, const QgsExpressionContext *context ) = 0;
786-
%Docstring
787-
Abstract virtual eval method
788-
Errors are reported to the parent
789-
.. versionadded:: 2.12
790-
:rtype: QVariant
791-
%End
792-
793-
virtual bool prepare( QgsExpression *parent, const QgsExpressionContext *context ) = 0;
805+
virtual QString dump() const = 0;
794806
%Docstring
795-
Abstract virtual preparation method
796-
Errors are reported to the parent
797-
.. versionadded:: 2.12
798-
:rtype: bool
807+
Dump this node into a serialized (part) of an expression.
808+
The returned expression does not necessarily literally match
809+
the original expression, it's just guaranteed to behave the same way.
810+
:rtype: str
799811
%End
800812

801-
virtual QString dump() const = 0;
813+
QVariant eval( QgsExpression *parent, const QgsExpressionContext *context );
802814
%Docstring
803-
Abstract virtual dump method
815+
Evaluate this node with the given context and parent.
816+
This will return a cached value if it has been determined to be static
817+
during the prepare() execution.
804818

805-
:return: An expression which represents this node as string
806-
:rtype: str
819+
.. versionadded:: 2.12
820+
:rtype: QVariant
807821
%End
808822

809823
virtual QgsExpression::Node *clone() const = 0;
@@ -832,7 +846,7 @@ return index of the function in Functions array
832846

833847
virtual QSet<QString> referencedVariables() const = 0;
834848
%Docstring
835-
Return a list of all variables which are used in this expression.
849+
Return a set of all variables which are used in this expression.
836850
:rtype: set of str
837851
%End
838852

@@ -846,6 +860,45 @@ return index of the function in Functions array
846860
:return: true if a geometry is required to evaluate this expression
847861
:rtype: bool
848862
%End
863+
864+
virtual bool isStatic( QgsExpression *parent, const QgsExpressionContext *context ) const = 0;
865+
%Docstring
866+
Returns true if this node can be evaluated for a static value. This is used during
867+
the prepare() step and in case it returns true, the value of this node will already
868+
be evaluated and the result cached (and therefore not re-evaluated in subsequent calls
869+
to eval()). In case this returns true, prepareNode() will never be called.
870+
871+
.. versionadded:: 3.0
872+
:rtype: bool
873+
%End
874+
875+
bool prepare( QgsExpression *parent, const QgsExpressionContext *context );
876+
%Docstring
877+
Prepare this node for evaluation.
878+
This will check if the node content is static and in this case cache the value.
879+
If it's not static it will call prepareNode() to allow the node to do initialization
880+
work like for example resolving a column name to an attribute index.
881+
882+
.. versionadded:: 2.12
883+
:rtype: bool
884+
%End
885+
886+
private:
887+
virtual bool prepareNode( QgsExpression *parent, const QgsExpressionContext *context ) = 0 ;
888+
%Docstring
889+
Abstract virtual preparation method
890+
Errors are reported to the parent
891+
.. versionadded:: 3.0
892+
:rtype: bool
893+
%End
894+
private:
895+
virtual QVariant evalNode( QgsExpression *parent, const QgsExpressionContext *context ) = 0 ;
896+
%Docstring
897+
Abstract virtual eval method
898+
Errors are reported to the parent
899+
.. versionadded:: 3.0
900+
:rtype: QVariant
901+
%End
849902
};
850903

851904
class NamedNode
@@ -937,18 +990,23 @@ Creates a deep copy of this list. Ownership is transferred to the caller
937990
:rtype: str
938991
%End
939992

940-
protected:
941-
942993
};
943994

944995
class NodeUnaryOperator : QgsExpression::Node
945996
{
997+
%Docstring
998+
A unary node is either negative as in boolean (not) or as in numbers (minus).
999+
%End
9461000

9471001
%TypeHeaderCode
9481002
#include "qgsexpression.h"
9491003
%End
9501004
public:
1005+
9511006
NodeUnaryOperator( QgsExpression::UnaryOperator op, QgsExpression::Node *operand /Transfer/ );
1007+
%Docstring
1008+
A node unary operator is modifying the value of ``operand`` by negating it with \op.
1009+
%End
9521010
~NodeUnaryOperator();
9531011

9541012
QgsExpression::UnaryOperator op() const;
@@ -961,16 +1019,17 @@ Creates a deep copy of this list. Ownership is transferred to the caller
9611019
%End
9621020

9631021
virtual QgsExpression::NodeType nodeType() const;
964-
virtual bool prepare( QgsExpression *parent, const QgsExpressionContext *context );
965-
virtual QVariant eval( QgsExpression *parent, const QgsExpressionContext *context );
1022+
virtual bool prepareNode( QgsExpression *parent, const QgsExpressionContext *context );
1023+
virtual QVariant evalNode( QgsExpression *parent, const QgsExpressionContext *context );
9661024
virtual QString dump() const;
9671025

9681026
virtual QSet<QString> referencedColumns() const;
9691027
virtual QSet<QString> referencedVariables() const;
9701028
virtual bool needsGeometry() const;
9711029
virtual QgsExpression::Node *clone() const;
9721030

973-
protected:
1031+
virtual bool isStatic( QgsExpression *parent, const QgsExpressionContext *context ) const;
1032+
9741033
};
9751034

9761035
class NodeBinaryOperator : QgsExpression::Node
@@ -980,7 +1039,11 @@ Creates a deep copy of this list. Ownership is transferred to the caller
9801039
#include "qgsexpression.h"
9811040
%End
9821041
public:
1042+
9831043
NodeBinaryOperator( QgsExpression::BinaryOperator op, QgsExpression::Node *opLeft /Transfer/, QgsExpression::Node *opRight /Transfer/ );
1044+
%Docstring
1045+
Binary combination of the left and the right with op.
1046+
%End
9841047
~NodeBinaryOperator();
9851048

9861049
QgsExpression::BinaryOperator op() const;
@@ -997,14 +1060,15 @@ Creates a deep copy of this list. Ownership is transferred to the caller
9971060
%End
9981061

9991062
virtual QgsExpression::NodeType nodeType() const;
1000-
virtual bool prepare( QgsExpression *parent, const QgsExpressionContext *context );
1001-
virtual QVariant eval( QgsExpression *parent, const QgsExpressionContext *context );
1063+
virtual bool prepareNode( QgsExpression *parent, const QgsExpressionContext *context );
1064+
virtual QVariant evalNode( QgsExpression *parent, const QgsExpressionContext *context );
10021065
virtual QString dump() const;
10031066

10041067
virtual QSet<QString> referencedColumns() const;
10051068
virtual QSet<QString> referencedVariables() const;
10061069
virtual bool needsGeometry() const;
10071070
virtual QgsExpression::Node *clone() const;
1071+
virtual bool isStatic( QgsExpression *parent, const QgsExpressionContext *context ) const;
10081072

10091073
int precedence() const;
10101074
%Docstring
@@ -1024,7 +1088,11 @@ Creates a deep copy of this list. Ownership is transferred to the caller
10241088
#include "qgsexpression.h"
10251089
%End
10261090
public:
1091+
10271092
NodeInOperator( QgsExpression::Node *node /Transfer/, QgsExpression::NodeList *list /Transfer/, bool notin = false );
1093+
%Docstring
1094+
This node tests if the result of \node is in the result of ``list``. Optionally it can be inverted with ``notin`` which by default is false.
1095+
%End
10281096
virtual ~NodeInOperator();
10291097

10301098
QgsExpression::Node *node() const;
@@ -1041,16 +1109,16 @@ Creates a deep copy of this list. Ownership is transferred to the caller
10411109
%End
10421110

10431111
virtual QgsExpression::NodeType nodeType() const;
1044-
virtual bool prepare( QgsExpression *parent, const QgsExpressionContext *context );
1045-
virtual QVariant eval( QgsExpression *parent, const QgsExpressionContext *context );
1112+
virtual bool prepareNode( QgsExpression *parent, const QgsExpressionContext *context );
1113+
virtual QVariant evalNode( QgsExpression *parent, const QgsExpressionContext *context );
10461114
virtual QString dump() const;
10471115

10481116
virtual QSet<QString> referencedColumns() const;
10491117
virtual QSet<QString> referencedVariables() const;
10501118
virtual bool needsGeometry() const;
10511119
virtual QgsExpression::Node *clone() const;
1120+
virtual bool isStatic( QgsExpression *parent, const QgsExpressionContext *context ) const;
10521121

1053-
protected:
10541122
};
10551123

10561124
class NodeFunction : QgsExpression::Node
@@ -1060,7 +1128,12 @@ Creates a deep copy of this list. Ownership is transferred to the caller
10601128
#include "qgsexpression.h"
10611129
%End
10621130
public:
1131+
10631132
NodeFunction( int fnIndex, QgsExpression::NodeList *args /Transfer/ );
1133+
%Docstring
1134+
A function node consists of an index of the function in the global function array and
1135+
a list of arguments that will be passed to it.
1136+
%End
10641137

10651138
virtual ~NodeFunction();
10661139

@@ -1074,14 +1147,15 @@ Creates a deep copy of this list. Ownership is transferred to the caller
10741147
%End
10751148

10761149
virtual QgsExpression::NodeType nodeType() const;
1077-
virtual bool prepare( QgsExpression *parent, const QgsExpressionContext *context );
1078-
virtual QVariant eval( QgsExpression *parent, const QgsExpressionContext *context );
1150+
virtual bool prepareNode( QgsExpression *parent, const QgsExpressionContext *context );
1151+
virtual QVariant evalNode( QgsExpression *parent, const QgsExpressionContext *context );
10791152
virtual QString dump() const;
10801153

10811154
virtual QSet<QString> referencedColumns() const;
10821155
virtual QSet<QString> referencedVariables() const;
10831156
virtual bool needsGeometry() const;
10841157
virtual QgsExpression::Node *clone() const;
1158+
virtual bool isStatic( QgsExpression *parent, const QgsExpressionContext *context ) const;
10851159

10861160
static bool validateParams( int fnIndex, QgsExpression::NodeList *args, QString &error );
10871161
%Docstring
@@ -1107,16 +1181,16 @@ The value of the literal.
11071181
%End
11081182

11091183
virtual QgsExpression::NodeType nodeType() const;
1110-
virtual bool prepare( QgsExpression *parent, const QgsExpressionContext *context );
1111-
virtual QVariant eval( QgsExpression *parent, const QgsExpressionContext *context );
1184+
virtual bool prepareNode( QgsExpression *parent, const QgsExpressionContext *context );
1185+
virtual QVariant evalNode( QgsExpression *parent, const QgsExpressionContext *context );
11121186
virtual QString dump() const;
11131187

11141188
virtual QSet<QString> referencedColumns() const;
11151189
virtual QSet<QString> referencedVariables() const;
11161190
virtual bool needsGeometry() const;
11171191
virtual QgsExpression::Node *clone() const;
1192+
virtual bool isStatic( QgsExpression *parent, const QgsExpressionContext *context ) const;
11181193

1119-
protected:
11201194
};
11211195

11221196
class NodeColumnRef : QgsExpression::Node
@@ -1135,32 +1209,40 @@ The name of the column.
11351209
%End
11361210

11371211
virtual QgsExpression::NodeType nodeType() const;
1138-
virtual bool prepare( QgsExpression *parent, const QgsExpressionContext *context );
1139-
virtual QVariant eval( QgsExpression *parent, const QgsExpressionContext *context );
1212+
virtual bool prepareNode( QgsExpression *parent, const QgsExpressionContext *context );
1213+
virtual QVariant evalNode( QgsExpression *parent, const QgsExpressionContext *context );
11401214
virtual QString dump() const;
11411215

11421216
virtual QSet<QString> referencedColumns() const;
11431217
virtual QSet<QString> referencedVariables() const;
11441218
virtual bool needsGeometry() const;
11451219

11461220
virtual QgsExpression::Node *clone() const;
1221+
virtual bool isStatic( QgsExpression *parent, const QgsExpressionContext *context ) const;
11471222

1148-
protected:
11491223
};
11501224

1225+
11511226
class WhenThen
11521227
{
11531228

11541229
%TypeHeaderCode
11551230
#include "qgsexpression.h"
11561231
%End
11571232
public:
1158-
WhenThen( QgsExpression::Node *whenExp /Transfer/, QgsExpression::Node *thenExp /Transfer/ );
1233+
1234+
WhenThen( QgsExpression::Node *whenExp, QgsExpression::Node *thenExp );
1235+
%Docstring
1236+
A combination of when and then. Simple as that.
1237+
%End
11591238
~WhenThen();
11601239

11611240

1162-
QgsExpression::Node *mWhenExp;
1163-
QgsExpression::Node *mThenExp;
1241+
QgsExpression::WhenThen *clone() const;
1242+
%Docstring
1243+
Get a deep copy of this WhenThen combination.
1244+
:rtype: QgsExpression.WhenThen
1245+
%End
11641246

11651247
private:
11661248
WhenThen( const QgsExpression::WhenThen &rh );
@@ -1174,29 +1256,33 @@ The name of the column.
11741256
#include "qgsexpression.h"
11751257
%End
11761258
public:
1259+
11771260
NodeCondition( QgsExpression::WhenThenList *conditions, QgsExpression::Node *elseExp = 0 );
1261+
%Docstring
1262+
Create a new node with the given list of ``conditions`` and an optional ``elseExp`` expression.
1263+
%End
11781264

11791265

11801266
~NodeCondition();
11811267

11821268
virtual QgsExpression::NodeType nodeType() const;
1183-
virtual QVariant eval( QgsExpression *parent, const QgsExpressionContext *context );
1184-
virtual bool prepare( QgsExpression *parent, const QgsExpressionContext *context );
1269+
virtual QVariant evalNode( QgsExpression *parent, const QgsExpressionContext *context );
1270+
virtual bool prepareNode( QgsExpression *parent, const QgsExpressionContext *context );
11851271
virtual QString dump() const;
11861272

11871273
virtual QSet<QString> referencedColumns() const;
11881274
virtual QSet<QString> referencedVariables() const;
11891275
virtual bool needsGeometry() const;
11901276
virtual QgsExpression::Node *clone() const;
1277+
virtual bool isStatic( QgsExpression *parent, const QgsExpressionContext *context ) const;
11911278

1192-
protected:
11931279
};
11941280

11951281
static QString helpText( QString name );
11961282
%Docstring
11971283
Returns the help text for a specified function.
11981284
\param name function name
1199-
\see variableHelpText()
1285+
.. seealso:: variableHelpText()
12001286
:rtype: str
12011287
%End
12021288

@@ -1206,7 +1292,7 @@ The name of the column.
12061292
\param variableName name of variable
12071293
\param showValue set to true to include current value of variable in help text
12081294
\param value current value of variable to show in help text
1209-
\see helpText()
1295+
.. seealso:: helpText()
12101296
.. versionadded:: 2.12
12111297
:rtype: str
12121298
%End

‎src/core/qgsexpression.cpp

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5778,7 +5778,7 @@ bool QgsExpression::NodeColumnRef::prepareNode( QgsExpression *parent, const Qgs
57785778

57795779
QString QgsExpression::NodeColumnRef::dump() const
57805780
{
5781-
return quotedColumnRef( mName );
5781+
return QRegExp( "^[A-Za-z_\x80-\xff][A-Za-z0-9_\x80-\xff]*$" ).exactMatch( mName ) ? mName : quotedColumnRef( mName );
57825782
}
57835783

57845784
QSet<QString> QgsExpression::NodeColumnRef::referencedColumns() const
@@ -5805,6 +5805,11 @@ bool QgsExpression::NodeColumnRef::isStatic( QgsExpression *parent, const QgsExp
58055805

58065806
//
58075807

5808+
QgsExpression::NodeCondition::NodeCondition( QgsExpression::WhenThenList *conditions, QgsExpression::Node *elseExp )
5809+
: mConditions( *conditions )
5810+
, mElseExp( elseExp )
5811+
{ delete conditions; }
5812+
58085813
QVariant QgsExpression::NodeCondition::evalNode( QgsExpression *parent, const QgsExpressionContext *context )
58095814
{
58105815
Q_FOREACH ( WhenThen *cond, mConditions )

‎src/core/qgsexpression.h

Lines changed: 99 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -829,16 +829,19 @@ class CORE_EXPORT QgsExpression
829829

830830
enum NodeType
831831
{
832-
ntUnaryOperator,
833-
ntBinaryOperator,
834-
ntInOperator,
835-
ntFunction,
836-
ntLiteral,
837-
ntColumnRef,
838-
ntCondition
832+
ntUnaryOperator, //!< \see QgsExpression::Node::NodeUnaryOperator
833+
ntBinaryOperator, //!< \see QgsExpression::Node::NodeBinaryOperator
834+
ntInOperator, //!< \see QgsExpression::Node::NodeInOperator
835+
ntFunction, //!< \see QgsExpression::Node::NodeFunction
836+
ntLiteral, //!< \see QgsExpression::Node::NodeLiteral
837+
ntColumnRef, //!< \see QgsExpression::Node::NodeColumnRef
838+
ntCondition //!< \see QgsExpression::Node::NodeCondition
839839
};
840840

841-
/** \ingroup core
841+
/**
842+
* \ingroup core
843+
*
844+
* Abstract base class for all nodes that can appear in an expression.
842845
*/
843846
class CORE_EXPORT Node
844847
{
@@ -847,14 +850,30 @@ class CORE_EXPORT QgsExpression
847850
SIP_CONVERT_TO_SUBCLASS_CODE
848851
switch ( sipCpp->nodeType() )
849852
{
850-
case QgsExpression::ntUnaryOperator: sipType = sipType_QgsExpression_NodeUnaryOperator; break;
851-
case QgsExpression::ntBinaryOperator: sipType = sipType_QgsExpression_NodeBinaryOperator; break;
852-
case QgsExpression::ntInOperator: sipType = sipType_QgsExpression_NodeInOperator; break;
853-
case QgsExpression::ntFunction: sipType = sipType_QgsExpression_NodeFunction; break;
854-
case QgsExpression::ntLiteral: sipType = sipType_QgsExpression_NodeLiteral; break;
855-
case QgsExpression::ntColumnRef: sipType = sipType_QgsExpression_NodeColumnRef; break;
856-
case QgsExpression::ntCondition: sipType = sipType_QgsExpression_NodeCondition; break;
857-
default: sipType = 0; break;
853+
case QgsExpression::ntUnaryOperator:
854+
sipType = sipType_QgsExpression_NodeUnaryOperator;
855+
break;
856+
case QgsExpression::ntBinaryOperator:
857+
sipType = sipType_QgsExpression_NodeBinaryOperator;
858+
break;
859+
case QgsExpression::ntInOperator:
860+
sipType = sipType_QgsExpression_NodeInOperator;
861+
break;
862+
case QgsExpression::ntFunction:
863+
sipType = sipType_QgsExpression_NodeFunction;
864+
break;
865+
case QgsExpression::ntLiteral:
866+
sipType = sipType_QgsExpression_NodeLiteral;
867+
break;
868+
case QgsExpression::ntColumnRef:
869+
sipType = sipType_QgsExpression_NodeColumnRef;
870+
break;
871+
case QgsExpression::ntCondition:
872+
sipType = sipType_QgsExpression_NodeCondition;
873+
break;
874+
default:
875+
sipType = 0;
876+
break;
858877
}
859878
SIP_END
860879
#endif
@@ -863,23 +882,25 @@ class CORE_EXPORT QgsExpression
863882
virtual ~Node() = default;
864883

865884
/**
866-
* Abstract virtual that returns the type of this node.
885+
* Get the type of this node.
867886
*
868887
* \returns The type of this node
869888
*/
870889
virtual QgsExpression::NodeType nodeType() const = 0;
871890

872891
/**
873-
* Abstract virtual dump method
874-
*
875-
* \returns An expression which represents this node as string
892+
* Dump this node into a serialized (part) of an expression.
893+
* The returned expression does not necessarily literally match
894+
* the original expression, it's just guaranteed to behave the same way.
876895
*/
877896
virtual QString dump() const = 0;
878897

879898
/**
880899
* Evaluate this node with the given context and parent.
881900
* This will return a cached value if it has been determined to be static
882901
* during the prepare() execution.
902+
*
903+
* \since QGIS 2.12
883904
*/
884905
QVariant eval( QgsExpression *parent, const QgsExpressionContext *context );
885906

@@ -906,7 +927,7 @@ class CORE_EXPORT QgsExpression
906927
virtual QSet<QString> referencedColumns() const = 0;
907928

908929
/**
909-
* Return a list of all variables which are used in this expression.
930+
* Return a set of all variables which are used in this expression.
910931
*/
911932
virtual QSet<QString> referencedVariables() const = 0;
912933

@@ -920,26 +941,41 @@ class CORE_EXPORT QgsExpression
920941
*/
921942
virtual bool needsGeometry() const = 0;
922943

944+
/**
945+
* Returns true if this node can be evaluated for a static value. This is used during
946+
* the prepare() step and in case it returns true, the value of this node will already
947+
* be evaluated and the result cached (and therefore not re-evaluated in subsequent calls
948+
* to eval()). In case this returns true, prepareNode() will never be called.
949+
*
950+
* \since QGIS 3.0
951+
*/
923952
virtual bool isStatic( QgsExpression *parent, const QgsExpressionContext *context ) const = 0;
924953

954+
/**
955+
* Prepare this node for evaluation.
956+
* This will check if the node content is static and in this case cache the value.
957+
* If it's not static it will call prepareNode() to allow the node to do initialization
958+
* work like for example resolving a column name to an attribute index.
959+
*
960+
* \since QGIS 2.12
961+
*/
925962
bool prepare( QgsExpression *parent, const QgsExpressionContext *context );
926963

927-
928964
private:
929965

930966
/**
931967
* Abstract virtual preparation method
932968
* Errors are reported to the parent
933-
* \since QGIS 2.12
969+
* \since QGIS 3.0
934970
*/
935-
virtual bool prepareNode( QgsExpression *parent, const QgsExpressionContext *context ) = 0;
971+
virtual bool prepareNode( QgsExpression *parent, const QgsExpressionContext *context ) = 0 SIP_FORCE;
936972

937973
/**
938974
* Abstract virtual eval method
939975
* Errors are reported to the parent
940-
* \since QGIS 2.12
976+
* \since QGIS 3.0
941977
*/
942-
virtual QVariant evalNode( QgsExpression *parent, const QgsExpressionContext *context ) = 0;
978+
virtual QVariant evalNode( QgsExpression *parent, const QgsExpressionContext *context ) = 0 SIP_FORCE;
943979

944980
bool mHasCachedValue = false;
945981
QVariant mCachedStaticValue;
@@ -1020,10 +1056,15 @@ class CORE_EXPORT QgsExpression
10201056
};
10211057

10221058
/** \ingroup core
1059+
* A unary node is either negative as in boolean (not) or as in numbers (minus).
10231060
*/
10241061
class CORE_EXPORT NodeUnaryOperator : public QgsExpression::Node
10251062
{
10261063
public:
1064+
1065+
/**
1066+
* A node unary operator is modifying the value of \a operand by negating it with \op.
1067+
*/
10271068
NodeUnaryOperator( QgsExpression::UnaryOperator op, QgsExpression::Node *operand SIP_TRANSFER )
10281069
: mOp( op )
10291070
, mOperand( operand )
@@ -1055,16 +1096,20 @@ class CORE_EXPORT QgsExpression
10551096
class CORE_EXPORT NodeBinaryOperator : public QgsExpression::Node
10561097
{
10571098
public:
1099+
1100+
/**
1101+
* Binary combination of the left and the right with op.
1102+
*/
10581103
NodeBinaryOperator( QgsExpression::BinaryOperator op, QgsExpression::Node *opLeft SIP_TRANSFER, QgsExpression::Node *opRight SIP_TRANSFER )
10591104
: mOp( op )
10601105
, mOpLeft( opLeft )
10611106
, mOpRight( opRight )
10621107
{}
10631108
~NodeBinaryOperator() { delete mOpLeft; delete mOpRight; }
10641109

1065-
BinaryOperator op() const { return mOp; }
1066-
Node *opLeft() const { return mOpLeft; }
1067-
Node *opRight() const { return mOpRight; }
1110+
QgsExpression::BinaryOperator op() const { return mOp; }
1111+
QgsExpression::Node *opLeft() const { return mOpLeft; }
1112+
QgsExpression::Node *opRight() const { return mOpRight; }
10681113

10691114
virtual QgsExpression::NodeType nodeType() const override { return ntBinaryOperator; }
10701115
virtual bool prepareNode( QgsExpression *parent, const QgsExpressionContext *context ) override;
@@ -1101,6 +1146,10 @@ class CORE_EXPORT QgsExpression
11011146
class CORE_EXPORT NodeInOperator : public QgsExpression::Node
11021147
{
11031148
public:
1149+
1150+
/**
1151+
* This node tests if the result of \node is in the result of \a list. Optionally it can be inverted with \a notin which by default is false.
1152+
*/
11041153
NodeInOperator( QgsExpression::Node *node SIP_TRANSFER, QgsExpression::NodeList *list SIP_TRANSFER, bool notin = false )
11051154
: mNode( node )
11061155
, mList( list )
@@ -1134,6 +1183,11 @@ class CORE_EXPORT QgsExpression
11341183
class CORE_EXPORT NodeFunction : public QgsExpression::Node
11351184
{
11361185
public:
1186+
1187+
/**
1188+
* A function node consists of an index of the function in the global function array and
1189+
* a list of arguments that will be passed to it.
1190+
*/
11371191
NodeFunction( int fnIndex, QgsExpression::NodeList *args SIP_TRANSFER );
11381192

11391193
virtual ~NodeFunction() { delete mArgs; }
@@ -1225,6 +1279,10 @@ class CORE_EXPORT QgsExpression
12251279
class CORE_EXPORT WhenThen
12261280
{
12271281
public:
1282+
1283+
/**
1284+
* A combination of when and then. Simple as that.
1285+
*/
12281286
WhenThen( QgsExpression::Node *whenExp, QgsExpression::Node *thenExp );
12291287
~WhenThen();
12301288

@@ -1233,7 +1291,10 @@ class CORE_EXPORT QgsExpression
12331291
//! WhenThen nodes cannot be copied.
12341292
WhenThen &operator=( const WhenThen &rh ) = delete;
12351293

1236-
WhenThen *clone() const;
1294+
/**
1295+
* Get a deep copy of this WhenThen combination.
1296+
*/
1297+
QgsExpression::WhenThen *clone() const;
12371298

12381299
private:
12391300
#ifdef SIP_RUN
@@ -1252,11 +1313,15 @@ class CORE_EXPORT QgsExpression
12521313
class CORE_EXPORT NodeCondition : public QgsExpression::Node
12531314
{
12541315
public:
1255-
NodeCondition( QgsExpression::WhenThenList *conditions, QgsExpression::Node *elseExp = nullptr )
1256-
: mConditions( *conditions )
1257-
, mElseExp( elseExp )
1258-
{ delete conditions; }
12591316

1317+
/**
1318+
* Create a new node with the given list of \a conditions and an optional \a elseExp expression.
1319+
*/
1320+
NodeCondition( QgsExpression::WhenThenList *conditions, QgsExpression::Node *elseExp = nullptr );
1321+
1322+
/**
1323+
* Create a new node with the given list of \a conditions and an optional \a elseExp expression.
1324+
*/
12601325
NodeCondition( const QgsExpression::WhenThenList &conditions, QgsExpression::Node *elseExp = nullptr ) SIP_SKIP
12611326
: mConditions( conditions )
12621327
, mElseExp( elseExp )

0 commit comments

Comments
 (0)
Please sign in to comment.