Shortcuts on this page
r m x toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
1"""
2Module of functions that are like ufuncs in acting on arrays and optionally
3storing results in an output array.
5"""
6__all__ = ['fix', 'isneginf', 'isposinf']
8import numpy._core.numeric as nx
9from numpy._core.overrides import array_function_dispatch
12def _dispatcher(x, out=None):
13 return (x, out)
16@array_function_dispatch(_dispatcher, verify=False, module='numpy')
17def fix(x, out=None):
18 """
19 Round to nearest integer towards zero.
21 Round an array of floats element-wise to nearest integer towards zero.
22 The rounded values have the same data-type as the input.
24 Parameters
25 ----------
26 x : array_like
27 An array to be rounded
28 out : ndarray, optional
29 A location into which the result is stored. If provided, it must have
30 a shape that the input broadcasts to. If not provided or None, a
31 freshly-allocated array is returned.
33 Returns
34 -------
35 out : ndarray of floats
36 An array with the same dimensions and data-type as the input.
37 If second argument is not supplied then a new array is returned
38 with the rounded values.
40 If a second argument is supplied the result is stored there.
41 The return value ``out`` is then a reference to that array.
43 See Also
44 --------
45 rint, trunc, floor, ceil
46 around : Round to given number of decimals
48 Examples
49 --------
50 >>> import numpy as np
51 >>> np.fix(3.14)
52 3.0
53 >>> np.fix(3)
54 3
55 >>> np.fix([2.1, 2.9, -2.1, -2.9])
56 array([ 2., 2., -2., -2.])
58 """
59 # promote back to an array if flattened
60 res = nx.asanyarray(nx.ceil(x, out=out))
61 res = nx.floor(x, out=res, where=nx.greater_equal(x, 0))
63 # when no out argument is passed and no subclasses are involved, flatten
64 # scalars
65 if out is None and type(res) is nx.ndarray:
66 res = res[()]
67 return res
70@array_function_dispatch(_dispatcher, verify=False, module='numpy')
71def isposinf(x, out=None):
72 """
73 Test element-wise for positive infinity, return result as bool array.
75 Parameters
76 ----------
77 x : array_like
78 The input array.
79 out : array_like, optional
80 A location into which the result is stored. If provided, it must have a
81 shape that the input broadcasts to. If not provided or None, a
82 freshly-allocated boolean array is returned.
84 Returns
85 -------
86 out : ndarray
87 A boolean array with the same dimensions as the input.
88 If second argument is not supplied then a boolean array is returned
89 with values True where the corresponding element of the input is
90 positive infinity and values False where the element of the input is
91 not positive infinity.
93 If a second argument is supplied the result is stored there. If the
94 type of that array is a numeric type the result is represented as zeros
95 and ones, if the type is boolean then as False and True.
96 The return value `out` is then a reference to that array.
98 See Also
99 --------
100 isinf, isneginf, isfinite, isnan
102 Notes
103 -----
104 NumPy uses the IEEE Standard for Binary Floating-Point for Arithmetic
105 (IEEE 754).
107 Errors result if the second argument is also supplied when x is a scalar
108 input, if first and second arguments have different shapes, or if the
109 first argument has complex values
111 Examples
112 --------
113 >>> import numpy as np
114 >>> np.isposinf(np.inf)
115 True
116 >>> np.isposinf(-np.inf)
117 False
118 >>> np.isposinf([-np.inf, 0., np.inf])
119 array([False, False, True])
121 >>> x = np.array([-np.inf, 0., np.inf])
122 >>> y = np.array([2, 2, 2])
123 >>> np.isposinf(x, y)
124 array([0, 0, 1])
125 >>> y
126 array([0, 0, 1])
128 """
129 is_inf = nx.isinf(x)
130 try:
131 signbit = ~nx.signbit(x)
132 except TypeError as e:
133 dtype = nx.asanyarray(x).dtype
134 raise TypeError(f'This operation is not supported for {dtype} values '
135 'because it would be ambiguous.') from e
136 else:
137 return nx.logical_and(is_inf, signbit, out)
140@array_function_dispatch(_dispatcher, verify=False, module='numpy')
141def isneginf(x, out=None):
142 """
143 Test element-wise for negative infinity, return result as bool array.
145 Parameters
146 ----------
147 x : array_like
148 The input array.
149 out : array_like, optional
150 A location into which the result is stored. If provided, it must have a
151 shape that the input broadcasts to. If not provided or None, a
152 freshly-allocated boolean array is returned.
154 Returns
155 -------
156 out : ndarray
157 A boolean array with the same dimensions as the input.
158 If second argument is not supplied then a numpy boolean array is
159 returned with values True where the corresponding element of the
160 input is negative infinity and values False where the element of
161 the input is not negative infinity.
163 If a second argument is supplied the result is stored there. If the
164 type of that array is a numeric type the result is represented as
165 zeros and ones, if the type is boolean then as False and True. The
166 return value `out` is then a reference to that array.
168 See Also
169 --------
170 isinf, isposinf, isnan, isfinite
172 Notes
173 -----
174 NumPy uses the IEEE Standard for Binary Floating-Point for Arithmetic
175 (IEEE 754).
177 Errors result if the second argument is also supplied when x is a scalar
178 input, if first and second arguments have different shapes, or if the
179 first argument has complex values.
181 Examples
182 --------
183 >>> import numpy as np
184 >>> np.isneginf(-np.inf)
185 True
186 >>> np.isneginf(np.inf)
187 False
188 >>> np.isneginf([-np.inf, 0., np.inf])
189 array([ True, False, False])
191 >>> x = np.array([-np.inf, 0., np.inf])
192 >>> y = np.array([2, 2, 2])
193 >>> np.isneginf(x, y)
194 array([1, 0, 0])
195 >>> y
196 array([1, 0, 0])
198 """
199 is_inf = nx.isinf(x)
200 try:
201 signbit = nx.signbit(x)
202 except TypeError as e:
203 dtype = nx.asanyarray(x).dtype
204 raise TypeError(f'This operation is not supported for {dtype} values '
205 'because it would be ambiguous.') from e
206 else:
207 return nx.logical_and(is_inf, signbit, out)