Number: Difference between revisions

From Bohemia Interactive Community
Jump to navigation Jump to search
(added technical specs)
(Add infinity representation string table)
 
(30 intermediate revisions by 7 users not shown)
Line 1: Line 1:
=Number Type=
{{TOC|side}}
A real number, i.e. 1, -25, 6.52, 1805.6352
A number is, depending on scope, either a {{Link|https://en.wikipedia.org/wiki/Single-precision_floating-point_format|single precision floating-point number}} (when talking about scripting) or a range of numerical types when talking about config context.


Numbers are stored as [http://en.wikipedia.org/wiki/Single-precision_floating-point_format single precision floating point numbers], which allow for a large range of values with limited precision (generally accurate to 6 or 7 decimal places). The number [[Data Types|data type]] is also sometimes referred to as "scalar" (for example, returned by the [[supportInfo]] script command).


The largest real positive number that can be entered via script is:  3.4028235e38
== Scripting ==


The largest real negative number that can be entered via script is: -3.4028235e38
In [[SQF Syntax|SQF]], there are multiple accepted number formats.
However, all of them will result in the same {{hl|SCALAR}} ([[typeName]]) value type '''as long as they remain within float range''';


Larger numbers: In scripts it is possible to generate a representation of an infinite positive or negative number which compares even larger or smaller than the above two floating point limits;
{| class="wikitable float-right"
|+ Infinity string representation
! Value
! Before<br>{{GVI|arma3|2.18}}
! Since<br>{{GVI|arma3|2.18}}
|-
| +Inf
| {{hl|1.#INF}}
| {{hl|inf}}
|-
| -Inf
| {{hl|-1.#INF}}
| {{hl|-inf}}
|}
The '''{{Color|#080|largest positive}}''' number that can be achieved is {{hl|3.4028235e38}} and the '''{{Color|#800|largest negative}}''' is {{hl|-3.4028235e38}}.
It is possible to generate positive or negative infinity values using either {{hl|1e39}} or {{hl|-1e39}}, both being of {{hl|"NaN"}} [[typeName]].


Positive infinity  1e39  = "1.#INF"
To check if a number is finite one can use the [[finite]] operator.


Negative infinity -1e39  = "-1.#INF"
{{Feature|informative|Regex to match all numbers in [[SQF Syntax|SQF]] is {{hl|<nowiki>(((\$|0x)[0-9a-fA-F]+)|(\.[0-9]+))|(\b[0-9]+(\.[0-9]+|[eE][-+]?[0-9]+)?)\b</nowiki>}}}}
{{Feature|important|Due to technical limitations, the precision of floating-point numbers is limited. Please refer to {{Link|https://en.wikipedia.org/wiki/IEEE_754|IEEE 754}} for more info about the technical details.}}


Indeterminate (NaN) = "-1.#IND"
=== Decimal (Base 10) ===


A decimal number is your normal {{hl|0.5}} syntax stuff with one extra: You may omit the initial pack of digits.


The [[finite]] command can be used to verify if a number represents infinity or NaN.
Some Examples would be:
* {{hl|5.197}}
* {{hl|&nbsp;0.47}}
* {{hl|&nbsp;16.0}}
* {{hl|.8314}}
* {{hl|12345}}


===Technical Specification===
A regex catching these kind of numbers could look like this {{hl|<nowiki>((\.[0-9]+)|(\b[0-9]+(\.[0-9]+)?))\b</nowiki>}}
A number is a sequence of characters starting either with a digit, an '''$''' or a '''.'''. If it starts with a digit it may be an integer (e.g. 3), a floating point number (e.g. 3.2) or a hexadecimal number (see below). If it starts with a '''$''' it is also a hexadecimal number and if it starts with a '''.''' it is a floating point number smaller than 0 (e.g. .1 = 0.1).
If the number is not hexadecimal it may contain exactly one period and ends before the first non-digit character (except that one period of course). The only exception from that is the scientific notation.


The scientific notation in SQF has the syntax <code>([0-9]+.)?[0-9]+[eE][0-9]+</code>
==== Scientific Notation ====
The {{Link|https://en.wikipedia.org/wiki/Scientific_notation|Scientific Notation}} is a way of expressing numbers that are too big or too small to be conveniently written in decimal form.


That means it consists of a pre-factor that can be any number (integer or floating point). Then a '''e''' or '''E''' and at the end an <b>integer</b> (a whole number). This will then be interpreted in the following way
It starts of like a normal decimal and then gets expressed by an {{hl|E}} (Not case-sensitive, thus {{hl|e}} is also valid) followed by an '''optional''' {{hl|+}} or {{hl|-}} sign and ends with a range of digits.


<code>aEb = a * 10^b</code>
Some examples would be:
<b>Examples:</b>
* {{hl|1.23E4 ⇔ 1.23 ⋅ 10<sup>4 </sup> ⇔ 12300}}
<code>1e2 = 1E2 = 100<br>5e2 = 5E2 = 500<br>1.234e4 = 1.234E4 = 12340</code>
* {{hl|5e-2  ⇔    5 ⋅ 10<sup>-2</sup> ⇔  0.05}}


If omitted the exponent '''b''' will be considered to be zero and therefore
A regex catching these kind of numbers could look like this  {{hl|([0-9]+.)?[0-9]+[eE][+-]?[0-9]+}}
<pre>aE = a</pre>
Although the result is being calculated the engine will issue an error on that becasue the exponent is not optional!
If the pre-factor '''a''' is omitted it is no longer a number as it doesn't start with a digit or a period. If one tries to use a hexadecimal number as the pre-factor the '''e''' will simply be interpreted as part of that hexadecimal number and therefore it is no longer a scientific notation.


Essentially numbers in SQF are in the format the '''atof''' function in C(++) expects numbers to be (See http://www.cplusplus.com/reference/cstdlib/atof/) with the exception that hexadecimals can also start with a '''$''' as well.
=== Hexadecimal (Base 16) ===


==Hex numbers==
In [[SQF Syntax|SQF]], {{Link|https://en.wikipedia.org/wiki/Hexadecimal|hexadecimal}} (also base 16, or hex) is a positional numeral system with a base of 16.
They start either with {{hl|0x}} or with a single {{hl|$}}.


Arma supports hexadecimal numbers in both scripts and configs. Most common notation for hex numbers is '''0x''' followed by the hexadecimal value. Alternatively symbol '''$''' can be used for the same thing. It is also possible to mix and match notations:
This gets followed by one of the following characters: {{hl|0 1 2 3 4 5 6 7 8 9 A B C D E F}}.<br>
Note that casing does not matter, thus both {{hl|0xa}} and {{hl|0xA}} are valid.


<code>[[hint]] [[str]] 0xFF; //255
Some Examples would be:
[[hint]] [[str]] $FF; //255
* {{hl|0xa5}}
[[hint]] [[str]] (0xFF + $FF + 255); //765</code>
* {{hl|$5C}}
Hexadecimal numbers are case-insensitive:
* {{hl|$FFFFFF}}
<pre>0xFF = 0xff</pre>
* {{hl|0x123ABC}}


==Degrees==
A regex catching these kind of numbers could look like this {{hl|<nowiki>((\$|0x)[0-9a-fA-F]+)\b</nowiki>}}


Degrees are a poetic label used to indicate a number returned from functions like [[acos]] and [[asin]]


It's special properties are that it will always supply a value from 0 to 360
== Config ==


==Radians==
Unlike scripting, configs actually do allow for multiple number types (Integer, [[Float]], etc). They are properly stored with their corresponding type in mind.
{{Feature|informative|In a config, a [[Number]] can also mean a [[Boolean]]: in [[Description.ext]] for example, <syntaxhighlight lang="cpp" inline>disabledAI = 1;</syntaxhighlight> means [[true]].}}


Another poetic label for a Number. Used in angular math computations with commands like [[rad]] and [[deg]]
<syntaxhighlight lang="cpp">
class MyClass
{
myInt = 1; // integer
myFloat = 0.01; // float
};


==Scripting vs Addons==
// description.ext example
===Integers and Floats===
disabledAI = 1; // boolean: 0 = false, everything else = true (usually 1)
Note that unlike config.cpp's (addons), a ''Number'' in scripting language is '''ANY''' numeric entity. Floats, or integers. It is NOT the same as a config's [[Integer]] or [[Float]]. Number covers both types.
</syntaxhighlight>


===Booleans===


Note also, unlike config.cpp's, [[Boolean]] is a real type in scripting language. In addons, it is a poetic licence for a zero/non zero [[Integer]]. In Arma 3 command [[parseNumber]] has been extended to accept booleans:
== Floating-point Precision ==
 
Humans are typically used to performing mathematical calculations on the set of ''real numbers'' (ℝ). There are no gaps between real numbers, i.e. there is always another real number between two real numbers. However, as mentioned above, every number in scripting is a ''floating-point number''. Because any given floating-point number can only consist of a finite amount of bits (a computer's memory is finite after all), any given floating-point format can only represent a finite amount of distinct numbers. Consequently, there are gaps between floating-point numbers.
 
This induces the following problem: There are real numbers that the computer does not have a binary representation for (and that it therefore can not work with) because there is no representation for these numbers in the specific floating-point format used by the computer. Of course, by extension, this also applies to the [[Real Virtuality]] Engine - there are real numbers that it does not have a representation for.
 
This issue is dealt with by rounding to the nearest number that can actually be represented as a floating-point number.
 
{| class="wikitable" style="margin: auto"
|-
! <var>n</var> ∈ ℝ !! <var>n</var> in {{arma3}}<br><span style="font-weight: normal">(value of <sqf inline>n toFixed 20</sqf>)</span>
|- style="background-color: lightgreen"
| 0 || 0.00000000000000000000
|- style="background-color: lightgreen"
| 1 || 1.00000000000000000000
|-
| 1.1 || 1.10000002384185790000
|- style="background-color: lightgreen"
| 2.5 || 2.50000000000000000000
|-
| 2.51 || 2.50999999046325680000
|}
 
Unfortunately, this rounding introduces a new problem in the form of unexpected, seemingly erroneous behaviour: For instance, despite being entirely correct mathematically, the expression <sqf inline>0.3 + 0.4 == 0.7</sqf> surprisingly returns [[false]] in {{arma3}}. In order to understand why this happens, examine the evaluation of the expression step by step:
# The 0.3 from the source code has to be rounded to 0.30000001192092896
# The 0.4 from the source code has to be rounded to 0.40000000596046448
# Now the addition can be performed: 0.30000001192092896 + 0.40000000596046448 = 0.70000004768371582<br>(that is the result with floating-point arithmetic; the result of the same addition in ℝ is 0.70000001788139344)
# The 0.7 from the source code has to be rounded to 0.69999998807907104
# Finally, the comparison <sqf inline>0.70000004768371582 == 0.69999998807907104</sqf> returns [[false]]
 
To add to the confusion, <sqf inline>0.3 + 0.4</sqf> will actually output {{hl|0.7}} in the [[Arma 3: Debug Console|Debug Console]] or when used with commands like [[hint]] or [[systemChat]] - that is because numbers are rounded yet again when they are converted to [[String]] for the output. If this needs to be avoided, the [[toFixed]] command can be used to obtain the accurate value of a number.
 
Floating-point formats are designed so that the density of floating-point numbers is highest around the number zero. Accordingly, there are more floating-point numbers between 0 and 1 than there are between 100,000 and 100,001. As such, the gaps between consecutive floating-point numbers with small absolute values are also small, while the gaps between consecutive floating-point numbers with large absolute values become increasingly larger. For instance, the next larger floating-point number after 87,654,320 is 87,654,328 in {{arma3}}.
 
=== Consequences ===
 
* Fractional floating-point numbers should not be compared for exact equality. Instead, one should check the distance (i.e. absolute difference) between the numbers. Numbers can then be considered equal if the distance between them is smaller than some threshold (e.g. 0.000001). Consequently, expressions like <sqf inline>0.3 + 0.4 == 0.7</sqf> should be replaced with expressions such as <sqf inline>_res = 0.3 + 0.4; abs (_res - 0.7) < 0.000001</sqf>.<br>Note that this is only necessary if fractional numbers are involved; if only whole numbers are involved, this procedure is not necessary.
* Large numbers can not always be incremented / decremented. For example, <sqf inline>87654320 + 1</sqf> returns {{hl|87,654,320}} because any real number between 87,654,316 and 87,654,324 has to be rounded to 87,654,320 in {{arma3}}.
 


<code>[[hint]] [[str]] [[parseNumber]] [[true]]; //1</code>
[[Category: Data Types]]
[[Category: Data Types]]

Latest revision as of 13:07, 26 September 2024

A number is, depending on scope, either a single precision floating-point number (when talking about scripting) or a range of numerical types when talking about config context.


Scripting

In SQF, there are multiple accepted number formats. However, all of them will result in the same SCALAR (typeName) value type as long as they remain within float range;

Infinity string representation
Value Before
Arma 3 logo black.png2.18
Since
Arma 3 logo black.png2.18
+Inf 1.#INF inf
-Inf -1.#INF -inf

The largest positive number that can be achieved is 3.4028235e38 and the largest negative is -3.4028235e38. It is possible to generate positive or negative infinity values using either 1e39 or -1e39, both being of "NaN" typeName.

To check if a number is finite one can use the finite operator.

Regex to match all numbers in SQF is (((\$|0x)[0-9a-fA-F]+)|(\.[0-9]+))|(\b[0-9]+(\.[0-9]+|[eE][-+]?[0-9]+)?)\b
Due to technical limitations, the precision of floating-point numbers is limited. Please refer to IEEE 754 for more info about the technical details.

Decimal (Base 10)

A decimal number is your normal 0.5 syntax stuff with one extra: You may omit the initial pack of digits.

Some Examples would be:

  • 5.197
  •  0.47
  •  16.0
  • .8314
  • 12345

A regex catching these kind of numbers could look like this ((\.[0-9]+)|(\b[0-9]+(\.[0-9]+)?))\b

Scientific Notation

The Scientific Notation is a way of expressing numbers that are too big or too small to be conveniently written in decimal form.

It starts of like a normal decimal and then gets expressed by an E (Not case-sensitive, thus e is also valid) followed by an optional + or - sign and ends with a range of digits.

Some examples would be:

  • 1.23E4 ⇔ 1.23 ⋅ 104 ⇔ 12300
  • 5e-2 ⇔ 5 ⋅ 10-2 ⇔ 0.05

A regex catching these kind of numbers could look like this ([0-9]+.)?[0-9]+[eE][+-]?[0-9]+

Hexadecimal (Base 16)

In SQF, hexadecimal (also base 16, or hex) is a positional numeral system with a base of 16. They start either with 0x or with a single $.

This gets followed by one of the following characters: 0 1 2 3 4 5 6 7 8 9 A B C D E F.
Note that casing does not matter, thus both 0xa and 0xA are valid.

Some Examples would be:

  • 0xa5
  • $5C
  • $FFFFFF
  • 0x123ABC

A regex catching these kind of numbers could look like this ((\$|0x)[0-9a-fA-F]+)\b


Config

Unlike scripting, configs actually do allow for multiple number types (Integer, Float, etc). They are properly stored with their corresponding type in mind.

In a config, a Number can also mean a Boolean: in Description.ext for example, disabledAI = 1; means true.
class MyClass
{
	myInt = 1;		// integer
	myFloat = 0.01;	// float
};

// description.ext example
disabledAI = 1;		// boolean: 0 = false, everything else = true (usually 1)


Floating-point Precision

Humans are typically used to performing mathematical calculations on the set of real numbers (ℝ). There are no gaps between real numbers, i.e. there is always another real number between two real numbers. However, as mentioned above, every number in scripting is a floating-point number. Because any given floating-point number can only consist of a finite amount of bits (a computer's memory is finite after all), any given floating-point format can only represent a finite amount of distinct numbers. Consequently, there are gaps between floating-point numbers.

This induces the following problem: There are real numbers that the computer does not have a binary representation for (and that it therefore can not work with) because there is no representation for these numbers in the specific floating-point format used by the computer. Of course, by extension, this also applies to the Real Virtuality Engine - there are real numbers that it does not have a representation for.

This issue is dealt with by rounding to the nearest number that can actually be represented as a floating-point number.

n ∈ ℝ n in Arma 3
(value of n toFixed 20)
0 0.00000000000000000000
1 1.00000000000000000000
1.1 1.10000002384185790000
2.5 2.50000000000000000000
2.51 2.50999999046325680000

Unfortunately, this rounding introduces a new problem in the form of unexpected, seemingly erroneous behaviour: For instance, despite being entirely correct mathematically, the expression 0.3 + 0.4 == 0.7 surprisingly returns false in Arma 3. In order to understand why this happens, examine the evaluation of the expression step by step:

  1. The 0.3 from the source code has to be rounded to 0.30000001192092896
  2. The 0.4 from the source code has to be rounded to 0.40000000596046448
  3. Now the addition can be performed: 0.30000001192092896 + 0.40000000596046448 = 0.70000004768371582
    (that is the result with floating-point arithmetic; the result of the same addition in ℝ is 0.70000001788139344)
  4. The 0.7 from the source code has to be rounded to 0.69999998807907104
  5. Finally, the comparison 0.70000004768371582 == 0.69999998807907104 returns false

To add to the confusion, 0.3 + 0.4 will actually output 0.7 in the Debug Console or when used with commands like hint or systemChat - that is because numbers are rounded yet again when they are converted to String for the output. If this needs to be avoided, the toFixed command can be used to obtain the accurate value of a number.

Floating-point formats are designed so that the density of floating-point numbers is highest around the number zero. Accordingly, there are more floating-point numbers between 0 and 1 than there are between 100,000 and 100,001. As such, the gaps between consecutive floating-point numbers with small absolute values are also small, while the gaps between consecutive floating-point numbers with large absolute values become increasingly larger. For instance, the next larger floating-point number after 87,654,320 is 87,654,328 in Arma 3.

Consequences

  • Fractional floating-point numbers should not be compared for exact equality. Instead, one should check the distance (i.e. absolute difference) between the numbers. Numbers can then be considered equal if the distance between them is smaller than some threshold (e.g. 0.000001). Consequently, expressions like 0.3 + 0.4 == 0.7 should be replaced with expressions such as _res = 0.3 + 0.4; abs (_res - 0.7) < 0.000001.
    Note that this is only necessary if fractional numbers are involved; if only whole numbers are involved, this procedure is not necessary.
  • Large numbers can not always be incremented / decremented. For example, 87654320 + 1 returns 87,654,320 because any real number between 87,654,316 and 87,654,324 has to be rounded to 87,654,320 in Arma 3.