diff options
Diffstat (limited to 'doc/source/reference/arrays.scalars.rst')
| -rw-r--r-- | doc/source/reference/arrays.scalars.rst | 288 |
1 files changed, 288 insertions, 0 deletions
diff --git a/doc/source/reference/arrays.scalars.rst b/doc/source/reference/arrays.scalars.rst new file mode 100644 index 000000000..70c1d07c9 --- /dev/null +++ b/doc/source/reference/arrays.scalars.rst @@ -0,0 +1,288 @@ +.. _arrays.scalars: + +******* +Scalars +******* + +.. currentmodule:: numpy + +Python defines only one type of a particular data class (there is only +one integer type, one floating-point type, etc.). This can be +convenient in applications that don't need to be concerned with all +the ways data can be represented in a computer. For scientific +computing, however, more control is often needed. + +In NumPy, there are 21 new fundamental Python types to describe +different types of scalars. These type descriptors are mostly based on +the types available in the C language that CPython is written in, with +several additional types compatible with Python's types. + +Array scalars have the same attributes and methods as :class:`ndarrays +<ndarray>`. [#]_ This allows one to treat items of an array partly on +the same footing as arrays, smoothing out rough edges that result when +mixing scalar and array operations. + +Array scalars live in a hierarchy (see the Figure below) of data +types. They can be detected using the hierarchy: For example, +``isinstance(val, np.generic)`` will return :const:`True` if *val* is +an array scalar object. Alternatively, what kind of array scalar is +present can be determined using other members of the data type +hierarchy. Thus, for example ``isinstance(val, np.complexfloating)`` +will return :const:`True` if *val* is a complex valued type, while +:const:`isinstance(val, np.flexible)` will return true if *val* is one +of the flexible itemsize array types (:class:`string`, +:class:`unicode`, :class:`void`). + +.. figure:: figures/dtype-hierarchy.png + + **Figure:** Hierarchy of type objects representing the array data + types. Not shown are the two integer types :class:`intp` and + :class:`uintp` which just point to the integer type that holds a + pointer for the platform. All the number types can be obtained + using bit-width names as well. + +.. [#] However, array scalars are immutable, so that none of the array + scalar attributes are settable. + +.. _arrays.scalars.character-codes: + +.. _arrays.scalars.built-in: + +Built-in scalar types +===================== + +The built-in scalar types are shown below. Along with their (mostly) +C-derived names, the integer, float, and complex data-types are also +available using a bit-width convention so that an array of the right +size can always be ensured (e.g. :class:`int8`, :class:`float64`, +:class:`complex128`). Two aliases (:class:`intp` and :class:`uintp`) +pointing to the integer type that is sufficiently large to hold a C pointer +are also provided. The C-like names are associated with character codes, +which are shown in the table. Use of the character codes, however, +is discouraged. + +Five of the scalar types are essentially equivalent to fundamental +Python types and therefore inherit from them as well as from the +generic array scalar type: + +==================== ==================== +Array scalar type Related Python type +==================== ==================== +:class:`int_` :class:`IntType` +:class:`float_` :class:`FloatType` +:class:`complex_` :class:`ComplexType` +:class:`str_` :class:`StringType` +:class:`unicode_` :class:`UnicodeType` +==================== ==================== + +The :class:`bool_` data type is very similar to the Python +:class:`BooleanType` but does not inherit from it because Python's +:class:`BooleanType` does not allow itself to be inherited from, and +on the C-level the size of the actual bool data is not the same as a +Python Boolean scalar. + +.. warning:: + + The :class:`bool_` type is not a subclass of the :class:`int_` type + (the :class:`bool_` is not even a number type). This is different + than Python's default implementation of :class:`bool` as a + sub-class of int. + + +.. tip:: The default data type in Numpy is :class:`float_`. + +In the tables below, ``platform?`` means that the type may not +available on all platforms. Compatibility with different C or Python +types is indicated: two types are compatible if their data is of the +same size and interpreted in the same way. + +Booleans: + +=================== ============================= =============== +Type Remarks Character code +=================== ============================= =============== +:class:`bool_` compatible: Python bool ``'?'`` +:class:`bool8` 8 bits +=================== ============================= =============== + +Integers: + +=================== ============================= =============== +:class:`byte` compatible: C char ``'b'`` +:class:`short` compatible: C short ``'h'`` +:class:`intc` compatible: C int ``'i'`` +:class:`int_` compatible: Python int ``'l'`` +:class:`longlong` compatible: C long long ``'q'`` +:class:`intp` large enough to fit a pointer ``'p'`` +:class:`int8` 8 bits +:class:`int16` 16 bits +:class:`int32` 32 bits +:class:`int64` 64 bits +=================== ============================= =============== + +Unsigned integers: + +=================== ============================= =============== +:class:`ubyte` compatible: C unsigned char ``'B'`` +:class:`ushort` compatible: C unsigned short ``'H'`` +:class:`uintc` compatible: C unsigned int ``'I'`` +:class:`uint` compatible: Python int ``'L'`` +:class:`ulonglong` compatible: C long long ``'Q'`` +:class:`uintp` large enough to fit a pointer ``'P'`` +:class:`uint8` 8 bits +:class:`uint16` 16 bits +:class:`uint32` 32 bits +:class:`uint64` 64 bits +=================== ============================= =============== + +Floating-point numbers: + +=================== ============================= =============== +:class:`single` compatible: C float ``'f'`` +:class:`double` compatible: C double +:class:`float_` compatible: Python float ``'d'`` +:class:`longfloat` compatible: C long float ``'g'`` +:class:`float32` 32 bits +:class:`float64` 64 bits +:class:`float96` 92 bits, platform? +:class:`float128` 128 bits, platform? +=================== ============================= =============== + +Complex floating-point numbers: + +=================== ============================= =============== +:class:`csingle` ``'F'`` +:class:`complex_` compatible: Python complex ``'D'`` +:class:`clongfloat` ``'G'`` +:class:`complex64` two 32-bit floats +:class:`complex128` two 64-bit floats +:class:`complex192` two 96-bit floats, + platform? +:class:`complex256` two 128-bit floats, + platform? +=================== ============================= =============== + +Any Python object: + +=================== ============================= =============== +:class:`object_` any Python object ``'O'`` +=================== ============================= =============== + +.. note:: + + The data actually stored in :term:`object arrays <object array>` + (*i.e.* arrays having dtype :class:`object_`) are references to + Python objects, not the objects themselves. Hence, object arrays + behave more like usual Python :class:`lists <list>`, in the sense + that their contents need not be of the same Python type. + + The object type is also special because an array containing + :class:`object_` items does not return an :class:`object_` object + on item access, but instead returns the actual object that + the array item refers to. + +The following data types are :term:`flexible`. They have no predefined +size: the data they describe can be of different length in different +arrays. (In the character codes ``#`` is an integer denoting how many +elements the data type consists of.) + +=================== ============================= ======== +:class:`str_` compatible: Python str ``'S#'`` +:class:`unicode_` compatible: Python unicode ``'U#'`` +:class:`void` ``'V#'`` +=================== ============================= ======== + + +.. warning:: + + Numeric Compatibility: If you used old typecode characters in your + Numeric code (which was never recommended), you will need to change + some of them to the new characters. In particular, the needed + changes are ``c -> S1``, ``b -> B``, ``1 -> b``, ``s -> h``, ``w -> + H``, and ``u -> I``. These changes make the type character + convention more consistent with other Python modules such as the + :mod:`struct` module. + + +.. note:: XXX: what to put in the type docstrings, and where to put them? + +Attributes +========== + +The array scalar objects have an :obj:`array priority +<__array_priority__>` of :cdata:`NPY_SCALAR_PRIORITY` +(-1,000,000.0). They also do not (yet) have a :attr:`ctypes <ndarray.ctypes>` +attribute. Otherwise, they share the same attributes as arrays: + +.. autosummary:: + :toctree: generated/ + + generic.flags + generic.shape + generic.strides + generic.ndim + generic.data + generic.size + generic.itemsize + generic.base + generic.dtype + generic.real + generic.imag + generic.flat + generic.T + generic.__array_interface__ + generic.__array_struct__ + generic.__array_priority__ + generic.__array_wrap__ + +.. note:: XXX: import the documentation into the docstrings? + +Indexing +======== +.. seealso:: :ref:`arrays.indexing`, :ref:`arrays.dtypes` + +Array scalars can be indexed like 0-dimensional arrays: if *x* is an +array scalar, + +- ``x[()]`` returns a 0-dimensional :class:`ndarray` +- ``x['field-name']`` returns the array scalar in the field *field-name*. + (*x* can have fields, for example, when it corresponds to a record data type.) + +Methods +======= + +Array scalars have exactly the same methods as arrays. The default +behavior of these methods is to internally convert the scalar to an +equivalent 0-dimensional array and to call the corresponding array +method. In addition, math operations on array scalars are defined so +that the same hardware flags are set and used to interpret the results +as for :ref:`ufunc <ufuncs>`, so that the error state used for ufuncs +also carries over to the math on array scalars. + +The exceptions to the above rules are given below: + +.. autosummary:: + :toctree: generated/ + + generic + generic.__array__ + generic.__array_wrap__ + generic.__squeeze__ + generic.byteswap + generic.__reduce__ + generic.__setstate__ + generic.setflags + +.. note:: XXX: import the documentation into the docstrings? + +Defining new types +================== + +There are two ways to effectively define a new array scalar type +(apart from composing record :ref:`dtypes <arrays.dtypes>` from the built-in +scalar types): One way is to simply subclass the :class:`ndarray` and +overwrite the methods of interest. This will work to a degree, but +internally certain behaviors are fixed by the data type of the array. +To fully customize the data type of an array you need to define a new +data-type, and register it with NumPy. Such new types can only be +defined in C, using the :ref:`Numpy C-API <c-api>`. |