Skip to content

Add note to negative for signed integer dtype behavior #270

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Sep 20, 2021
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions spec/API_specification/array_object.md
Original file line number Diff line number Diff line change
Expand Up @@ -934,6 +934,10 @@ Element-wise results must equal the results returned by the equivalent element-w

Evaluates `-self_i` for each element of an array instance.

```{note}
For signed integer data types, the numerical negative of the minimum representable integer is implementation-dependent.
```

#### Parameters

- **self**: _<array>_
Expand Down
10 changes: 4 additions & 6 deletions spec/API_specification/elementwise_functions.md
Original file line number Diff line number Diff line change
Expand Up @@ -128,7 +128,6 @@ For floating-point operands,
- In the remaining cases, when neither `infinity`, `+0`, `-0`, nor a `NaN` is involved, and the operands have the same mathematical sign or have different magnitudes, the sum must be computed and rounded to the nearest representable value according to IEEE 754-2019 and a supported round mode. If the magnitude is too large to represent, the operation overflows and the result is an `infinity` of appropriate mathematical sign.

```{note}

Floating-point addition is a commutative operation, but not always associative.
```

Expand Down Expand Up @@ -237,7 +236,6 @@ Calculates an implementation-dependent approximation of the inverse tangent of t
The mathematical signs of `x1_i` and `x2_i` determine the quadrant of each element-wise result. The quadrant (i.e., branch) is chosen such that each element-wise result is the signed angle in radians between the ray ending at the origin and passing through the point `(1,0)` and the ray ending at the origin and passing through the point `(x2_i, x1_i)`.

```{note}

Note the role reversal: the "y-coordinate" is the first function parameter; the "x-coordinate" is the second function parameter. The parameter order is intentional and traditional for the two-argument inverse tangent function where the y-coordinate argument is first and the x-coordinate argument is second.
```

Expand Down Expand Up @@ -402,7 +400,6 @@ Computes the bitwise OR of the underlying binary representation of each element
Shifts the bits of each element `x1_i` of the input array `x1` to the right according to the respective element `x2_i` of the input array `x2`.

```{note}

This operation must be an arithmetic shift (i.e., sign-propagating) and thus equivalent to floor division by a power of two.
```

Expand Down Expand Up @@ -620,7 +617,6 @@ For floating-point operands,
Calculates an implementation-dependent approximation to `exp(x)-1`, having domain `[-infinity, +infinity]` and codomain `[-1, +infinity]`, for each element `x_i` of the input array `x`.

```{note}

The purpose of this function is to calculate `exp(x)-1.0` more accurately when `x` is close to zero. Accordingly, conforming implementations should avoid implementing this function as simply `exp(x)-1.0`. See FDLIBM, or some other IEEE 754-2019 compliant mathematical library, for a potential reference implementation.
```

Expand Down Expand Up @@ -856,7 +852,6 @@ For floating-point operands,
Calculates an implementation-dependent approximation to `log(1+x)`, where `log` refers to the natural (base `e`) logarithm, having domain `[-1, +infinity]` and codomain `[-infinity, +infinity]`, for each element `x_i` of the input array `x`.

```{note}

The purpose of this function is to calculate `log(1+x)` more accurately when `x` is close to zero. Accordingly, conforming implementations should avoid implementing this function as simply `log(1+x)`. See FDLIBM, or some other IEEE 754-2019 compliant mathematical library, for a potential reference implementation.
```

Expand Down Expand Up @@ -1085,7 +1080,6 @@ For floating-point operands,
- In the remaining cases, where neither `infinity` nor `NaN` is involved, the product must be computed and rounded to the nearest representable value according to IEEE 754-2019 and a supported rounding mode. If the magnitude is too large to represent, the result is an `infinity` of appropriate mathematical sign. If the magnitude is too small to represent, the result is a zero of appropriate mathematical sign.

```{note}

Floating-point multiplication is not always associative due to finite precision.
```

Expand All @@ -1110,6 +1104,10 @@ Floating-point multiplication is not always associative due to finite precision.

Computes the numerical negative of each element `x_i` (i.e., `y_i = -x_i`) of the input array `x`.

```{note}
For signed integer data types, the numerical negative of the minimum representable integer is implementation-dependent.
```

#### Parameters

- **x**: _<array>_
Expand Down