lnum-README.txt

   1
   2 =================
   3   NUMBERS PATCH
   4 =================
   5
   6 Copyright (c) 2006-07, Asko Kauppi <akauppi@gmail.com>
   7
   8 The "Numbers" patch, also known as "lnum" or "integer patch" allows Lua
   9 5.1 internal number mode to be easily set to a combination of any of the
  10 following:
  11
  12 General number type ('lua_Number'):
  13
  14   LNUM_DOUBLE (default)         double precision FP (52 bit mantissa)
  15   LNUM_FLOAT                    single precision FP (23 bit mantissa)
  16   LNUM_LDOUBLE                  extra precision FP (80+ bit mantissa, varies)
  17
  18 Integer number type ('lua_Integer'):
  19
  20   LNUM_INT32                    -2^31..2^31-1 integer optimized
  21   LNUM_INT64                    -2^63..2^63-1 integer optimized
  22   (none)                        all numbers stored as FP
  23
  24 Complex number support:
  25
  26   LNUM_COMPLEX                  Complex (a+bi) number mode, scalars may be
  27                                 integer optimized
  28
  29 One shall combine these defines, i.e. '-DLNUM_DOUBLE -DLNUM_INT64' gives
  30 normal (double) Lua range, added with full signed 64-bit integer accuracy.
  31
  32 With complex numbers, the general number type gives type for both real and
  33 imaginary components. Integer number type (if any) will be applied for real
  34 component (scalar integers).
  35
  36 Even though the optimized (bit accurate) integer range is signed, using
  37 hexadecimal notation for the values, they will behave as an unsigned 0 ..
  38 0xffffffff or 0xffffffffffffffff range. Care has to be applied, though, and no
  39 arithmetic applied on the values; they are stored as signed values internally.
  40
  41   Recommendations:
  42    - x86 and PowerPC desktops: nothing or LNUM_INT64
  43    - Embedded without an FPU: LNUM_INT32
  44
  45   Limitations:
  46    - Precompiled bytecodes cannot be read into a Lua core with a different
  47      number format.
  48
  49 Using the patch does NOT change Lua external behaviour in any way, only
  50 numerical accuracy is enhanced. On non-FPU platforms use of the integer
  51 optimized modes will yield a runtime boost of 30-500% depending largely on the
  52 application in question (for loops will see most benefits). On FPU platforms,
  53 use of the integer optimized modes is within +-5% of regular runtime performance.
  54 See attached performance results for real world results.
  55
  56 The most external changes done by this patch are:
  57
  58 - integer constant VM instruction
  59
  60 It could be run without this, but feeding in integer constants would be risky,
  61 and surprising loss of accuracy could occur. This allows i.e. 64-bit integer
  62 constants.
  63
  64 - '_LNUM' global that carries the number mode as a string:
  65     "[complex] double|float|ldouble [int32|int64]"
  66
  67 This is mostly for testing purposes, normally an application would not care
  68 to check what the number mode is (or, it can be checked as numerical expressions,
  69 but that is a bit uncertain and complex).
  70
  71 The same string is also appeneded to the Lua "opening screen" printout,
  72 alongside version, copyright etc.
  73
  74 - 'lua_isinteger()' addition to the API
  75
  76 To accompany 'lua_tointeger()' already in the API.
  77
  78 - 'lua_tocomplex()', 'lua_iscomplex()' and 'luaL_checkcomplex()' consistent
  79 with the number and integer counterparts (only available with LNUM_COMPLEX).
  80
  81 - Following C99 complex functions added to 'math' namespace:
  82
  83     scalar= math.arg()
  84     scalar= math.imag(c)
  85     scalar= math.real(c)
  86     complex= math.conj(c)
  87     complex= math.proj(c)
  88
  89 Note that using LNUM_COMPLEX does _not_ break Lua API that uses 'lua_Number'.
  90 It remains a scalar, and thus existing Lua modules should be usable also with
  91 Complex internal number mode (of course, as long as imaginary numbers are not
  92 fed to such modules, which will cause an error).
  93
  94 The LNUM_COMPLEX code relies exclusively on the C99 <complex.h> implementation
  95 of complex numbers. Thus, in order to use LNUM_COMPLEX, also enable C99 mode
  96 (i.e. '--std=c99' in gcc).
  97
  98 Currently, use of LNUM_COMPLEX needs the use of integer optimization also
  99 (either LNUM_INT32 or LNUM_INT64). This could be relaxed, but with the cost
 100 of more complex code.
 101
 102
 103 Use of the patch:
 104 =================
 105
 106   tar xvzf lua-5.1.2
 107   mv lua-5.1.2 lua-5.1.2-patched
 108   cd lua-5.1.2-patched/src
 109   patch < ../../lua512_numbers.patch
 110   cd ..
 111   make linux / make macosx / your regular Lua make spell :)
 112
 113 or:
 114
 115   make lua-5.1.2-patched
 116   cd lua-5.1.2-patched && make linux / make macosx / ...
 117
 118 or:
 119
 120   make test
 121
 122
 123 Remake of the patch (for developers):
 124 =====================================
 125
 126   make diff > lua_numbers.patch
 127
 128
 129 -- AKa 9-Jan-2007 (started 26.8.2006) (updated 13 Aug 2007) (updated 1-2 Oct 2007)
 130