1Data Type API 2============= 3 4.. sectionauthor:: Travis E. Oliphant 5 6The standard array can have 24 different data types (and has some 7support for adding your own types). These data types all have an 8enumerated type, an enumerated type-character, and a corresponding 9array scalar Python type object (placed in a hierarchy). There are 10also standard C typedefs to make it easier to manipulate elements of 11the given data type. For the numeric types, there are also bit-width 12equivalent C typedefs and named typenumbers that make it easier to 13select the precision desired. 14 15.. warning:: 16 17 The names for the types in c code follows c naming conventions 18 more closely. The Python names for these types follow Python 19 conventions. Thus, :c:data:`NPY_FLOAT` picks up a 32-bit float in 20 C, but :class:`numpy.float_` in Python corresponds to a 64-bit 21 double. The bit-width names can be used in both Python and C for 22 clarity. 23 24 25Enumerated Types 26---------------- 27 28.. c:var:: NPY_TYPES 29 30There is a list of enumerated types defined providing the basic 24 31data types plus some useful generic names. Whenever the code requires 32a type number, one of these enumerated types is requested. The types 33are all called ``NPY_{NAME}``: 34 35.. c:var:: NPY_BOOL 36 37 The enumeration value for the boolean type, stored as one byte. 38 It may only be set to the values 0 and 1. 39 40.. c:var:: NPY_BYTE 41.. c:var:: NPY_INT8 42 43 The enumeration value for an 8-bit/1-byte signed integer. 44 45.. c:var:: NPY_SHORT 46.. c:var:: NPY_INT16 47 48 The enumeration value for a 16-bit/2-byte signed integer. 49 50.. c:var:: NPY_INT 51.. c:var:: NPY_INT32 52 53 The enumeration value for a 32-bit/4-byte signed integer. 54 55.. c:var:: NPY_LONG 56 57 Equivalent to either NPY_INT or NPY_LONGLONG, depending on the 58 platform. 59 60.. c:var:: NPY_LONGLONG 61.. c:var:: NPY_INT64 62 63 The enumeration value for a 64-bit/8-byte signed integer. 64 65.. c:var:: NPY_UBYTE 66.. c:var:: NPY_UINT8 67 68 The enumeration value for an 8-bit/1-byte unsigned integer. 69 70.. c:var:: NPY_USHORT 71.. c:var:: NPY_UINT16 72 73 The enumeration value for a 16-bit/2-byte unsigned integer. 74 75.. c:var:: NPY_UINT 76.. c:var:: NPY_UINT32 77 78 The enumeration value for a 32-bit/4-byte unsigned integer. 79 80.. c:var:: NPY_ULONG 81 82 Equivalent to either NPY_UINT or NPY_ULONGLONG, depending on the 83 platform. 84 85.. c:var:: NPY_ULONGLONG 86.. c:var:: NPY_UINT64 87 88 The enumeration value for a 64-bit/8-byte unsigned integer. 89 90.. c:var:: NPY_HALF 91.. c:var:: NPY_FLOAT16 92 93 The enumeration value for a 16-bit/2-byte IEEE 754-2008 compatible floating 94 point type. 95 96.. c:var:: NPY_FLOAT 97.. c:var:: NPY_FLOAT32 98 99 The enumeration value for a 32-bit/4-byte IEEE 754 compatible floating 100 point type. 101 102.. c:var:: NPY_DOUBLE 103.. c:var:: NPY_FLOAT64 104 105 The enumeration value for a 64-bit/8-byte IEEE 754 compatible floating 106 point type. 107 108.. c:var:: NPY_LONGDOUBLE 109 110 The enumeration value for a platform-specific floating point type which is 111 at least as large as NPY_DOUBLE, but larger on many platforms. 112 113.. c:var:: NPY_CFLOAT 114.. c:var:: NPY_COMPLEX64 115 116 The enumeration value for a 64-bit/8-byte complex type made up of 117 two NPY_FLOAT values. 118 119.. c:var:: NPY_CDOUBLE 120.. c:var:: NPY_COMPLEX128 121 122 The enumeration value for a 128-bit/16-byte complex type made up of 123 two NPY_DOUBLE values. 124 125.. c:var:: NPY_CLONGDOUBLE 126 127 The enumeration value for a platform-specific complex floating point 128 type which is made up of two NPY_LONGDOUBLE values. 129 130.. c:var:: NPY_DATETIME 131 132 The enumeration value for a data type which holds dates or datetimes with 133 a precision based on selectable date or time units. 134 135.. c:var:: NPY_TIMEDELTA 136 137 The enumeration value for a data type which holds lengths of times in 138 integers of selectable date or time units. 139 140.. c:var:: NPY_STRING 141 142 The enumeration value for ASCII strings of a selectable size. The 143 strings have a fixed maximum size within a given array. 144 145.. c:var:: NPY_UNICODE 146 147 The enumeration value for UCS4 strings of a selectable size. The 148 strings have a fixed maximum size within a given array. 149 150.. c:var:: NPY_OBJECT 151 152 The enumeration value for references to arbitrary Python objects. 153 154.. c:var:: NPY_VOID 155 156 Primarily used to hold struct dtypes, but can contain arbitrary 157 binary data. 158 159Some useful aliases of the above types are 160 161.. c:var:: NPY_INTP 162 163 The enumeration value for a signed integer type which is the same 164 size as a (void \*) pointer. This is the type used by all 165 arrays of indices. 166 167.. c:var:: NPY_UINTP 168 169 The enumeration value for an unsigned integer type which is the 170 same size as a (void \*) pointer. 171 172.. c:var:: NPY_MASK 173 174 The enumeration value of the type used for masks, such as with 175 the :c:data:`NPY_ITER_ARRAYMASK` iterator flag. This is equivalent 176 to :c:data:`NPY_UINT8`. 177 178.. c:var:: NPY_DEFAULT_TYPE 179 180 The default type to use when no dtype is explicitly specified, for 181 example when calling np.zero(shape). This is equivalent to 182 :c:data:`NPY_DOUBLE`. 183 184Other useful related constants are 185 186.. c:macro:: NPY_NTYPES 187 188 The total number of built-in NumPy types. The enumeration covers 189 the range from 0 to NPY_NTYPES-1. 190 191.. c:macro:: NPY_NOTYPE 192 193 A signal value guaranteed not to be a valid type enumeration number. 194 195.. c:macro:: NPY_USERDEF 196 197 The start of type numbers used for Custom Data types. 198 199The various character codes indicating certain types are also part of 200an enumerated list. References to type characters (should they be 201needed at all) should always use these enumerations. The form of them 202is ``NPY_{NAME}LTR`` where ``{NAME}`` can be 203 204 **BOOL**, **BYTE**, **UBYTE**, **SHORT**, **USHORT**, **INT**, 205 **UINT**, **LONG**, **ULONG**, **LONGLONG**, **ULONGLONG**, 206 **HALF**, **FLOAT**, **DOUBLE**, **LONGDOUBLE**, **CFLOAT**, 207 **CDOUBLE**, **CLONGDOUBLE**, **DATETIME**, **TIMEDELTA**, 208 **OBJECT**, **STRING**, **VOID** 209 210 **INTP**, **UINTP** 211 212 **GENBOOL**, **SIGNED**, **UNSIGNED**, **FLOATING**, **COMPLEX** 213 214The latter group of ``{NAME}s`` corresponds to letters used in the array 215interface typestring specification. 216 217 218Defines 219------- 220 221Max and min values for integers 222^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 223 224``NPY_MAX_INT{bits}``, ``NPY_MAX_UINT{bits}``, ``NPY_MIN_INT{bits}`` 225 These are defined for ``{bits}`` = 8, 16, 32, 64, 128, and 256 and provide 226 the maximum (minimum) value of the corresponding (unsigned) integer 227 type. Note: the actual integer type may not be available on all 228 platforms (i.e. 128-bit and 256-bit integers are rare). 229 230``NPY_MIN_{type}`` 231 This is defined for ``{type}`` = **BYTE**, **SHORT**, **INT**, 232 **LONG**, **LONGLONG**, **INTP** 233 234``NPY_MAX_{type}`` 235 This is defined for all defined for ``{type}`` = **BYTE**, **UBYTE**, 236 **SHORT**, **USHORT**, **INT**, **UINT**, **LONG**, **ULONG**, 237 **LONGLONG**, **ULONGLONG**, **INTP**, **UINTP** 238 239 240Number of bits in data types 241^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 242 243All ``NPY_SIZEOF_{CTYPE}`` constants have corresponding 244``NPY_BITSOF_{CTYPE}`` constants defined. The ``NPY_BITSOF_{CTYPE}`` 245constants provide the number of bits in the data type. Specifically, 246the available ``{CTYPE}s`` are 247 248 **BOOL**, **CHAR**, **SHORT**, **INT**, **LONG**, 249 **LONGLONG**, **FLOAT**, **DOUBLE**, **LONGDOUBLE** 250 251 252Bit-width references to enumerated typenums 253^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 254 255All of the numeric data types (integer, floating point, and complex) 256have constants that are defined to be a specific enumerated type 257number. Exactly which enumerated type a bit-width type refers to is 258platform dependent. In particular, the constants available are 259``PyArray_{NAME}{BITS}`` where ``{NAME}`` is **INT**, **UINT**, 260**FLOAT**, **COMPLEX** and ``{BITS}`` can be 8, 16, 32, 64, 80, 96, 128, 261160, 192, 256, and 512. Obviously not all bit-widths are available on 262all platforms for all the kinds of numeric types. Commonly 8-, 16-, 26332-, 64-bit integers; 32-, 64-bit floats; and 64-, 128-bit complex 264types are available. 265 266 267Integer that can hold a pointer 268^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 269 270The constants **NPY_INTP** and **NPY_UINTP** refer to an 271enumerated integer type that is large enough to hold a pointer on the 272platform. Index arrays should always be converted to **NPY_INTP** 273, because the dimension of the array is of type npy_intp. 274 275 276C-type names 277------------ 278 279There are standard variable types for each of the numeric data types 280and the bool data type. Some of these are already available in the 281C-specification. You can create variables in extension code with these 282types. 283 284 285Boolean 286^^^^^^^ 287 288.. c:type:: npy_bool 289 290 unsigned char; The constants :c:data:`NPY_FALSE` and 291 :c:data:`NPY_TRUE` are also defined. 292 293 294(Un)Signed Integer 295^^^^^^^^^^^^^^^^^^ 296 297Unsigned versions of the integers can be defined by pre-pending a 'u' 298to the front of the integer name. 299 300.. c:type:: npy_(u)byte 301 302 (unsigned) char 303 304.. c:type:: npy_short 305 306 short 307 308.. c:type:: npy_ushort 309 310 unsigned short 311 312.. c:type:: npy_uint 313 314 unsigned int 315 316.. c:type:: npy_int 317 318 int 319 320.. c:type:: npy_int16 321 322 16-bit integer 323 324.. c:type:: npy_uint16 325 326 16-bit unsigned integer 327 328.. c:type:: npy_int32 329 330 32-bit integer 331 332.. c:type:: npy_uint32 333 334 32-bit unsigned integer 335 336.. c:type:: npy_int64 337 338 64-bit integer 339 340.. c:type:: npy_uint64 341 342 64-bit unsigned integer 343 344.. c:type:: npy_(u)long 345 346 (unsigned) long int 347 348.. c:type:: npy_(u)longlong 349 350 (unsigned long long int) 351 352.. c:type:: npy_intp 353 354 Py_intptr_t (an integer that is the size of a pointer on 355 the platform). 356 357.. c:type:: npy_uintp 358 359 unsigned Py_intptr_t (an integer that is the size of a pointer on 360 the platform). 361 362 363(Complex) Floating point 364^^^^^^^^^^^^^^^^^^^^^^^^ 365 366.. c:type:: npy_half 367 368 16-bit float 369 370.. c:type:: npy_(c)float 371 372 32-bit float 373 374.. c:type:: npy_(c)double 375 376 64-bit double 377 378.. c:type:: npy_(c)longdouble 379 380 long double 381 382complex types are structures with **.real** and **.imag** members (in 383that order). 384 385 386Bit-width names 387^^^^^^^^^^^^^^^ 388 389There are also typedefs for signed integers, unsigned integers, 390floating point, and complex floating point types of specific bit- 391widths. The available type names are 392 393 ``npy_int{bits}``, ``npy_uint{bits}``, ``npy_float{bits}``, 394 and ``npy_complex{bits}`` 395 396where ``{bits}`` is the number of bits in the type and can be **8**, 397**16**, **32**, **64**, 128, and 256 for integer types; 16, **32** 398, **64**, 80, 96, 128, and 256 for floating-point types; and 32, 399**64**, **128**, 160, 192, and 512 for complex-valued types. Which 400bit-widths are available is platform dependent. The bolded bit-widths 401are usually available on all platforms. 402 403 404Printf Formatting 405----------------- 406 407For help in printing, the following strings are defined as the correct 408format specifier in printf and related commands. 409 410.. c:macro:: NPY_LONGLONG_FMT 411 412.. c:macro:: NPY_ULONGLONG_FMT 413 414.. c:macro:: NPY_INTP_FMT 415 416.. c:macro:: NPY_UINTP_FMT 417 418.. c:macro:: NPY_LONGDOUBLE_FMT 419