Skip to content

DO NOT LAND: Remove all coerce functions #741

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.

Sign up for GitHub

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

Draft
chiphogg wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

DO NOT LAND: Remove all coerce functions #741

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
22 changes: 0 additions & 22 deletions au/constant.hh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,17 +55,6 @@ struct Constant : detail::MakesQuantityFromNumber<Constant, Unit>,
return make_quantity<Unit>(static_cast<T>(1));
}

// Convert this constant to a Quantity of the given unit and rep, ignoring safety checks.
template <typename T, typename OtherUnit>
[[deprecated(
"`coerce_as()` is deprecated. Use `as()` instead, and pass a risk policy parameter. "
"Upgrade guide: "
"<https://aurora-opensource.github.io/au/0.5.1/reference/quantity/"
"#coerce>")]] constexpr auto
coerce_as(OtherUnit u) const {
return as<T>().coerce_as(u);
}

// Convert this constant to a Quantity of the given unit and rep.
template <typename T, typename OtherUnit>
AU_DEVICE_FUNC constexpr auto as(OtherUnit u) const {
Expand All @@ -90,17 +79,6 @@ struct Constant : detail::MakesQuantityFromNumber<Constant, Unit>,
return this_value.template as<T>(OtherUnit{}, ignore(ALL_RISKS));
}

// Get the value of this constant in the given unit and rep, ignoring safety checks.
template <typename T, typename OtherUnit>
[[deprecated(
"`coerce_in()` is deprecated. Use `in()` instead, and pass a risk policy parameter. "
"Upgrade guide: "
"<https://aurora-opensource.github.io/au/0.5.1/reference/quantity/"
"#coerce>")]] constexpr auto
coerce_in(OtherUnit u) const {
return as<T>().coerce_in(u);
}

// Get the value of this constant in the given unit and rep.
template <typename T, typename OtherUnit>
AU_DEVICE_FUNC constexpr auto in(OtherUnit u) const {
Expand Down
42 changes: 0 additions & 42 deletions au/quantity.hh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -244,48 +244,6 @@ class Quantity {
return in_impl<detail::UseStaticCast, void>(u, policy);
}

// "Forcing" conversions, which explicitly ignore safety checks for overflow and truncation.
template <typename NewUnit>
[[deprecated(
"`coerce_as()` is deprecated. Use `as()` instead, and pass a risk policy parameter. "
"Upgrade guide: "
"<https://aurora-opensource.github.io/au/0.5.1/reference/quantity/"
"#coerce>")]] constexpr auto
coerce_as(NewUnit) const {
// Usage example: `q.coerce_as(new_units)`.
return as(NewUnit{}, ignore(ALL_RISKS));
}
template <typename NewRep, typename NewUnit>
[[deprecated(
"`coerce_as()` is deprecated. Use `as()` instead, and pass a risk policy parameter. "
"Upgrade guide: "
"<https://aurora-opensource.github.io/au/0.5.1/reference/quantity/"
"#coerce>")]] constexpr auto
coerce_as(NewUnit) const {
// Usage example: `q.coerce_as<T>(new_units)`.
return as<NewRep>(NewUnit{}, ignore(ALL_RISKS));
}
template <typename NewUnit>
[[deprecated(
"`coerce_in()` is deprecated. Use `in()` instead, and pass a risk policy parameter. "
"Upgrade guide: "
"<https://aurora-opensource.github.io/au/0.5.1/reference/quantity/"
"#coerce>")]] constexpr auto
coerce_in(NewUnit) const {
// Usage example: `q.coerce_in(new_units)`.
return in(NewUnit{}, ignore(ALL_RISKS));
}
template <typename NewRep, typename NewUnit>
[[deprecated(
"`coerce_in()` is deprecated. Use `in()` instead, and pass a risk policy parameter. "
"Upgrade guide: "
"<https://aurora-opensource.github.io/au/0.5.1/reference/quantity/"
"#coerce>")]] constexpr auto
coerce_in(NewUnit) const {
// Usage example: `q.coerce_in<T>(new_units)`.
return in<NewRep>(NewUnit{}, ignore(ALL_RISKS));
}

// Direct access to the underlying value member, with any Quantity-equivalent Unit.
//
// Mutable access:
Expand Down
42 changes: 0 additions & 42 deletions au/quantity_point.hh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -188,48 +188,6 @@ class QuantityPoint {
return in_impl<Rep>(u, policy);
}

// "Forcing" conversions, which explicitly ignore safety checks for overflow and truncation.
template <typename NewUnit>
[[deprecated(
"`coerce_as()` is deprecated. Use `as()` instead, and pass a risk policy parameter. "
"Upgrade guide: "
"<https://aurora-opensource.github.io/au/0.5.1/reference/quantity/"
"#coerce>")]] constexpr auto
coerce_as(NewUnit) const {
// Usage example: `p.coerce_as(new_units)`.
return as(NewUnit{}, ignore(ALL_RISKS));
}
template <typename NewRep, typename NewUnit>
[[deprecated(
"`coerce_as()` is deprecated. Use `as()` instead, and pass a risk policy parameter. "
"Upgrade guide: "
"<https://aurora-opensource.github.io/au/0.5.1/reference/quantity/"
"#coerce>")]] constexpr auto
coerce_as(NewUnit) const {
// Usage example: `p.coerce_as<T>(new_units)`.
return as<NewRep>(NewUnit{}, ignore(ALL_RISKS));
}
template <typename NewUnit>
[[deprecated(
"`coerce_in()` is deprecated. Use `in()` instead, and pass a risk policy parameter. "
"Upgrade guide: "
"<https://aurora-opensource.github.io/au/0.5.1/reference/quantity/"
"#coerce>")]] constexpr auto
coerce_in(NewUnit) const {
// Usage example: `p.coerce_in(new_units)`.
return in(NewUnit{}, ignore(ALL_RISKS));
}
template <typename NewRep, typename NewUnit>
[[deprecated(
"`coerce_in()` is deprecated. Use `in()` instead, and pass a risk policy parameter. "
"Upgrade guide: "
"<https://aurora-opensource.github.io/au/0.5.1/reference/quantity/"
"#coerce>")]] constexpr auto
coerce_in(NewUnit) const {
// Usage example: `p.coerce_in<T>(new_units)`.
return in<NewRep>(NewUnit{}, ignore(ALL_RISKS));
}

// Direct access to the underlying value member, with any Point-equivalent Unit.
//
// Mutable access:
Expand Down
34 changes: 0 additions & 34 deletions docs/reference/constant.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -327,23 +327,6 @@ specific conversion will _actually cause truncation_.
imagine, as they will produce a grossly incorrect result with no physical relationship to the
actual value.

### `.coerce_as<T>(unit)`

!!! warning
These functions are deprecated. For a `Constant` `c`, instead of `c.coerce_as<T>(unit)`, prefer
`c.as<T>(unit, policy)`, where `policy` is the desired [conversion risk
policy](./conversion_risk_policies.md).

This function expresses the constant as a `Quantity` in the requested unit, using a rep of `T`. It
is similar to [`.as<T>(unit)`](#as-T-unit), except that it will ignore the safety checks that
prevent truncation and overflow.

!!! warning
Because `.as<T>(unit)` has a perfect conversion policy, we know that this function either
produces the exact same result (in which case you could simply _call_ `.as<T>(unit)`), _or_ it
produces a result which is **guaranteed to be lossy**. Therefore, be very judicious in using
this function.

### `.in<T>(unit)` {#in-T-unit}

This function produces a raw numeric value, of type `T`, holding the value of the constant in the
Expand Down Expand Up @@ -379,23 +362,6 @@ specific conversion will _actually cause truncation_.
imagine, as they will produce a grossly incorrect result with no physical relationship to the
actual value.

### `.coerce_in<T>(unit)`

!!! warning
These functions are deprecated. For a `Constant` `c`, instead of `c.coerce_in<T>(unit)`, prefer
`c.in<T>(unit, policy)`, where `policy` is the desired [conversion risk
policy](./conversion_risk_policies.md).

This function produces a raw numeric value, of type `T`, holding the value of the constant in the
requested unit. It is similar to [`.in<T>(unit)`](#in-T-unit), except that it will ignore the
safety checks that prevent truncation and overflow.

!!! warning
Because `.in<T>(unit)` has a perfect conversion policy, we know that this function either
produces the exact same result (in which case you could simply _call_ `.in<T>(unit)`), _or_ it
produces a result which is **guaranteed to be lossy**. Therefore, be very judicious in using
this function.

### Implicit `Quantity` conversion

`Constant` will implicitly convert to any `Quantity` type which passes the safety checks on
Expand Down
52 changes: 0 additions & 52 deletions docs/reference/quantity.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -444,58 +444,6 @@ To be concrete, here are the signatures of the functions that support the policy
the default compile-time safety surface (although at the cost of runtime operations). See the
[subsequent section](#runtime-conversion-checkers) for more details.

### Forcing lossy conversions: `.coerce_as(unit)`, `.coerce_in(unit)` {#coerce}

!!! warning
These functions are deprecated. Here is how you convert them.

First, figure out which conversion risks you are trying to override: **overflow**, or
**truncation**, or **both**. (You can simply delete the `"coerce_"` word and compile, and the
error message will tell you which one, if any, is relevant.)

Then, follow this table to rewrite your conversion, using the conversion risk you identified
above.

| "Coerce" version (dis-preferred; will be deprecated) | "Policy" version (preferred) |
|------------------------------------------------------|------------------------------|
| `q.coerce_as(unit)` | One of:<br>`q.as(unit, ignore(OVERFLOW_RISK))`<br>`q.as(unit, ignore(TRUNCATION_RISK))`<br>`q.as(unit, ignore(OVERFLOW_RISK | TRUNCATION_RISK))` |
| `q.coerce_as<T>(unit)` | One of:<br>`q.as<T>(unit, ignore(OVERFLOW_RISK))`<br>`q.as<T>(unit, ignore(TRUNCATION_RISK))`<br>`q.as<T>(unit, ignore(OVERFLOW_RISK | TRUNCATION_RISK))` |
| `q.coerce_in(unit)` | One of:<br>`q.in(unit, ignore(OVERFLOW_RISK))`<br>`q.in(unit, ignore(TRUNCATION_RISK))`<br>`q.in(unit, ignore(OVERFLOW_RISK | TRUNCATION_RISK))` |
| `q.coerce_in<T>(unit)` | One of:<br>`q.in<T>(unit, ignore(OVERFLOW_RISK))`<br>`q.in<T>(unit, ignore(TRUNCATION_RISK))`<br>`q.in<T>(unit, ignore(OVERFLOW_RISK | TRUNCATION_RISK))` |

These new versions are both more clear about their intent, and safer (because they only turn off
the safety checks that they need to).

Note: if you were only providing `<T>` in order to keep the same rep as the input (rather than
to genuinely change it), use [`SameRep`](#same-rep) for `T` instead of naming the concrete type.

This function performs the exact same kind of unit conversion as if the string `coerce_` were
removed. However, it will ignore any safety checks for overflow or truncation.

??? example "Example: forcing a conversion from inches to feet"
`inches(24).as(feet)` is not allowed. This conversion will divide the underlying value, `24`,
by `12`. While this particular value would produce an integer result, most other `int` values
would not. Because our result uses `int` for storage --- same as the input --- we forbid this.

`inches(24).coerce_as(feet)` _is_ allowed. The `coerce_` prefix has "forcing" semantics. This
would produce `feet(2)`. However, note that this operation uses integer division, which
truncates: so, for example, `inches(23).coerce_as(feet)` would produce `feet(1)`.

These functions also support an explicit template parameter: so, `.coerce_as<T>(unit)` and
`.coerce_in<T>(unit)`. If you supply this parameter, it will be the rep of the result.

??? example "Example: simultaneous unit and type conversion"
`inches(27.8).coerce_as<int>(feet)` will return `feet(2)`.

!!! tip
In most cases, prefer **not** to use the "coercing versions" if possible, because you will get
more safety checks. The risks which the "base" versions warn about are real.

However, one place where it's _very safe_ to use the "coercing versions" is right after running
a _runtime conversion checker_. These provde _exact_ conversion checks, even more accurate than
the default compile-time safety surface (although at the cost of runtime operations). See the
next section for more details.

### Runtime conversion checkers {#runtime-conversion-checkers}

Au's default, compile-time conversion checks are only heuristics, based on the _general_ risk of
Expand Down
50 changes: 0 additions & 50 deletions docs/reference/quantity_point.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -307,56 +307,6 @@ To be concrete, here are the signatures of the functions that support the policy
will always be safe to provide a policy argument that ignores a risk that you have just verified
to be absent.

### Forcing lossy conversions: `.coerce_as(unit)`, `.coerce_in(unit)` {#coerce}

!!! warning
These functions are deprecated. Here is how you convert them.

First, figure out which conversion risks you are trying to override: **overflow**, or
**truncation**, or **both**. (You can simply delete the `"coerce_"` word and compile, and the
error message will tell you which one, if any, is relevant.)

Then, follow this table to rewrite your conversion, using the conversion risk you identified
above.

| "Coerce" version (dis-preferred; will be deprecated) | "Policy" version (preferred) |
|------------------------------------------------------|------------------------------|
| `q.coerce_as(unit)` | One of:<br>`q.as(unit, ignore(OVERFLOW_RISK))`<br>`q.as(unit, ignore(TRUNCATION_RISK))`<br>`q.as(unit, ignore(OVERFLOW_RISK | TRUNCATION_RISK))` |
| `q.coerce_as<T>(unit)` | One of:<br>`q.as<T>(unit, ignore(OVERFLOW_RISK))`<br>`q.as<T>(unit, ignore(TRUNCATION_RISK))`<br>`q.as<T>(unit, ignore(OVERFLOW_RISK | TRUNCATION_RISK))` |
| `q.coerce_in(unit)` | One of:<br>`q.in(unit, ignore(OVERFLOW_RISK))`<br>`q.in(unit, ignore(TRUNCATION_RISK))`<br>`q.in(unit, ignore(OVERFLOW_RISK | TRUNCATION_RISK))` |
| `q.coerce_in<T>(unit)` | One of:<br>`q.in<T>(unit, ignore(OVERFLOW_RISK))`<br>`q.in<T>(unit, ignore(TRUNCATION_RISK))`<br>`q.in<T>(unit, ignore(OVERFLOW_RISK | TRUNCATION_RISK))` |

These new versions are both more clear about their intent, and safer (because they only turn off
the safety checks that they need to).

Note: if you were only providing `<T>` in order to keep the same rep as the input (rather than
to genuinely change it), use [`SameRep`](#same-rep) for `T` instead of naming the concrete type.

This function performs the exact same kind of unit conversion as if the string `coerce_` were
removed. However, it will ignore any safety checks for overflow or truncation.

??? example "Example: forcing a conversion from centimeters to meters"
`centi(meters_pt)(200).in(meters_pt)` is not allowed. This conversion will divide the
underlying value, `200`, by `100`. Now, it so happens that this _particular_ value _would_
produce an integer result. However, the compiler must decide whether to permit this operation
_at compile time_, which means we don't yet know the value. Since most `int` values would _not_
produce integer results, we forbid this.

`centi(meters_pt)(200).coerce_in(meters_pt)` _is_ allowed. The `coerce_` prefix has "forcing"
semantics. This would produce `2`. However, note that this operation uses integer division,
which truncates: so, for example, `centi(meters_pt)(199).coerce_in(meters_pt)` would produce
`1`.

These functions also support an explicit template parameter: so, `.coerce_as<T>(unit)` and
`.coerce_in<T>(unit)`. If you supply this parameter, it will be the rep of the result.

??? example "Example: simultaneous unit and type conversion"
`centi(meters_pt)(271.8).coerce_as<int>(meters_pt)` will return `meters_pt(2)`.

!!! tip
Prefer **not** to use the "coercing versions" if possible, because you will get more safety
checks. The risks which the "base" versions warn about are real.

## Changing the representation type

There are two ways to change the representation type of a `QuantityPoint`, `p`, to some target type
Expand Down
Loading