chore: migrate math/iter/special examples to random/iter/uniform

[Planeshifter]

Description

This pull request migrates the examples/index.js file (and the matching inline code block in README.md) for seven packages under lib/node_modules/@stdlib/math/iter/special/ from the legacy @stdlib/random/iter/randu pseudorandom source to the conventional @stdlib/random/iter/uniform source, using a sampling interval matched to each function's mathematical domain.

Namespace summary

• Members analyzed: 97 (all non-autogenerated)
• Features with clear majority (≥75%): README structure, package.json shape, file tree, function signature shape, JSDoc shape, example pseudorandom source pattern
• Drift identified on a single feature: example pseudorandom source pattern. 88 of 97 packages (90.7%) use @stdlib/random/iter/uniform( a, b, { 'seed': 1234, 'iter': 10 } ); 9 deviate.
• Outliers retained as intentional deviation: factorial, factorialln (use @stdlib/random/iter/discrete-uniform because the underlying functions are integer-valued).
• Outliers corrected: abs, abs2, cos, cospi, inv, sin, sinpi.

Per-outlier corrections

math/iter/special/abs

Migrates examples/index.js and the corresponding README.md code block from the legacy randu + iterAdd(rand, -0.5) shift pattern to @stdlib/random/iter/uniform( -2.0, 2.0, ... ). The shift approach was a workaround that obscured intent; the uniform iterator expresses the range directly. Interval precedent follows the signum and ramp sibling cluster (90.7% conformance).

math/iter/special/abs2

Migrates examples/index.js and the corresponding README.md code block from the legacy randu + iterAdd(rand, -0.5) shift pattern to @stdlib/random/iter/uniform( -2.0, 2.0, ... ). As with abs, the shift was an implicit range selection with no documented rationale. Interval follows the signum and ramp sibling cluster (90.7% conformance).

math/iter/special/cos

Migrates examples/index.js and the corresponding README.md code block from randu to @stdlib/random/iter/uniform( 0.0, 6.28, ... ), spanning one full period of cosine. The [0, 1) output of randu exercised only a fraction of the function's domain. Interval follows the cosm1, coversin, and havercos sibling cluster (90.7% conformance).

math/iter/special/cospi

Migrates examples/index.js and the corresponding README.md code block from randu to @stdlib/random/iter/uniform( 0.0, 2.0, ... ), spanning one full period of cos(πx). The [0, 1) range of randu covered only half a period of the scaled argument. Interval follows the acovercos, acoversin, and aversin sibling cluster (90.7% conformance).

math/iter/special/inv

Migrates examples/index.js and the corresponding README.md code block from randu to @stdlib/random/iter/uniform( 1.0, 10.0, ... ). Values drawn from [0, 1) caused 1/x to blow up near zero, producing outputs that were uninformative for demonstration purposes. Interval follows the acosh and acoth sibling cluster (90.7% conformance).

math/iter/special/sin

Migrates examples/index.js and the corresponding README.md code block from randu to @stdlib/random/iter/uniform( 0.0, 6.28, ... ), spanning one full period of sine. Migration shape is identical to cos. Interval follows the cosm1, coversin, and havercos sibling cluster (90.7% conformance).

math/iter/special/sinpi

Migrates examples/index.js and the corresponding README.md code block from randu to @stdlib/random/iter/uniform( 0.0, 2.0, ... ), spanning one full period of sin(πx). Migration shape is identical to cospi. Interval follows the acovercos, acoversin, and aversin sibling cluster (90.7% conformance).

Related Issues

None.

Questions

No.

Other

Validation

• Structural extraction across all 97 members confirmed 100% conformance on file tree, package.json top-level keys, package.json scripts, and README.md section structure (## Usage, ## Notes, ## Examples, ## See Also).
• Semantic extraction (cheap source-grep over lib/main.js of every member) confirmed uniform JSDoc shape (@param/@returns/@throws types), uniform error-handling delegation to the underlying iter/tools/map / iter/tools/map2, and identified the example pseudorandom source as the only feature with detectable drift.
• Three-agent drift validation (semantic review, cross-reference, structural review) confirmed all 7 corrected outliers as confirmed-drift and confirmed factorial/factorialln as intentional-deviation.
• Deliberately excluded from this PR: features without a clear majority (none observed); outliers whose tests rely on the deviation (none observed; tests do not depend on example output); the 5 binary-function packages (atan2, beta, betaln, log, pow) whose 2-arg signature reflects a genuine semantic difference and is not drift; factorial, factorialln, which intentionally use discrete-uniform because the underlying functions are integer-valued.
• Each example file was executed locally and produced finite values matching the expected mathematical output.

Each correction was committed as a separate commit, one per package, so the audit trail is per-package rather than per-feature.

Checklist

• Read, understood, and followed the contributing guidelines.

AI Assistance

• Yes
• No

If you answered "yes" above, how did you use AI assistance?

• Code generation (e.g., when writing an implementation or fixing a bug)
• Test/benchmark generation
• Documentation (including examples)
• Research and understanding

Disclosure

This PR was authored by Claude Code as part of a cross-package API drift detection routine: the random target namespace was selected, structural and semantic features were extracted across all 97 members, a 90.7% majority pattern was identified for the example pseudorandom source, three validation agents (two opus, one sonnet) confirmed the 7 outliers as unintentional drift, and the corrections were applied mechanically.

---

@stdlib-js/reviewers

---

Generated by Claude Code

[stdlib-bot]

Coverage Report

Package	Statements	Branches	Functions	Lines
math/iter/special/abs	$\color{green}114/114$ $\color{green}+100.00%$	$\color{green}3/3$ $\color{green}+100.00%$	$\color{green}1/1$ $\color{green}+100.00%$	$\color{green}114/114$ $\color{green}+100.00%$
math/iter/special/abs2	$\color{green}114/114$ $\color{green}+100.00%$	$\color{green}3/3$ $\color{green}+100.00%$	$\color{green}1/1$ $\color{green}+100.00%$	$\color{green}114/114$ $\color{green}+100.00%$
math/iter/special/cos	$\color{green}114/114$ $\color{green}+100.00%$	$\color{green}3/3$ $\color{green}+100.00%$	$\color{green}1/1$ $\color{green}+100.00%$	$\color{green}114/114$ $\color{green}+100.00%$
math/iter/special/cospi	$\color{green}115/115$ $\color{green}+100.00%$	$\color{green}3/3$ $\color{green}+100.00%$	$\color{green}1/1$ $\color{green}+100.00%$	$\color{green}115/115$ $\color{green}+100.00%$
math/iter/special/inv	$\color{green}114/114$ $\color{green}+100.00%$	$\color{green}3/3$ $\color{green}+100.00%$	$\color{green}1/1$ $\color{green}+100.00%$	$\color{green}114/114$ $\color{green}+100.00%$
math/iter/special/sin	$\color{green}114/114$ $\color{green}+100.00%$	$\color{green}3/3$ $\color{green}+100.00%$	$\color{green}1/1$ $\color{green}+100.00%$	$\color{green}114/114$ $\color{green}+100.00%$
math/iter/special/sinpi	$\color{green}115/115$ $\color{green}+100.00%$	$\color{green}3/3$ $\color{green}+100.00%$	$\color{green}1/1$ $\color{green}+100.00%$	$\color{green}115/115$ $\color{green}+100.00%$

The above coverage report was generated for the changes in this PR.