Expressions/Mathematical operators

modules/ROOT/content-nav.adoc

@@ -72,6 +72,7 @@
 *** xref:expressions/predicates/string-operators.adoc[]
 *** xref:expressions/predicates/path-pattern-expressions.adoc[]
 *** xref:expressions/predicates/type-predicate-expressions.adoc[]
+** xref:expressions/mathematical-operators.adoc[]
 ** xref:expressions/conditional-expressions.adoc[]
 
 * xref:functions/index.adoc[]

modules/ROOT/pages/appendix/gql-conformance/supported-mandatory.adoc

@@ -185,7 +185,7 @@ For example, `RETURN sum(<expr>)` on an empty table returns `NULL` in GQL, but i
 
 | 20.21
 | <numeric value expression>
-| xref:syntax/operators.adoc#query-operators-mathematical[Mathematical operators]
+| xref:expressions/mathematical-operators.adoc[Mathematical operators]
 |
 
 | 20.22

modules/ROOT/pages/expressions/index.adoc

@@ -11,4 +11,5 @@ For details and examples of specific expressions, see the following sections:
 ** xref:expressions/predicates/string-operators.adoc[]: `STARTS WITH`, `ENDS WITH`, `CONTAINS`, `IS NORMALIZED`, `IS NOT NORMALIZED`, `=~`
 ** xref:expressions/predicates/path-pattern-expressions.adoc[]: information about filtering queries with path pattern expressions.
 ** xref:expressions/predicates/type-predicate-expressions.adoc[]: information about how to verify the value type of a Cypher expression.
+* xref:expressions/mathematical-operators.adoc[]: `+`, `-`, `*`, `/`, `%`, `^`.
 * xref:expressions/conditional-expressions.adoc[]

modules/ROOT/pages/expressions/mathematical-operators.adoc

@@ -0,0 +1,257 @@
+= Mathematical operators
+:description: Information about Cypher's mathematical operators.
+:table-caption!:
+
+Cypher contains the following mathematical operators:
+
+* Addition or unary addition: `+`
+* Subtraction or unary minus: `-`
+* Multiplication: `*`
+* Division: `/`
+* Modulo division: `%`
+* Exponentiation: `^`
+
+For additional mathematical expressions, see:
+
+* xref:functions/mathematical-logarithmic.adoc[Logarithmic functions]
+* xref:functions/mathematical-numeric.adoc[Numeric functions]
+* xref:functions/mathematical-trigonometric.adoc[Trigonometric functions]
+
+[[examples]]
+== Examples
+
+.Addition operator (`+`)
+[source, cypher]
+----
+RETURN 10 + 5 AS result
+----
+
+.Result
+[role="queryresult",options="header,footer",cols="1*<m"]
+|===
+| result
+
+| 15
+
+1+d|Rows: 1
+|===
+
+.Unary addition operator (`+`)
+[source, cypher]
+----
+RETURN + 5 AS result
+----
+
+.Result
+[role="queryresult",options="header,footer",cols="1*<m"]
+|===
+| result
+
+| 5
+
+1+d|Rows: 1
+|===
+
+
+.Subtraction operator (`-`)
+[source, cypher]
+----
+RETURN 10 - 5 AS result
+----
+
+.Result
+[role="queryresult",options="header,footer",cols="1*<m"]
+|===
+| result
+
+| 5
+
+1+d|Rows: 1
+|===
+
+.Unary subtraction operator (`-`)
+[source, cypher]
+----
+RETURN - 5 AS result
+----
+
+.Result
+[role="queryresult",options="header,footer",cols="1*<m"]
+|===
+| result
+
+| -5
+
+1+d|Rows: 1
+|===
+
+.Multiplication operator (`*`)
+[source, cypher]
+----
+RETURN 10 * 5 AS result
+----
+
+.Result
+[role="queryresult",options="header,footer",cols="1*<m"]
+|===
+| result
+
+| 50
+
+1+d|Rows: 1
+|===
+
+.Division operator (`/`)
+[source, cypher]
+----
+RETURN 10 / 5 AS result
+----
+
+.Result
+[role="queryresult",options="header,footer",cols="1*<m"]
+|===
+| result
+
+| 2
+
+1+d|Rows: 1
+|===
+
+.Modulo division operator (`%`)
+[source, cypher]
+----
+RETURN 10 % 3 AS result
+----
+
+.Result
+[role="queryresult",options="header,footer",cols="1*<m"]
+|===
+| result
+
+| 1
+
+1+d|Rows: 1
+|===
+
+
+.Exponentiation operator (`^`)
+[source, cypher]
+----
+RETURN 10 ^ 5 AS result
+----
+
+.Result
+[role="queryresult",options="header,footer",cols="1*<m"]
+|===
+| result
+
+| 100000.0
+
+1+d|Rows: 1
+|===
+
+
+.Modifying properties using mathematical operators
+[source, cypher]
+----
+CREATE (p:Product {price: 10})
+SET p.discountPrice = p.price * (1 - 0.15)
+RETURN p.discountPrice AS discountPrice
+----
+
+.Result
+[role="queryresult",options="header,footer",cols="1*<m"]
+|===
+| discountPrice
+
+| 8.5
+
+1+d|Rows: 1
+|===
+
+
+[[order-of-precedence]]
+== Order of precedence
+
+The following table details the order of precedence of the mathematical operators in ascending order.
+Note, the lower the precedence level, the higher the binding power of the operands.
+Also note, if parentheses `()` are used, any operation within them takes precedence, overriding the default order of precedence.
+
+.Mathematical operators: order of precedence
+[options="header"cols="a,2a,2a"]
+|===
+| Precedence | Operators | Associativity
+
+| 1 | Unary negation (`-`), unary positive (`+`) | Right to left
+| 2 | Exponentiation (`^`) | Right to left
+| 3 | Multiplication (`*`), division (`/`), modulo division (`%`) | Left to right
+| 4 | Addition (`+`), subtraction (`-`) | Left to right
+
+|===
+
+Operators within the same precedence group are evaluated based on associativity.
+
+The order of precedence ensures that the following two expressions return the same result.
+
+.Expression with several different mathematical operations
+[source, cypher]
+----
+RETURN -50 + 6 * 3 - 100 / 5 ^ 2 % 12 AS result1, 
+       (((-50) + (6 * 3)) - ((100 / (5 ^ 2)) % 12)) AS result2
+----
+
+.Result
+[role="queryresult",options="header,footer",cols="2*<m"]
+|===
+| result1 | result2
+
+| -36 | -36
+
+1+d|Rows: 1
+|===
+
+.Order of evaluation
+[options="header", cols="a,2a,a"]
+|===
+| Precedence | Operation | Result
+
+| 1 | Unary negation (`-50`) | `-50`
+| 2 | Exponentiation (`5 ^ 2`) | `25`
+| 3 | Multiplication (`6 * 3`) | `18`
+| 3 | Division (`100 / 25`) | `4`
+| 3 | Modulo division (`4 % 12`) | `4`
+| 4 | Addition (`-50 + 18`) | `-32`
+| 4 | Subtraction (`-32 - 4`) | `-36`
+
+|===
+
+Only bracketing some of the operations within parentheses will change the order of precedence and may, therefore, change the result of an expression.
+
+.Parenthesizing single operation
+[source, cypher]
+----
+RETURN (-50 + 6) * 3 - 100 / 5 ^ 2 % 12 AS result
+----
+
+.Result
+[role="queryresult",options="header,footer",cols="1*<m"]
+|===
+| result
+
+| -136
+
+1+d|Rows: 1
+|===
+
+.Changed order of evaluation
+[options="header",cols="a,2a,a"]
+|===
+| Precedence | Operation | Result
+
+| 1 | Parenthesized operation (`-50 + 6`) | `-44`
+| 2 | Exponentiation (`5 ^ 2`) | `25`
+| 3 | Multiplication (`-44 * 3`) | `132`
+| 3 | Division (`100 / 25`) | `4`
+| 3 | Modulo division (`4 % 12`) | `4`
+| 4 | Subtraction (`-132 - 4`) |  `-136`
+|===

modules/ROOT/pages/functions/mathematical-logarithmic.adoc

@@ -4,7 +4,7 @@
 [[query-functions-logarithmic]]
 = Mathematical functions - logarithmic
 
-Logarithmic mathematical functions operate on numeric expressions only, and will return an error if used on any other values. See also xref::syntax/operators.adoc#query-operators-mathematical[Mathematical operators].
+Logarithmic mathematical functions operate on numeric expressions only, and will return an error if used on any other values. See also xref:expressions/mathematical-operators.adoc[Mathematical operators].
 
 
 [[functions-e]]

modules/ROOT/pages/functions/mathematical-numeric.adoc

@@ -5,7 +5,7 @@
 = Mathematical functions - numeric
 
 Numeric mathematical functions operate on numeric expressions only, and will return an error if used on any other values.
-See also xref::syntax/operators.adoc#query-operators-mathematical[Mathematical operators].
+See also xref:expressions/mathematical-operators.adoc[Mathematical operators].
 
 [[example-graph]]
 == Example graph

modules/ROOT/pages/functions/mathematical-trigonometric.adoc

@@ -4,7 +4,7 @@
 [[query-functions-trigonometric]]
 = Mathematical functions - trigonometric
 
-Trigonometric mathematical functions operate on numeric expressions only, and will return an error if used on any other values. See also xref::syntax/operators.adoc#query-operators-mathematical[Mathematical operators].
+Trigonometric mathematical functions operate on numeric expressions only, and will return an error if used on any other values. See also xref:expressions/mathematical-operators.adoc[Mathematical operators].
 
 [[functions-acos]]
 == acos()

modules/ROOT/pages/syntax/operators.adoc

@@ -12,7 +12,6 @@ This page contains an overview of the available Cypher operators.
 |===
 | xref::syntax/operators.adoc#query-operators-aggregation[Aggregation operators] | `DISTINCT`
 | xref::syntax/operators.adoc#query-operators-property[Property operators] | `.` for static property access, `[]` for dynamic property access, `=` for replacing all properties, `+=` for mutating specific properties
-| xref::syntax/operators.adoc#query-operators-mathematical[Mathematical operators] | `+`, `-`, `*`, `/`, `%`, `^`
 | xref::syntax/operators.adoc#query-operators-string[String operators]   | `+` and `\|\|` (string concatenation), `IS NORMALIZED`
 | xref::syntax/operators.adoc#query-operators-temporal[Temporal operators]   | `+` and `-` for operations between durations and temporal instants/durations, `*` and `/` for operations between durations and numbers
 | xref::syntax/operators.adoc#query-operators-map[Map operators]       |  `.` for static value access by key, `[]` for dynamic value access by key
@@ -189,59 +188,6 @@ The properties on the node are updated as follows by those provided in the map:
 
 See xref::clauses/set.adoc#set-setting-properties-using-map[Mutate specific properties using a map and `+=`] for more details on using the property mutation operator `+=`.
 
-
-[[query-operators-mathematical]]
-== Mathematical operators
-
-The mathematical operators comprise:
-
-* addition: `+`
-* subtraction or unary minus: `-`
-* multiplication: `*`
-* division: `/`
-* modulo division: `%`
-* exponentiation: `^`
-
-
-[[syntax-using-the-exponentiation-operator]]
-=== Using the exponentiation operator `^`
-
-.Query
-[source, cypher]
-----
-WITH 2 AS number, 3 AS exponent
-RETURN number ^ exponent AS result
-----
-
-.Result
-[role="queryresult",options="header,footer",cols="1*<m"]
-|===
-| +result+
-| +8.0+
-1+d|Rows: 1
-|===
-
-
-[[syntax-using-the-unary-minus-operator]]
-=== Using the unary minus operator `-`
-
-.Query
-[source, cypher]
-----
-WITH -3 AS a, 4 AS b
-RETURN b - a AS result
-----
-
-.Result
-[role="queryresult",options="header,footer",cols="1*<m"]
-|===
-| +result+
-| +7+
-
-1+d|Rows: 1
-|===
-
-
 [[query-operators-string]]
 == String operators