[RFC]: replace inline NaN generation with stdlib NaN constants in C source files (tracking issue)
- Lingua principale
- JavaScript
- Stelle
- 6k
- Fork
- 1.3k
- Merge medio
- 1g 3h
- PR unite (30g)
- 611
Descrizione
## Instructions
1. Read the issue description below.
2. Review the example pull requests linked below.
3. Search the codebase for a package containing inline NaN generation in a C source file and update it according to this issue.
4. Follow all additional guidance in this issue.
---
## Description
This RFC proposes replacing inline NaN generation (e.g., `0.0/0.0` or `0.0f/0.0f`) in C source files, examples, benchmarks, and README C usage snippets with the stdlib NaN constant from `@stdlib/constants/float64/nan` or `@stdlib/constants/float32/nan`.
In short, this RFC seeks to refactor code from this pattern:
```c
return 0.0/0.0; // NaN
```
to this pattern:
```c
#include "stdlib/constants/float64/nan.h"
// ...
return STDLIB_CONSTANT_FLOAT64_NAN;
```
This refactoring is demonstrated in [PR #11768 (float64)](https://github.com/stdlib-js/stdlib/pull/11768) and [PR #11769 (float32)](https://github.com/stdlib-js/stdlib/pull/11769). Study both PRs before starting, as they demonstrate the exact changes being sought.
In particular, notice three things:
1. We add the C header include for the NaN constant: `#include "stdlib/constants/float64/nan.h"`.
2. We replace inline NaN generation with the macro `STDLIB_CONSTANT_FLOAT64_NAN`.
3. We add the dependency `@stdlib/constants/float64/nan` to all manifest configuration entries (`build`, `benchmark`, `examples`) which compile the updated C source file.
By performing this refactoring, we facilitate:
1. Consistent NaN handling across packages and targets.
2. Better readability and maintainability in C implementations.
### Float32
There are also inline float32 NaN occurrences written as `0.0f/0.0f` which must be replaced with `STDLIB_CONSTANT_FLOAT32_NAN` from `@stdlib/constants/float32/nan`. The equivalent include is `#include "stdlib/constants/float32/nan.h"` and the manifest dependency is `@stdlib/constants/float32/nan`. The float32 migration is demonstrated in [PR #11769](https://github.com/stdlib-js/stdlib/pull/11769).
---
## Steps
1. Study the changes in [PR #11768](https://github.com/stdlib-js/stdlib/pull/11768) (float64) and [PR #11769](https://github.com/stdlib-js/stdlib/pull/11769) (float32), as these demonstrate the exact changes being sought.
2. Ensure your local development environment is set up by following the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md), including running `make install-node-modules` and `make init`.
3. Find a package containing inline NaN generation in a C source file. A possible global project search can use the following regular expression:
```
0\.0f?\s*/\s*0\.0f?
```
From the search results, locate a package not already addressed by an open or merged PR referencing this issue.
4. Update that package, and **only that package**, to use `STDLIB_CONSTANT_FLOAT64_NAN` (or `STDLIB_CONSTANT_FLOAT32_NAN` for float32). Updated files may include `src/main.c`, `examples/c/example.c`, `benchmark/c/benchmark.c`, and any C code snippets in `README.md`.
5. When adding the `#include` statement, place it with the existing stdlib includes in the file, following the include ordering already present. Do not reorder existing includes.
6. Update `manifest.json` to add the NaN constant package as a dependency in **every** `confs` entry that compiles the updated C source file. This typically includes the `build`, `benchmark`, and `examples` task entries. For example (float64 shown; use `@stdlib/constants/float32/nan` for float32 packages):
```diff
{
"task": "build",
"src": [
"./src/main.c"
],
"include": [
"./include"
],
"libraries": [],
"libpath": [],
"dependencies": [
- "@stdlib/some/existing/dep"
+ "@stdlib/some/existing/dep",
+ "@stdlib/constants/float64/nan"
]
}
```
7. Also check the package `README.md` for any C usage examples containing `0.0/0.0` or `0.0f/0.0f` and update those to use the macro as well.
8. Build the Node add-on and run the C examples, benchmarks, and native tests using the commands below. Replace `` with the path of the package you updated (e.g., `stats/strided/dnanmeanpn`):
```bash
cd /path/to/stdlib
# Build the Node add-on for the specific package
make install-node-addons NODE_ADDONS_PATTERN=""
# Run C examples, benchmarks, and native tests
make EXAMPLES_FILTER=".*//.*" examples-c
make BENCHMARKS_FILTER=".*//.*" benchmark-c
make test TESTS_FILTER=".*//.*"
```
Verify that the test and example output after refactoring is identical to what it was before (i.e., `NaN` is returned wherever expected). No behavioral changes should result from this refactor.
9. Before opening a PR, search existing open pull requests that reference this issue to confirm no one has already submitted the same package.
10. Commit your changes and submit a PR updating **only that package**.
11. Use the appropriate PR title template based on which constant you replaced:
For float64 packages:
```
refactor: use `constants/float64/nan` in
```
For float32 packages:
```
refactor: use `constants/float32/nan` in
```
12. In the PR body, use the phrase **"Resolves a part of"** followed by a link to this issue. Do **not** use "Resolves" or "Closes", as this is a tracking issue and your PR only addresses one package of many.
---
## Related Issues
None.
## Questions
None.
---
## Other
- For each pull request, please update **only one package**.
- Do **not** make unrelated or stylistic changes. Only replace inline NaN generation with the shared NaN constant and make the required dependency and include updates. Failure to respect this guidance will result in your PR being closed without review.
- Before opening a PR, verify that no existing open PR already addresses the same package by searching pull requests that reference this issue.
- As this is a **Good First Issue**, you are **strongly encouraged** to **avoid** using AI when authoring your contribution. One of the primary intents of Good First Issues is to help introduce you to stdlib, its development environment, and the contribution process, as documented in the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md). Most new contributors are unfamiliar with stdlib and its conventions, and thus fail to appropriately use AI assistance, most often generating low-quality output that leads to wasted time for everyone involved. Take the time to manually author your first several PRs, and once you are intimately familiar with project conventions, you can consider leveraging AI to augment your development tasks.
---
## Checklist
- [x] I have read and understood the [Code of Conduct](https://github.com/stdlib-js/stdlib/blob/develop/CODE_OF_CONDUCT.md).
- [x] I have searched for existing issues and pull requests.
- [x] The issue title begins with `RFC:`.
Guida per i contributori
Apri la guida per i contributori
Valutazione
Questa issue non è ancora stata valutata.