简介

项目仓库

项目文档

Math Complex 是一个采用 TypeScript 编写的 JavaScript 扩展数学库，它扩展了 Math 数学类的一些方法，让 JavaScript 支持复数计算。

基础功能

  • 扩展了复数类
  • 实现了复数类的四则、乘方开方运算
  • 扩充了辐角、指数转换计算
  • 通过 Reflect 静态类实现函数式
  • 函数式对原生 number 类型兼容

特性

  • 所有操作都是返回新的 Complex Number 对象
import { define } from "math-complex";

const z1 = define(3, 4); // z1 = 3 + 4i
const z2 = z1.contrary(); // z2 = -z1 = 3 - 4i
z1.imaginary === 4; // true, z1本身从未改变
  • 支持链式操作（严格从左至右执行）
import { define } from "math-complex";

const z1 = define(3, 4);
const z2 = define(5, 12);
const z3 = z1.add(z2).mult(z1); // z3  = (z1 + z2)*z1
  • 支持 Reflect 函数式操作
import { define, ComplexReflect } from "math-complex";

const z1 = define(3, 4);
const z2 = define(5, 12);
// z3 = z1 + z2 + z1 + z2 +z1
const z3 = ComplexReflect.add(z1, z2, z1, z2, z1);

API

全局对象

默认导出 Complex

Complex 是 math-complex 的默认导出模块，你可以这样使用它

import Complex from "math-complex";

const { realize, imagine, add, mult, abs, contrary } = Complex.Reflect;

Complex 本身就已经包含了math-complex的所有导出对象，不过一些是采用了别名。

以下将列出在 Complex 中的所有对象

Complex.abs

参见 abs。

Complex.absSquare

参见 absSquare。

Complex.contrary

参见 contrary。

Complex.define

参见 define。

Complex.fromAngle

参见 fromAngle。

Complex.imagine

参见 imagine。

Complex.isComplex

参见 isComplex。

Complex.mult

参见 mult。

Complex.Number

ComplexNumber 类的别名引用，参见 ComplexNumber。

Complex.pow

参见 pow。

Complex.random

参见 random。

Complex.realize

参见 realize。

Complex.Reflect

ComplexReflect 类的别名引用，参见 ComplexReflect。

Complex.toComplex

参见 toComplex。

abs

即定义在 ComplexReflect 类中的静态方法的别名，参见 abs。

absSquare

即定义在 ComplexReflect 类中的静态方法的别名，参见 abs。

add

即定义在 ComplexReflect 类中的静态方法的别名，参见 ComplexReflect.add。

ComplexNumber

即 ComplexNumber 类，参见 ComplexReflect.add

ComplexReflect

即 ComplexReflect 类，参见 ComplexReflect.add

contrary

即定义在 ComplexReflect 类中的静态方法，参见contrary。

define

参见 define。

fromAngle

即定义在 ComplexReflect 类中的静态方法的别名，参见 fromAngle

imagine

即定义在 ComplexReflect 类中的静态方法的别名，参见 imagine。

isComplex

即定义在 ComplexReflect 类中的静态方法，参见 isComplex。

mult

即定义在 ComplexReflect 类中的静态方法的别名，参见 mult。

pow

即定义在 ComplexReflect 类中的静态方法的别名，参见 pow。

random

即定义在 ComplexReflect 类中的静态方法的别名，参见 random。

realize

即定义在 ComplexReflect 类中的静态方法的别名，参见 realize。

toComplex

即定义在 ComplexReflect 类中的静态方法的别名，参见 toComplex。

tryRealize

即定义在 ComplexReflect 类中的静态方法的别名，参见 tryRealize。

ComplexNumber 类

ComplexNumber 是本库的核心类，所有其他类都由此衍生，且通过 new 即可声明一个复数对象。

  • constructor 类型定义
constructor(real?: number, imaginary?: number)
  • 示例
import { ComplexNumber } from "math-complex";

const z1 = new ComplexNumber(3, 4); // z1 = 3 + 4i

对象属性

imaginary

imaginary 是一个 number 对象，即为该对象的虚部。

import { ComplexNumber } from "math-complex";

const z1 = new ComplexNumber(3, 4); // z1 = 3 + 4i
z1.imaginary === 4; // true

real

real 是一个 number 对象，即为该对象的实部。

import { ComplexNumber } from "math-complex";

const z1 = new ComplexNumber(3, 4); // z1 = 3 + 4i
z1.real === 3; // true

radius

radius 是一个 number 对象，即为该对象的模长。

import { ComplexNumber } from "math-complex";

const z1 = new ComplexNumber(3, 4); // z1 = 3 + 4i
z1.radius === 5; // true

mainAngle

mainAngle 是一个 number 对象，即为该对象的幅角主值。

import { ComplexNumber } from "math-complex";

const z1 = new ComplexNumber(1, 1); // z1 = 1 + i
z1.mainAngle === Math.PI / 4; // true

静态方法

define

define 是一个 ComplexNumber 对象的构造器，返回一个 ComplexNumber 对象。

  • 类型定义
static define(real?: number, imaginary?: number): ComplexNumber;
  • 示例
import { ComplexNumber } from "math-complex";

const { define } = ComplexNumber;
const z1 = define(3, 4); // z1 = 3 + 4i

本质上 define 就是调用了ComplexNumber 类的 new 方法：

ComplexNumber.define = (...args) => new ComplexNumber(...args);

fromAngle

fromAngle 是另一个 ComplexNumber 对象的构造器，返回一个 ComplexNumber 对象，与 define 不同，fromAngle 接收的参数是复数的模长和幅角主值。

  • 类型定义
static fromAngle(radius?: number, mainAngle?: number): ComplexNumber;
  • 示例
import { ComplexNumber } from "math-complex";

const { fromAngle } = ComplexNumber;
const z1 = fromAngle(Math.sqrt(2), Math.PI / 4);
// z1 = sqrt(2) * (cos(π/4) + sin(π/4)) = 1 + i

对象方法

abs

abs 返回一个 ComplexNumber 对象的模长。

  • 类型定义
abs(): number;
  • 示例
import { define } from "math-complex";
// 此处 define 即为 ComplexNumber.define 在全局的导出对象

const z1 = define(3, 4); // z1 = 3 + 4i
z1.abs() === 5; // true

absSquare

absSquare 返回一个 ComplexNumber 对象模长的平方。

  • 类型定义
absSquare(): number;
  • 示例
import { define } from "math-complex";

const z1 = define(3, 4); // z1 = 3 + 4i
z1.absSquare() === 25; // true

add

add 定义了 ComplexNumber 的加法运算，且支持原生number 对象。

  • 类型定义
add(addend: number | ComplexNumber): ComplexNumber;
  • 示例
import { define } from "math-complex";

const z1 = define(3, 4); // z1 = 3 + 4i
const z2 = define(5, 12); // z1 = 5 + 12i
const z3 = z1.add(2); // z3 = z1 + 2 = 5 + 4i
const z4 = z1.add(z2); // z4 = z1 + z2 = 8 + 16i

angle

angle 返回 ComplexNumber 的辐角主值。

  • 类型定义
angle(): number;
  • 示例
import { define } from "math-complex";

const z1 = define(1, 1);
z1.angle() === Math.PI / 4; // true

contrary

contrary 返回一个 ComplexNumber 对象的相反数。

  • 类型定义
contrary(): number;
  • 示例
import { define } from "math-complex";

const z1 = define(3, 4); // z1 = 3 + 4i
z1.contrary().real === -3; // true
z1.contrary().imaginary === -4; // true

conj

conj 返回一个 ComplexNumber 对象的共轭复数。

  • 类型定义
conj(): number;
  • 示例
import { define } from "math-complex";

const z1 = define(3, 4); // z1 = 3 + 4i
z1.conj().real === 3; // true
z1.conj().imaginary === -4; // true

divide

divide 定义了 ComplexNumber 的除法运算，且支持原生number 对象。

  • 类型定义
divide(divisor: number | ComplexNumber): ComplexNumber;
  • 示例
import { define, tryRealize } from "math-complex";

const z1 = define(6, 8); // z1 = 6 + 8i
const z2 = z1.divide(2); // z2 = z1 / 2 = 3 + 4i
tryRealize(z1.divide(z2)) === 2; // true, z1 / z2 = 2

isAngle

isAngle 用来检查一个弧度角是否是 ComplexNumber 的一个辐角（即与辐角主值相差 2π 的整数倍）。

  • 类型定义
isAngle(angle: number, accuracy?: number): boolean;
  • 示例
import { define } from "math-complex";

const z1 = define(1, 1);
const angle = (9 * Math.PI) / 4;
z1.isAngle(angle) === true; // true
  • 设置精度 accuracy

有时由于浮点计算问题，对 π 的检查存在偏差，我们可以适当设置精度 accuracy 参数的值，默认为 0.0001，accuracy 的定义是 (角度差/2π) 的小数部分。

import { define } from "math-complex";

z1.isAngle(angle) === false; // false，应为true，精度过小
z1.isAngle(angle, 0.01) === true; // 精度合理

mult

mult 定义了 ComplexNumber 的乘法运算，且支持原生number 对象。

  • 类型定义
mult(multiplier: number | ComplexNumber): ComplexNumber;
  • 示例
import { define } from "math-complex";

const z1 = define(3, 4); // z1 = 3 + 4i
const z2 = z1.mult(2); // z2 = z1 * 2 = 6 + 8i

pow

pow 定义了 ComplexNumber 的乘方运算。

  • 类型定义
pow(power: number): ComplexNumber | 1;

幂必须是整数，如果幂为分数参见 sqrt 方法，且乘方运算在幂不同时候执行不同的运算方法。

  • 幂为 0 时，返回值为 1

  • 幂为正整数时，返回值为复数自乘 n 次的结果

  • 幂为负整数时，返回值为复数自乘 n 次的结果的倒数 （参见 recip 方法）

recip

recip 返回一个 ComplexNumber 的倒数结果。

  • 类型定义
recip(): ComplexNumber;
  • 示例
import { define } from "math-complex";

const z1 = define(3, 4); // z1 = 3 + 4i
const z2 = z1.recip(); // z2 = 1 / z1 = 0.6- 0.8i
  • 实际上，recip() 方法就是返回 1 + 0i 的除法运算结果。
class ComplexNumber {
	// ...
	recip() {
		return new ComplexNumber(1, 0).divide(this);
	}
}

sub

substract 的别名，参见 subtract。

subtract

subtract 定义了 ComplexNumber 对象的减法运算。

  • 类型定义
subtract(subtrahend: number | ComplexNumber): ComplexNumber;
  • 示例
import { define } from "math-complex";

const z1 = define(3, 4); // z1 = 3 + 4i
const z2 = define(5, 12); // z1 = 5 + 12i
const z3 = z1.subtract(2); // z3 = z1 - 2 = 1 + 4i
const z4 = z1.subtract(z2); // z4 = z1 - z2 = -2 + -7i
  • 实际上，subtract() 方法就是参数的相反数的加法运算结果。
class ComplexNumber {
	// ...
	subtract(params) {
		return this.add(params.contrary());
	}
}

sqrt

sqrt 定义了 ComplexNumber 对象的开方运算。

  • 类型定义
sqrt(power?: number): ComplexNumber;

  • power 必须为正整数，默认空参数是开平方，即 power 为 2。

  • 开方运算是利用棣莫佛定理，将复数转换成模长和辐角的形式计算，参见 fromAngle 静态方法。

class ComplexNumber {
	// ...
	sqrt(power) {
		return ComplexNumber.fromAngle(
			Math.pow(this.radius, 1 / power),
			this.mainAngle / power
		);
	}
}

关于链式操作

所有返回 ComplexNumber 对象的方法都支持链式运算。

其中包含：add, contrary, conj, divide, mult, recip, subtract, sqrt

ComplexReflect 静态类

ComplexReflect 是本库的函数方法类，使用本类的静态方法可以更直接地操作 ComplexNumber 或原生 number 对象数据，并且 ComplexReflect 类中的所有方法都是静态方法，并且对原生 number 对象也有良好兼容性。

abs

abs 返回一个 ComplexNumber 或原生 number 对象的模长。

  • 类型定义
static abs(num: number | ComplexNumber): number | ComplexNumber;
  • 示例
import { define, ComplexReflect } from "math-complex";

const x = 2; // 原生number对象
const z = define(3, 4); // ComplexNumber对象

ComplexReflect.abs(x) === 2; // true
ComplexReflect.abs(z) === 5; // true

absSquare

absSquare 返回一个 ComplexNumber 或原生 number 对象模长的平方。

  • 类型定义
static absSquare(num: number | ComplexNumber): number | ComplexNumber;
  • 示例
import { define, ComplexReflect } from "math-complex";

const x = 2; // 原生number对象
const z = define(3, 4); // ComplexNumber对象

ComplexReflect.absSquare(x) === 4; // true
ComplexReflect.absSquare(z) === 25; // true

add

add 定义了 ComplexNumber 或原生 number 对象的加法运算，并且支持多个参数（至少 2 个）。

  • 类型定义
static add(num: number | ComplexNumber, ...args: Array<number | ComplexNumber>): number | ComplexNumber;
  • 示例
import { define, ComplexReflect } from "math-complex";

const z1 = define(3, 4);
const z2 = define(5, 12);
const z3 = 5;
const z4 = ComplexReflect.add(z1, z2, z3);
// z4 = z1 + z2 + z3

angle

angle 返回 ComplexNumber 或原生 number 对象的辐角主值（原生 number 对象即为 0）。

  • 类型定义
static angle(num: number | ComplexNumber): number | ComplexNumber;
  • 示例
import { define, ComplexReflect } from "math-complex";

const z1 = define(1, 1);
ComplexReflect.angle(z1) === Math.PI / 4; // true
ComplexReflect.angle(1234) === 0; // true

contrary

contrary 返回一个 ComplexNumber 或原生 number 对象的相反数。

  • 类型定义
static contrary(num: number | ComplexNumber): number | ComplexNumber;
  • 示例
import { define, ComplexReflect } from "math-complex";

const z1 = define(3, 4); // z1 = 3 + 4i
ComplexReflect.contrary(z1).real === -3; // true
ComplexReflect.contrary(z1).imaginary === -4; // true
ComplexReflect.contrary(5) === -5; // true

fromAngle

fromAngle 是另一个 ComplexNumber 对象的构造器，fromAngle 接收的参数是复数的模长和幅角主值。

参见 fromAngle。

imagine

imagine 返回一个 ComplexNumber 的虚部， 或参数为原生 number 对象，则返回 0。

  • 类型定义
static imagine(num: number | ComplexNumber): number;
  • 示例
import { define, ComplexReflect } from "math-complex";

const z1 = define(3, 4);
ComplexReflect.imagine(z1).real === 4; // true
ComplexReflect.imagine(5) === 0; // true

isComplex

isComplex 用来判断一个对象是不是 ComplexNumber 构造的对象。

  • 类型定义
static isComplex(num: any): boolean;
  • 示例
import { define, ComplexReflect } from "math-complex";

const z1 = define(3, 4);
ComplexReflect.imagine(z1).real === 4; // true
ComplexReflect.imagine(5) === 0; // true

mult

add 定义了 ComplexNumber 或原生 number 对象的乘法法运算，并且支持多个参数（至少 2 个）。

  • 类型定义
static mult(num: number | ComplexNumber, ...args: Array<number | ComplexNumber>): number | ComplexNumber;
  • 示例
import { define, ComplexReflect } from "math-complex";

const z1 = define(3, 4);
const z2 = define(5, 12);
const z3 = ComplexReflect.mult(z1, 5, z2);
// z3 = z1 * 5 *z2

pow

pow 定义了 ComplexNumber 的乘方运算。

  • 类型定义
static pow(num: number | ComplexNumber, power: number): number | ComplexNumber;

  • 幂可为 0、正整数、负整数和分数

  • 幂为 0 时，返回值为 1

  • 幂为正整数时，返回值为复数自乘 n 次的结果 （参见 pow 方法）

  • 幂为负整数时，返回值为复数自乘 n 次的结果的倒数 （参见 recip 方法）

  • 幂为分数时，返回值为复数开 1 / n 次方的结果 （参见 sqrt 方法）

import { define, ComplexReflect } from "math-complex";

const z1 = define(3, 4);
const z2 = ComplexReflect.pow(z1, 2);
const z3 = ComplexReflect.pow(z1, -3);
const z4 = ComplexReflect.pow(z1, 0.5);

random

random 返回一个随机的 ComplexNumber 的对象。

  • 类型定义
static random(): ComplexNumber;
  • 示例
import { ComplexReflect } from "math-complex";

const z1 = ComplexReflect.random();
  • 实际上，random() 方法就是返回实部虚部都为 Math.random() 的对象。
class ComplexReflect {
	// ...
	random() {
		return new ComplexNumber(Math.random(), Math.random());
	}
}

realize

realize 返回一个 ComplexNumber 的虚部，或参数为原生 number 对象，则返回自身。

  • 类型定义
static realize(num: number | ComplexNumber): number | ComplexNumber;
  • 示例
import { define, ComplexReflect } from "math-complex";

const z1 = define(3, 4);
const z2 = 5;

ComplexReflect.realize(z1) === 3; // true
ComplexReflect.realize(z2) === 5; // true

toComplex

toComplex 可以将原生 number 对象转化为虚部为 0 的 ComplexNumber 对象，如果参数本身已经是 ComplexNumber 对象，则直接返回自身。

  • 类型定义
static toComplex(num: number | ComplexNumber): ComplexNumber;
  • 示例
import { ComplexReflect } from "math-complex";

const x = 5;
const z = ComplexReflect.toComplex(x);
ComplexReflect.realize(z) === 5; // true
ComplexReflect.imagine(z2) === 0; // true

tryRealize

与 toComplex 相反，tryRealize 可以将虚部为 0 的 ComplexNumber 对象转化为原生 number 对象，如果ComplexNumber 对象参数的虚部不为 0 ，则直接返回自身。

  • 类型定义
static tryRealize(complex: ComplexNumber): number | ComplexNumber;
  • 示例
import { define, ComplexReflect } from "math-complex";

const z = define(5);
const x = ComplexReflect.tryRealize(z);
x === 5; // true