$DOUBLE; $DOUBLE

Returns a number converted to a 64-bit floating point value.

The outline

$DOUBLE(num)
Copy the code

parameter

• Num Specifies the value to be converted. You can also specify the string”NAN“And”INF“(and variations).

describe

$DOUBLE returns a number converted to an IEEE DOUBLE (64-bit) floating-point data type. This type of floating point number can contain up to 20 digits. To an IEEE double precision (64-bit) floating point data type. If num has more than 20 digits, $DOUBLE rounds the decimal part to the appropriate number of digits. If the integer part of num is greater than 20 digits, $DOUBLE rounds the integer to 20 significant digits and represents the rest with zero.

$DOUBLE converts a Cache float to an IEEE DOUBLE float. $DECIMAL performs a reverse operation to convert an IEEE double floating-point number to a standard Cache floating-point number.

$DOUBLE generates a floating-point value that conforms to the IEEE DOUBLE precision (64-bit) binary floating-point standard. It is primarily used for interchangeability and compatibility with applications that use this data type standard. IEEE floating point numbers are represented in binary notation. They have an accuracy of 53 binary bits, corresponding to 15.95 decimal digits. (Note that the binary representation does not correspond exactly to the decimal part.)

IEEE floats have a larger range of min/Max values than standard Cache floats. However, standard Cache floating-point numbers have higher precision. In most cases, it is best to use standard Cache floating-point numbers.

Note: Cache numeric string literals outside the minimum/maximum range supported by Cache floating-point data types such as “1E128” are automatically converted to IEEE double-precision floating-point numbers. This conversion is performed only on numeric text; It is not performed on the result of a mathematical operation. This automatic conversion can be controlled on a per-process basis using the TruncateOverflow () method of the % System.process class. You can establish system-wide default behavior by setting the TruncateOverflow property of the config. Miscellaneous class.

The num value can be specified as a number or a numeric string. Resolves to canonical form (removes leading and trailing zeros, resolves multiple signs, and so on). Before the $DOUBLE conversion. Specifying a non-numeric string for num returns 0. Specifying a mixed numeric string for num (such as “7Dwarves” or “7.5.4”) truncates the input value of the first non-numeric character and then converts the numeric part. The $DOUBLE value supplied to a JSON array or JSON object follows different validation and conversion rules.

The CacheSQL data types DOUBLE and DOUBLE PRECISION represent IEEE floating point numbers. The FLOAT data type represents a standard Cache floating point number.

Parity comparison and hybrid algorithms

Because the number generated by $DOUBLE is converted to a binary representation that does not correspond exactly to a decimal number, equality comparisons between a $DOUBLE value and a standard Cache floating-point value can produce unexpected results and should generally be avoided. Comparisons between $DOUBLE values and standard Cache floating-point values can be performed precisely without rounding.

A combined arithmetic operation containing a $DOUBLE value and one or more standard Cache numbers returns a $DOUBLE value. In mixed arithmetic, the Cache automatically converts all numbers to $DOUBLE before performing the arithmetic operation. The Cache handles the conversion and comparison between $DOUBLE numeric representations. Therefore, these operations are the same on all platforms. However, the arithmetic operations involving the $DOUBLE value are controlled by the underlying operating system, so they can sometimes vary from platform to platform.

Integer division

For some values, Cache decimal floating-point numbers and IEEE doubles produce different integer division products. Such as:

DHC-APP> WRITE ! ."Cache /: ".4.1/.01           / / 410
 
Cache  /: 410DHC-APP>WRITE ! ."Double /: ",$DOUBLE(4.1) /.01  / / 410
 
Double /: 409.99999999999994316DHC-APP>WRITE ! ."Cache \: ".4.1\.01           / / 410
 
Cache  \: 410DHC-APP>WRITE ! ."Double \: ",$DOUBLE(4.1) \.01  / / 409
 
Double \: 409
Copy the code

Platform independence

Standard Cache DECIMAL floating-point numbers ($DECIMAL numbers) have an accuracy of about 18.96 DECIMAL numbers. The precision of all system platforms supported by Cache is consistent.

IEEE DOUBLE floating-point numbers ($doubles) have a standard internal representation that is platform-independent.

Conversions and comparisons between $DOUBLE and $DECIMAL are consistent across all system platforms supported by Cache. However, depending on the system platform, other calculations of the $DOUBLE number may show slight differences.

INF and NAN

By IEEE standards, $DOUBLE can return the strings INF(infinity) and NaN(not a number). Inf can be positive or negative (Inf and -INF); NaN is always unsigned. Although these are valid IEEE return values, they are not actual numbers.

INF and NAN as input values

One way to cause $DOUBLE to return INF and NAN is to specify the corresponding string as the num input value. These input strings are case insensitive and can be signed plus or minus (INF resolves symbols, NAN ignores symbols). To return NAN, specify “NAN”, “sNAN”, “+ NAN”, “-nan”. To return INF, specify INF, + INF, Infinity. To return -INF, specify -INF, +-INF.

IEEEError

IEEEError controls how $DOUBLE responds to unparsed numeric conversions. If IEEEError is set to 0, INF and NAN will be returned if $DOUBLE cannot resolve the conversion. If IEEEError is set to 1, $DOUBLE generates standard Cache error code if the conversion cannot be parsed. The default value is 1.

You can control this behavior on a per-process basis using the IEEEError () method of the % System.process class. You can set up system-wide default behavior by setting the IEEEError property of the Config.Miscellaneous class.

Return INF and NAN

When specifying a very large number or an unparsable arithmetic operation, $DOUBLE can return INF and NAN. These values are returned only if IEEEError is set to return INF and NAN.

Very large floating point numbers are not supported. DOUBLE maximum support of binary floating-point number is 1.7976931348623158079 e308. $DOUBLE the minimum supported value for binary floating point numbers is 1.0E-323. Num less than this value returns 0.

Note: The maximum value supported for Cache decimal floating-point numbers is9.223372036854775807 e145. The minimum value supported by the Cache decimal floating point number is2.2250738585072013831 e-308(conventional) or4.9406564584124654654417 e-324(de-normalized).

The following table shows the values returned or errors generated by non-resolvable arithmetic operations:

Compare INF and NAN

INF can be compared as a numeric value. So, INF = INF, INF’= — INF, — INF = — INF, and INF> — INF.

NAN cannot be compared as a numeric value. Because numeric operators cannot be used to meaningfully compare nans (non-numbers), Cache operations (for example, equal, less than, or greater than) attempt to compare $DOUBLE (” NAN “) with another $DOUBLE (” NAN “). Failure. A comparison with NAN <= or > = is a special case.

$LISTSAME does consider the $DOUBLE (” NAN “) list element to be the same as another $DOUBLE (” NAN “) list element.

$ISVALIDENUM,$The NUMBER and $FNUMBER

These ObjectScript functions support the $DOUBLE number.

$ISVALIDNUM Supports INF and NAN. Even though these strings are not numbers, $ISVALIDNUM returns 1 for these values as if they were numbers. When $DOUBLE is specified as a non-numeric string, such as $DOUBLE (” “), the Cache returns 0. Therefore, $ISVALIDNUM ($DOUBLE (” “))) returns 1, because 0 is a number.

$INUMBER and $FNUMBER provide the “D” format option to support the $DOUBLE value. $INUMBER converts numbers to IEEE floating point numbers. $FNUMBER “D” supports case conversions including INF and NAN, as well as choosing whether $DOUBLE (-0) should return 0 or -0.

INF and NAN with operators

You can perform arithmetic and logical operations on INF and NAN. Using the operator with INF and NAN is not recommended; If this is done, the result is as follows:

Arithmetic operators:

No | ` INF - NAN = NAN ` | | free ` INF/NAN = NAN `Copy the code

INF+INF=INF| INF-INF=NAN| INF*INF=INF |INF/INF=NAN

Logical operators:

Other operators, such as pattern matching and concatenation, treat NaN and INF as three-character alphabetic strings.

INF and NAN examples

$DOUBLE returns INF (-INF if negative) if the value exceeds the available precision, as shown in the following example:

/// d ##class(PHA.TEST.Function).double()
ClassMethod double(a)
{
	SET rtn=##class(%SYSTEM.Process).IEEEError(0)
	SET x=$DOUBLE(1.2 e300) WRITE ! ."Double: ",x WRITE ! ."Is number? ",$ISVALIDNUM(x) SET y= $DOUBLE(x*x) WRITE ! ."Double squared: ",y WRITE ! ."Is number? ",$ISVALIDNUM(y)
}

Copy the code

DHC-APP>d ##class(PHA.TEST.Function).double(a)Double: 120000000000000006310000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000 000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000 0000000000000000000000000000000000000000000000000000000000000Is number? 1
Double squared: INF
Is number? 1
Copy the code

$DOUBLE returns a NaN(non-numeric) value if the value is invalid. For example, when an arithmetic expression involves two INF values, as shown in the following example. Arithmetic expressions involving a single INF value return INF.

/// d ##class(PHA.TEST.Function).double1()
ClassMethod double1(a)
{
	SET rtn=##class(%SYSTEM.Process).IEEEError(0)
	SET x=$DOUBLE(1.2 e500) WRITE ! ."Double: ",x WRITE ! ."Is number? ",$ISVALIDNUM(x) SET y= $DOUBLE(x-x) WRITE ! ."Double INF minus INF: ",y WRITE ! ."Is number? ",$ISVALIDNUM(y)
}
Copy the code

DHC-APP>d ##class(PHA.TEST.Function).double1()
 
Double: INF
Is number? 1
Double INF minus INF: NAN
Is number? 1
Copy the code

JSON digital

JSON validation of numeric literals is described in the set command. $DOUBLE numeric literals specified in JSON arrays or JSON objects are subject to the following additional rules:

• Inf,-INFandNaNValues can be stored in JSON structures, but not by%ToJSON()To return. Trying to do so would lead to<ILLEGAL VALUE>Error, as shown in the following example:

/// d ##class(PHA.TEST.Function).double2()
ClassMethod double2(a)
{
	SET jary=[123,($DOUBLE("INF")))// executes successfully
	WRITE jary.%ToJSON()            // fails with <ILLEGAL VALUE> error
}

Copy the code

DHC-APP>d ##class(PHA.TEST.Function).double2()
[123,INF]
Copy the code

$DOUBLE(-0) is stored in the JSON structure as -0.0. $Double(0) is stored as a zero in the JSON structure. The following example shows this:

/// d ##class(PHA.TEST.Function).double3()
ClassMethod double3(a)
{
	SET jary=[0, -0,($DOUBLE(0)),($DOUBLE(-0))] 
	WRITE jary.%ToJSON()  / / returns [0, 0, 0, 0.0]
}
Copy the code

DHC-APP>d ##class(PHA.TEST.Function).double3()
[0,-0,0,0]
Copy the code

The sample

The following example returns a 20-bit floating-point number:

DHC-APP>WRITE ! ,$DOUBLE(999.12345678987654321)
 
999.12345678987651353DHC-APP>WRITE ! ,$DOUBLE(99912345678987654321.)
 
99912345678987657393.DHC-APP>WRITE ! ,$DOUBLE(999123456789.87654321)
 
999123456789.87658691
Copy the code

The following example returns the value of PI as a $DOUBLE value and a standard Cache value. This example shows that an equality operation should not be attempted between $DOUBLE and standard Cache numbers, and that larger bits are returned for standard Cache numbers:

/// d ##class(PHA.TEST.Function).double4()
ClassMethod double4(a)
{ SET x=$ZPI SET y=$DOUBLE($ZPI) IF x=y { WRITE ! ."Same"} ELSE { WRITE ! ."Different"WRITE ! ."standard: ",x WRITE ! ."IEEE float: ",y 
	}
}
Copy the code

DHC-APP>d ##class(PHA.TEST.Function).double4(a)Different
standard:   3.141592653589793238
IEEE float: 3.1415926535897931159
Copy the code

The following example shows that floating point numbers are not necessarily equal to numeric strings of the same value:

/// d ##class(PHA.TEST.Function).double5()
ClassMethod double5(a)
{
	SET x=123.4567891234560
	SET y=123.4567891234567IF x=$DOUBLE(x) { WRITE ! ."Same"} ELSE { WRITE ! ."Different"} IF y=$DOUBLE(y) { WRITE ! ."Same"} ELSE { WRITE ! ."Different"}}Copy the code

DHC-APP>d ##class(PHA.TEST.Function).double5(a)Different
Different
Copy the code

/// d ##class(PHA.TEST.Function).double6()
ClassMethod double6(a)
{
	SET x=1234567891234560
	SET y=1234567891234567IF x=$DOUBLE(x) { WRITE ! ."Same"} ELSE { WRITE ! ."Different"} IF y=$DOUBLE(y) { WRITE ! ."Same"} ELSE { WRITE ! ."Different"}}Copy the code

DHC-APP>d ##class(PHA.TEST.Function).double6(a)Same
Same
Copy the code