diff options
Diffstat (limited to 'numpy/add_newdocs.py')
| -rw-r--r-- | numpy/add_newdocs.py | 102 |
1 files changed, 99 insertions, 3 deletions
diff --git a/numpy/add_newdocs.py b/numpy/add_newdocs.py index a3381d47e..0f58f66a2 100644 --- a/numpy/add_newdocs.py +++ b/numpy/add_newdocs.py @@ -1144,9 +1144,12 @@ add_newdoc('numpy.core.multiarray', 'lexsort', add_newdoc('numpy.core.multiarray', 'can_cast', """ - can_cast(fromtype, totype) + can_cast(from, totype, casting = 'safe') - Returns True if cast between data types can occur without losing precision. + Returns True if cast between data types can occur according to the + casting rule. If from is a scalar or array scalar, also returns + True if the scalar value can be cast without overflow or truncation + to an integer. Parameters ---------- @@ -1154,14 +1157,19 @@ add_newdoc('numpy.core.multiarray', 'can_cast', Data type to cast from. totype : dtype or dtype specifier Data type to cast to. + casting : casting rule + May be any of 'no', 'equiv', 'safe', 'same_kind', or 'unsafe'. Returns ------- out : bool - True if cast can occur without losing precision. + True if cast can occur according to the casting rule. Examples -------- + + Basic examples + >>> np.can_cast(np.int32, np.int64) True >>> np.can_cast(np.float64, np.complex) @@ -1176,6 +1184,52 @@ add_newdoc('numpy.core.multiarray', 'can_cast', >>> np.can_cast('i4', 'S4') True + Casting scalars + + >>> np.can_cast(100, 'i1') + True + >>> np.can_cast(150, 'i1') + False + >>> np.can_cast(150, 'u1') + True + + >>> np.can_cast(3.5e100, np.float32) + False + >>> np.can_cast(1000.0, np.float32) + True + + Array scalar checks the value, array does not + + >>> np.can_cast(np.array(1000.0), np.float32) + True + >>> np.can_cast(np.array([1000.0]), np.float32) + False + + Using the casting rules + + >>> np.can_cast('i8', 'i8', 'no') + True + >>> np.can_cast('<i8', '>i8', 'no') + False + + >>> np.can_cast('<i8', '>i8', 'equiv') + True + >>> np.can_cast('<i4', '>i8', 'equiv') + False + + >>> np.can_cast('<i4', '>i8', 'safe') + True + >>> np.can_cast('<i8', '>i4', 'safe') + False + + >>> np.can_cast('<i8', '>i4', 'same_kind') + True + >>> np.can_cast('<i8', '>u4', 'same_kind') + False + + >>> np.can_cast('<i8', '>u4', 'unsafe') + True + """) add_newdoc('numpy.core.multiarray', 'promote_types', @@ -1255,6 +1309,48 @@ add_newdoc('numpy.core.multiarray', 'min_scalar_type', """) +add_newdoc('numpy.core.multiarray', 'result_type', + """ + result_type(*arrays_and_dtypes) + + Returns the type that results from applying the NumPy + type promotion rules to the arguments. + + Type promotion in NumPy works similarly to the rules in languages + like C++, with some slight differences. When both scalars and + arrays are used, the array's type takes precedence and the actual value + of the scalar is taken into account. + + For example, calculating 3*a, where a is an array of 32-bit floats, + intuitively should result in a 32-bit float output. If the 3 is a + 32-bit integer, the NumPy rules indicate it can't convert losslessly + into a 32-bit float, so a 64-bit float should be the result type. + By examining the value of the constant, '3', we see that it fits in + an 8-bit integer, which can be cast losslessly into the 32-bit float. + + Parameters + ---------- + arrays_and_dtypes : list of arrays and dtypes + The operands of some operation whose result type is needed. + + Returns + ------- + out : dtype + The result type. + + Examples + -------- + >>> np.result_type(3, np.arange(7, dtype='i1')) + dtype('int8') + + >>> np.result_type('i4', 'c8') + dtype('complex128') + + >>> np.result_type(3.0, -2) + dtype('float64') + + """) + add_newdoc('numpy.core.multiarray','newbuffer', """newbuffer(size) |