diff --git a/au/constant.hh b/au/constant.hh index 6a017b1e..cfae25aa 100644 --- a/au/constant.hh +++ b/au/constant.hh @@ -55,17 +55,6 @@ struct Constant : detail::MakesQuantityFromNumber, return make_quantity(static_cast(1)); } - // Convert this constant to a Quantity of the given unit and rep, ignoring safety checks. - template - [[deprecated( - "`coerce_as()` is deprecated. Use `as()` instead, and pass a risk policy parameter. " - "Upgrade guide: " - "")]] constexpr auto - coerce_as(OtherUnit u) const { - return as().coerce_as(u); - } - // Convert this constant to a Quantity of the given unit and rep. template AU_DEVICE_FUNC constexpr auto as(OtherUnit u) const { @@ -90,17 +79,6 @@ struct Constant : detail::MakesQuantityFromNumber, return this_value.template as(OtherUnit{}, ignore(ALL_RISKS)); } - // Get the value of this constant in the given unit and rep, ignoring safety checks. - template - [[deprecated( - "`coerce_in()` is deprecated. Use `in()` instead, and pass a risk policy parameter. " - "Upgrade guide: " - "")]] constexpr auto - coerce_in(OtherUnit u) const { - return as().coerce_in(u); - } - // Get the value of this constant in the given unit and rep. template AU_DEVICE_FUNC constexpr auto in(OtherUnit u) const { diff --git a/au/quantity.hh b/au/quantity.hh index 54ad2499..29777292 100644 --- a/au/quantity.hh +++ b/au/quantity.hh @@ -244,48 +244,6 @@ class Quantity { return in_impl(u, policy); } - // "Forcing" conversions, which explicitly ignore safety checks for overflow and truncation. - template - [[deprecated( - "`coerce_as()` is deprecated. Use `as()` instead, and pass a risk policy parameter. " - "Upgrade guide: " - "")]] constexpr auto - coerce_as(NewUnit) const { - // Usage example: `q.coerce_as(new_units)`. - return as(NewUnit{}, ignore(ALL_RISKS)); - } - template - [[deprecated( - "`coerce_as()` is deprecated. Use `as()` instead, and pass a risk policy parameter. " - "Upgrade guide: " - "")]] constexpr auto - coerce_as(NewUnit) const { - // Usage example: `q.coerce_as(new_units)`. - return as(NewUnit{}, ignore(ALL_RISKS)); - } - template - [[deprecated( - "`coerce_in()` is deprecated. Use `in()` instead, and pass a risk policy parameter. " - "Upgrade guide: " - "")]] constexpr auto - coerce_in(NewUnit) const { - // Usage example: `q.coerce_in(new_units)`. - return in(NewUnit{}, ignore(ALL_RISKS)); - } - template - [[deprecated( - "`coerce_in()` is deprecated. Use `in()` instead, and pass a risk policy parameter. " - "Upgrade guide: " - "")]] constexpr auto - coerce_in(NewUnit) const { - // Usage example: `q.coerce_in(new_units)`. - return in(NewUnit{}, ignore(ALL_RISKS)); - } - // Direct access to the underlying value member, with any Quantity-equivalent Unit. // // Mutable access: diff --git a/au/quantity_point.hh b/au/quantity_point.hh index f8eb29b3..3a6c4a9f 100644 --- a/au/quantity_point.hh +++ b/au/quantity_point.hh @@ -188,48 +188,6 @@ class QuantityPoint { return in_impl(u, policy); } - // "Forcing" conversions, which explicitly ignore safety checks for overflow and truncation. - template - [[deprecated( - "`coerce_as()` is deprecated. Use `as()` instead, and pass a risk policy parameter. " - "Upgrade guide: " - "")]] constexpr auto - coerce_as(NewUnit) const { - // Usage example: `p.coerce_as(new_units)`. - return as(NewUnit{}, ignore(ALL_RISKS)); - } - template - [[deprecated( - "`coerce_as()` is deprecated. Use `as()` instead, and pass a risk policy parameter. " - "Upgrade guide: " - "")]] constexpr auto - coerce_as(NewUnit) const { - // Usage example: `p.coerce_as(new_units)`. - return as(NewUnit{}, ignore(ALL_RISKS)); - } - template - [[deprecated( - "`coerce_in()` is deprecated. Use `in()` instead, and pass a risk policy parameter. " - "Upgrade guide: " - "")]] constexpr auto - coerce_in(NewUnit) const { - // Usage example: `p.coerce_in(new_units)`. - return in(NewUnit{}, ignore(ALL_RISKS)); - } - template - [[deprecated( - "`coerce_in()` is deprecated. Use `in()` instead, and pass a risk policy parameter. " - "Upgrade guide: " - "")]] constexpr auto - coerce_in(NewUnit) const { - // Usage example: `p.coerce_in(new_units)`. - return in(NewUnit{}, ignore(ALL_RISKS)); - } - // Direct access to the underlying value member, with any Point-equivalent Unit. // // Mutable access: diff --git a/docs/reference/constant.md b/docs/reference/constant.md index 618f270c..a4903db2 100644 --- a/docs/reference/constant.md +++ b/docs/reference/constant.md @@ -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(unit)` - -!!! warning - These functions are deprecated. For a `Constant` `c`, instead of `c.coerce_as(unit)`, prefer - `c.as(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(unit)`](#as-T-unit), except that it will ignore the safety checks that -prevent truncation and overflow. - -!!! warning - Because `.as(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(unit)`), _or_ it - produces a result which is **guaranteed to be lossy**. Therefore, be very judicious in using - this function. - ### `.in(unit)` {#in-T-unit} This function produces a raw numeric value, of type `T`, holding the value of the constant in the @@ -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(unit)` - -!!! warning - These functions are deprecated. For a `Constant` `c`, instead of `c.coerce_in(unit)`, prefer - `c.in(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(unit)`](#in-T-unit), except that it will ignore the -safety checks that prevent truncation and overflow. - -!!! warning - Because `.in(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(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 diff --git a/docs/reference/quantity.md b/docs/reference/quantity.md index 49402ec0..00eac752 100644 --- a/docs/reference/quantity.md +++ b/docs/reference/quantity.md @@ -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:
`q.as(unit, ignore(OVERFLOW_RISK))`
`q.as(unit, ignore(TRUNCATION_RISK))`
`q.as(unit, ignore(OVERFLOW_RISK | TRUNCATION_RISK))` | - | `q.coerce_as(unit)` | One of:
`q.as(unit, ignore(OVERFLOW_RISK))`
`q.as(unit, ignore(TRUNCATION_RISK))`
`q.as(unit, ignore(OVERFLOW_RISK | TRUNCATION_RISK))` | - | `q.coerce_in(unit)` | One of:
`q.in(unit, ignore(OVERFLOW_RISK))`
`q.in(unit, ignore(TRUNCATION_RISK))`
`q.in(unit, ignore(OVERFLOW_RISK | TRUNCATION_RISK))` | - | `q.coerce_in(unit)` | One of:
`q.in(unit, ignore(OVERFLOW_RISK))`
`q.in(unit, ignore(TRUNCATION_RISK))`
`q.in(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 `` 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(unit)` and -`.coerce_in(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(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 diff --git a/docs/reference/quantity_point.md b/docs/reference/quantity_point.md index 41098ee9..7de471ac 100644 --- a/docs/reference/quantity_point.md +++ b/docs/reference/quantity_point.md @@ -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:
`q.as(unit, ignore(OVERFLOW_RISK))`
`q.as(unit, ignore(TRUNCATION_RISK))`
`q.as(unit, ignore(OVERFLOW_RISK | TRUNCATION_RISK))` | - | `q.coerce_as(unit)` | One of:
`q.as(unit, ignore(OVERFLOW_RISK))`
`q.as(unit, ignore(TRUNCATION_RISK))`
`q.as(unit, ignore(OVERFLOW_RISK | TRUNCATION_RISK))` | - | `q.coerce_in(unit)` | One of:
`q.in(unit, ignore(OVERFLOW_RISK))`
`q.in(unit, ignore(TRUNCATION_RISK))`
`q.in(unit, ignore(OVERFLOW_RISK | TRUNCATION_RISK))` | - | `q.coerce_in(unit)` | One of:
`q.in(unit, ignore(OVERFLOW_RISK))`
`q.in(unit, ignore(TRUNCATION_RISK))`
`q.in(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 `` 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(unit)` and -`.coerce_in(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(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