Deprecate PI
#250
Merged
Deprecate PI
#250
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
If we have anything called `PI` --- even if it is properly encapsulated inside a C++ namespace! --- then users will be unable to use our library if they also depend on _any library_ that defines a macro called `PI`, in _any_ namespace (because macros _do not care_ about namespaces). Of course, defining a macro named `PI` would be an execrable and amateurish violation of long-accepted best practices for C++ software engineering. However, at least one library does this: the Arduino core library. Therefore, if we want to support it --- which we most certainly do --- then we will have to yield. The plan going forward is to release this deprecation as part of 0.3.5, and then fully delete the variable as part of 0.4.0. In the meantime, users can still get Au to work; they just need to make sure that they include Au _after_ any files that --- _lamentably_ --- define a macro `PI`. We have other "short all-caps" identifiers, `ONE` and `ZERO`. We could get rid of `ONE` with no trouble at all; `mag<1>()` is a fine replacement. Getting rid of `ZERO` would be extremely painful, though. The motivation to define a `ZERO` macro is far less than for `PI`, so I am planning to simply hope that no library of note has done this, and expecting to tell users of any such library that they are simply out of luck. Fixes #246.
chiphogg
added
the
release notes: 🗑️ lib (deprecation)
geoffviola
approved these changes
Jun 24, 2024
chiphogg
added a commit
that referenced
this pull request
Aug 12, 2024
It conflicts with the `pascal` macro in `<Windows.h>`. Yes, they really did define a lowercase-named macro in `<Windows.h>`. As with `PI` (#247), the `#ifndef` should immediately unblock most users, but it's not a long-term solution, because it depends on order-of-includes. Therefore, we also deprecate `pascal` (as with `PI` in #250). I think a good rule of thumb is that deprecated constructs should be deprecated for at least one full minor release cycle, so we'll plan to delete it (along with `PI`) as part of 0.5.0. Fixes #284.
Merged
chiphogg
added a commit
that referenced
this pull request
Aug 12, 2024
It conflicts with the `pascal` macro in `<Windows.h>`. Yes, they really did define a lowercase-named macro in `<Windows.h>`. As with `PI` (#247), the `#ifndef` should immediately unblock most users, but it's not a long-term solution, because it depends on order-of-includes. Therefore, we also deprecate `pascal` (as with `PI` in #250). I think a good rule of thumb is that deprecated constructs should be deprecated for at least one full minor release cycle, so we'll plan to delete it (along with `PI`) as part of 0.5.0. Fixes #284.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
If we have anything called
PI--- even if it is properly encapsulatedinside a C++ namespace! --- then users will be unable to use our library
if they also depend on any library that defines a macro called
PI,in any namespace (because macros do not care about namespaces).
Of course, defining a macro named
PIwould be an execrable andamateurish violation of long-accepted best practices for C++ software
engineering. However, at least one library does this: the Arduino core
library. Therefore, if we want to support it --- which we most
certainly do --- then we will have to yield.
The plan going forward is to release this deprecation as part of 0.3.5,
and then fully delete the variable as part of 0.4.0. In the meantime,
users can still get Au to work; they just need to make sure that they
include Au after any files that --- lamentably --- define a macro
PI.We have other "short all-caps" identifiers,
ONEandZERO. We couldget rid of
ONEwith no trouble at all;mag<1>()is a finereplacement. Getting rid of
ZEROwould be extremely painful, though.The motivation to define a
ZEROmacro is far less than forPI, so Iam planning to simply hope that no library of note has done this, and
expecting to tell users of any such library that they are simply out of
luck.
Fixes #246.