-------------------------------------------------------------------------------
DC reverse polish mathematics

a stack based arbitrary-precision calculator

See..  http://wiki.bash-hackers.org/howto/calculate-dc
Also   http://en.wikipedia.org/wiki/Dc_%28Unix%29

Also See "bc" which is a in-fix more language like "dc"
   https://en.wikipedia.org/wiki/Bc_(programming_language)

-------------------------------------------------------------------------------
Basic Usage

Using "dc" command...

  dc <<< '1 1+p'         # bash here string
  echo '1 1+p' | dc      # echo pipe

  dc -e '1 1+p'          # GNU -e expression
  dc -f <(echo '1 1+p')  # GNU -f file with named pipe command


NOTES:
* spaces are only used to separate numbers, otherwise they are ignored
    dc -e '1 1+p'       # result: 1 + 1  => 2

* Use '_' to input a negative number (also start a new number)
    dc -e '1_1-p'       # result: 1 - -1  => 2

* Input letters 'A' to 'F' are equivalent to numbers 10 to 15
    dc -e 'Ap'          # result:  10

* Results are stored as integers unless output is scaled using 'k'
    dc -e '5 3 / p'     # result: 1     -- an integer
    dc -e '2k 5 3 / p'  # result: 1.66  -- scaled result
    dc -e '5 3 / 2k p'  # result: 1     -- stored as integer in memory

Most important operators

Basic...
      #        comment to next newline
     p f       print top or the full stack (stack remains unchanged)
      k        scaling factor (fixed point arithmetic)
      q        quit

   + - * /     basic arithmetic
      %        remainder (of a division)
      ~        quotient then remainder  EG: dc -e '5 2 ~ f'
      ^        power-of  EG:  dc -e '2 3^ p'   # => 2 cubed => 8
      v        sqrt      EG:  dc -e '60k 2v p' # => sqrt(2) to 60 places

Intermediate...
     o i       output and input bases (does not effect numbers in memory)

    d r c      stack:  duplicate, swap top two values, or clear stack
      z        number of elements on stack

      sa       store in register (stack) 'a'
      Sa       pop and push (move) onto the stack 'a'   -- SP = Stack Pop
      la       lookup (copy) top of stack 'a'
      La       pops (move to main stack) top value of stack 'a'

   [string]    push a string (or macro) onto stack

                  dc -e'[hello world]p'

      ?        Ask for input (number, string, or macro)

      P        pop and print string or character code, without newline
               Typically used for prompts and results
                   dc -e '[number to cube = ]P? dd** [result is : ]Pp'

               Example print string with add newline, leaving stack AS IS
                   dc -e '[----]P10P'
               OR
                   dc -e '[----]pSP'

Advanced...
      x        execute a string on top of stack
               Example macro (power of 3 using multiply)
                  dc -e '[dd**] sa   3 la x p'

               Loop forever (recursivally)
               This executes 'H' then re-executes itself 'R'
                  dc -e '[[Hello World]pc] sH  [ lHx lRx ] sR lRx'

     >a        Conditional: Execute macro in 'a' if top is larger than second
     <a        Or top is less than second.   Both values are popped!
               Also can be used for a loop

               Example: Count Down Loop
                  dc -e '[ p 1 -  d 0 <L ] sL    10 lLx  [----]pSP p'
               (value duplicated and compared to zero, leaving just original)

      z        number of elements on the stack (before it is executed)
               This executes 'H' until 5 copies of the string has been pushed!
                  dc -e '[[Hello World]p] sH  [ z 5 <Rx ] sR lRx'

-------------------------------------------------------------------------------
Get an integer...

You must divide by 1 while using a scale of 0 EG '0k1/'
Note that using '0+'  '1*' does not work.

  dc -e '
    8k  5 3 /   [result  = ]P p
    0k1/ 8k     [integer = ]P p
  '

  result  = 1.66666666
  integer = 1

-------------------------------------------------------------------------------
Base Conversions

You must specify input base after output base otherwise you will
need to specify the output base, number using the input base!

  Hexadecimal to Binary (not raw)
    hex=81
    echo "2o 16i ${hex} p" | dc
    10000001

    dc -e '2o 16i DEADBEEF p'
    11011110101011011011111011101111

  Binary to Hexadecimal
    binary=00111100
    echo "16o 2i ${binary} p" | dc
    3C

-------------------------------------------------------------------------------
  Print primes....
    2p3p[dl!d2+s!%0=@l!l^!<#]s#[s/0ds^]s@[p]s&[ddvs^3s!l#x0<&2+l.x]ds.x'

  Meters to feet and inches
    10   d0=z10k39.370079*.5+0k12~1/r   n[ feet ]P n[ inches]P10P

  Euclidean algorithm to find the GCD:  (asks for 2 numbers number)
     '??[dSarLa%d0<a]dsax+p'                     # short version
     '[a=]P?[b=]P?[dSarLa%d0<a]dsax+[GCD:]Pp'    # prompted

  Factorial
     '?[q]sQ[d1=Qd1-lFx*]dsFxp'

-------------------------------------------------------------------------------
The program dc (and thus bc) on a SunOS manchine produces the following
error for a calculation.

  136504418857628610282244 3651283949359 % p
  10-980-90-2598968327

This is clearly incorrect
                                           Paul Pritchard ---- Jan 6 1992

This problem is fixed on newer Solaris and Linux machines
                                           Anthony Thyssen

------
Bug in GNU dc (2012 onward)

  dc -e "0 k 3 4 5 | p q"      # => 1  correct
  dc -e "8 k 3 4 5 | p q"      # => 0  incorrect

The expotential modulus operator '|' should give same integer result,
regardless of scale.

-------------------------------------------------------------------------------