Skip to content
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

Add coercing versions of conversion functions #171

Merged
merged 1 commit into from
Sep 1, 2023
Merged

Conversation

chiphogg
Copy link
Contributor

@chiphogg chiphogg commented Aug 29, 2023

These are variants of .as and .in for both Quantity and
QuantityPoint. When we precede these with the "coerce" vocabulary
word, they become forcing, ignoring the safety checks for truncation and
overflow.

This new syntax has two major advantages over the explicit-Rep version.
First, it makes the intent clearer. Second, it stops forcing users to
repeat the rep when they want the same rep they started with, which I
think is the usual case. (Thus, without these APIs, explicit-rep
obscures intent: one never knows whether the author wanted a cast, or
wanted to bypass the safety checks.)

It also unlocks another, later improvement: we will be able to extend
the safety checks to the explicit-rep versions! But we won't attempt
that for a while because that's a breaking change.

There may be other APIs that would benefit from using the "coerce"
vocabulary word instead of explicit-rep. However, we'll start with just
these, both because they're the overwhelmingly most common use case, and
because it gives us a chance to try out these ideas in practice for a
while.

To test this PR, I added new unit tests to cover all of the use cases.
I also rendered the docs locally and checked that the links worked as
intended.

Helps #122.

These are variants of `.as` and `.in` for both `Quantity` and
`QuantityPoint`.  When we precede these with the "coerce" vocabulary
word, they become forcing, ignoring the safety checks for truncation and
overflow.

This new syntax has two major advantages over the explicit-Rep version.
First, it makes the intent clearer.  Second, it stops forcing users to
repeat the rep when they want the same rep they started with, which I
think is the usual case.  (Thus, without these APIs, explicit-rep
obscures intent: one never knows whether the author wanted a cast, or
wanted to bypass the safety checks.)

It also unlocks another, later improvement: we will be able to extend
the safety checks to the explicit-rep versions!  But we won't attempt
that for a while because that's a breaking change.

There may be other APIs that would benefit from using the "coerce"
vocabulary word instead of explicit-rep.  However, we'll start with just
these, both because they're the overwhelmingly most common use case, and
because it gives us a chance to try out these ideas in practice for a
while.

Helps #122.

We'll start with just these functions because they're by far the most
prevalent.  Later on, we can
@chiphogg chiphogg added the release notes: ✨ lib (enhancement) PR enhancing the library code label Aug 29, 2023
@chiphogg chiphogg marked this pull request as ready for review August 29, 2023 23:53
Copy link
Contributor

@geoffviola geoffviola left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The API changes look good. I like that the truncation/overflow at runtime is enabled with a longer, explicit name like static_cast. Also, it's nice not to have to repeat the rep in doing a conversion. The tests cover truncation and overflow for quantity and quantity point. The docs changes seem good.

@chiphogg chiphogg merged commit 8553753 into main Sep 1, 2023
9 checks passed
@chiphogg chiphogg deleted the dot-coerce#122 branch September 1, 2023 12:12
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
release notes: ✨ lib (enhancement) PR enhancing the library code
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants