Merge branch 'master' into poly1d-fixes-fixes-fixes-fixes

1 files changed, 195 insertions, 38 deletions

diff --git a/numpy/doc/basics.py b/numpy/doc/basics.py
index dac236644..61f5bf4ef 100644
--- a/numpy/doc/basics.py
+++ b/numpy/doc/basics.py
@@ -9,39 +9,157 @@ Array types and conversions between types
 NumPy supports a much greater variety of numerical types than Python does.
 This section shows which are available, and how to modify an array's data-type.
 
-==========  ==========================================================
-Data type   Description
-==========  ==========================================================
-bool_       Boolean (True or False) stored as a byte
-int_        Default integer type (same as C ``long``; normally either
-            ``int64`` or ``int32``)
-intc        Identical to C ``int`` (normally ``int32`` or ``int64``)
-intp        Integer used for indexing (same as C ``ssize_t``; normally
-            either ``int32`` or ``int64``)
-int8        Byte (-128 to 127)
-int16       Integer (-32768 to 32767)
-int32       Integer (-2147483648 to 2147483647)
-int64       Integer (-9223372036854775808 to 9223372036854775807)
-uint8       Unsigned integer (0 to 255)
-uint16      Unsigned integer (0 to 65535)
-uint32      Unsigned integer (0 to 4294967295)
-uint64      Unsigned integer (0 to 18446744073709551615)
-float_      Shorthand for ``float64``.
-float16     Half precision float: sign bit, 5 bits exponent,
-            10 bits mantissa
-float32     Single precision float: sign bit, 8 bits exponent,
-            23 bits mantissa
-float64     Double precision float: sign bit, 11 bits exponent,
-            52 bits mantissa
-complex_    Shorthand for ``complex128``.
-complex64   Complex number, represented by two 32-bit floats (real
-            and imaginary components)
-complex128  Complex number, represented by two 64-bit floats (real
-            and imaginary components)
-==========  ==========================================================
-
-Additionally to ``intc`` the platform dependent C integer types ``short``,
-``long``, ``longlong`` and their unsigned versions are defined.
+The primitive types supported are tied closely to those in C:
+
+.. list-table::
+    :header-rows: 1
+
+    * - Numpy type
+      - C type
+      - Description
+
+    * - `np.bool`
+      - ``bool``
+      - Boolean (True or False) stored as a byte
+
+    * - `np.byte`
+      - ``signed char``
+      - Platform-defined
+
+    * - `np.ubyte`
+      - ``unsigned char``
+      - Platform-defined
+
+    * - `np.short`
+      - ``short``
+      - Platform-defined
+
+    * - `np.ushort`
+      - ``unsigned short``
+      - Platform-defined
+
+    * - `np.intc`
+      - ``int``
+      - Platform-defined
+
+    * - `np.uintc`
+      - ``unsigned int``
+      - Platform-defined
+
+    * - `np.int_`
+      - ``long``
+      - Platform-defined
+
+    * - `np.uint`
+      - ``unsigned long``
+      - Platform-defined
+
+    * - `np.longlong`
+      - ``long long``
+      - Platform-defined
+
+    * - `np.ulonglong`
+      - ``unsigned long long``
+      - Platform-defined
+
+    * - `np.half` / `np.float16`
+      -
+      - Half precision float:
+        sign bit, 5 bits exponent, 10 bits mantissa
+
+    * - `np.single`
+      - ``float``
+      - Platform-defined single precision float:
+        typically sign bit, 8 bits exponent, 23 bits mantissa
+
+    * - `np.double`
+      - ``double``
+      - Platform-defined double precision float:
+        typically sign bit, 11 bits exponent, 52 bits mantissa.
+
+    * - `np.longdouble`
+      - ``long double``
+      - Platform-defined extended-precision float
+
+    * - `np.csingle`
+      - ``float complex``
+      - Complex number, represented by two single-precision floats (real and imaginary components)
+
+    * - `np.cdouble`
+      - ``double complex``
+      - Complex number, represented by two double-precision floats (real and imaginary components).
+
+    * - `np.clongdouble`
+      - ``long double complex``
+      - Complex number, represented by two extended-precision floats (real and imaginary components).
+
+
+Since many of these have platform-dependent definitions, a set of fixed-size
+aliases are provided:
+
+.. list-table::
+    :header-rows: 1
+
+    * - Numpy type
+      - C type
+      - Description
+
+    * - `np.int8`
+      - ``int8_t``
+      - Byte (-128 to 127)
+
+    * - `np.int16`
+      - ``int16_t``
+      - Integer (-32768 to 32767)
+
+    * - `np.int32`
+      - ``int32_t``
+      - Integer (-2147483648 to 2147483647)
+
+    * - `np.int64`
+      - ``int64_t``
+      - Integer (-9223372036854775808 to 9223372036854775807)
+
+    * - `np.uint8`
+      - ``uint8_t``
+      - Unsigned integer (0 to 255)
+
+    * - `np.uint16`
+      - ``uint16_t``
+      - Unsigned integer (0 to 65535)
+
+    * - `np.uint32`
+      - ``uint32_t``
+      - Unsigned integer (0 to 4294967295)
+
+    * - `np.uint64`
+      - ``uint64_t``
+      - Unsigned integer (0 to 18446744073709551615)
+
+    * - `np.intp`
+      - ``intptr_t``
+      - Integer used for indexing, typically the same as ``ssize_t``
+
+    * - `np.uintp`
+      - ``uintptr_t``
+      - Integer large enough to hold a pointer
+
+    * - `np.float32`
+      - ``float``
+      -
+
+    * - `np.float64` / `np.float_`
+      - ``double``
+      - Note that this matches the precision of the builtin python `float`.
+
+    * - `np.complex64`
+      - ``float complex``
+      - Complex number, represented by two 32-bit floats (real and imaginary components)
+
+    * - `np.complex128` / `np.complex_`
+      - ``double complex``
+      - Note that this matches the precision of the builtin python `complex`.
+
 
 NumPy numerical types are instances of ``dtype`` (data-type) objects, each
 having unique characteristics.  Once you have imported NumPy using
@@ -114,10 +232,10 @@ properties of the type, such as whether it is an integer::
     >>> d
     dtype('int32')
 
-    >>> np.issubdtype(d, int)
+    >>> np.issubdtype(d, np.integer)
     True
 
-    >>> np.issubdtype(d, float)
+    >>> np.issubdtype(d, np.floating)
     False
 
 
@@ -142,6 +260,45 @@ identical behaviour between arrays and scalars, irrespective of whether the
 value is inside an array or not.  NumPy scalars also have many of the same
 methods arrays do.
 
+Overflow Errors
+===============
+
+The fixed size of NumPy numeric types may cause overflow errors when a value
+requires more memory than available in the data type. For example, 
+`numpy.power` evaluates ``100 * 10 ** 8`` correctly for 64-bit integers,
+but gives 1874919424 (incorrect) for a 32-bit integer.
+
+    >>> np.power(100, 8, dtype=np.int64)
+    10000000000000000
+    >>> np.power(100, 8, dtype=np.int32)
+    1874919424
+
+The behaviour of NumPy and Python integer types differs significantly for
+integer overflows and may confuse users expecting NumPy integers to behave
+similar to Python's ``int``. Unlike NumPy, the size of Python's ``int`` is
+flexible. This means Python integers may expand to accomodate any integer and
+will not overflow.
+
+NumPy provides `numpy.iinfo` and `numpy.finfo` to verify the
+minimum or maximum values of NumPy integer and floating point values
+respectively ::
+
+    >>> np.iinfo(np.int) # Bounds of the default integer on this system.
+    iinfo(min=-9223372036854775808, max=9223372036854775807, dtype=int64)
+    >>> np.iinfo(np.int32) # Bounds of a 32-bit integer
+    iinfo(min=-2147483648, max=2147483647, dtype=int32)
+    >>> np.iinfo(np.int64) # Bounds of a 64-bit integer
+    iinfo(min=-9223372036854775808, max=9223372036854775807, dtype=int64)
+
+If 64-bit integers are still too small the result may be cast to a
+floating point number. Floating point numbers offer a larger, but inexact,
+range of possible values.
+
+    >>> np.power(100, 100, dtype=np.int64) # Incorrect even with 64-bit int
+    0
+    >>> np.power(100, 100, dtype=np.float64)
+    1e+200
+
 Extended Precision
 ==================
 
@@ -155,11 +312,11 @@ with 80-bit precision, and while most C compilers provide this as their
 ``long double`` identical to ``double`` (64 bits). NumPy makes the
 compiler's ``long double`` available as ``np.longdouble`` (and
 ``np.clongdouble`` for the complex numbers). You can find out what your
-numpy provides with``np.finfo(np.longdouble)``.
+numpy provides with ``np.finfo(np.longdouble)``.
 
 NumPy does not provide a dtype with more precision than C
-``long double``s; in particular, the 128-bit IEEE quad precision
-data type (FORTRAN's ``REAL*16``) is not available.
+``long double``\\s; in particular, the 128-bit IEEE quad precision
+data type (FORTRAN's ``REAL*16``\\) is not available.
 
 For efficient memory alignment, ``np.longdouble`` is usually stored
 padded with zero bits, either to 96 or 128 bits. Which is more efficient