Support 3rdparty Traits

Supporting Third-Party Traits in dashu

Standard operating procedure for two related changes:

• Branch A — implement traits from a new third-party crate (e.g. add borsh, arbitrary, bytemuck support, or a trait crate the repo doesn't depend on yet).
• Branch B — support a new major version of a crate that is already integrated (e.g. add rand_v09 alongside rand_v08, or diesel_v3 alongside diesel_v2).

Both share the same invariants; Branch B reuses Branch A's steps plus a versioning layer.

Repository context (load-bearing facts)

Read these before touching anything — they are the conventions every existing integration follows.

• Impls live in <crate>/src/third_party/, one file per external crate. <crate>/src/third_party/mod.rs gates each submodule with #[cfg(feature = "...")]. <crate>/src/lib.rs declares mod third_party; (private) then pub use third_party::*; to expose any public items.
• Two visibility flavors in mod.rs:
  • pub mod rand; — when the file defines new public types (e.g. UniformBits, UniformUBig) that users import from crate::rand.
  • mod num_traits; / mod serde; — when the file only impls an external trait for a local type; the impl is globally reachable once compiled, so nothing public needs re-exporting.
• "Stable" vs "unstable" dependencies (this split is explicit in every Cargo.toml, marked # stable dependencies / # unstable dependencies):
  • Stable = the crate's API is essentially frozen across versions (serde, zeroize, num-order). One feature, named after the crate. Example: serde = ["dep:serde", "dashu-int/serde"].
  • Unstable = breaking changes between major versions (rand, num-traits, num-integer, diesel, postgres-types). Always a versioned feature/dep with a _vXX suffix, plus an unversioned alias feature pointing at the current default.
• Versioned dependency = renamed optional dep. The dep key carries the suffix and package = resolves it to the real crate:

  rand_v08 = { optional = true, version = "0.8.3", package = "rand", default-features = false }

  In Rust code you import by the suffixed key: use rand_v08::{Rng, ...};. Inside a file you may alias it back to the natural name for readability: use num_traits_v02 as num_traits;.
• Versioned feature enables its own dep AND forwards downstream. Because float/rational re-export int's types, their feature must also turn on the matching feature in the lower crate:

  num-traits_v02 = ["dep:num-traits_v02", "dashu-int/num-traits_v02"]

• Unversioned alias points at the latest version: rand = ["rand_v08"], num-traits = ["num-traits_v02"]. Users write features = ["rand"]; the alias decides which real version that means.
• Multiple major versions coexist as peers (see diesel): diesel_v1 and diesel_v2 are both real, each with its own versioned dep + feature + module file (third_party/postgres/diesel_v1.rs, diesel_v2.rs). Shared conversion logic lives in third_party/postgres/mod.rs; each version file only wires that logic to its own diesel traits.
• Private helper deps use a leading-underscore key and are never given their own user-facing feature. Enabled as a side effect: num-order = ["dep:num-order", "dep:_num-modular"] (rational).
• no_std: every optional dep is declared default-features = false so it cannot drag std into the default (no_std) build. If the dep itself needs std, the feature must pull in std (e.g. postgres-types_v02 = ["dep:postgres-types_v02", "dep:_bytes", "std"]).
• Meta crate dashu (root Cargo.toml) forwards every feature to all sub-crates that have it — both the versioned form and the unversioned alias: rand_v08 = ["dashu-int/rand_v08", "dashu-float/rand_v08", "dashu-ratio/rand_v08"] and rand = ["dashu-int/rand", ...].
• MSRV is 1.68. A new dep must build on 1.68; if it doesn't, it must be stripped from MSRV builds via .github/workflows/drop_incompatible_deps_for_msrv.py (see pre-publish-check skill, Step 6).
• Two Cargo.toml styles coexist in the repo: integer uses the legacy style where optional = true deps auto-create an implicit feature (so serde/zeroize/num-order aren't listed in [features]). float/rational use the modern explicit style with dep: syntax. Prefer the dep: (modern) style for any new work; match the surrounding crate's existing style when editing an existing feature.

Decision: which branch?

• The crate is not yet in any Cargo.toml → Branch A.
• The crate is already integrated and you're adding a second major version (or replacing the supported one) → Branch B.

Branch A — Support a trait from a new third-party crate

Step A1 — Classify the dependency: stable or unstable?

If the upstream crate has a history of breaking changes between major versions (rand, num-traits, num-integer) or is pre-1.0, treat it as unstable → you need the versioned suffix machinery. If its API is effectively frozen at 1.x (serde, zeroize, num-order) → stable → a single unversioned feature suffices. When in doubt, choose unstable; the cost is one extra alias line and you avoid a painful migration later.

Step A2 — Declare the optional dependency in the target crate's Cargo.toml

Under the matching # stable dependencies or # unstable dependencies comment. Always default-features = false.

Stable:

borsh = { optional = true, version = "1.x", default-features = false }

Unstable (note the _vXX key + package =):

arbitrary_v1 = { optional = true, version = "1.x", package = "arbitrary", default-features = false }

Step A3 — Define the feature flag(s)

Stable (modern dep: style):

borsh = ["dep:borsh"]

Unstable — two entries: the versioned feature (with cross-crate forwarding if a lower crate also exposes the type) plus the unversioned alias:

arbitrary_v1 = ["dep:arbitrary_v1"]
arbitrary = ["arbitrary_v1"]

If the trait must also be enabled on a crate this one depends on (because it re-exports that crate's types), add the downstream feature to the versioned feature list — see load-bearing fact above.

Step A4 — Create the implementation module

Add <crate>/src/third_party/<crate_name>.rs. Import the external crate by its dep key (alias back to the natural name if it reads better). impl the external trait(s) for the local types (UBig/IBig/FBig/RBig). Follow existing files as a template: integer/src/third_party/num_traits.rs (pure trait impls), integer/src/third_party/rand.rs (defines new public types + a module-level # Examples doc), float/src/third_party/postgres/ (multi-version, shared logic).

If the file defines new public items the user will name, declare it pub mod in mod.rs; otherwise plain mod.

Step A5 — Wire it into third_party/mod.rs

#[cfg(feature = "borsh")]
mod borsh;
// or, if it exposes public types:
#[cfg(feature = "arbitrary_v1")]
pub mod arbitrary;

No change to lib.rs is needed beyond the existing pub use third_party::*; — that line already re-exports anything pub from these modules.

Step A6 — Forward the feature across crates (if applicable)

If the same trait makes sense on types from more than one sub-crate, repeat Steps A2–A5 in each crate, and make each higher crate's versioned feature turn on the lower crate's matching feature (load-bearing fact). Keep the feature name identical across crates (arbitrary_v1 everywhere).

Step A7 — Forward the feature in the meta crate

In the root Cargo.toml [features], add both forms (versioned + unversioned alias), each forwarding to every sub-crate that implements it:

arbitrary_v1 = ["dashu-int/arbitrary_v1", "dashu-float/arbitrary_v1", "dashu-ratio/arbitrary_v1"]
arbitrary = ["dashu-int/arbitrary", "dashu-float/arbitrary", "dashu-ratio/arbitrary"]

List only the sub-crates that actually have the feature — do not forward to a crate that doesn't implement it (that's a build error).

Step A8 — Tests, doc examples, dev-dependencies

• Add a [[test]] with required-features = ["<feature>"] (see the random / serde tests in each Cargo.toml), or put unit tests in a #[cfg(test)] mod tests at the bottom of the new module file.
• Re-declare the dep (un-suffixed or suffixed to match) under [dev-dependencies] without optional, so doctests/examples resolve.
• Any public item documented at module level (like rand.rs) needs a # Examples block; in examples use the dep by its dep key (use rand_v08::{...}).