From cf038a70104ed9311660d41d43010cbdbf002f14 Mon Sep 17 00:00:00 2001
From: Karan Anand <anandkarancompsci@gmail.com>
Date: Thu, 27 Aug 2026 11:22:09 +0530
Subject: [PATCH] docs: add equations to complex-valued function READMEs

Add defining equations to the intro sections of cceil, cfloor, cround,
cceiln, cfloorn, croundn, cpolar, csignum, cflipsign and their
single-precision variants.

Ref: https://github.com/stdlib-js/metr-issue-tracker/issues/1257
---
 .../@stdlib/math/base/special/cceil/README.md    | 14 ++++++++++++++
 .../@stdlib/math/base/special/cceilf/README.md   | 14 ++++++++++++++
 .../@stdlib/math/base/special/cceiln/README.md   | 14 ++++++++++++++
 .../math/base/special/cflipsign/README.md        |  8 ++++++++
 .../math/base/special/cflipsignf/README.md       |  8 ++++++++
 .../@stdlib/math/base/special/cfloor/README.md   | 14 ++++++++++++++
 .../@stdlib/math/base/special/cfloorf/README.md  | 14 ++++++++++++++
 .../@stdlib/math/base/special/cfloorn/README.md  | 14 ++++++++++++++
 .../@stdlib/math/base/special/cfloornf/README.md | 14 ++++++++++++++
 .../@stdlib/math/base/special/cpolar/README.md   | 16 ++++++++++++++++
 .../@stdlib/math/base/special/cpolarf/README.md  | 16 ++++++++++++++++
 .../@stdlib/math/base/special/cround/README.md   | 14 ++++++++++++++
 .../@stdlib/math/base/special/croundf/README.md  | 14 ++++++++++++++
 .../@stdlib/math/base/special/croundn/README.md  | 14 ++++++++++++++
 .../@stdlib/math/base/special/csignum/README.md  | 10 ++++++++++
 .../@stdlib/math/base/special/csignumf/README.md | 10 ++++++++++
 16 files changed, 208 insertions(+)

diff --git a/lib/node_modules/@stdlib/math/base/special/cceil/README.md b/lib/node_modules/@stdlib/math/base/special/cceil/README.md
index 9ac96e4aa841..0b2c3369cd32 100644
--- a/lib/node_modules/@stdlib/math/base/special/cceil/README.md
+++ b/lib/node_modules/@stdlib/math/base/special/cceil/README.md
@@ -22,6 +22,20 @@ limitations under the License.
 
 > Round each component of a double-precision complex floating-point number toward positive infinity.
 
+<section class="intro">
+
+<!-- <equation class="equation" label="eq:cceil_function" align="center" raw="\operatorname{cceil}(a + bi) = \lceil a \rceil + \lceil b \rceil i" alt="Complex ceiling function"> -->
+
+```math
+\mathop{\mathrm{cceil}}(a + bi) = \lceil a \rceil + \lceil b \rceil i
+```
+
+<!-- </equation> -->
+
+</section>
+
+<!-- /.intro -->
+
 <section class="usage">
 
 ## Usage
diff --git a/lib/node_modules/@stdlib/math/base/special/cceilf/README.md b/lib/node_modules/@stdlib/math/base/special/cceilf/README.md
index 2945eccd8ae0..bc0a61ef7a19 100644
--- a/lib/node_modules/@stdlib/math/base/special/cceilf/README.md
+++ b/lib/node_modules/@stdlib/math/base/special/cceilf/README.md
@@ -22,6 +22,20 @@ limitations under the License.
 
 > Round each component of a single-precision complex floating-point number toward positive infinity.
 
+<section class="intro">
+
+<!-- <equation class="equation" label="eq:cceil_function" align="center" raw="\operatorname{cceil}(a + bi) = \lceil a \rceil + \lceil b \rceil i" alt="Complex ceiling function"> -->
+
+```math
+\mathop{\mathrm{cceil}}(a + bi) = \lceil a \rceil + \lceil b \rceil i
+```
+
+<!-- </equation> -->
+
+</section>
+
+<!-- /.intro -->
+
 <section class="usage">
 
 ## Usage
diff --git a/lib/node_modules/@stdlib/math/base/special/cceiln/README.md b/lib/node_modules/@stdlib/math/base/special/cceiln/README.md
index befda7b2b10d..cf91f2a3444d 100644
--- a/lib/node_modules/@stdlib/math/base/special/cceiln/README.md
+++ b/lib/node_modules/@stdlib/math/base/special/cceiln/README.md
@@ -22,6 +22,20 @@ limitations under the License.
 
 > Round each component of a double-precision complex floating-point number to the nearest multiple of `10^n` toward positive infinity.
 
+<section class="intro">
+
+<!-- <equation class="equation" label="eq:cceiln_function" align="center" raw="\operatorname{cceiln}(a + bi, n) = \operatorname{ceiln}(a, n) + \operatorname{ceiln}(b, n)\,i" alt="Complex ceiling to n decimal places"> -->
+
+```math
+\mathop{\mathrm{cceiln}}(a + bi, n) = \mathop{\mathrm{ceiln}}(a, n) + \mathop{\mathrm{ceiln}}(b, n)\,i
+```
+
+<!-- </equation> -->
+
+</section>
+
+<!-- /.intro -->
+
 <section class="usage">
 
 ## Usage
diff --git a/lib/node_modules/@stdlib/math/base/special/cflipsign/README.md b/lib/node_modules/@stdlib/math/base/special/cflipsign/README.md
index 8fd0610d4ddb..87028e633138 100644
--- a/lib/node_modules/@stdlib/math/base/special/cflipsign/README.md
+++ b/lib/node_modules/@stdlib/math/base/special/cflipsign/README.md
@@ -26,6 +26,14 @@ limitations under the License.
 
 <section class="intro">
 
+<!-- <equation class="equation" label="eq:cflipsign_function" align="center" raw="w = z \cdot \operatorname{sign}(y)" alt="Complex flip sign function"> -->
+
+```math
+w = z \cdot \mathop{\mathrm{sign}}(y)
+```
+
+<!-- </equation> -->
+
 </section>
 
 <!-- /.intro -->
diff --git a/lib/node_modules/@stdlib/math/base/special/cflipsignf/README.md b/lib/node_modules/@stdlib/math/base/special/cflipsignf/README.md
index aa983fc53791..7155258c2418 100644
--- a/lib/node_modules/@stdlib/math/base/special/cflipsignf/README.md
+++ b/lib/node_modules/@stdlib/math/base/special/cflipsignf/README.md
@@ -26,6 +26,14 @@ limitations under the License.
 
 <section class="intro">
 
+<!-- <equation class="equation" label="eq:cflipsign_function" align="center" raw="w = z \cdot \operatorname{sign}(y)" alt="Complex flip sign function"> -->
+
+```math
+w = z \cdot \mathop{\mathrm{sign}}(y)
+```
+
+<!-- </equation> -->
+
 </section>
 
 <!-- /.intro -->
diff --git a/lib/node_modules/@stdlib/math/base/special/cfloor/README.md b/lib/node_modules/@stdlib/math/base/special/cfloor/README.md
index 00c2385932f1..d8918742885f 100644
--- a/lib/node_modules/@stdlib/math/base/special/cfloor/README.md
+++ b/lib/node_modules/@stdlib/math/base/special/cfloor/README.md
@@ -22,6 +22,20 @@ limitations under the License.
 
 > Round a double-precision complex floating-point number toward negative infinity.
 
+<section class="intro">
+
+<!-- <equation class="equation" label="eq:cfloor_function" align="center" raw="\operatorname{cfloor}(a + bi) = \lfloor a \rfloor + \lfloor b \rfloor i" alt="Complex floor function"> -->
+
+```math
+\mathop{\mathrm{cfloor}}(a + bi) = \lfloor a \rfloor + \lfloor b \rfloor i
+```
+
+<!-- </equation> -->
+
+</section>
+
+<!-- /.intro -->
+
 <section class="usage">
 
 ## Usage
diff --git a/lib/node_modules/@stdlib/math/base/special/cfloorf/README.md b/lib/node_modules/@stdlib/math/base/special/cfloorf/README.md
index 8c4c4ce3dd55..75f28097a9c5 100644
--- a/lib/node_modules/@stdlib/math/base/special/cfloorf/README.md
+++ b/lib/node_modules/@stdlib/math/base/special/cfloorf/README.md
@@ -22,6 +22,20 @@ limitations under the License.
 
 > Round each component of a single-precision complex floating-point number toward negative infinity.
 
+<section class="intro">
+
+<!-- <equation class="equation" label="eq:cfloor_function" align="center" raw="\operatorname{cfloor}(a + bi) = \lfloor a \rfloor + \lfloor b \rfloor i" alt="Complex floor function"> -->
+
+```math
+\mathop{\mathrm{cfloor}}(a + bi) = \lfloor a \rfloor + \lfloor b \rfloor i
+```
+
+<!-- </equation> -->
+
+</section>
+
+<!-- /.intro -->
+
 <section class="usage">
 
 ## Usage
diff --git a/lib/node_modules/@stdlib/math/base/special/cfloorn/README.md b/lib/node_modules/@stdlib/math/base/special/cfloorn/README.md
index 65e7bd025b44..3cb38b6d20e8 100644
--- a/lib/node_modules/@stdlib/math/base/special/cfloorn/README.md
+++ b/lib/node_modules/@stdlib/math/base/special/cfloorn/README.md
@@ -22,6 +22,20 @@ limitations under the License.
 
 > Round each component of a double-precision complex floating-point number to the nearest multiple of `10^n` toward negative infinity.
 
+<section class="intro">
+
+<!-- <equation class="equation" label="eq:cfloorn_function" align="center" raw="\operatorname{cfloorn}(a + bi, n) = \operatorname{floorn}(a, n) + \operatorname{floorn}(b, n)\,i" alt="Complex floor to n decimal places"> -->
+
+```math
+\mathop{\mathrm{cfloorn}}(a + bi, n) = \mathop{\mathrm{floorn}}(a, n) + \mathop{\mathrm{floorn}}(b, n)\,i
+```
+
+<!-- </equation> -->
+
+</section>
+
+<!-- /.intro -->
+
 <section class="usage">
 
 ## Usage
diff --git a/lib/node_modules/@stdlib/math/base/special/cfloornf/README.md b/lib/node_modules/@stdlib/math/base/special/cfloornf/README.md
index 58181f0d8a44..33b87f9e16b1 100644
--- a/lib/node_modules/@stdlib/math/base/special/cfloornf/README.md
+++ b/lib/node_modules/@stdlib/math/base/special/cfloornf/README.md
@@ -22,6 +22,20 @@ limitations under the License.
 
 > Round each component of a single-precision complex floating-point number to the nearest multiple of `10^n` toward negative infinity.
 
+<section class="intro">
+
+<!-- <equation class="equation" label="eq:cfloorn_function" align="center" raw="\operatorname{cfloorn}(a + bi, n) = \operatorname{floorn}(a, n) + \operatorname{floorn}(b, n)\,i" alt="Complex floor to n decimal places"> -->
+
+```math
+\mathop{\mathrm{cfloorn}}(a + bi, n) = \mathop{\mathrm{floorn}}(a, n) + \mathop{\mathrm{floorn}}(b, n)\,i
+```
+
+<!-- </equation> -->
+
+</section>
+
+<!-- /.intro -->
+
 <section class="usage">
 
 ## Usage
diff --git a/lib/node_modules/@stdlib/math/base/special/cpolar/README.md b/lib/node_modules/@stdlib/math/base/special/cpolar/README.md
index 3175adc49d39..0f4a90ff7146 100644
--- a/lib/node_modules/@stdlib/math/base/special/cpolar/README.md
+++ b/lib/node_modules/@stdlib/math/base/special/cpolar/README.md
@@ -24,6 +24,18 @@ limitations under the License.
 
 <section class="intro">
 
+The function computes the [absolute value][absolute-value] and [phase][complex-number-argument] of a complex number
+
+<!-- <equation class="equation" label="eq:cpolar_function" align="center" raw="z = r e^{i\theta}" alt="Complex polar form"> -->
+
+```math
+z = r e^{i\theta}
+```
+
+<!-- </equation> -->
+
+where `r = |z|` is the absolute value (modulus) and `θ` is the phase (argument).
+
 </section>
 
 <!-- /.intro -->
@@ -223,6 +235,10 @@ int main( void ) {
 
 <section class="links">
 
+[absolute-value]: https://en.wikipedia.org/wiki/Absolute_value
+
+[complex-number-argument]: https://en.wikipedia.org/wiki/Argument_(complex_analysis)
+
 [@stdlib/math/base/special/cabs]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/math/base/special/cabs
 
 [@stdlib/math/base/special/cphase]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/math/base/special/cphase
diff --git a/lib/node_modules/@stdlib/math/base/special/cpolarf/README.md b/lib/node_modules/@stdlib/math/base/special/cpolarf/README.md
index 8e5cf1a4ab96..1ff78ec172ac 100644
--- a/lib/node_modules/@stdlib/math/base/special/cpolarf/README.md
+++ b/lib/node_modules/@stdlib/math/base/special/cpolarf/README.md
@@ -24,6 +24,18 @@ limitations under the License.
 
 <section class="intro">
 
+The function computes the [absolute value][absolute-value] and [phase][complex-number-argument] of a complex number
+
+<!-- <equation class="equation" label="eq:cpolar_function" align="center" raw="z = r e^{i\theta}" alt="Complex polar form"> -->
+
+```math
+z = r e^{i\theta}
+```
+
+<!-- </equation> -->
+
+where `r = |z|` is the absolute value (modulus) and `θ` is the phase (argument).
+
 </section>
 
 <!-- /.intro -->
@@ -210,6 +222,10 @@ int main( void ) {
 
 <section class="links">
 
+[absolute-value]: https://en.wikipedia.org/wiki/Absolute_value
+
+[complex-number-argument]: https://en.wikipedia.org/wiki/Argument_(complex_analysis)
+
 [@stdlib/math/base/special/cabsf]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/math/base/special/cabsf
 
 [@stdlib/math/base/special/cphasef]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/math/base/special/cphasef
diff --git a/lib/node_modules/@stdlib/math/base/special/cround/README.md b/lib/node_modules/@stdlib/math/base/special/cround/README.md
index 3669e00e181a..39fd16443c18 100644
--- a/lib/node_modules/@stdlib/math/base/special/cround/README.md
+++ b/lib/node_modules/@stdlib/math/base/special/cround/README.md
@@ -22,6 +22,20 @@ limitations under the License.
 
 > Round each component of a double-precision complex floating-point number to the nearest integer.
 
+<section class="intro">
+
+<!-- <equation class="equation" label="eq:cround_function" align="center" raw="\operatorname{cround}(a + bi) = \lfloor a + 0.5 \rfloor + \lfloor b + 0.5 \rfloor i" alt="Complex round function"> -->
+
+```math
+\mathop{\mathrm{cround}}(a + bi) = \lfloor a + 0.5 \rfloor + \lfloor b + 0.5 \rfloor i
+```
+
+<!-- </equation> -->
+
+</section>
+
+<!-- /.intro -->
+
 <section class="usage">
 
 ## Usage
diff --git a/lib/node_modules/@stdlib/math/base/special/croundf/README.md b/lib/node_modules/@stdlib/math/base/special/croundf/README.md
index c0348b3f3bcf..02a1e9e7a930 100644
--- a/lib/node_modules/@stdlib/math/base/special/croundf/README.md
+++ b/lib/node_modules/@stdlib/math/base/special/croundf/README.md
@@ -22,6 +22,20 @@ limitations under the License.
 
 > Round each component of a single-precision complex floating-point number to the nearest integer.
 
+<section class="intro">
+
+<!-- <equation class="equation" label="eq:cround_function" align="center" raw="\operatorname{cround}(a + bi) = \lfloor a + 0.5 \rfloor + \lfloor b + 0.5 \rfloor i" alt="Complex round function"> -->
+
+```math
+\mathop{\mathrm{cround}}(a + bi) = \lfloor a + 0.5 \rfloor + \lfloor b + 0.5 \rfloor i
+```
+
+<!-- </equation> -->
+
+</section>
+
+<!-- /.intro -->
+
 <section class="usage">
 
 ## Usage
diff --git a/lib/node_modules/@stdlib/math/base/special/croundn/README.md b/lib/node_modules/@stdlib/math/base/special/croundn/README.md
index f76e440f3b15..e2e386d7ae48 100644
--- a/lib/node_modules/@stdlib/math/base/special/croundn/README.md
+++ b/lib/node_modules/@stdlib/math/base/special/croundn/README.md
@@ -22,6 +22,20 @@ limitations under the License.
 
 > Round each component of a double-precision complex floating-point number to the nearest multiple of `10^n`.
 
+<section class="intro">
+
+<!-- <equation class="equation" label="eq:croundn_function" align="center" raw="\operatorname{croundn}(a + bi, n) = \operatorname{roundn}(a, n) + \operatorname{roundn}(b, n)\,i" alt="Complex round to n decimal places"> -->
+
+```math
+\mathop{\mathrm{croundn}}(a + bi, n) = \mathop{\mathrm{roundn}}(a, n) + \mathop{\mathrm{roundn}}(b, n)\,i
+```
+
+<!-- </equation> -->
+
+</section>
+
+<!-- /.intro -->
+
 <section class="usage">
 
 ## Usage
diff --git a/lib/node_modules/@stdlib/math/base/special/csignum/README.md b/lib/node_modules/@stdlib/math/base/special/csignum/README.md
index a3c8fdd72fff..cc8ae1fa0dd4 100644
--- a/lib/node_modules/@stdlib/math/base/special/csignum/README.md
+++ b/lib/node_modules/@stdlib/math/base/special/csignum/README.md
@@ -26,6 +26,16 @@ limitations under the License.
 
 <section class="intro">
 
+The [signum][signum] function of a complex number is defined as
+
+<!-- <equation class="equation" label="eq:csignum_function" align="center" raw="\operatorname{csignum}(z) = \begin{cases} \frac{z}{|z|} & \textrm{if}\ z \neq 0 \\ 0 & \textrm{if}\ z = 0 \end{cases}" alt="Complex signum function"> -->
+
+```math
+\mathop{\mathrm{csignum}}(z) = \begin{cases} \frac{z}{|z|} & \textrm{if}\ z \neq 0 \\ 0 & \textrm{if}\ z = 0 \end{cases}
+```
+
+<!-- </equation> -->
+
 </section>
 
 <!-- /.intro -->
diff --git a/lib/node_modules/@stdlib/math/base/special/csignumf/README.md b/lib/node_modules/@stdlib/math/base/special/csignumf/README.md
index ac0c4d8f21f4..6f11b22408fd 100644
--- a/lib/node_modules/@stdlib/math/base/special/csignumf/README.md
+++ b/lib/node_modules/@stdlib/math/base/special/csignumf/README.md
@@ -26,6 +26,16 @@ limitations under the License.
 
 <section class="intro">
 
+The [signum][signum] function of a complex number is defined as
+
+<!-- <equation class="equation" label="eq:csignum_function" align="center" raw="\operatorname{csignum}(z) = \begin{cases} \frac{z}{|z|} & \textrm{if}\ z \neq 0 \\ 0 & \textrm{if}\ z = 0 \end{cases}" alt="Complex signum function"> -->
+
+```math
+\mathop{\mathrm{csignum}}(z) = \begin{cases} \frac{z}{|z|} & \textrm{if}\ z \neq 0 \\ 0 & \textrm{if}\ z = 0 \end{cases}
+```
+
+<!-- </equation> -->
+
 </section>
 
 <!-- /.intro -->