Add core::{f32,f64}::consts::TAU.

[m-ou-se]

τ

[rust-highfive]

r? @kennytm

(rust_highfive has picked a reviewer for you, use r? to override)

[kennytm]

r? @dtolnay

[steveklabnik]

I am not on the libs team, so my opinion doesn't really matter, but I don't think we should add this. Rust is not batteries included, and this just doesn't add enough value to justify itself.

[m-ou-se]

Python has added this a few years ago, and it has become quite popular. (More popular than things like asinh for example.)

Considering the Rust standard library already comes with constants like FRAC_2_SQRT_PI, FRAC_PI_6 and LOG10_E, this seems like a rather small addition.

[RustyYato]

@steveklabnik given that we already have various fractions of pi (pi/2, pi/3, pi/4, pi/6, and pi/8), and adding a new const is super low cost, I don't think that there is much of a cost to adding TAU. Adding TAU allows thinking in terms of rotations instead of half rotations, which is significantly easier. So it does have really nice benefits.

We also have FRAC_2_SQRT_PI which is significantly more niche that TAU.

I realize that saying we have other constants is not an argument for adding another one, but the cost of adding a constant is almost nonexistent, so I don't see a reason to block it if there is some reason for adding it. Given that TAU makes thinking about rotations easier, and no one would pull a crate for a constant, I think this is fine.

[MikailBag]

Related: https://blog.wolfram.com/2015/06/28/2-pi-or-not-2-pi/
Many usages of Pi should be replaced with Tau.
For example, if I want to get root of unity:

// with pi
use std::f64::{PI, sin, cos};
let omega = (cos(2*PI / n), sin(2*PI / n));
// with tau
use std::f64::{TAU, sin, cos};
let omega = (cos(TAU / n), sin(TAU / n));

You can see tau makes code simpler for understanding.

@m-ou-se , do you mind adding

• link to tau manifesto (https://tauday.com/tau-manifesto),
• definition of tau,
• or some simple example that makes use of tau.
  to docs?
  Of course, Rust docs are not Math textbook, but tau is not well-known constant and maybe some explanation is worth addition.

[m-ou-se]

@MikailBag The reason to add it to the standard library is that it's popular enough now that there are plenty of people who will want to use it. The point is not to use Rust's documentation to convice people to switch to tau (e.g. by linking the manifesto). I already put the definition (τ=2π) in the doc comments.

[m-ou-se]

Note also that two other new constants (LOG2_10, LOG10_2) are being stabilized right now because they are somewhat useful in specific use cases, and also exist in the D language: See #50540 and #50539

Considering tau has way more use cases, and has been in use in Python, Perl, Processing, Nim, Zig, and some others, I don't see why the idea of adding tau should lead to a big discussion every time.

[kennytm]

@KrishnaSannasi We have FRAC_2_SQRT_PI because it was usually defined in C, not because it was commonly used. All stable numeric constants except π/3, π/6, π/8 (#6048) have corresponding C constants (once upon a time there was PI_2/two_pi() as well, but for some reason it was gone after the num reform).

Rust	C
E	M_E
FRAC_1_PI	M_1_PI
FRAC_2_PI	M_2_PI
FRAC_2_SQRT_PI	M_2_SQRTPI
FRAC_1_SQRT_2	M_SQRT1_2
FRAC_PI_2	M_PI_2
FRAC_PI_3	-
FRAC_PI_4	M_PI_4
FRAC_PI_6	-
FRAC_PI_8	-
LN_2	M_LN2
LN_10	M_LN10
LOG2_E	M_LOG2E
LOG10_E	M_LOG10E
PI	M_PI
SQRT_2	M_SQRT2
LOG10_2	-
LOG2_10	-
TAU	-

[dtolnay]

I am on board with adding a 2π constant. 2π appears commonly, and the justification that it's useful to have something that couples tightly (#66770 (comment)) is compelling to me. #66769 (comment) is compelling as well: "The point is not to use Rust's documentation to convince people to switch to tau (e.g. by linking the manifesto)." People are free to continue writing 2.0 * PI, just as they are free to continue using PI / 2.0 instead of our FRAC_PI_2 constant.

I added two checklist items to the tracking issue to follow up prior to stabilization:

• Confirm that these numeric values are accurate. I did not do any validation other than eyeballing the numbers.
• Decide whether we are comfortable using the name TAU or instead a longer but more widely accepted name like TWO_PI could be better.

[dtolnay]

@bors r+

[bors]

📌 Commit d220ed4 has been approved by dtolnay

[scottmcm]

Confirm that these numeric values are accurate. I did not do any validation other than eyeballing the numbers.

Because of floating point, I would expect 2.0 * PI to be perfectly accurate for this at all times, since it's just an exponent adjustment. Should it just be implemented that way to avoid the question?

[solson]

@scottmcm Would the same argument apply to FRAC_PI_2, FRAC_PI_4, and FRAC_PI_8? Perhaps somewhere someone has written down a best practices for numerical constants.

Edit: One can input the digits of pi and tau from this PR here in separate tabs and confirm they share the same significand, differing only by exponent. For a bit of fun, press "toggle details", and tick the exponent value up or down.