Arithmetic operations

• abs
• add and subtract
• compare
• compare-signal
• divide
• divide-integer
• exp
• fused-multiply-add
• ln
• log10
• max
• max-magnitude
• min
• min-magnitude
• minus and plus
• multiply
• next-minus
• next-plus
• next-toward
• power
• quantize
• reduce
• remainder
• remainder-near
• round-to-integral-exact
• round-to-integral-value
• square-root

Arithmetic operation notation

Also, operations are indicated as functions (taking up to three operands), and the sequence ==> means ‘results in’. Hence:

  add(’12’, ’7.00’) ==> ’19.00’

Finally, in this example and in the examples below, the context is assumed to have precision set to 9, rounding set to round-half-up, and all trap-enablers set to 0.

Arithmetic operation rules

• Every operation on finite numbers is carried out (as described under the individual operations below) as though an exact mathematical result is computed, using integer arithmetic on the coefficient where possible.
  If the coefficient of the theoretical exact result has no more than precision digits, then (unless there is an underflow or overflow) it is used for the result without change. Otherwise (it has more than precision digits) it is rounded (shortened) to exactly precision digits, using the current rounding algorithm, and the exponent is increased by the number of digits removed.
  If the value of the adjusted exponent of the result is less than E_min (that is, the result is zero or subnormal), the calculated coefficient and exponent form the result, unless the value of the exponent is less than E_tiny, in which case the exponent will be set to E_tiny, the coefficient will be rounded (if necessary, and possibly to zero) to match the adjustment of the exponent, and the sign is unchanged.
  If the result (before rounding) was non-zero and subnormal then the Subnormal exceptional condition is raised. If rounding of a subnormal result leads to an inexact result then the Underflow exceptional condition is also raised.
  If the value of the adjusted exponent of a non-zero result is larger than E_max, then an exceptional condition (overflow) results. In this case, the result is as defined under the Overflow exceptional condition, and may be infinite. It will have the same sign as the theoretical result.^[1] 
• Arithmetic using the special value infinity follows the usual rules, where [1,inf] is less than every finite number and [0,inf] is greater than every finite number. Under these rules, an infinite result is always exact. Certain uses of infinity raise an Invalid operation condition.
• signaling NaNs always raise the Invalid operation condition when used as an operand to an arithmetic operation.
• The Invalid operation condition may also be raised when an operand to an operation is invalid (for example, if it exceeds the bounds that an implementation can handle, or the operation is a logarithm and the operand is negative).
• The result of any arithmetic operation which has an operand which is a NaN (a quiet NaN or a signaling NaN) is [s,qNaN] or [s,qNaN,d]. The sign and any diagnostic information is copied from the first operand which is a signaling NaN, or if neither is signaling then from the first operand which is a NaN. Whenever a result is a NaN, the sign of the result depends only on the copied operand (the following rules do not apply).
• The sign of the result of a multiplication or division will be 1 only if the operands have different signs.
• The sign of the result of an addition or subtraction will be 1 only if the result is less than zero, except for the special cases below where the result is a negative 0.
• A result which is a negative zero ([1,0,n]) can occur only when:
  • a result is rounded to zero, and the value before rounding had a sign of 1.
  • the operation is an addition of [1,0,n] to [1,0,n], or a subtraction of [0,0,n] from [1,0,n]
  • the operation is an addition of operands with opposite signs (or is a subtraction of operands with the same sign), the result has a coefficient of 0, and the rounding is round-floor.
  • the operation is a multiplication or division and the result has a coefficient of 0 and the signs of the operands are different.
  • the operation is power, the left-hand operand is [1,0,n], and the right-hand operand is positive, integral, and odd.
  • the operation is power, the left-hand operand is [1,inf], and the right-hand operand is negative, integral, and odd.
  • the operation is quantize or a round-to-integral, the left-hand operand is negative, and the magnitude of the result is zero. In either case the final exponent may be non-zero.
  • the operation is square-root and the operand is [1,0,n].
  • the operation is one of the operations max, max-magnitude, min, min-magnitude, next-plus, next-toward, reduce, or is a copy operation.

Examples involving special values:

  add(’Infinity’, ’1’)        ==>  ’Infinity’
  add(’NaN’, ’1’)             ==>  ’NaN’
  add(’NaN’, ’Infinity’)      ==>  ’NaN’
  subtract(’1’, ’Infinity’)   ==>  ’-Infinity’
  multiply(’-1’, ’Infinity’)  ==>  ’-Infinity’
  subtract(’-0’, ’0’)         ==>  ’-0’
  multiply(’-1’, ’0’)         ==>  ’-0’
  divide(’1’, ’0’)            ==>  ’Infinity’
  divide(’1’, ’-0’)           ==>  ’-Infinity’
  divide(’-1’, ’0’)           ==>  ’-Infinity’

1. Operands may have more than precision digits and are not rounded before use.
2. The context (precision and rounding, etc.) for an operation might be wholly implied, or be a global or local setting, or be passed to operations individually – depending on the implementation of the specification (for example, in a programming language).
3. NaNs propagate any associated diagnostic information as described in IEEE 854 §6.2. The meaning of any such diagnostic information is outside the scope of this specification, but typically indicates the origin of the NaN. In IEEE 754-2008, this information is only held in the coefficient of decimal numbers and does not use the first digit of the coefficient.
4. The rules above imply that the compare operation can return a quiet NaN as a result, which indicates an ‘unordered’ comparison (see IEEE 754 §5.11).
5. An implementation may use the compare operation ‘under the covers’ to implement a closed set of comparison operations (greater than, equal, etc.) if desired. In this case, the additional constraints detailed in IEEE 754 §5.11 will apply; that is, a comparison (such a ‘greater than’) which does not explicitly allow for an ‘unordered’ result yet would require an unordered result will give rise to an Invalid operation condition.
6. If a result is rounded, remains finite, and is not subnormal, its coefficient will have exactly precision digits (except after the quantize or round-to-integral operations, as described below). That is, only unrounded or subnormal coefficients can have fewer than precision digits.
7. Trailing zeros are not removed after operations. The reduce operation may be used to remove trailing zeros if desired.

abs

Examples:

  abs(’2.1’)    ==>  ’2.1’
  abs(’-100’)   ==>  ’100’
  abs(’101.5’)  ==>  ’101.5’
  abs(’-101.5’) ==>  ’101.5’

add and subtract

Otherwise, the operands are added (after inverting the sign used for the second operand if the operation is a subtraction), as follows:

• The coefficient of the result is computed by adding or subtracting the aligned coefficients of the two operands. The aligned coefficients are computed by comparing the exponents of the operands:
  • If they have the same exponent, the aligned coefficients are the same as the original coefficients.
  • Otherwise the aligned coefficient of the number with the larger exponent is its original coefficient multiplied by 10ⁿ, where n is the absolute difference between the exponents, and the aligned coefficient of the other operand is the same as its original coefficient.
  If the signs of the operands differ then the smaller aligned coefficient is subtracted from the larger; otherwise they are added.
• The exponent of the result is the minimum of the exponents of the two operands.
• The sign of the result is determined as follows:
  • If the result is non-zero then the sign of the result is the sign of the operand having the larger absolute value.
  • Otherwise, the sign of a zero result is 0 unless either both operands were negative or the signs of the operands were different and the rounding is round-floor.

Examples:

  add(’12’, ’7.00’)        ==>  ’19.00’
  add(’1E+2’, ’1E+4’)      ==>  ’1.01E+4’
  subtract(’1.3’, ’1.07’)  ==>  ’0.23’
  subtract(’1.3’, ’1.30’)  ==>  ’0.00’
  subtract(’1.3’, ’2.07’)  ==>  ’-0.77’

compare

Otherwise, the operands are compared as follows.

If the signs of the operands differ, a value representing each operand (’-1’ if the operand is less than zero, ’0’ if the operand is zero or negative zero, or ’1’ if the operand is greater than zero) is used in place of that operand for the comparison instead of the actual operand.^[2] 

The comparison is then effected by subtracting the second operand from the first and then returning a value according to the result of the subtraction: ’-1’ if the result is less than zero, ’0’ if the result is zero or negative zero, or ’1’ if the result is greater than zero.

An implementation may use this operation ‘under the covers’ to implement a closed set of comparison operations (greater than, equal, etc.) if desired. It need not, in this case, expose the compare operation itself.

Examples:

  compare(’2.1’, ’3’)     ==>  ’-1’
  compare(’2.1’, ’2.1’)   ==>  ’0’
  compare(’2.1’, ’2.10’)  ==>  ’0’
  compare(’3’, ’2.1’)     ==>  ’1’
  compare(’2.1’, ’-3’)    ==>  ’1’
  compare(’-3’, ’2.1’)    ==>  ’-1’

1. The result of compare is always exact and unrounded, and may be a NaN.
2. The compare-total operation can be used for a non-numerical comparison which provides a total ordering over the abstract representation of values.

compare-signal

divide

Otherwise, if the divisor is zero then either the Division undefined condition is raised (if the dividend is zero) and the result is NaN, or the Division by zero condition is raised and the result is an Infinity with a sign which is the exclusive or of the signs of the operands.

Otherwise, a ‘long division’ is effected, as follows:

• An integer variable, adjust, is initialized to 0.
• If the dividend is non-zero, the coefficient of the result is computed as follows (using working copies of the operand coefficients, as necessary):
  1. The operand coefficients are adjusted so that the coefficient of the dividend is greater than or equal to the coefficient of the divisor and is also less than ten times the coefficient of the divisor, thus:
     • While the coefficient of the dividend is less than the coefficient of the divisor it is multiplied by 10 and adjust is incremented by 1.
     • While the coefficient of the dividend is greater than or equal to ten times the coefficient of the divisor the coefficient of the divisor is multiplied by 10 and adjust is decremented by 1.
  2. The result coefficient is initialized to 0.
  3. The following steps are then repeated until the division is complete:
     • While the coefficient of the divisor is smaller than or equal to the coefficient of the dividend the former is subtracted from the latter and the coefficient of the result is incremented by 1.
     • If the coefficient of the dividend is now 0 and adjust is greater than or equal to 0, or if the coefficient of the result has precision digits, the division is complete.
       Otherwise, the coefficients of the result and the dividend are multiplied by 10 and adjust is incremented by 1.
  4. Any remainder (the final coefficient of the dividend) is recorded and taken into account for rounding.^[3] 
  Otherwise (the dividend is zero), the coefficient of the result is zero and adjust is unchanged (is 0).
• The exponent of the result is computed by subtracting the sum of the original exponent of the divisor and the value of adjust at the end of the coefficient calculation from the original exponent of the dividend.
• The sign of the result is the exclusive or of the signs of the operands.

Examples:

  divide(’1’, ’3’  )      ==>  ’0.333333333’
  divide(’2’, ’3’  )      ==>  ’0.666666667’
  divide(’5’, ’2’  )      ==>  ’2.5’
  divide(’1’, ’10’ )      ==>  ’0.1’
  divide(’12’, ’12’)      ==>  ’1’
  divide(’8.00’, ’2’)     ==>  ’4.00’
  divide(’2.400’, ’2.0’)  ==>  ’1.20’
  divide(’1000’, ’100’)   ==>  ’10’
  divide(’1000’, ’1’)     ==>  ’1000’
  divide(’2.40E+6’, ’2’)  ==>  ’1.20E+6’

• The ideal (simplest) exponent for the result of a division is the exponent of the dividend less the exponent of the divisor.
• After the division, if the result is exact then the coefficient and exponent giving the correct value and with the exponent closest to the ideal exponent is returned. If the result is inexact, the coefficient will have exactly precision digits (unless the result is subnormal), and the exponent will be set appropriately.

divide-integer

Otherwise, the result returned is defined to be that which would result from repeatedly subtracting the divisor from the dividend while the dividend is larger than or equal to the divisor. During this subtraction, the absolute values of both the dividend and the divisor are used: the sign of the final result is the same as that which would result if normal division were used.

In other words, if the operands x and y were given to the divide-integer and remainder operations, resulting in i and r respectively, then the identity

The exponent of the result must be 0. Hence, if the result cannot be expressed exactly within precision digits, the operation is in error and will fail – that is, the result cannot have more digits than the value of precision in effect for the operation, and will not be rounded. For example, divide-integer(’10000000000’, ’3’) requires ten digits to express the result exactly (’3333333333’) and would therefore fail if precision were in the range 1 through 9.

Notes:

1. The divide-integer operation may not give the same result as truncating normal division (which could be affected by rounding and might be Inexact).
2. The divide-integer and remainder operations are defined so that they may be calculated as a by-product of the standard division operation (described above). The division process is ended as soon as the integer result is available; the residue of the dividend is the remainder.
3. The divide and divide-integer operation on the same operands give results of the same numerical value if no error occurs and there is no residue from the divide-integer operation.

Examples:

  divide-integer(’2’, ’3’)    ==>  ’0’
  divide-integer(’10’, ’3’)   ==>  ’3’
  divide-integer(’1’, ’0.3’)  ==>  ’3’

exp

Otherwise, the result is e raised to the power of the operand, with the following cases:

• If the operand is –Infinity, the result is 0 and exact.
• If the operand is a zero, the result is 1 and exact.
• If the operand is +Infinity, the result is +Infinity and exact.
• Otherwise the result is inexact and will be rounded using the round-half-even algorithm. The coefficient will have exactly precision digits (unless the result is subnormal). These inexact results should be correctly rounded, but may be up to 1 ulp (unit in last place) in error.

Examples:

  exp(’-Infinity’)    ==> ’0’
  exp(’-1’)           ==> ’0.367879441’
  exp(’0’)            ==> ’1’
  exp(’1’)            ==> ’2.71828183’
  exp(’0.693147181’)  ==> ’2.00000000’
  exp(’+Infinity’)    ==> ’Infinity’

1. The rounding setting in the context is not used; this means that the algorithm described in Variable Precision Exponential Function by T. E. Hull and A. Abrham (ACM Transactions on Mathematical Software, Vol 12 #2, pp79–91, ACM, June 1986) may be used for this operation.
2. When the result is inexact, the cost of exp at precision d is likely to be at least 13×log₂(d) times the cost of an inexact multiplication at the same precision (see Multiple-precision zero-finding methods and the complexity of elementary function evaluation by R. P. Brent, in Analytic Computational Complexity pp151–176, Academic Press, York, 1976, and Fast Multiple-Precision Evaluation of Elementary Functions by the same author, in Journal of the ACM (JACM), Vol 23 # 2, pp242–251, ACM, April 1976).

fused-multiply-add

Unless the multiplication failed, the third operand is then added to the result of that multiplication, using add, under the current context.

In other words, fused-multiply-add(x, y, z) delivers a result which is (x × y) + z with only the one, final, rounding.

Examples:

  fused-multiply-add(’3’, ’5’, ’7’)               ==>  ’22’
  fused-multiply-add(’3’, ’-5’, ’7’)              ==>  ’-8’
  fused-multiply-add(’888565290’, ’1557.96930’,
                                  ’-86087.7578’)  ==>  ’1.38435736E+12’

ln

Otherwise, the operand must be a zero or positive, and the result is the natural (base e) logarithm of the operand, with the following cases:

• If the operand is a zero, the result is –Infinity and exact.
• If the operand is +Infinity, the result is +Infinity and exact.
• If the operand equals one, the result is 0 and exact.
• Otherwise the result is inexact and will be rounded using the round-half-even algorithm. The coefficient will have exactly precision digits (unless the result is subnormal). These inexact results should be correctly rounded, but may be up to 1 ulp (unit in last place) in error.

Examples:

  ln(’0’)           ==> ’-Infinity’
  ln(’1.000’)       ==> ’0’
  ln(’2.71828183’)  ==> ’1.00000000’
  ln(’10’)          ==> ’2.30258509’
  ln(’+Infinity’)   ==> ’Infinity’

1. The rounding setting in the context is not used.
2. When the result is inexact, the cost of ln at a given precision is likely to be similar to, or more expensive than, the exp function (see notes under that function).

log10

Otherwise, the operand must be a zero or positive, and the result is the base 10 logarithm of the operand, with the following cases:

• If the operand is a zero, the result is –Infinity and exact.
• If the operand is +Infinity, the result is +Infinity and exact.
• If the operand equals an integral power of ten (including 10⁰ and negative powers) and there is sufficient precision to hold the integral part of the result, the result is an integer (with an exponent of 0) and exact.
• Otherwise the result is inexact and will be rounded using the round-half-even algorithm. The coefficient will have exactly precision digits (unless the result is subnormal). These inexact results should be correctly rounded, but may be up to 1 ulp (unit in last place) in error.

Examples:

  log10(’0’)          ==> ’-Infinity’
  log10(’0.001’)      ==> ’-3’
  log10(’1.000’)      ==> ’0’
  log10(’2’)          ==> ’0.301029996’
  log10(’10’)         ==> ’1’
  log10(’70’)         ==> ’1.84509804’
  log10(’+Infinity’)  ==> ’Infinity’

1. The rounding setting in the context is not used.
2. When the result is inexact, the cost of log10 at a given precision is likely to be similar to, or more expensive than, the exp function (see notes under that function).

max

Otherwise, the operands are compared as as though by the compare operation. If they are not numerically equal then the maximum (closer to positive infinity) of the two operands is chosen as the result. Otherwise (they are numerically equal):

• if the operand signs differ the operand with sign 0 is chosen
• if the signs and exponents are equal the operands are identical so either can be chosen
• if the signs are both positive, the operand with the maximum exponent is chosen
• if the signs are both negative, the operand with the minimum exponent is chosen.

For numerical results, the result is the same as using the plus operation on the chosen operand, except that the sign of a zero does not change.

Examples:

  max(’3’, ’2’)    ==>  ’3’
  max(’-10’, ’3’)  ==>  ’3’
  max(’1.0’, ’1’)  ==>  ’1’
  max(’7’, ’NaN’)  ==>  ’7’

max-magnitude

If, without signs, the first operand is the larger then the original first operand is returned (that is, with the original sign). If, without signs, the second operand is the larger then the original second operand is returned. Otherwise the result is the same as from the max operation.

min

Otherwise, the operands are compared as as though by the compare operation. If they are not numerically equal then the minimum (closer to negative infinity) of the two operands is chosen as the result. Otherwise (they are numerically equal):

• if the operand signs differ the operand with sign 1 is chosen
• if the signs and exponents are equal the operands are identical so either can be chosen
• if the signs are both positive, the operand with the minimum exponent is chosen
• if the signs are both negative, the operand with the maximum exponent is chosen.

For numerical results, the result is the same as using the plus operation on the chosen operand, except that the sign of a zero does not change.

Examples:

  min(’3’, ’2’)    ==>  ’2’
  min(’-10’, ’3’)  ==>  ’-10’
  min(’1.0’, ’1’)  ==>  ’1.0’
  min(’7’, ’NaN’)  ==>  ’7’

min-magnitude

If, without signs, the first operand is the smaller then the original first operand is returned (that is, with the original sign). If, without signs, the second operand is the smaller then the original second operand is returned. Otherwise the result is the same as from the min operation.

minus and plus

The operations are evaluated using the same rules as add and subtract; the operations plus(a) and minus(a) (where a and b refer to any numbers) are calculated as the operations add(’0’, a) and subtract(’0’, b) respectively, where the ’0’ has the same exponent as the operand.

Examples:

  plus(’1.3’)    ==>  ’1.3’
  plus(’-1.3’)   ==>  ’-1.3’
  minus(’1.3’)   ==>  ’-1.3’
  minus(’-1.3’)  ==>  ’1.3’

multiply

Otherwise, the operands are multiplied together (‘long multiplication’), resulting in a number which may be as long as the sum of the lengths of the two operands, as follows:

• The coefficient of the result, before rounding, is computed by multiplying together the coefficients of the operands.
• The exponent of the result, before rounding, is the sum of the exponents of the two operands.
• The sign of the result is the exclusive or of the signs of the operands.

Examples:

  multiply(’1.20’, ’3’)         ==>  ’3.60’
  multiply(’7’, ’3’)            ==>  ’21’
  multiply(’0.9’, ’0.8’)        ==>  ’0.72’
  multiply(’0.9’, ’-0’)         ==>  ’-0.0’
  multiply(’654321’, ’654321’)  ==>  ’4.28135971E+11’

next-minus

In the following examples, E_max and E_min are assumed to be +999 and –999 respectively.

Examples:

  next-minus(’1’)            ==>  ’0.999999999’
  next-minus(’1E-1007’)      ==>  ’0E-1007’
  next-minus(’-1.00000003’)  ==>  ’-1.00000004’
  next-minus(’Infinity’)     ==>  ’9.99999999E+999’

next-plus

In the following examples, E_max and E_min are assumed to be +999 and –999 respectively.

Examples:

  next-plus(’1’)            ==>  ’1.00000001’
  next-plus(’-1E-1007’)     ==>  ’-0E-1007’
  next-plus(’-1.00000003’)  ==>  ’-1.00000002’
  next-plus(’-Infinity’)    ==>  ’-9.99999999E+999’

next-toward

• If the second operand is larger than the first operand then the result is the result of the operation next-plus on the first operand
• If the second operand is smaller than the first operand then the result is the result of the operation next-minus on the first operand
• If the two operands are numerically equal, then the result is a copy of the first operand with the sign set to be the same as the sign of the second operand; in this case no flags are set.

In the following examples, E_max and E_min are assumed to be +999 and –999 respectively.

Examples:

  next-toward(’1’, ’2’)              ==>  ’1.00000001’
  next-toward(’-1E-1007’, ’1’)       ==>  ’-0E-1007’
  next-toward(’-1.00000003’, ’0’)    ==>  ’-1.00000002’
  next-toward(’1’, ’0’)              ==>  ’0.999999999’
  next-toward(’1E-1007’, ’-100’)     ==>  ’0E-1007’
  next-toward(’-1.00000003’, ’-10’)  ==>  ’-1.00000004’
  next-toward(’0.00’, ’-0.0000’)     ==>  ’-0.00’

power

The following rules apply:

• If both operands are zero, or if the left-hand operand is less than zero and the right-hand operand does not have an integral value^[9]  or is infinite, an Invalid operation condition is raised, the result is [0,qNaN], and the following rules do not apply.
• If the left-hand operand is infinite, the result will be exact and will be infinite if the right-hand side is positive, 1 if the right-hand side is a zero, and 0 if the right-hand side is negative.
• If the left-hand operand is a zero, the result will be exact and will be infinite if the right-hand side is negative or 0 if the right-hand side is positive.
• If the right-hand operand is a zero, the result will be 1 and exact.
• In cases not covered above, the result will be inexact unless the right-hand side has an integral value and the result is finite and can be expressed exactly within precision digits. In this latter case, if the result is unrounded then its exponent will be that which would result if the operation were calculated by repeated multiplication (if the second operand is negative then the reciprocal of the first operand is used, with the absolute value of the second operand determining the multiplications).
• Inexact finite results should be correctly rounded, but may be up to 1 ulp (unit in last place) in error.
• The sign of the result will be 1 only if the right-hand side has an integral value and is odd (and is not infinite) and also the sign of the left-hand side is 1. In all other cases, the sign of the result will be 0.

Examples:

  power(’2’, ’3’)             ==>  ’8’
  power(’-2’, ’3’)            ==>  ’-8’
  power(’2’, ’-3’)            ==>  ’0.125’
  power(’1.7’, ’8’)           ==>  ’69.7575744’
  power(’10’, ’0.301029996’)  ==>  ’2.00000000’
  power(’Infinity’, ’-1’)     ==>  ’0’
  power(’Infinity’, ’0’)      ==>  ’1’
  power(’Infinity’, ’1’)      ==>  ’Infinity’
  power(’-Infinity’, ’-1’)    ==>  ’-0’
  power(’-Infinity’, ’0’)     ==>  ’1’
  power(’-Infinity’, ’1’)     ==>  ’-Infinity’
  power(’-Infinity’, ’2’)     ==>  ’Infinity’
  power(’0’, ’0’)             ==>  ’NaN’

1. When the result is inexact, the cost of power at a given precision is likely to be at least twice as expensive as the exp function (see notes under that function).
2. An infinite result is always exact, as described in the general rules.
3. Versions of this specification prior to version 1.48 defined a simpler power operation which only required support for integer powers.
4. It can be argued that the special cases where one operand is zero and the other is infinite (such as power(’0’, ’Infinity’) and power(’Infinity’, ’0’)) should return a NaN, whereas the specification above leads to results of 0 and 1 respectively for the two examples (for compatibility with the earlier version of this operation). If NaN results are desired instead, then these special cases should be tested for before calling the power operation.

quantize

Otherwise (both operands are finite), quantize returns the number which is equal in value (except for any rounding) and sign to the first (left-hand) operand and which has an exponent set to be equal to the exponent of the second (right-hand) operand.

The coefficient of the result is derived from that of the left-hand operand. It may be rounded using the current rounding setting (if the exponent is being increased), multiplied by a positive power of ten (if the exponent is being decreased), or is unchanged (if the exponent is already equal to that of the right-hand operand).

Unlike other operations, if the length of the coefficient after the quantize operation would be greater than precision then an Invalid operation condition is raised. This guarantees that, unless there is an error condition, the exponent of the result of a quantize is always equal to that of the right-hand operand.

Also unlike other operations, quantize will never raise Underflow, even if the result is subnormal and inexact.

Examples:

  quantize(’2.17’, ’0.001’)        ==>  ’2.170’
  quantize(’2.17’, ’0.01’)         ==>  ’2.17’
  quantize(’2.17’, ’0.1’)          ==>  ’2.2’
  quantize(’2.17’, ’1e+0’)         ==>  ’2’
  quantize(’2.17’, ’1e+1’)         ==>  ’0E+1’
  quantize(’-Inf’  ’Infinity’)     ==>  ’-Infinity’
  quantize(’2’,    ’Infinity’)     ==>  ’NaN’
  quantize(’-0.1’, ’1’  )          ==>  ’-0’
  quantize(’-0’,   ’1e+5’)         ==>  ’-0E+5’
  quantize(’+35236450.6’, ’1e-2’)  ==>  ’NaN’
  quantize(’-35236450.6’, ’1e-2’)  ==>  ’NaN’
  quantize(’217’,  ’1e-1’)         ==>  ’217.0’
  quantize(’217’,  ’1e+0’)         ==>  ’217’
  quantize(’217’,  ’1e+1’)         ==>  ’2.2E+2’
  quantize(’217’,  ’1e+2’)         ==>  ’2E+2’

1. In the penultimate example the result is [0,22,1], leading to the string in scientific notation as shown.
2. This operation was previously called rescale, which had identical semantics except that the second operand specified the power of ten of the quantum. The quantize semantics specifies the desired quantum by example, which allows a faster implementation in most cases.
3. The sign and coefficient of the second operand are ignored; this allows a ‘match the quantum of a variable’ operation to be effected directly.

reduce

That is, while the coefficient is non-zero and a multiple of ten the coefficient is divided by ten and the exponent is incremented by 1. Otherwise (the coefficient is zero) the exponent is set to 0. In all cases the sign is unchanged.

Examples:

  reduce(’2.1’)     ==>  ’2.1’
  reduce(’-2.0’)    ==>  ’-2’
  reduce(’1.200’)   ==>  ’1.2’
  reduce(’-120’)    ==>  ’-1.2E+2’
  reduce(’120.00’)  ==>  ’1.2E+2’
  reduce(’0.00’)    ==>  ’0’

remainder

Otherwise, the result is the residue of the dividend after the operation of calculating integer division as described for divide-integer, rounded to precision digits if necessary. The sign of the result, if non-zero, is the same as that of the original dividend.

This operation will fail under the same conditions as integer division (that is, if integer division on the same two operands would fail, the remainder cannot be calculated).

Examples:

  remainder(’2.1’, ’3’)    ==>  ’2.1’
  remainder(’10’, ’3’)     ==>  ’1’
  remainder(’-10’, ’3’)    ==>  ’-1’
  remainder(’10.2’, ’1’)   ==>  ’0.2’
  remainder(’10’, ’0.3’)   ==>  ’0.1’
  remainder(’3.6’, ’1.3’)  ==>  ’1.0’

1. The divide-integer and remainder operations are defined so that they may be calculated as a by-product of the standard division operation (described above). The division process is ended as soon as the integer result is available; the residue of the dividend is the remainder.
2. The sign of the result will always be sign of the dividend.
3. The remainder operation differs from the remainder operation defined in IEEE 754 (the remainder-near operator), in that it gives the same results for numbers whose values are equal to integers as would the usual remainder operator on integers.
   For example, the result of the operation remainder(’10’, ’6’) as defined here is ’4’, and remainder(’10.0’, ’6’) would give ’4.0’ (as would remainder(’10’, ’6.0’) or remainder(’10.0’, ’6.0’)). The IEEE 754 remainder operation would, however, give the result ’-2’ because its integer division step chooses the closest integer, not the one nearer zero.

remainder-near

Otherwise, if the operands are given by x and y, then the result is defined to be x – y × n, where n is the integer nearest the exact value of x ÷ y (if two integers are equally near then the even one is chosen). If the result is equal to 0 then its sign will be the sign of x. (See IEEE 754 §5.3.1.)

This operation will fail under the same conditions as integer division (that is, if integer division on the same two operands would fail, the remainder cannot be calculated), except when the quotient is very close to 10 raised to the power of the precision.^[10] 

Examples:

  remainder-near(’2.1’, ’3’)    ==>  ’-0.9’
  remainder-near(’10’, ’6’)     ==>  ’-2’
  remainder-near(’10’, ’3’)     ==>  ’1’
  remainder-near(’-10’, ’3’)    ==>  ’-1’
  remainder-near(’10.2’, ’1’)   ==>  ’0.2’
  remainder-near(’10’, ’0.3’)   ==>  ’0.1’
  remainder-near(’3.6’, ’1.3’)  ==>  ’-0.3’

1. The remainder-near operation differs from the remainder operation in that it does not give the same results for numbers whose values are equal to integers as would the usual remainder operator on integers. For example, the operation remainder(’10’, ’6’) gives the result ’4’, and remainder(’10.0’, ’6’) gives ’4.0’ (as would the operations remainder(’10’, ’6.0’) or remainder(’10.0’, ’6.0’)). However, remainder-near(’10’, ’6’) gives the result ’-2’ because its integer division step chooses the closest integer, not the one nearer zero.
2. The result of this operation is always exact.
3. This operation is sometimes known as ‘IEEE remainder’.

round-to-integral-exact

Otherwise (the operand has a negative exponent) the result is the same as using the quantize operation using the given operand as the left-hand-operand, 1E+0 as the right-hand-operand, and the precision of the operand as the precision setting. The rounding mode is taken from the context, as usual.

Examples:

  round-to-integral-exact(’2.1’)      ==>  ’2’
  round-to-integral-exact(’100’)      ==>  ’100’
  round-to-integral-exact(’100.0’)    ==>  ’100’
  round-to-integral-exact(’101.5’)    ==>  ’102’
  round-to-integral-exact(’-101.5’)   ==>  ’-102’
  round-to-integral-exact(’10E+5’)    ==>  ’1.0E+6’
  round-to-integral-exact(’7.89E+77’) ==>  ’7.89E+77’
  round-to-integral-exact(’-Inf’)     ==>  ’-Infinity’

round-to-integral-value

square-root

Otherwise, the ideal exponent of the result is defined to be half the exponent of the operand (rounded to an integer, towards –Infinity,^[11]  if necessary) and then:

• If the operand is less than zero an Invalid operation condition is raised.
• If the operand is greater than zero, the result is the square root of the operand. If no rounding is necessary (the exact result requires precision digits or fewer) then the the coefficient and exponent giving the correct value and with the exponent closest to the ideal exponent is used. If the result must be inexact, it is rounded using the round-half-even algorithm and the coefficient will have exactly precision digits (unless the result is subnormal), and the exponent will be set to maintain the correct value.
• Otherwise (the operand is equal to zero), the result will be the zero with the same sign as the operand and with the ideal exponent.

Examples:

  square-root(’0’)     ==> ’0’
  square-root(’-0’)    ==> ’-0’
  square-root(’0.39’)  ==> ’0.62449980’
  square-root(’100’)   ==> ’10’
  square-root(’1’)     ==> ’1’
  square-root(’1.0’)   ==> ’1.0’
  square-root(’1.00’)  ==> ’1.0’
  square-root(’7’)     ==> ’2.64575131’
  square-root(’10’)    ==> ’3.16227766’

1. The rounding setting in the context is not used; this means that the algorithm described in Properly Rounded Variable Precision Square Root by T. E. Hull and A. Abrham (ACM Transactions on Mathematical Software, Vol 11 #3, pp229–237, ACM, September 1985) may be used for this operation.
2. A subnormal result is only possible if the working precision is greater than E_max+1.
3. The rules for setting the exponent of the result apply to many operations; they can be used for any operation for which an ideal exponent can be defined.
4. A negative zero is allowed as an operand as per IEEE 754 §5.4.1.
5. Square-root can also be calculated by using the power operation (with a second operand of 0.5). The result in that case will not be exact in most cases, and may not be correctly rounded.^[12]