-
-
Notifications
You must be signed in to change notification settings - Fork 3.6k
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
Direction: Rename from_normalized
to new_unchecked
#11425
Direction: Rename from_normalized
to new_unchecked
#11425
Conversation
@@ -28,6 +28,18 @@ impl Direction3d { | |||
Self::new_and_length(value).map(|(dir, _)| dir) | |||
} | |||
|
|||
/// Create a [`Direction3d`] from a [`Vec3`] that is already normalized. | |||
/// | |||
/// ## Safety |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
/// ## Safety | |
/// # Safety |
// SAFETY: Multipling a normalized vector (Vec3::Y) with a rotation returns a normalized vector. | ||
direction: unsafe { Direction3d::new_unchecked(rotation * Vec3::Y) }, |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Can Direction(3d,2d)
implements rotation ? (probably in another PR)
to directly use rotation * Direction3d::Y
without unsafe.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Conventionally, unsafe
in Rust is used strictly for memory safety issues (or other odd corners where you might hit genuine Undefined Behavior in the compiler). While I strongly think that there should be alternatives that work like unsafe
, but for other forms of danger, we should stick to the conventions of the ecosystem.
That said, I love the rest of these changes and think we need to warn more aggressively here.
Yes, but it's also used in cases where there is a promise that a certain type must have some limitation (being normalized in this case). All the Having a direction vector that is not normalized may not cause UB in the traditional sense, but it could cause unforeseen bugs. |
|
No, but it almost certainly cause bugs in code that expect Marking it as |
From the Book:
|
Panics are arent much of a problem here (they can easily be tracked down), what is a problem is a silent bug (A bug that doesn't provide any debug information when it occurs). For example, if you have a player movement function that takes in a The
- The The "contract" here is that the inner vector is normalized. As I said earlier, making this |
This has been a longstanding discussion in the rust community. "What should I mark as unsafe?" For the standard library, the answer is "only methods with invariants, which, if not upheld, invoke undefined behaviors". There is even a chapter on the rust reference about "behaviors not considered unsafe": https://doc.rust-lang.org/stable/reference/behavior-not-considered-unsafe.html. "Logic Errors" is in there. This doesn't answer the question of whether we should mark the method as unsafe. The thing is, we already expose API that assumes the values passed-in represent a normal vector: The |
Well, I guess I'll make it safe. |
from_normalized
to new_unchecked
and declare unsafefrom_normalized
to new_unchecked
Co-authored-by: Tristan Guichaoua <33934311+tguichaoua@users.noreply.github.com>
Co-authored-by: Tristan Guichaoua <33934311+tguichaoua@users.noreply.github.com>
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Some comment nits, but otherwise looks good
Co-authored-by: Joona Aalto <jondolf.dev@gmail.com>
Quaternions do not need to be normalized. Only quaternions that are used for rotation do. I've used quaternions to represent angular velocity before, and those were intentionally not normalized. In nalgebra, there's UnitQuaternion specifically for rotations, but there's nothing similar in bevy/glam. |
Objective
Direction2d::from_normalized
&Direction3d::from_normalized
don't emphasize that importance of the vector being normalized enough.Solution
Rename
from_normalized
tonew_unchecked
and add more documentation.Direction2d
andDirection3d
were added somewhat recently in #10466 (after 0.12), so I don't think documenting the changelog and migration guide is necessary (Since there is no major previous version to migrate from).But here it is anyway in case it's needed:
Changelog
Direction2d::from_normalized
andDirection3d::from_normalized
tonew_unchecked
.Migration Guide
Direction2d::from_normalized
andDirection3d::from_normalized
tonew_unchecked
.