0.2.9 (stable): Links to work on both GitHub and rustdoc/crates.io (part 3)

Author: peter-lyons-kehl

CHANGELOG.md

@@ -13,6 +13,10 @@ behind `main`. See also [CONTRIBUTING.md](CONTRIBUTING.md).
 `ndd::infer::NonDeDuplicatedStr` and `ndd::infer::NonDeDuplicatedCStr`
 -->
 
+## 0.2.9 (stable)
+
+`README.md` links to work on both GitHub and `rustdoc` or `crates.io` (more).
+
 ## 0.2.8 (stable)
 
 `README.md` links to work on both GitHub and `rustdoc` or `crates.io`.

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "ndd"
-version = "0.2.8"
+version = "0.2.9"
 edition = "2024"
 
 license = "BSD-2-Clause OR Apache-2.0 OR MIT"

Cargo.toml

@@ -1,16 +1,27 @@
-# ndd (Non-De-Duplicated)
-
 ![GitHub Actions
 results](https://github.com/peter-lyons-kehl/ndd/actions/workflows/main.yml/badge.svg)
 
-## Summary
+# Summary
+
+`ndd` (Non-De-Duplicated) is a zero-cost transparent wrapper. For `static` variables that do **not**
+share memory with any other `static` or `const` (or local) variables (or literals). Use for `static`
+data (single variables/arrays/slices) referenced with references/slices/pointers that are **compared
+by address**.
+
+# Use
+
+Use [`ndd::NonDeDuplicated`] to wrap your static data (other than string literals (`&str`) or C
+string literal bytes). Use it for (immutable) `static` variables only.
+
+Use [`ndd::NonDeDuplicatedStr`] and [`ndd::NonDeDuplicatedCStr`] to wrap static string slices
+(`&str`) and C strings (owned bytes that defer to `&CStr`). These two types need a `const` generic
+parameter `N`, which is the length (in bytes). There is no way around this (in stable Rust). On
+`nightly` Rust you can use `ndd::infer:NonDeDuplicatedStr` and `ndd::infer:NonDeDuplicatedCStr` from
+**odd-numbered** (`-nightly`) version of `ndd` instead.
 
-Zero-cost transparent wrapper. For `static` variables guaranteed not to share memory with any other
-`static` or `const` (or local literals). Especially for `static` data (single
-variables/arrays/slices) referenced with references/slices/pointers that are **compared by
-address**.
+See unit tests in [`src/lib.rs`], and [`cross_crate_demo_fix/callee/src/lib.rs`].
 
-## Problem
+# Problem
 
 Rust (or, rather, LLVM) by default de-duplicates or reuses **addresses** of `static` variables in
 `release` builds. And somewhat in `dev` (debug) builds, too. For most purposes that is good: The
@@ -31,16 +42,16 @@ the API could trigger your designated signalling unintentionally.
 
 That does work out of the box when the client passes a reference/slice defined as `static`: each
 `static` gets its own memory space (even with the default `release` optimizations). See a test
-[`src/lib.rs` -> `addresses_unique_between_statics()`].
+[`src/lib.rs` -> `tests_without_ndd` -> `addresses_unique_between_statics()`].
 
 However, there is a problem (caused by de-duplication in `release`, and for some types even in `dev
 or `miri). It affects ("ordinary") `const` values/expressions that equal in value to any `static`
 (whether it's a `static` variable, or a static literal), which may be your designated `static`.
 Rust/LLVM re-uses address of one such matching `static` for references to any equal value(s) defined
-as `const`. See a test [`src/lib.rs` ->
-`addresses_not_unique_between_const_and_static()`](https://github.com/peter-lyons-kehl/ndd/blob/26d743d9b7bbaf41155e00174f8827efca5d5f32/src/lib.rs#L95).
-Such `const`, `static` or literal could be in 3rd party code, even private. (See
-[`cross_crate_demo_bug/`](https://github.com/peter-lyons-kehl/ndd/tree/main/cross_crate_demo_bug))!
+as `const`. See <!-- padding for re-wrap                                                        -->
+[`src/lib.rs` -> `tests_without_ndd` -> `u8_global_const_and_global_static_release()`]. Such
+`const`, `static` or literal could be in 3rd party code, even private. (See
+[`cross_crate_demo_bug/`].)
 
 Things get worse: `dev` builds don't have this consistent:
 
@@ -69,42 +80,33 @@ lto = "fat"
 opt-level = 2
 ```
 
-## Solution
+# Solution
 
-`ndd:NonDeDuplicated` uses
-[`core::cell::Cell`](https://doc.rust-lang.org/nightly/core/cell/struct.Cell.html) to hold the data
-passed in by the user. There is no mutation and no mutation access. The only access it gives to the
-inner data is through shared references.
+[`ndd::NonDeDuplicated`] uses [`core::cell::Cell`] to hold the data passed in by the user. There is
+no mutation and no mutation access. The only access it gives to the inner data is through shared
+references.
 
-Unlike `Cell` (and friends), `NonDeDuplicated` **does** implement
-[`core::marker::Sync`](https://doc.rust-lang.org/nightly/core/marker/trait.Sync.html) (if the inner
-data's type implements `Send` and  `Sync`). It can safely do so, because it never provides mutable
-access, and it never mutates the inner data. That is similar to how
-[`std::sync::Mutex`](https://doc.rust-lang.org/nightly/std/sync/struct.Mutex.html#impl-Sync-for-Mutex%3CT%3E)
-implements `Sync`, too.
+Unlike [`core::cell::Cell`] (and friends), `NonDeDuplicated` **does** implement
+[`core::marker::Sync`] (if the inner data's type implements [`core::marker::Send`] and
+[`core::marker::Sync`]). It can safely do so, because it never provides mutable access, and it never
+mutates the inner data. That is similar to how [`std::sync::Mutex`] implements
+[`core::marker::Sync`], too.
 
-See [`src/lib.rs` ->
-`tests_behavior_with_ndd`](https://github.com/search?q=repo%3Apeter-lyons-kehl%2Fndd+tests_behavior_with_ndd+path%3Asrc%2Flib.rs&type=code).
+See [`src/lib.rs` -> `tests_with_ndd`].
 
-## Use
+# Compatibility
 
-Use `ndd::NonDeDuplicated` to wrap your static data. Use it for (immutable) `static` variables only.
-Do **not** use it for locals or on heap. That is validated by implementation of
-[core::ops::Drop](https://doc.rust-lang.org/nightly/core/ops/trait.Drop.html), which `panic`-s in
-`dev` builds.
-
-See unit tests in [src/lib.rs](src/lib.rs).
-
-## Compatibility
-
-`ndd` is `no_std`-compatible and it doesn't need heap (`alloc`) either. Release versions
+`ndd` is `no_std`-compatible and it doesn't need heap ([`alloc`]) either. Release versions
 (**even**-numbered major versions, and **not** `-nightly` pre-releases) compile with `stable` Rust.
 (More below.)
 
-### Stable is always forward compatible
+Do **not** use it for locals or on heap. That is validated by implementation of [`core::ops::Drop`],
+which `panic`s in `dev` builds.
 
-`ndd` is planned to be always below version `1.0`. (If a need arises for big incompatible
-functionality, that can go in a new crate.)
+## Always forward compatible
+
+`ndd` is planned to be always below version `1.0`. So stable (**even**-numbered) versions will be
+forward compatible. (If a need ever arises for big incompatibility, that can go in a new crate.)
 
 That allows you to specify `ndd` as a dependency with version `0.*`, which will match ANY **major**
 versions (below `1.0`, of course). That will match the newest (**even**-numbered major) stable
@@ -113,7 +115,7 @@ version (available for your Rust) automatically.
 This is special only to `0.*` - it is **not** possible to have a wildcard matching various **major**
 versions `1.0` or higher.
 
-### Versioning convention:
+## Versioning schema
 
 - **Even**-numbered major versions (`0.2`, `0.4`...)
   - are for **stable** functionality only.
@@ -123,8 +125,8 @@ versions `1.0` or higher.
 - **Odd**-numbered major versions (`0.3`, `0.5`...)
   - always contain `-nightly` (pre-release identifier) in their name.
   - are, indeed, for `nightly` (**unstable**) functionality, and need `nightly` Rust toolchain
-    (indicated with `rust-toolchain.toml` which is present on [`nightly`
-    branch](https://github.com/peter-lyons-kehl/ndd/tree/nightly) GIT branch only).
+    (indicated with `rust-toolchain.toml` which is present on [`nightly` GIT
+    branch](https://github.com/peter-lyons-kehl/ndd/tree/nightly) only).
   - include functionality already present in some lower stable versions. Not all of them - only:
     - stable versions with a **lower major** numeric version, and
     - if the stable **major** version is lower by **`0.1` only** (and not by more), then the stable
@@ -154,33 +156,36 @@ versions `1.0` or higher.
   trick](https://github.com/dtolnay/semver-trick). See also [The Cargo Book > Dependency
   Resolution](https://rustwiki.org/en/cargo/reference/resolver.html#version-incompatibility-hazards).
 
-  However, the only type exported from `ndd` is `ndd::NonDeDuplicated`. It is a zero-cost wrapper
-  suitable for immutable `static` variables. It is normally not being passed around as a
-  parameter/return type or a composite type. And its functions can get inlined/optimized away. So,
-  there shouldn't be any big binary size/speed difference, or usability difference, if there happen
-  to be multiple major versions of `ndd` in use at the same time. They would be all isolated. So
-  SemVer trick may be unnecessary.
+  However, the only types exported from `ndd` is [`ndd::NonDeDuplicated`],
+  [`ndd::NonDeDuplicatedStr`] and [`ndd::NonDeDuplicatedCStr`]. They are zero-cost wrappers suitable
+  for immutable `static` variables. They are normally not being passed around as a parameter/return
+  type or a composite type. And their functions can get inlined/optimized away. So, there shouldn't
+  be any big binary size/speed difference, or usability difference, if there happen to be multiple
+  major versions of `ndd` crate in use at the same time. They would be all isolated. So SemVer trick
+  may be unnecessary.
+
+Crate version is validated by GIT [`pre-commit`] and by [GitHub Actions].
 
-#### Rule of thumb for stable versions
+### Rule of thumb for stable versions
 
 On `stable` Rust, always specify `ndd` with version `0.*`. Then, automatically:
 
 - you will get the newest available even-numbered major (stable) version, and
 - your libraries will work with any newer **odd-numbered** major (`-nightly`) version of `ndd`, too,
   if any dependency (direct or transitive) requires it.
 
-#### Rule of thumb for unstable versions
+### Rule of thumb for unstable versions
 
 To find out the highest **even-numbered** (stable) version whose functionality is included in a
 given **odd-numbered** (`-nightly`) version, decrement the **odd-numbered** version by `0.1` (and
 remove the `-nightly` suffix).
 
-### Nightly versioning
+## Nightly versioning
 
 We prefer not to introduce temporary cargo features. Removing a feature later is a breaking change.
 And we don't want just to make such a feature no-op and let it sit around.
 
-So, instead, any `nightly`-only functionality is in separate version stream(s) that always
+So, instead, any `nightly`-only functionality has separate versions that always
 
 - are **pre-releases** (as per [The Cargo Book > Specifying Dependencies >
   Pre-releases](https://doc.rust-lang.org/nightly/cargo/reference/specifying-dependencies.html#pre-releases)
@@ -195,7 +200,7 @@ So, instead, any `nightly`-only functionality is in separate version stream(s) t
 
 As per Rust resolver rules, a stable (**non**-pre-release) version will NOT match/auto-update to a
 **pre-release** version on its own. Therefore, if your crate and/or its dependencies specify `ndd`
-version as `0.*`, they will **not** accidentally request an **odd**-numbered major (`-nightly`) on
+version as `0.*`, they will **not** accidentally request an **odd**-numbered (`-nightly`) major on
 their own.
 
 They can get a (`-nightly`) version, but only if another crate requires it. That's up to the
@@ -204,39 +209,37 @@ consumer.
 If you want more control over stable versions, you can fix the **even**-numbered major version, and
 use an asterisk mask for the minor version, like `0.2.*`. But then you lose automatic major updates.
 
-### Nightly functionality
+## Nightly functionality
 
-Functionality of odd-numbered major (`-nightly`) versions is always subject to change.
+WARNING: Functionality of odd-numbered major (`-nightly`) versions is always subject to change!
 
-The following extra functionality is available on `0.3.1-nightly`. You need `nightly` Rust toolchain
-(of course).
+The following extra functionality is available on `0.3.5-nightly`. Of course, you need `nightly`
+Rust toolchain.
 
-#### as_array_of_cells
+### as_array_of_cells
 
-`ndd::NonDeDuplicated` has function `as_array_of_cells`, similar to Rust's
-[`core::cell::Cell::as_array_of_cells`](https://doc.rust-lang.org/nightly/core/cell/struct.Cell.html#method.as_array_of_cells)
-(which will, hopefully, become stable in 1.91).
+[`ndd::NonDeDuplicated`] has function `as_array_of_cells`, similar to Rust's
+[`core::cell::Cell::as_array_of_cells`] (which will, hopefully, become stable in Rust 1.91).
 
-#### as_slice_of_cells
+### as_slice_of_cells
 
-Similar to `as_array_of_cells`, `ndd::NonDeDuplicated` has function `as_slice_of_cells`. That
+Similar to `as_array_of_cells`, [`ndd::NonDeDuplicated`] has function `as_slice_of_cells`. That
 **can** be stable with with Rust `1.88`+. However, to simplify versioning, it's bundled in
-`-nightly` together with `as_array_of_cells`. If you need it earlier, get in touch.
+`-nightly` together with `as_array_of_cells`. and may become stable at the same time. If you need it
+earlier, get in touch.
 
-#### const Deref and From
+### const Deref and From
 
-[core::ops::Deref](https://doc.rust-lang.org/nightly/core/ops/trait.Deref.html) and
-[core::convert::From](https://doc.rust-lang.org/nightly/core/convert/trait.From.html) are
-implemented as `const`. As of mid 2025, `const` traits are having high traction in Rust. Hopefully
-this will be stable not in years, but sooner.
+[`core::ops::Deref`] and [`core::convert::From`] are implemented as `const`. As of mid 2025, `const`
+traits are having high traction in Rust. Hopefully this will be stable not in years, but sooner.
 
 These traits are **not** implemented in stable versions at all. Why? Because `ndd` types are
 intended for `static` variables, so non-`const` functions don't help us.
 
-## Quality
+# Quality assurance
 
-Checks and tests are run by [GitHub Actions (CI)](.github/workflows/main.yml). All scripts run on
-Alpine Linux and are POSIX-compliant:
+Checks and tests are run by [GitHub Actions], which uses `rust:1.87-alpine` container. All scripts
+run on Alpine Linux (without `libc`) and are POSIX-compliant:
 
 - `cargo clippy`
 - `cargo fmt --check`
@@ -276,25 +279,52 @@ Alpine Linux and are POSIX-compliant:
     - `cross_crate_demo_fix/bin_fat_lto/not_deduplicated.sh release const_option_u8`
     - `cross_crate_demo_fix/bin_fat_lto/not_deduplicated.sh dev     const_bytes`
     - `cross_crate_demo_fix/bin_fat_lto/not_deduplicated.sh release const_bytes`
-- validate the versioning convention:
-  - [`pre-commit`](./pre-commit)
+- validate the versioning schema:
+  - [`pre-commit`]
 
-## Use cases
+# Use cases
 
 Used by
 [`hash-injector::signal`](https://github.com/peter-lyons-kehl/hash-injector/blob/main/lib/src/signal.rs).
 
-## Updates
+# Updates
 
 Please subscribe for low frequency updates at
-[#2](https://github.com/peter-lyons-kehl/ndd/issues/2).
+[peter-lyons-kehl/ndd/issues#2](https://github.com/peter-lyons-kehl/ndd/issues/2).
 
-## Side fruit
+# Side fruit
 
-The following side fruit is `std`-only, but related: `std::sync::mutex::data_ptr(&self)` is now
+The following side fruit is `std`-only, but related: `std::sync::mutex::data_ptr(&self)` is now a
 `const` function: pull request
 [rust-lang/rust#146904](https://github.com/rust-lang/rust/pull/146904).
 
+<!-- 1. Link URLs to be used on GitHub.
+     2. Relative links also work auto-magically on https://crates.io/crates/ndd.
+     3. Keep them in the same order as used above.
+-->
+[`ndd::NonDeDuplicated`]: https://docs.rs/ndd/latest/ndd/type.NonDeDuplicated.html
+[`ndd::NonDeDuplicatedStr`]: https://docs.rs/ndd/latest/ndd/type.NonDeDuplicatedStr.html
+[`ndd::NonDeDuplicatedCStr`]: https://docs.rs/ndd/latest/ndd/type.NonDeDuplicatedCStr.html
+[`src/lib.rs`]: src/lib.rs
+[`cross_crate_demo_fix/callee/src/lib.rs`]: cross_crate_demo_fix/callee/src/lib.rs
 [`core::ptr::eq`]: https://doc.rust-lang.org/1.86.0/core/ptr/fn.eq.html
 [`core::ptr::addr_eq`]: https://doc.rust-lang.org/1.86.0/core/ptr/fn.addr_eq.html
-[`src/lib.rs` -> `addresses_unique_between_statics()`]: src/lib.rs#L246
+[`src/lib.rs` -> `tests_without_ndd` -> `addresses_unique_between_statics()`]: src/lib.rs#L269
+[`src/lib.rs` -> `tests_without_ndd` -> `u8_global_const_and_global_static_release()`]:
+    src/lib.rs#L278
+[`cross_crate_demo_bug/`]: cross_crate_demo_bug/
+[`core::cell::Cell`]: https://doc.rust-lang.org/1.86.0/core/cell/struct.Cell.html
+[`core::marker::Sync`]: https://doc.rust-lang.org/1.86.0/core/marker/trait.Sync.html
+[`core::marker::Send`]: https://doc.rust-lang.org/1.86.0/core/marker/trait.Send.html
+[`std::sync::Mutex`]:
+    https://doc.rust-lang.org/1.86.0/std/sync/struct.Mutex.html#impl-Sync-for-Mutex<T>
+[`src/lib.rs` -> `tests_with_ndd`]: src/lib.rs#L355
+[`alloc`]: https://doc.rust-lang.org/1.86.0/alloc/index.html
+[`core::ops::Drop`]: https://doc.rust-lang.org/1.86.0/core/ops/trait.Drop.html
+[`pre-commit`]: pre-commit
+[GitHub Actions]: .github/workflows/main.yml
+<!-- nightly-only: -->
+[`core::cell::Cell::as_array_of_cells`]:
+    https://doc.rust-lang.org/nightly/core/cell/struct.Cell.html#method.as_array_of_cells
+[`core::ops::Deref`]: https://doc.rust-lang.org/nightly/core/ops/trait.Deref.html
+[`core::convert::From`]: https://doc.rust-lang.org/nightly/core/convert/trait.From.html

README.md

@@ -1,9 +1,26 @@
-// OVerride links, so that rustdoc can point them locally (or to docs.io, if run on docs.io).
-//! [`src/lib.rs` -> `addresses_unique_between_statics()`]:
-//!     https://github.com/peter-lyons-kehl/ndd/blob/main/src/lib.rs#L246
+// Override link URLs for local rustdoc and for docs.rs.
+//
+// Keep the following links in the same order as they appear in ../README.md. See also bottom of
+// ../README.md.
+//! [`ndd::NonDeDuplicated`]: crate::NonDeDuplicated
+//! [`ndd::NonDeDuplicatedStr`]: crate::NonDeDuplicatedStr
+//! [`ndd::NonDeDuplicatedCStr`]: crate::NonDeDuplicatedCStr
+//!
+//! [`core::ptr::eq`]: core::ptr::eq
+//! [`core::ptr::addr_eq`]: core::ptr::addr_eq
+//! [`core::cell::Cell`]: core::cell::Cell
+//! [`core::marker::Sync`]: core::marker::Sync
+//! [`core::marker::Send`]: core::marker::Send
+//! [`std::sync::Mutex`]: std::sync::Mutex#impl-Sync-for-Mutex<T>
+//! [`alloc`]: alloc
+//! [`core::ops::Drop`]: core::ops::Drop
+//! [`core::cell::Cell::as_array_of_cells`]: core::cell::Cell::as_array_of_cells
+//! [`core::ops::Deref`]: core::ops::Deref
+//! [`core::convert::From`]: core::convert::From
 #![doc = include_str!("../README.md")]
 #![cfg_attr(not(any(doc, test)), no_std)]
-#![allow(incomplete_features)]
+#[cfg(doc)]
+extern crate alloc;
 
 use core::any::Any;
 use core::cell::Cell;
@@ -237,7 +254,7 @@ mod tests_shared {
 
 /// These tests don't actually test `ndd`, but they test the behavior **without** `ndd`.
 #[cfg(test)]
-mod tests_behavior_without_ndd {
+mod tests_without_ndd {
     use crate::tests_shared::{STR_CONST_FROM_BYTE_ARRAY_HI, STR_CONST_FROM_BYTE_STRING_HELLO};
     use core::ptr;
 
@@ -332,7 +349,7 @@ mod tests_behavior_without_ndd {
 }
 
 #[cfg(test)]
-mod tests_behavior_with_ndd {
+mod tests_with_ndd {
     use super::*;
     use crate::tests_shared::{STR_CONST_FROM_BYTE_ARRAY_HI, STR_CONST_FROM_BYTE_STRING_HELLO};
     use core::ptr;