[Python-Dev] New operations in Decimal

[Facundo Batista]

The following are the new operations in the decimal module that we'll
be available according to the last published specification.

I wrote here the proposed name by me, the original name between
parenthesis, where it will be located between square brackets (C for
context and D for the decimal object itself), and a small description
of the operation (I specially trimmed the verbose special cases from
the description, if you want an exact explanation of what does each,
read the spec).

Note that always it says how many operands it takes. The number
implies you're calling it through the context. If called through
Decimal, you have to substract one from it (as the first operand will
be the number itself in this case).

Enjoy it, and any feedback is very appreciated, :)


- compare_signal (compare–signal) [CD]: Takes two operands and
  compares their values numerically (pretty much like compare(), but all
  NaNs signal, with signaling NaNs taking precedence over quiet NaNs. 

- fma (fused-multiply-add) [C]: Takes three operands; the first two are
  multiplied together, using multiply, the third operand is then added
  to the result of that multiplication, using add, all with only one
  final rounding.

- ln (ln) [CD]: Takes one operand, and the result is the natural (base
  e) logarithm of the operand.

- log10 (log10) [CD]: Takes one operand, and the result is the base 10
  logarithm of the operand.

- max_mag (max–magnitude), and min_mag (min-magnitude) [CD]: Takes two
  operands and compares their values numerically with their sign
  ignored. 

- next_minus (next–minus) [CD]: Takes one operand and the result is the
  largest representable number that is smaller than the operand.

- next_plus (next–plus) [CD]: Takes one operand and the result is the
  smallest representable number that is larger than the operand.

- next_toward (next–toward) [CD]: Takes two operands and the result is
  the representable number closest to the first operand (but not the
  first operand) that is in the direction towards the second operand,
  unless the operands have the same value.

- to_integral_exact (round-to-integral-exact) [C]: Takes one operand. It
  is similar to the round–to–integral–value (the old to_integral), with
  the difference the now Inexact and Rounded flags are allowed in the
  result.


The following operations appear in a new section of the specification
called "Miscelaneous Operations". Between these are logical
operations that take logical operands, which are finite positive
non-exponent numbers with a coefficient whose digits must all be either
0 or 1.

- and (and), or (or), xor (xor) [CD]: Takes two logical operands, the
  result is the logical operation applied between each digit.

- canonical (canonical) [CD]: Canonical takes one operand, returns the
  same Decimal object, as we do not have different encodings for the
  same number.

- number_class (class) [CD]: Takes one operando, returns an indication
  of the class of the operand, where the class is one of the following:
  "sNaN", "NaN", "–Infinity", "–Normal", "–Subnormal", "–Zero", "+Zero",
  "+Subnormal", "+Normal" or "+Infinity".

- compare_total (compare–total) [CD]: Takes two operands and compares
  them using their abstract representation rather than their numerical
  value (a total ordering is defined for all possible abstract
  representations).

- compare_total_mag (compare–total–magnitude) [CD]: Takes two operands
  and compares them using their abstract representation rather than
  their numerical value, with their sign ignored and assumed to be 0.

- copy_abs (copy-abs) [CD]: Takes one operand, returns a copy of it
  with the sign set to 0.

- copy_negate (copy-negate) [CD]: Takes one operand, returns a copy of
  it with the sign inverted.

- copy_sign (copy–sign) [CD]: Takes two operands, returns a copy of the
  first operand with the sign equal to the sign of the second operand.

- invert (invert) [CD]: Takes one logical operand, the result is the
  digit-wise inversion of the operand. 

- is-canonical (is–canonical) [CD]: Takes one operand, returns 1 if the
  operand is canonical; otherwise returns 0. 

- is_finite (is–finite) [CD]: Takes one operand, returns 1 if the
  operand is neither infinite nor a NaN, otherwise returns 0. 

- is_infinite (is–infinite) [CD]: Takes one operand, returns 1 if the
  operand is an Infinite, otherwise returns 0. 

- is_nan (is–NaN) [CD]: Takes one operand, returns 1 if the operand is
  a quiet or signaling NaN, otherwise returns 0. 

- is_normal (is–normal) [CD]: Takes one operand, returns 1 if the
  operand is a positive or negative normal number, otherwise returns 0. 

- is_qnan (is–qNaN) [CD]: Takes one operand, returns 1 if the operand
  is a quiet NaN, otherwise returns 0. 

- is_signed (is–signed) [CD]: Takes one operand, returns 1 if the sign
  of the operand is 1, otherwise returns 0. 

- is_snan (is–sNaN) [CD]: Takes one operand, returns 1 if the operand
  is a signaling NaN, otherwise returns 0.   

- is_subnormal (is–subnormal) [CD]: Takes one operand, returns 1 if the
  operand is a positive or negative subnormal number, otherwise returns
  0.

- is_zero (is–zero) [CD]: Takes one operand, returns 1 if the operand
  is a zero, otherwise returns 0. 

- logb (logb) [CD]: Takes one operand, returns the integer which is the
  exponent of the magnitude of the most significant digit of the operand
  (as though the operand were truncated to a single digit while
  maintaining the value of that digit and without limiting the resulting
  exponent). 

- radix (radix) [CD]: Takes no operands, returns 10.

- rotate (rotate) [CD]: Takes two operands. The coefficient of the
  result is a rotated copy of the digits in the coefficient of the first
  operand. The number of places of rotation is taken from the absolute
  value of the second operand, with the rotation being to the left if
  the second operand is positive or to the right otherwise.

- scaleb (scaleb) [CD]: Takes two operands. The result is the first
  operand modified by adding the value of the second operand to its
  exponent. 

- shift (shift) [CD]: Takes two operands. The coefficient of the result
  is a shifted copy of the digits in the coefficient of the first
  operand. The number of places to shift is taken from the absolute
  value of the second operand, with the shift being to the left if the
  second operand is positive or to the right otherwise. Digits shifted
  into the coefficient are zeros.


Regards,

-- 
.   Facundo
.
Blog: http://www.taniquetil.com.ar/plog/
PyAr: http://www.python.org/ar/