dashu_cmplx/
lib.rs

1// Copyright (c) 2026 Jacob Zhong
2//
3// Licensed under either of
4//
5// * Apache License, Version 2.0
6//   (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
7// * MIT license
8//   (LICENSE-MIT or https://opensource.org/licenses/MIT)
9//
10// at your option.
11//
12// Unless you explicitly state otherwise, any contribution intentionally submitted
13// for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
14// dual licensed as above, without any additional terms or conditions.
15
16//! A big arbitrary precision complex number library.
17//!
18//! The library provides the type [`CBig`]: an arbitrary-precision complex number built on top of
19//! [`dashu_float`]'s [`FBig`]. Each [`CBig`] stores a real and an imaginary part ([`Repr`]) over a
20//! single shared precision and rounding mode, mirroring [`FBig`]'s `Repr`+`Context` layout. It
21//! targets parity with GNU MPC for the common functionalities (field arithmetic + elementary
22//! transcendentals + abs/arg/conj/proj + I/O).
23//!
24//! Rounding follows the C99 Annex G / Kahan branch-cut and signed-zero model that `dashu-float`
25//! already implements for reals. There is **no NaN**: C99 NaN-producing cases are mapped to
26//! [`FpError`] at the [`Context`] layer (and panics at the convenience layer), exactly mirroring
27//! how `FBig` behaves.
28//!
29//! # Two-layer API
30//!
31//! Like `FBig`, operations come in two layers:
32//! * **Context layer** — [`Context`] methods return a [`CfpResult`] (`Result<CRounded<CBig>, FpError>`)
33//!   carrying per-axis inexactness `(Rounding, Rounding)`.
34//! * **Convenience layer** — [`CBig`] methods and operators unwrap to a plain [`CBig`], panicking on
35//!   `Indeterminate` / `OutOfDomain` / `InfiniteInput` and saturating `Overflow`/`Underflow`.
36//!
37//! # Examples
38//!
39//! ```
40//! use dashu_cmplx::CBig;
41//! use dashu_float::{FBig, round::mode::HalfAway};
42//!
43//! type C = CBig<HalfAway, 10>; // base-10 so values render as decimals
44//! let z = C::from_parts(FBig::from(3), FBig::from(4));
45//! let w = C::I;
46//! let sum = &z + &w; // (3+4i) + i = 3+5i
47//! assert_eq!(sum.re().significand(), &3.into());
48//! assert_eq!(sum.im().significand(), &5.into());
49//!
50//! // algebraic display
51//! assert_eq!(format!("{}", sum), "3+5i");
52//! ```
53//!
54//! # Optional dependencies
55//!
56//! * `std` (*default*): enable `std` for dependencies.
57//! * `num-order` (*default*): `NumOrd`/`NumHash` for `CBig`.
58//! * `num-complex`: `TryFrom` conversions between `CBig` and `num-complex`'s `Complex<f32>`/
59//!   `Complex<f64>` (base-2, mirroring `FBig`'s primitive-float conversions).
60
61#![cfg_attr(not(feature = "std"), no_std)]
62#![deny(missing_docs)]
63#![deny(clippy::dbg_macro)]
64#![deny(clippy::undocumented_unsafe_blocks)]
65#![deny(clippy::let_underscore_must_use)]
66
67extern crate alloc;
68
69mod add;
70mod cbig;
71mod cbig_cached;
72mod cbig_cached_ops;
73mod cmp;
74mod convert;
75mod div;
76mod exp;
77mod fmt;
78mod helper_macros;
79mod iter;
80mod log;
81pub mod math;
82mod misc;
83mod mul;
84mod parse;
85mod repr;
86mod root;
87mod third_party;
88
89// All the public items from third_party will be exposed
90#[allow(unused_imports)]
91pub use third_party::*;
92
93pub use cbig::CBig;
94pub use cbig_cached::CachedCBig;
95pub use repr::{CRounded, CfpResult, Context};
96
97// Rounding machinery and the float primitives CBig is built on are reused from dashu-float
98// unchanged (they appear in this crate's public signatures).
99pub use dashu_float::round; // → dashu_cmplx::round::{mode, Round, Rounding}
100pub use dashu_float::round::{Round, Rounding};
101pub use dashu_float::{ConstCache, FBig, FpError, Repr};
102
103#[doc(hidden)]
104pub use dashu_int::Word; // for the cbig! literal macro (M6)
dashu_cmplx/lib.rs

dashu_cmplx/
lib.rs
