From f94964cd057ace39caa05c10d9626ac6a4beb23b Mon Sep 17 00:00:00 2001 From: Marc Tiehuis Date: Wed, 1 May 2019 18:12:16 +1200 Subject: [PATCH 1/3] std.math: Add upstream changes/fixes and simplify go derived code This also starts the documentation effort for the math/ subdirectory. The intent is to use this as a somewhat representative test-case for any work on the documentation generator. --- std/math/cos.zig | 146 ++++++++++++++---------------------------- std/math/fma.zig | 10 ++- std/math/pow.zig | 96 ++++++++++++++++------------ std/math/sin.zig | 162 ++++++++++++++++------------------------------- std/math/tan.zig | 156 +++++++++++++++------------------------------ 5 files changed, 216 insertions(+), 354 deletions(-) diff --git a/std/math/cos.zig b/std/math/cos.zig index 947948289..6d0cc80c3 100644 --- a/std/math/cos.zig +++ b/std/math/cos.zig @@ -1,18 +1,23 @@ -// Special Cases: +// Ported from go, which is licensed under a BSD-3 license. +// https://golang.org/LICENSE // -// - cos(+-inf) = nan -// - cos(nan) = nan +// https://golang.org/src/math/sin.go const builtin = @import("builtin"); const std = @import("../std.zig"); const math = std.math; const expect = std.testing.expect; +/// Returns the cosine of the radian value x. +/// +/// Special Cases: +/// - cos(+-inf) = nan +/// - cos(nan) = nan pub fn cos(x: var) @typeOf(x) { const T = @typeOf(x); return switch (T) { - f32 => cos32(x), - f64 => cos64(x), + f32 => cos_(f32, x), + f64 => cos_(f64, x), else => @compileError("cos not implemented for " ++ @typeName(T)), }; } @@ -33,14 +38,13 @@ const C3 = 2.48015872888517045348E-5; const C4 = -1.38888888888730564116E-3; const C5 = 4.16666666666665929218E-2; -// NOTE: This is taken from the go stdlib. The musl implementation is much more complex. -// -// This may have slight differences on some edge cases and may need to replaced if so. -fn cos32(x_: f32) f32 { - const pi4a = 7.85398125648498535156e-1; - const pi4b = 3.77489470793079817668E-8; - const pi4c = 2.69515142907905952645E-15; - const m4pi = 1.273239544735162542821171882678754627704620361328125; +const pi4a = 7.85398125648498535156e-1; +const pi4b = 3.77489470793079817668E-8; +const pi4c = 2.69515142907905952645E-15; +const m4pi = 1.273239544735162542821171882678754627704620361328125; + +fn cos_(comptime T: type, x_: T) T { + const I = @IntType(true, T.bit_count); var x = x_; if (math.isNan(x) or math.isInf(x)) { @@ -48,12 +52,10 @@ fn cos32(x_: f32) f32 { } var sign = false; - if (x < 0) { - x = -x; - } + x = math.fabs(x); var y = math.floor(x * m4pi); - var j = @floatToInt(i64, y); + var j = @floatToInt(I, y); if (j & 1 == 1) { j += 1; @@ -72,107 +74,51 @@ fn cos32(x_: f32) f32 { const z = ((x - y * pi4a) - y * pi4b) - y * pi4c; const w = z * z; - const r = r: { - if (j == 1 or j == 2) { - break :r z + z * w * (S5 + w * (S4 + w * (S3 + w * (S2 + w * (S1 + w * S0))))); - } else { - break :r 1.0 - 0.5 * w + w * w * (C5 + w * (C4 + w * (C3 + w * (C2 + w * (C1 + w * C0))))); - } - }; + const r = if (j == 1 or j == 2) + z + z * w * (S5 + w * (S4 + w * (S3 + w * (S2 + w * (S1 + w * S0))))) + else + 1.0 - 0.5 * w + w * w * (C5 + w * (C4 + w * (C3 + w * (C2 + w * (C1 + w * C0))))); - if (sign) { - return -r; - } else { - return r; - } -} - -fn cos64(x_: f64) f64 { - const pi4a = 7.85398125648498535156e-1; - const pi4b = 3.77489470793079817668E-8; - const pi4c = 2.69515142907905952645E-15; - const m4pi = 1.273239544735162542821171882678754627704620361328125; - - var x = x_; - if (math.isNan(x) or math.isInf(x)) { - return math.nan(f64); - } - - var sign = false; - if (x < 0) { - x = -x; - } - - var y = math.floor(x * m4pi); - var j = @floatToInt(i64, y); - - if (j & 1 == 1) { - j += 1; - y += 1; - } - - j &= 7; - if (j > 3) { - j -= 4; - sign = !sign; - } - if (j > 1) { - sign = !sign; - } - - const z = ((x - y * pi4a) - y * pi4b) - y * pi4c; - const w = z * z; - - const r = r: { - if (j == 1 or j == 2) { - break :r z + z * w * (S5 + w * (S4 + w * (S3 + w * (S2 + w * (S1 + w * S0))))); - } else { - break :r 1.0 - 0.5 * w + w * w * (C5 + w * (C4 + w * (C3 + w * (C2 + w * (C1 + w * C0))))); - } - }; - - if (sign) { - return -r; - } else { - return r; - } + return if (sign) -r else r; } test "math.cos" { - expect(cos(f32(0.0)) == cos32(0.0)); - expect(cos(f64(0.0)) == cos64(0.0)); + expect(cos(f32(0.0)) == cos_(f32, 0.0)); + expect(cos(f64(0.0)) == cos_(f64, 0.0)); } test "math.cos32" { const epsilon = 0.000001; - expect(math.approxEq(f32, cos32(0.0), 1.0, epsilon)); - expect(math.approxEq(f32, cos32(0.2), 0.980067, epsilon)); - expect(math.approxEq(f32, cos32(0.8923), 0.627623, epsilon)); - expect(math.approxEq(f32, cos32(1.5), 0.070737, epsilon)); - expect(math.approxEq(f32, cos32(37.45), 0.969132, epsilon)); - expect(math.approxEq(f32, cos32(89.123), 0.400798, epsilon)); + expect(math.approxEq(f32, cos_(f32, 0.0), 1.0, epsilon)); + expect(math.approxEq(f32, cos_(f32, 0.2), 0.980067, epsilon)); + expect(math.approxEq(f32, cos_(f32, 0.8923), 0.627623, epsilon)); + expect(math.approxEq(f32, cos_(f32, 1.5), 0.070737, epsilon)); + expect(math.approxEq(f32, cos_(f32, -1.5), 0.070737, epsilon)); + expect(math.approxEq(f32, cos_(f32, 37.45), 0.969132, epsilon)); + expect(math.approxEq(f32, cos_(f32, 89.123), 0.400798, epsilon)); } test "math.cos64" { const epsilon = 0.000001; - expect(math.approxEq(f64, cos64(0.0), 1.0, epsilon)); - expect(math.approxEq(f64, cos64(0.2), 0.980067, epsilon)); - expect(math.approxEq(f64, cos64(0.8923), 0.627623, epsilon)); - expect(math.approxEq(f64, cos64(1.5), 0.070737, epsilon)); - expect(math.approxEq(f64, cos64(37.45), 0.969132, epsilon)); - expect(math.approxEq(f64, cos64(89.123), 0.40080, epsilon)); + expect(math.approxEq(f64, cos_(f64, 0.0), 1.0, epsilon)); + expect(math.approxEq(f64, cos_(f64, 0.2), 0.980067, epsilon)); + expect(math.approxEq(f64, cos_(f64, 0.8923), 0.627623, epsilon)); + expect(math.approxEq(f64, cos_(f64, 1.5), 0.070737, epsilon)); + expect(math.approxEq(f64, cos_(f64, -1.5), 0.070737, epsilon)); + expect(math.approxEq(f64, cos_(f64, 37.45), 0.969132, epsilon)); + expect(math.approxEq(f64, cos_(f64, 89.123), 0.40080, epsilon)); } test "math.cos32.special" { - expect(math.isNan(cos32(math.inf(f32)))); - expect(math.isNan(cos32(-math.inf(f32)))); - expect(math.isNan(cos32(math.nan(f32)))); + expect(math.isNan(cos_(f32, math.inf(f32)))); + expect(math.isNan(cos_(f32, -math.inf(f32)))); + expect(math.isNan(cos_(f32, math.nan(f32)))); } test "math.cos64.special" { - expect(math.isNan(cos64(math.inf(f64)))); - expect(math.isNan(cos64(-math.inf(f64)))); - expect(math.isNan(cos64(math.nan(f64)))); + expect(math.isNan(cos_(f64, math.inf(f64)))); + expect(math.isNan(cos_(f64, -math.inf(f64)))); + expect(math.isNan(cos_(f64, math.nan(f64)))); } diff --git a/std/math/fma.zig b/std/math/fma.zig index a317bc96d..19c306fa2 100644 --- a/std/math/fma.zig +++ b/std/math/fma.zig @@ -1,7 +1,14 @@ +// Ported from musl, which is licensed under the MIT license: +// https://git.musl-libc.org/cgit/musl/tree/COPYRIGHT +// +// https://git.musl-libc.org/cgit/musl/tree/src/math/fmaf.c +// https://git.musl-libc.org/cgit/musl/tree/src/math/fma.c + const std = @import("../std.zig"); const math = std.math; const expect = std.testing.expect; +/// Returns x * y + z with a single rounding error. pub fn fma(comptime T: type, x: T, y: T, z: T) T { return switch (T) { f32 => fma32(x, y, z), @@ -16,7 +23,7 @@ fn fma32(x: f32, y: f32, z: f32) f32 { const u = @bitCast(u64, xy_z); const e = (u >> 52) & 0x7FF; - if ((u & 0x1FFFFFFF) != 0x10000000 or e == 0x7FF or xy_z - xy == z) { + if ((u & 0x1FFFFFFF) != 0x10000000 or e == 0x7FF or (xy_z - xy == z and xy_z - z == xy)) { return @floatCast(f32, xy_z); } else { // TODO: Handle inexact case with double-rounding @@ -24,6 +31,7 @@ fn fma32(x: f32, y: f32, z: f32) f32 { } } +// NOTE: Upstream fma.c has been rewritten completely to raise fp exceptions more accurately. fn fma64(x: f64, y: f64, z: f64) f64 { if (!math.isFinite(x) or !math.isFinite(y)) { return x * y + z; diff --git a/std/math/pow.zig b/std/math/pow.zig index 81bb2d95d..18c9f8063 100644 --- a/std/math/pow.zig +++ b/std/math/pow.zig @@ -1,32 +1,36 @@ -// Special Cases: +// Ported from go, which is licensed under a BSD-3 license. +// https://golang.org/LICENSE // -// pow(x, +-0) = 1 for any x -// pow(1, y) = 1 for any y -// pow(x, 1) = x for any x -// pow(nan, y) = nan -// pow(x, nan) = nan -// pow(+-0, y) = +-inf for y an odd integer < 0 -// pow(+-0, -inf) = +inf -// pow(+-0, +inf) = +0 -// pow(+-0, y) = +inf for finite y < 0 and not an odd integer -// pow(+-0, y) = +-0 for y an odd integer > 0 -// pow(+-0, y) = +0 for finite y > 0 and not an odd integer -// pow(-1, +-inf) = 1 -// pow(x, +inf) = +inf for |x| > 1 -// pow(x, -inf) = +0 for |x| > 1 -// pow(x, +inf) = +0 for |x| < 1 -// pow(x, -inf) = +inf for |x| < 1 -// pow(+inf, y) = +inf for y > 0 -// pow(+inf, y) = +0 for y < 0 -// pow(-inf, y) = pow(-0, -y) -// pow(x, y) = nan for finite x < 0 and finite non-integer y +// https://golang.org/src/math/pow.go const builtin = @import("builtin"); const std = @import("../std.zig"); const math = std.math; const expect = std.testing.expect; -// This implementation is taken from the go stlib, musl is a bit more complex. +/// Returns x raised to the power of y (x^y). +/// +/// Special Cases: +/// - pow(x, +-0) = 1 for any x +/// - pow(1, y) = 1 for any y +/// - pow(x, 1) = x for any x +/// - pow(nan, y) = nan +/// - pow(x, nan) = nan +/// - pow(+-0, y) = +-inf for y an odd integer < 0 +/// - pow(+-0, -inf) = +inf +/// - pow(+-0, +inf) = +0 +/// - pow(+-0, y) = +inf for finite y < 0 and not an odd integer +/// - pow(+-0, y) = +-0 for y an odd integer > 0 +/// - pow(+-0, y) = +0 for finite y > 0 and not an odd integer +/// - pow(-1, +-inf) = 1 +/// - pow(x, +inf) = +inf for |x| > 1 +/// - pow(x, -inf) = +0 for |x| > 1 +/// - pow(x, +inf) = +0 for |x| < 1 +/// - pow(x, -inf) = +inf for |x| < 1 +/// - pow(+inf, y) = +inf for y > 0 +/// - pow(+inf, y) = +0 for y < 0 +/// - pow(-inf, y) = pow(-0, -y) +/// - pow(x, y) = nan for finite x < 0 and finite non-integer y pub fn pow(comptime T: type, x: T, y: T) T { if (@typeInfo(T) == builtin.TypeId.Int) { return math.powi(T, x, y) catch unreachable; @@ -53,15 +57,6 @@ pub fn pow(comptime T: type, x: T, y: T) T { return x; } - // special case sqrt - if (y == 0.5) { - return math.sqrt(x); - } - - if (y == -0.5) { - return 1 / math.sqrt(x); - } - if (x == 0) { if (y < 0) { // pow(+-0, y) = +- 0 for y an odd integer @@ -112,14 +107,16 @@ pub fn pow(comptime T: type, x: T, y: T) T { } } - var ay = y; - var flip = false; - if (ay < 0) { - ay = -ay; - flip = true; + // special case sqrt + if (y == 0.5) { + return math.sqrt(x); } - const r1 = math.modf(ay); + if (y == -0.5) { + return 1 / math.sqrt(x); + } + + const r1 = math.modf(math.fabs(y)); var yi = r1.ipart; var yf = r1.fpart; @@ -148,8 +145,18 @@ pub fn pow(comptime T: type, x: T, y: T) T { var xe = r2.exponent; var x1 = r2.significand; - var i = @floatToInt(i32, yi); + var i = @floatToInt(@IntType(true, T.bit_count), yi); while (i != 0) : (i >>= 1) { + const overflow_shift = math.floatExponentBits(T) + 1; + if (xe < -(1 << overflow_shift) or (1 << overflow_shift) < xe) { + // catch xe before it overflows the left shift below + // Since i != 0 it has at least one bit still set, so ae will accumulate xe + // on at least one more iteration, ae += xe is a lower bound on ae + // the lower bound on ae exceeds the size of a float exp + // so the final call to Ldexp will produce under/overflow (0/Inf) + ae += xe; + break; + } if (i & 1 == 1) { a1 *= x1; ae += xe; @@ -163,7 +170,7 @@ pub fn pow(comptime T: type, x: T, y: T) T { } // a *= a1 * 2^ae - if (flip) { + if (y < 0) { a1 = 1 / a1; ae = -ae; } @@ -202,6 +209,9 @@ test "math.pow.special" { expect(pow(f32, 45, 1.0) == 45); expect(pow(f32, -45, 1.0) == -45); expect(math.isNan(pow(f32, math.nan(f32), 5.0))); + expect(math.isPositiveInf(pow(f32, -math.inf(f32), 0.5))); + expect(math.isPositiveInf(pow(f32, -0, -0.5))); + expect(pow(f32, -0, 0.5) == 0); expect(math.isNan(pow(f32, 5.0, math.nan(f32)))); expect(math.isPositiveInf(pow(f32, 0.0, -1.0))); //expect(math.isNegativeInf(pow(f32, -0.0, -3.0))); TODO is this required? @@ -232,3 +242,11 @@ test "math.pow.special" { expect(math.isNan(pow(f32, -1.0, 1.2))); expect(math.isNan(pow(f32, -12.4, 78.5))); } + +test "math.pow.overflow" { + expect(math.isPositiveInf(pow(f64, 2, 1 << 32))); + expect(pow(f64, 2, -(1 << 32)) == 0); + expect(math.isNegativeInf(pow(f64, -2, (1 << 32) + 1))); + expect(pow(f64, 0.5, 1 << 45) == 0); + expect(math.isPositiveInf(pow(f64, 0.5, -(1 << 45)))); +} diff --git a/std/math/sin.zig b/std/math/sin.zig index e25b8a292..f21db4054 100644 --- a/std/math/sin.zig +++ b/std/math/sin.zig @@ -1,19 +1,24 @@ -// Special Cases: +// Ported from go, which is licensed under a BSD-3 license. +// https://golang.org/LICENSE // -// - sin(+-0) = +-0 -// - sin(+-inf) = nan -// - sin(nan) = nan +// https://golang.org/src/math/sin.go const builtin = @import("builtin"); const std = @import("../std.zig"); const math = std.math; const expect = std.testing.expect; +/// Returns the sine of the radian value x. +/// +/// Special Cases: +/// - sin(+-0) = +-0 +/// - sin(+-inf) = nan +/// - sin(nan) = nan pub fn sin(x: var) @typeOf(x) { const T = @typeOf(x); return switch (T) { - f32 => sin32(x), - f64 => sin64(x), + f32 => sin_(T, x), + f64 => sin_(T, x), else => @compileError("sin not implemented for " ++ @typeName(T)), }; } @@ -34,31 +39,27 @@ const C3 = 2.48015872888517045348E-5; const C4 = -1.38888888888730564116E-3; const C5 = 4.16666666666665929218E-2; -// NOTE: This is taken from the go stdlib. The musl implementation is much more complex. -// -// This may have slight differences on some edge cases and may need to replaced if so. -fn sin32(x_: f32) f32 { - const pi4a = 7.85398125648498535156e-1; - const pi4b = 3.77489470793079817668E-8; - const pi4c = 2.69515142907905952645E-15; - const m4pi = 1.273239544735162542821171882678754627704620361328125; +const pi4a = 7.85398125648498535156e-1; +const pi4b = 3.77489470793079817668E-8; +const pi4c = 2.69515142907905952645E-15; +const m4pi = 1.273239544735162542821171882678754627704620361328125; + +fn sin_(comptime T: type, x_: T) T { + const I = @IntType(true, T.bit_count); var x = x_; if (x == 0 or math.isNan(x)) { return x; } if (math.isInf(x)) { - return math.nan(f32); + return math.nan(T); } - var sign = false; - if (x < 0) { - x = -x; - sign = true; - } + var sign = x < 0; + x = math.fabs(x); var y = math.floor(x * m4pi); - var j = @floatToInt(i64, y); + var j = @floatToInt(I, y); if (j & 1 == 1) { j += 1; @@ -74,113 +75,56 @@ fn sin32(x_: f32) f32 { const z = ((x - y * pi4a) - y * pi4b) - y * pi4c; const w = z * z; - const r = r: { - if (j == 1 or j == 2) { - break :r 1.0 - 0.5 * w + w * w * (C5 + w * (C4 + w * (C3 + w * (C2 + w * (C1 + w * C0))))); - } else { - break :r z + z * w * (S5 + w * (S4 + w * (S3 + w * (S2 + w * (S1 + w * S0))))); - } - }; + const r = if (j == 1 or j == 2) + 1.0 - 0.5 * w + w * w * (C5 + w * (C4 + w * (C3 + w * (C2 + w * (C1 + w * C0))))) + else + z + z * w * (S5 + w * (S4 + w * (S3 + w * (S2 + w * (S1 + w * S0))))); - if (sign) { - return -r; - } else { - return r; - } -} - -fn sin64(x_: f64) f64 { - const pi4a = 7.85398125648498535156e-1; - const pi4b = 3.77489470793079817668E-8; - const pi4c = 2.69515142907905952645E-15; - const m4pi = 1.273239544735162542821171882678754627704620361328125; - - var x = x_; - if (x == 0 or math.isNan(x)) { - return x; - } - if (math.isInf(x)) { - return math.nan(f64); - } - - var sign = false; - if (x < 0) { - x = -x; - sign = true; - } - - var y = math.floor(x * m4pi); - var j = @floatToInt(i64, y); - - if (j & 1 == 1) { - j += 1; - y += 1; - } - - j &= 7; - if (j > 3) { - j -= 4; - sign = !sign; - } - - const z = ((x - y * pi4a) - y * pi4b) - y * pi4c; - const w = z * z; - - const r = r: { - if (j == 1 or j == 2) { - break :r 1.0 - 0.5 * w + w * w * (C5 + w * (C4 + w * (C3 + w * (C2 + w * (C1 + w * C0))))); - } else { - break :r z + z * w * (S5 + w * (S4 + w * (S3 + w * (S2 + w * (S1 + w * S0))))); - } - }; - - if (sign) { - return -r; - } else { - return r; - } + return if (sign) -r else r; } test "math.sin" { - expect(sin(f32(0.0)) == sin32(0.0)); - expect(sin(f64(0.0)) == sin64(0.0)); + expect(sin(f32(0.0)) == sin_(f32, 0.0)); + expect(sin(f64(0.0)) == sin_(f64, 0.0)); expect(comptime (math.sin(f64(2))) == math.sin(f64(2))); } test "math.sin32" { const epsilon = 0.000001; - expect(math.approxEq(f32, sin32(0.0), 0.0, epsilon)); - expect(math.approxEq(f32, sin32(0.2), 0.198669, epsilon)); - expect(math.approxEq(f32, sin32(0.8923), 0.778517, epsilon)); - expect(math.approxEq(f32, sin32(1.5), 0.997495, epsilon)); - expect(math.approxEq(f32, sin32(37.45), -0.246544, epsilon)); - expect(math.approxEq(f32, sin32(89.123), 0.916166, epsilon)); + expect(math.approxEq(f32, sin_(f32, 0.0), 0.0, epsilon)); + expect(math.approxEq(f32, sin_(f32, 0.2), 0.198669, epsilon)); + expect(math.approxEq(f32, sin_(f32, 0.8923), 0.778517, epsilon)); + expect(math.approxEq(f32, sin_(f32, 1.5), 0.997495, epsilon)); + expect(math.approxEq(f32, sin_(f32, -1.5), -0.997495, epsilon)); + expect(math.approxEq(f32, sin_(f32, 37.45), -0.246544, epsilon)); + expect(math.approxEq(f32, sin_(f32, 89.123), 0.916166, epsilon)); } test "math.sin64" { const epsilon = 0.000001; - expect(math.approxEq(f64, sin64(0.0), 0.0, epsilon)); - expect(math.approxEq(f64, sin64(0.2), 0.198669, epsilon)); - expect(math.approxEq(f64, sin64(0.8923), 0.778517, epsilon)); - expect(math.approxEq(f64, sin64(1.5), 0.997495, epsilon)); - expect(math.approxEq(f64, sin64(37.45), -0.246543, epsilon)); - expect(math.approxEq(f64, sin64(89.123), 0.916166, epsilon)); + expect(math.approxEq(f64, sin_(f64, 0.0), 0.0, epsilon)); + expect(math.approxEq(f64, sin_(f64, 0.2), 0.198669, epsilon)); + expect(math.approxEq(f64, sin_(f64, 0.8923), 0.778517, epsilon)); + expect(math.approxEq(f64, sin_(f64, 1.5), 0.997495, epsilon)); + expect(math.approxEq(f64, sin_(f64, -1.5), -0.997495, epsilon)); + expect(math.approxEq(f64, sin_(f64, 37.45), -0.246543, epsilon)); + expect(math.approxEq(f64, sin_(f64, 89.123), 0.916166, epsilon)); } test "math.sin32.special" { - expect(sin32(0.0) == 0.0); - expect(sin32(-0.0) == -0.0); - expect(math.isNan(sin32(math.inf(f32)))); - expect(math.isNan(sin32(-math.inf(f32)))); - expect(math.isNan(sin32(math.nan(f32)))); + expect(sin_(f32, 0.0) == 0.0); + expect(sin_(f32, -0.0) == -0.0); + expect(math.isNan(sin_(f32, math.inf(f32)))); + expect(math.isNan(sin_(f32, -math.inf(f32)))); + expect(math.isNan(sin_(f32, math.nan(f32)))); } test "math.sin64.special" { - expect(sin64(0.0) == 0.0); - expect(sin64(-0.0) == -0.0); - expect(math.isNan(sin64(math.inf(f64)))); - expect(math.isNan(sin64(-math.inf(f64)))); - expect(math.isNan(sin64(math.nan(f64)))); + expect(sin_(f64, 0.0) == 0.0); + expect(sin_(f64, -0.0) == -0.0); + expect(math.isNan(sin_(f64, math.inf(f64)))); + expect(math.isNan(sin_(f64, -math.inf(f64)))); + expect(math.isNan(sin_(f64, math.nan(f64)))); } diff --git a/std/math/tan.zig b/std/math/tan.zig index fc11ebdef..e8259ee7a 100644 --- a/std/math/tan.zig +++ b/std/math/tan.zig @@ -1,19 +1,24 @@ -// Special Cases: +// Ported from go, which is licensed under a BSD-3 license. +// https://golang.org/LICENSE // -// - tan(+-0) = +-0 -// - tan(+-inf) = nan -// - tan(nan) = nan +// https://golang.org/src/math/tan.go const builtin = @import("builtin"); const std = @import("../std.zig"); const math = std.math; const expect = std.testing.expect; +/// Returns the tangent of the radian value x. +/// +/// Special Cases: +/// - tan(+-0) = +-0 +/// - tan(+-inf) = nan +/// - tan(nan) = nan pub fn tan(x: var) @typeOf(x) { const T = @typeOf(x); return switch (T) { - f32 => tan32(x), - f64 => tan64(x), + f32 => tan_(f32, x), + f64 => tan_(f64, x), else => @compileError("tan not implemented for " ++ @typeName(T)), }; } @@ -27,31 +32,27 @@ const Tq2 = -1.32089234440210967447E6; const Tq3 = 2.50083801823357915839E7; const Tq4 = -5.38695755929454629881E7; -// NOTE: This is taken from the go stdlib. The musl implementation is much more complex. -// -// This may have slight differences on some edge cases and may need to replaced if so. -fn tan32(x_: f32) f32 { - const pi4a = 7.85398125648498535156e-1; - const pi4b = 3.77489470793079817668E-8; - const pi4c = 2.69515142907905952645E-15; - const m4pi = 1.273239544735162542821171882678754627704620361328125; +const pi4a = 7.85398125648498535156e-1; +const pi4b = 3.77489470793079817668E-8; +const pi4c = 2.69515142907905952645E-15; +const m4pi = 1.273239544735162542821171882678754627704620361328125; + +fn tan_(comptime T: type, x_: T) T { + const I = @IntType(true, T.bit_count); var x = x_; if (x == 0 or math.isNan(x)) { return x; } if (math.isInf(x)) { - return math.nan(f32); + return math.nan(T); } - var sign = false; - if (x < 0) { - x = -x; - sign = true; - } + var sign = x < 0; + x = math.fabs(x); var y = math.floor(x * m4pi); - var j = @floatToInt(i64, y); + var j = @floatToInt(I, y); if (j & 1 == 1) { j += 1; @@ -61,112 +62,57 @@ fn tan32(x_: f32) f32 { const z = ((x - y * pi4a) - y * pi4b) - y * pi4c; const w = z * z; - var r = r: { - if (w > 1e-14) { - break :r z + z * (w * ((Tp0 * w + Tp1) * w + Tp2) / ((((w + Tq1) * w + Tq2) * w + Tq3) * w + Tq4)); - } else { - break :r z; - } - }; + var r = if (w > 1e-14) + z + z * (w * ((Tp0 * w + Tp1) * w + Tp2) / ((((w + Tq1) * w + Tq2) * w + Tq3) * w + Tq4)) + else + z; if (j & 2 == 2) { r = -1 / r; } - if (sign) { - r = -r; - } - return r; -} - -fn tan64(x_: f64) f64 { - const pi4a = 7.85398125648498535156e-1; - const pi4b = 3.77489470793079817668E-8; - const pi4c = 2.69515142907905952645E-15; - const m4pi = 1.273239544735162542821171882678754627704620361328125; - - var x = x_; - if (x == 0 or math.isNan(x)) { - return x; - } - if (math.isInf(x)) { - return math.nan(f64); - } - - var sign = false; - if (x < 0) { - x = -x; - sign = true; - } - - var y = math.floor(x * m4pi); - var j = @floatToInt(i64, y); - - if (j & 1 == 1) { - j += 1; - y += 1; - } - - const z = ((x - y * pi4a) - y * pi4b) - y * pi4c; - const w = z * z; - - var r = r: { - if (w > 1e-14) { - break :r z + z * (w * ((Tp0 * w + Tp1) * w + Tp2) / ((((w + Tq1) * w + Tq2) * w + Tq3) * w + Tq4)); - } else { - break :r z; - } - }; - - if (j & 2 == 2) { - r = -1 / r; - } - if (sign) { - r = -r; - } - - return r; + return if (sign) -r else r; } test "math.tan" { - expect(tan(f32(0.0)) == tan32(0.0)); - expect(tan(f64(0.0)) == tan64(0.0)); + expect(tan(f32(0.0)) == tan_(f32, 0.0)); + expect(tan(f64(0.0)) == tan_(f64, 0.0)); } test "math.tan32" { const epsilon = 0.000001; - expect(math.approxEq(f32, tan32(0.0), 0.0, epsilon)); - expect(math.approxEq(f32, tan32(0.2), 0.202710, epsilon)); - expect(math.approxEq(f32, tan32(0.8923), 1.240422, epsilon)); - expect(math.approxEq(f32, tan32(1.5), 14.101420, epsilon)); - expect(math.approxEq(f32, tan32(37.45), -0.254397, epsilon)); - expect(math.approxEq(f32, tan32(89.123), 2.285852, epsilon)); + expect(math.approxEq(f32, tan_(f32, 0.0), 0.0, epsilon)); + expect(math.approxEq(f32, tan_(f32, 0.2), 0.202710, epsilon)); + expect(math.approxEq(f32, tan_(f32, 0.8923), 1.240422, epsilon)); + expect(math.approxEq(f32, tan_(f32, 1.5), 14.101420, epsilon)); + expect(math.approxEq(f32, tan_(f32, 37.45), -0.254397, epsilon)); + expect(math.approxEq(f32, tan_(f32, 89.123), 2.285852, epsilon)); } test "math.tan64" { const epsilon = 0.000001; - expect(math.approxEq(f64, tan64(0.0), 0.0, epsilon)); - expect(math.approxEq(f64, tan64(0.2), 0.202710, epsilon)); - expect(math.approxEq(f64, tan64(0.8923), 1.240422, epsilon)); - expect(math.approxEq(f64, tan64(1.5), 14.101420, epsilon)); - expect(math.approxEq(f64, tan64(37.45), -0.254397, epsilon)); - expect(math.approxEq(f64, tan64(89.123), 2.2858376, epsilon)); + expect(math.approxEq(f64, tan_(f64, 0.0), 0.0, epsilon)); + expect(math.approxEq(f64, tan_(f64, 0.2), 0.202710, epsilon)); + expect(math.approxEq(f64, tan_(f64, 0.8923), 1.240422, epsilon)); + expect(math.approxEq(f64, tan_(f64, 1.5), 14.101420, epsilon)); + expect(math.approxEq(f64, tan_(f64, 37.45), -0.254397, epsilon)); + expect(math.approxEq(f64, tan_(f64, 89.123), 2.2858376, epsilon)); } test "math.tan32.special" { - expect(tan32(0.0) == 0.0); - expect(tan32(-0.0) == -0.0); - expect(math.isNan(tan32(math.inf(f32)))); - expect(math.isNan(tan32(-math.inf(f32)))); - expect(math.isNan(tan32(math.nan(f32)))); + expect(tan_(f32, 0.0) == 0.0); + expect(tan_(f32, -0.0) == -0.0); + expect(math.isNan(tan_(f32, math.inf(f32)))); + expect(math.isNan(tan_(f32, -math.inf(f32)))); + expect(math.isNan(tan_(f32, math.nan(f32)))); } test "math.tan64.special" { - expect(tan64(0.0) == 0.0); - expect(tan64(-0.0) == -0.0); - expect(math.isNan(tan64(math.inf(f64)))); - expect(math.isNan(tan64(-math.inf(f64)))); - expect(math.isNan(tan64(math.nan(f64)))); + expect(tan_(f64, 0.0) == 0.0); + expect(tan_(f64, -0.0) == -0.0); + expect(math.isNan(tan_(f64, math.inf(f64)))); + expect(math.isNan(tan_(f64, -math.inf(f64)))); + expect(math.isNan(tan_(f64, math.nan(f64)))); } From 89d71a960b0f90335fded84a449a84806bb6f661 Mon Sep 17 00:00:00 2001 From: Marc Tiehuis Date: Wed, 1 May 2019 18:15:57 +1200 Subject: [PATCH 2/3] std.math: Add documentation for all functions and algorithm sources --- std/math/acos.zig | 10 ++- std/math/acosh.zig | 12 ++- std/math/asin.zig | 12 ++- std/math/asinh.zig | 14 +++- std/math/atan.zig | 12 ++- std/math/atan2.zig | 42 +++++----- std/math/atanh.zig | 14 +++- std/math/big/int.zig | 157 ++++++++++++++++++++++++++----------- std/math/big/rational.zig | 68 +++++++++++++--- std/math/cbrt.zig | 14 +++- std/math/ceil.zig | 14 +++- std/math/complex.zig | 12 +++ std/math/complex/abs.zig | 1 + std/math/complex/acos.zig | 1 + std/math/complex/acosh.zig | 1 + std/math/complex/arg.zig | 1 + std/math/complex/asin.zig | 1 + std/math/complex/asinh.zig | 1 + std/math/complex/atan.zig | 7 ++ std/math/complex/atanh.zig | 1 + std/math/complex/conj.zig | 1 + std/math/complex/cos.zig | 1 + std/math/complex/cosh.zig | 7 ++ std/math/complex/exp.zig | 7 ++ std/math/complex/ldexp.zig | 7 ++ std/math/complex/log.zig | 1 + std/math/complex/pow.zig | 1 + std/math/complex/proj.zig | 1 + std/math/complex/sin.zig | 1 + std/math/complex/sinh.zig | 7 ++ std/math/complex/sqrt.zig | 8 ++ std/math/complex/tan.zig | 1 + std/math/complex/tanh.zig | 7 ++ std/math/copysign.zig | 7 ++ std/math/cosh.zig | 14 +++- std/math/exp.zig | 12 ++- std/math/exp2.zig | 12 ++- std/math/expm1.zig | 17 +++- std/math/expo2.zig | 7 ++ std/math/fabs.zig | 12 ++- std/math/floor.zig | 14 +++- std/math/frexp.zig | 15 +++- std/math/hypot.zig | 16 ++-- std/math/ilogb.zig | 14 +++- std/math/inf.zig | 1 + std/math/isfinite.zig | 1 + std/math/isinf.zig | 3 + std/math/isnan.zig | 6 +- std/math/isnormal.zig | 1 + std/math/ln.zig | 16 ++-- std/math/log.zig | 7 ++ std/math/log10.zig | 16 ++-- std/math/log1p.zig | 18 +++-- std/math/log2.zig | 16 ++-- std/math/modf.zig | 13 ++- std/math/nan.zig | 6 +- std/math/powi.zig | 22 +++--- std/math/round.zig | 14 +++- std/math/scalbn.zig | 7 ++ std/math/signbit.zig | 1 + std/math/sinh.zig | 14 +++- std/math/sqrt.zig | 14 ++-- std/math/tanh.zig | 14 +++- std/math/trunc.zig | 14 +++- 64 files changed, 592 insertions(+), 197 deletions(-) diff --git a/std/math/acos.zig b/std/math/acos.zig index 763d9d8ab..de07da8fe 100644 --- a/std/math/acos.zig +++ b/std/math/acos.zig @@ -1,11 +1,17 @@ -// Special Cases: +// Ported from musl, which is licensed under the MIT license: +// https://git.musl-libc.org/cgit/musl/tree/COPYRIGHT // -// - acos(x) = nan if x < -1 or x > 1 +// https://git.musl-libc.org/cgit/musl/tree/src/math/acosf.c +// https://git.musl-libc.org/cgit/musl/tree/src/math/acos.c const std = @import("../std.zig"); const math = std.math; const expect = std.testing.expect; +/// Returns the arc-cosine of x. +/// +/// Special cases: +/// - acos(x) = nan if x < -1 or x > 1 pub fn acos(x: var) @typeOf(x) { const T = @typeOf(x); return switch (T) { diff --git a/std/math/acosh.zig b/std/math/acosh.zig index a2a992686..503c0433f 100644 --- a/std/math/acosh.zig +++ b/std/math/acosh.zig @@ -1,13 +1,19 @@ -// Special Cases: +// Ported from musl, which is licensed under the MIT license: +// https://git.musl-libc.org/cgit/musl/tree/COPYRIGHT // -// - acosh(x) = snan if x < 1 -// - acosh(nan) = nan +// https://git.musl-libc.org/cgit/musl/tree/src/math/acoshf.c +// https://git.musl-libc.org/cgit/musl/tree/src/math/acosh.c const builtin = @import("builtin"); const std = @import("../std.zig"); const math = std.math; const expect = std.testing.expect; +/// Returns the hyperbolic arc-cosine of x. +/// +/// Special cases: +/// - acosh(x) = snan if x < 1 +/// - acosh(nan) = nan pub fn acosh(x: var) @typeOf(x) { const T = @typeOf(x); return switch (T) { diff --git a/std/math/asin.zig b/std/math/asin.zig index b01a1ac49..2db9f86ff 100644 --- a/std/math/asin.zig +++ b/std/math/asin.zig @@ -1,12 +1,18 @@ -// Special Cases: +// Ported from musl, which is licensed under the MIT license: +// https://git.musl-libc.org/cgit/musl/tree/COPYRIGHT // -// - asin(+-0) = +-0 -// - asin(x) = nan if x < -1 or x > 1 +// https://git.musl-libc.org/cgit/musl/tree/src/math/asinf.c +// https://git.musl-libc.org/cgit/musl/tree/src/math/asin.c const std = @import("../std.zig"); const math = std.math; const expect = std.testing.expect; +/// Returns the arc-sin of x. +/// +/// Special Cases: +/// - asin(+-0) = +-0 +/// - asin(x) = nan if x < -1 or x > 1 pub fn asin(x: var) @typeOf(x) { const T = @typeOf(x); return switch (T) { diff --git a/std/math/asinh.zig b/std/math/asinh.zig index cef9bfb23..0fb51d1b4 100644 --- a/std/math/asinh.zig +++ b/std/math/asinh.zig @@ -1,14 +1,20 @@ -// Special Cases: +// Ported from musl, which is licensed under the MIT license: +// https://git.musl-libc.org/cgit/musl/tree/COPYRIGHT // -// - asinh(+-0) = +-0 -// - asinh(+-inf) = +-inf -// - asinh(nan) = nan +// https://git.musl-libc.org/cgit/musl/tree/src/math/asinhf.c +// https://git.musl-libc.org/cgit/musl/tree/src/math/asinh.c const std = @import("../std.zig"); const math = std.math; const expect = std.testing.expect; const maxInt = std.math.maxInt; +/// Returns the hyperbolic arc-sin of x. +/// +/// Special Cases: +/// - asinh(+-0) = +-0 +/// - asinh(+-inf) = +-inf +/// - asinh(nan) = nan pub fn asinh(x: var) @typeOf(x) { const T = @typeOf(x); return switch (T) { diff --git a/std/math/atan.zig b/std/math/atan.zig index ba5a11dd1..cc4cad0dd 100644 --- a/std/math/atan.zig +++ b/std/math/atan.zig @@ -1,12 +1,18 @@ -// Special Cases: +// Ported from musl, which is licensed under the MIT license: +// https://git.musl-libc.org/cgit/musl/tree/COPYRIGHT // -// - atan(+-0) = +-0 -// - atan(+-inf) = +-pi/2 +// https://git.musl-libc.org/cgit/musl/tree/src/math/atanf.c +// https://git.musl-libc.org/cgit/musl/tree/src/math/atan.c const std = @import("../std.zig"); const math = std.math; const expect = std.testing.expect; +/// Returns the arc-tangent of x. +/// +/// Special Cases: +/// - atan(+-0) = +-0 +/// - atan(+-inf) = +-pi/2 pub fn atan(x: var) @typeOf(x) { const T = @typeOf(x); return switch (T) { diff --git a/std/math/atan2.zig b/std/math/atan2.zig index 7f1350740..68e381607 100644 --- a/std/math/atan2.zig +++ b/std/math/atan2.zig @@ -1,27 +1,33 @@ -// Special Cases: +// Ported from musl, which is licensed under the MIT license: +// https://git.musl-libc.org/cgit/musl/tree/COPYRIGHT // -// atan2(y, nan) = nan -// atan2(nan, x) = nan -// atan2(+0, x>=0) = +0 -// atan2(-0, x>=0) = -0 -// atan2(+0, x<=-0) = +pi -// atan2(-0, x<=-0) = -pi -// atan2(y>0, 0) = +pi/2 -// atan2(y<0, 0) = -pi/2 -// atan2(+inf, +inf) = +pi/4 -// atan2(-inf, +inf) = -pi/4 -// atan2(+inf, -inf) = 3pi/4 -// atan2(-inf, -inf) = -3pi/4 -// atan2(y, +inf) = 0 -// atan2(y>0, -inf) = +pi -// atan2(y<0, -inf) = -pi -// atan2(+inf, x) = +pi/2 -// atan2(-inf, x) = -pi/2 +// https://git.musl-libc.org/cgit/musl/tree/src/math/atan2f.c +// https://git.musl-libc.org/cgit/musl/tree/src/math/atan2.c const std = @import("../std.zig"); const math = std.math; const expect = std.testing.expect; +/// Returns the arc-tangent of y/x. +/// +/// Special Cases: +/// - atan2(y, nan) = nan +/// - atan2(nan, x) = nan +/// - atan2(+0, x>=0) = +0 +/// - atan2(-0, x>=0) = -0 +/// - atan2(+0, x<=-0) = +pi +/// - atan2(-0, x<=-0) = -pi +/// - atan2(y>0, 0) = +pi/2 +/// - atan2(y<0, 0) = -pi/2 +/// - atan2(+inf, +inf) = +pi/4 +/// - atan2(-inf, +inf) = -pi/4 +/// - atan2(+inf, -inf) = 3pi/4 +/// - atan2(-inf, -inf) = -3pi/4 +/// - atan2(y, +inf) = 0 +/// - atan2(y>0, -inf) = +pi +/// - atan2(y<0, -inf) = -pi +/// - atan2(+inf, x) = +pi/2 +/// - atan2(-inf, x) = -pi/2 pub fn atan2(comptime T: type, y: T, x: T) T { return switch (T) { f32 => atan2_32(y, x), diff --git a/std/math/atanh.zig b/std/math/atanh.zig index 9056064f5..8ba29be76 100644 --- a/std/math/atanh.zig +++ b/std/math/atanh.zig @@ -1,14 +1,20 @@ -// Special Cases: +// Ported from musl, which is licensed under the MIT license: +// https://git.musl-libc.org/cgit/musl/tree/COPYRIGHT // -// - atanh(+-1) = +-inf with signal -// - atanh(x) = nan if |x| > 1 with signal -// - atanh(nan) = nan +// https://git.musl-libc.org/cgit/musl/tree/src/math/atanhf.c +// https://git.musl-libc.org/cgit/musl/tree/src/math/atanh.c const std = @import("../std.zig"); const math = std.math; const expect = std.testing.expect; const maxInt = std.math.maxInt; +/// Returns the hyperbolic arc-tangent of x. +/// +/// Special Cases: +/// - atanh(+-1) = +-inf with signal +/// - atanh(x) = nan if |x| > 1 with signal +/// - atanh(nan) = nan pub fn atanh(x: var) @typeOf(x) { const T = @typeOf(x); return switch (T) { diff --git a/std/math/big/int.zig b/std/math/big/int.zig index aced892e1..beac3c85f 100644 --- a/std/math/big/int.zig +++ b/std/math/big/int.zig @@ -21,32 +21,49 @@ comptime { debug.assert(Limb.is_signed == false); } +/// An arbitrary-precision big integer. +/// +/// Memory is allocated by an Int as needed to ensure operations never overflow. The range of an +/// Int is bounded only by available memory. pub const Int = struct { const sign_bit: usize = 1 << (usize.bit_count - 1); + /// Default number of limbs to allocate on creation of an Int. + pub const default_capacity = 4; + + /// Allocator used by the Int when requesting memory. allocator: ?*Allocator, - // - little-endian ordered - // - len >= 1 always - // - zero value -> len == 1 with limbs[0] == 0 + + /// Raw digits. These are: + /// + /// * Little-endian ordered + /// * limbs.len >= 1 + /// * Zero is represent as Int.len() == 1 with limbs[0] == 0. + /// + /// Accessing limbs directly should be avoided. limbs: []Limb, - // High bit is the sign bit. 1 is negative, 0 positive. - // Remaining bits indicate the number of used limbs. - // - // If Zig gets smarter about packing data, this can be rewritten as a u1 and usize - 1 field. + + /// High bit is the sign bit. If set, Int is negative, else Int is positive. + /// The remaining bits represent the number of limbs used by Int. metadata: usize, - const default_capacity = 4; - + /// Creates a new Int. default_capacity limbs will be allocated immediately. + /// Int will be zeroed. pub fn init(allocator: *Allocator) !Int { return try Int.initCapacity(allocator, default_capacity); } + /// Creates a new Int. Int will be set to `value`. + /// + /// This is identical to an `init`, followed by a `set`. pub fn initSet(allocator: *Allocator, value: var) !Int { var s = try Int.init(allocator); try s.set(value); return s; } + /// Creates a new Int with a specific capacity. If capacity < default_capacity then the + /// default capacity will be used instead. pub fn initCapacity(allocator: *Allocator, capacity: usize) !Int { return Int{ .allocator = allocator, @@ -59,14 +76,17 @@ pub const Int = struct { }; } + /// Returns the number of limbs currently in use. pub fn len(self: Int) usize { return self.metadata & ~sign_bit; } + /// Returns whether an Int is positive. pub fn isPositive(self: Int) bool { return self.metadata & sign_bit == 0; } + /// Sets the sign of an Int. pub fn setSign(self: *Int, positive: bool) void { if (positive) { self.metadata &= ~sign_bit; @@ -75,14 +95,17 @@ pub const Int = struct { } } + /// Sets the length of an Int. + /// + /// If setLen is used, then the Int must be normalized to suit. pub fn setLen(self: *Int, new_len: usize) void { self.metadata &= sign_bit; self.metadata |= new_len; } - // Initialize an Int directly from a fixed set of limb values. This is considered read-only - // and cannot be used as a receiver argument to any functions. If this tries to allocate - // at any point a panic will occur due to the null allocator. + /// Returns an Int backed by a fixed set of limb values. + /// This is read-only and cannot be used as a result argument. If the Int tries to allocate + /// memory a runtime panic will occur. pub fn initFixed(limbs: []const Limb) Int { var self = Int{ .allocator = null, @@ -95,6 +118,9 @@ pub const Int = struct { return self; } + /// Ensures an Int has enough space allocated for capacity limbs. If the Int does not have + /// sufficient capacity, the exact amount will be allocated. This occurs even if the requested + /// capacity is only greater than the current capacity by one limb. pub fn ensureCapacity(self: *Int, capacity: usize) !void { self.assertWritable(); if (capacity <= self.limbs.len) { @@ -110,12 +136,15 @@ pub const Int = struct { } } + /// Frees all memory associated with an Int. pub fn deinit(self: *Int) void { self.assertWritable(); self.allocator.?.free(self.limbs); self.* = undefined; } + /// Clones an Int and returns a new Int with the same value. The new Int is a deep copy and + /// can be modified separately from the original. pub fn clone(other: Int) !Int { other.assertWritable(); return Int{ @@ -129,6 +158,8 @@ pub const Int = struct { }; } + /// Copies the value of an Int to an existing Int so that they both have the same value. + /// Extra memory will be allocated if the receiver does not have enough capacity. pub fn copy(self: *Int, other: Int) !void { self.assertWritable(); if (self.limbs.ptr == other.limbs.ptr) { @@ -140,6 +171,8 @@ pub const Int = struct { self.metadata = other.metadata; } + /// Efficiently swap an Int with another. This swaps the limb pointers and a full copy is not + /// performed. The address of the limbs field will not be the same after this function. pub fn swap(self: *Int, other: *Int) void { self.assertWritable(); mem.swap(Int, self, other); @@ -152,35 +185,39 @@ pub const Int = struct { debug.warn("\n"); } + /// Negate the sign of an Int. pub fn negate(self: *Int) void { self.metadata ^= sign_bit; } + /// Make an Int positive. pub fn abs(self: *Int) void { self.metadata &= ~sign_bit; } + /// Returns true if an Int is odd. pub fn isOdd(self: Int) bool { return self.limbs[0] & 1 != 0; } + /// Returns true if an Int is even. pub fn isEven(self: Int) bool { return !self.isOdd(); } - // Returns the number of bits required to represent the absolute value of self. + /// Returns the number of bits required to represent the absolute value an Int. fn bitCountAbs(self: Int) usize { return (self.len() - 1) * Limb.bit_count + (Limb.bit_count - @clz(self.limbs[self.len() - 1])); } - // Returns the number of bits required to represent the integer in twos-complement form. - // - // If the integer is negative the value returned is the number of bits needed by a signed - // integer to represent the value. If positive the value is the number of bits for an - // unsigned integer. Any unsigned integer will fit in the signed integer with bitcount - // one greater than the returned value. - // - // e.g. -127 returns 8 as it will fit in an i8. 127 returns 7 since it fits in a u7. + /// Returns the number of bits required to represent the integer in twos-complement form. + /// + /// If the integer is negative the value returned is the number of bits needed by a signed + /// integer to represent the value. If positive the value is the number of bits for an + /// unsigned integer. Any unsigned integer will fit in the signed integer with bitcount + /// one greater than the returned value. + /// + /// e.g. -127 returns 8 as it will fit in an i8. 127 returns 7 since it fits in a u7. fn bitCountTwosComp(self: Int) usize { var bits = self.bitCountAbs(); @@ -203,7 +240,7 @@ pub const Int = struct { return bits; } - pub fn fitsInTwosComp(self: Int, is_signed: bool, bit_count: usize) bool { + fn fitsInTwosComp(self: Int, is_signed: bool, bit_count: usize) bool { if (self.eqZero()) { return true; } @@ -215,18 +252,20 @@ pub const Int = struct { return bit_count >= req_bits; } + /// Returns whether self can fit into an integer of the requested type. pub fn fits(self: Int, comptime T: type) bool { return self.fitsInTwosComp(T.is_signed, T.bit_count); } - // Returns the approximate size of the integer in the given base. Negative values accommodate for - // the minus sign. This is used for determining the number of characters needed to print the - // value. It is inexact and will exceed the given value by 1-2 digits. + /// Returns the approximate size of the integer in the given base. Negative values accommodate for + /// the minus sign. This is used for determining the number of characters needed to print the + /// value. It is inexact and may exceed the given value by ~1-2 bytes. pub fn sizeInBase(self: Int, base: usize) usize { const bit_count = usize(@boolToInt(!self.isPositive())) + self.bitCountAbs(); return (bit_count / math.log2(base)) + 1; } + /// Sets an Int to value. Value must be an primitive integer type. pub fn set(self: *Int, value: var) Allocator.Error!void { self.assertWritable(); const T = @typeOf(value); @@ -290,6 +329,9 @@ pub const Int = struct { TargetTooSmall, }; + /// Convert self to type T. + /// + /// Returns an error if self cannot be narrowed into the requested type without truncation. pub fn to(self: Int, comptime T: type) ConvertError!T { switch (@typeId(T)) { TypeId.Int => { @@ -353,6 +395,13 @@ pub const Int = struct { }; } + /// Set self from the string representation `value`. + /// + /// value must contain only digits <= `base`. Base prefixes are not allowed (e.g. 0x43 should + /// simply be 43). + /// + /// Returns an error if memory could not be allocated or `value` has invalid digits for the + /// requested base. pub fn setString(self: *Int, base: u8, value: []const u8) !void { self.assertWritable(); if (base < 2 or base > 16) { @@ -380,6 +429,8 @@ pub const Int = struct { self.setSign(positive); } + /// Converts self to a string in the requested base. Memory is allocated from the provided + /// allocator and not the one present in self. /// TODO make this call format instead of the other way around pub fn toString(self: Int, allocator: *Allocator, base: u8) ![]const u8 { if (base < 2 or base > 16) { @@ -463,7 +514,7 @@ pub const Int = struct { return s; } - /// for the std lib format function + /// To allow `std.fmt.printf` to work with Int. /// TODO make this non-allocating pub fn format( self: Int, @@ -480,7 +531,7 @@ pub const Int = struct { return output(context, str); } - // returns -1, 0, 1 if |a| < |b|, |a| == |b| or |a| > |b| respectively. + /// Returns -1, 0, 1 if |a| < |b|, |a| == |b| or |a| > |b| respectively. pub fn cmpAbs(a: Int, b: Int) i8 { if (a.len() < b.len()) { return -1; @@ -505,7 +556,7 @@ pub const Int = struct { } } - // returns -1, 0, 1 if a < b, a == b or a > b respectively. + /// Returns -1, 0, 1 if a < b, a == b or a > b respectively. pub fn cmp(a: Int, b: Int) i8 { if (a.isPositive() != b.isPositive()) { return if (a.isPositive()) i8(1) else -1; @@ -515,17 +566,17 @@ pub const Int = struct { } } - // if a == 0 + /// Returns true if a == 0. pub fn eqZero(a: Int) bool { return a.len() == 1 and a.limbs[0] == 0; } - // if |a| == |b| + /// Returns true if |a| == |b|. pub fn eqAbs(a: Int, b: Int) bool { return cmpAbs(a, b) == 0; } - // if a == b + /// Returns true if a == b. pub fn eq(a: Int, b: Int) bool { return cmp(a, b) == 0; } @@ -559,7 +610,11 @@ pub const Int = struct { }; } - // r = a + b + /// r = a + b + /// + /// r, a and b may be aliases. + /// + /// Returns an error if memory could not be allocated. pub fn add(r: *Int, a: Int, b: Int) Allocator.Error!void { r.assertWritable(); if (a.eqZero()) { @@ -617,7 +672,11 @@ pub const Int = struct { r[i] = carry; } - // r = a - b + /// r = a - b + /// + /// r, a and b may be aliases. + /// + /// Returns an error if memory could not be allocated. pub fn sub(r: *Int, a: Int, b: Int) !void { r.assertWritable(); if (a.isPositive() != b.isPositive()) { @@ -684,9 +743,11 @@ pub const Int = struct { debug.assert(borrow == 0); } - // rma = a * b - // - // For greatest efficiency, ensure rma does not alias a or b. + /// rma = a * b + /// + /// rma, a and b may be aliases. However, it is more efficient if rma does not alias a or b. + /// + /// Returns an error if memory could not be allocated. pub fn mul(rma: *Int, a: Int, b: Int) !void { rma.assertWritable(); @@ -759,6 +820,9 @@ pub const Int = struct { } } + /// q = a / b (rem r) + /// + /// a / b are floored (rounded towards 0). pub fn divFloor(q: *Int, r: *Int, a: Int, b: Int) !void { try div(q, r, a, b); @@ -771,6 +835,9 @@ pub const Int = struct { r.setSign(b.isPositive()); } + /// q = a / b (rem r) + /// + /// a / b are truncated (rounded towards -inf). pub fn divTrunc(q: *Int, r: *Int, a: Int, b: Int) !void { try div(q, r, a, b); r.setSign(a.isPositive()); @@ -969,7 +1036,7 @@ pub const Int = struct { r.normalize(r.len()); } - // r = a << shift, in other words, r = a * 2^shift + /// r = a << shift, in other words, r = a * 2^shift pub fn shiftLeft(r: *Int, a: Int, shift: usize) !void { r.assertWritable(); @@ -1002,7 +1069,7 @@ pub const Int = struct { mem.set(Limb, r[0 .. limb_shift - 1], 0); } - // r = a >> shift + /// r = a >> shift pub fn shiftRight(r: *Int, a: Int, shift: usize) !void { r.assertWritable(); @@ -1038,7 +1105,9 @@ pub const Int = struct { } } - // r = a | b + /// r = a | b + /// + /// a and b are zero-extended to the longer of a or b. pub fn bitOr(r: *Int, a: Int, b: Int) !void { r.assertWritable(); @@ -1067,7 +1136,7 @@ pub const Int = struct { } } - // r = a & b + /// r = a & b pub fn bitAnd(r: *Int, a: Int, b: Int) !void { r.assertWritable(); @@ -1093,7 +1162,7 @@ pub const Int = struct { } } - // r = a ^ b + /// r = a ^ b pub fn bitXor(r: *Int, a: Int, b: Int) !void { r.assertWritable(); @@ -1279,10 +1348,8 @@ test "big.int bitcount/to" { try a.set(0); testing.expect(a.bitCountTwosComp() == 0); - // TODO: stack smashing - // testing.expect((try a.to(u0)) == 0); - // TODO: sigsegv - // testing.expect((try a.to(i0)) == 0); + testing.expect((try a.to(u0)) == 0); + testing.expect((try a.to(i0)) == 0); try a.set(-1); testing.expect(a.bitCountTwosComp() == 1); diff --git a/std/math/big/rational.zig b/std/math/big/rational.zig index 34cf3bf76..58a5e3ac7 100644 --- a/std/math/big/rational.zig +++ b/std/math/big/rational.zig @@ -14,11 +14,22 @@ const Limb = bn.Limb; const DoubleLimb = bn.DoubleLimb; const Int = bn.Int; +/// An arbitrary-precision rational number. +/// +/// Memory is allocated as needed for operations to ensure full precision is kept. The precision +/// of a Rational is only bounded by memory. +/// +/// Rational's are always normalized. That is, for a Rational r = p/q where p and q are integers, +/// gcd(p, q) = 1 always. pub const Rational = struct { - // Sign of Rational is sign of p. Sign of q is ignored + /// Numerator. Determines the sign of the Rational. p: Int, + + /// Denominator. Sign is ignored. q: Int, + /// Create a new Rational. A small amount of memory will be allocated on initialization. + /// This will be 2 * Int.default_capacity. pub fn init(a: *Allocator) !Rational { return Rational{ .p = try Int.init(a), @@ -26,18 +37,21 @@ pub const Rational = struct { }; } + /// Frees all memory associated with a Rational. pub fn deinit(self: *Rational) void { self.p.deinit(); self.q.deinit(); } + /// Set a Rational from a primitive integer type. pub fn setInt(self: *Rational, a: var) !void { try self.p.set(a); try self.q.set(1); } - // TODO: Accept a/b fractions and exponent form + /// Set a Rational from a string of the form `A/B` where A and B are base-10 integers. pub fn setFloatString(self: *Rational, str: []const u8) !void { + // TODO: Accept a/b fractions and exponent form if (str.len == 0) { return error.InvalidFloatString; } @@ -111,8 +125,10 @@ pub const Rational = struct { } } - // Translated from golang.go/src/math/big/rat.go. + /// Set a Rational from a floating-point value. The rational will have enough precision to + /// completely represent the provided float. pub fn setFloat(self: *Rational, comptime T: type, f: T) !void { + // Translated from golang.go/src/math/big/rat.go. debug.assert(@typeId(T) == builtin.TypeId.Float); const UnsignedIntType = @IntType(false, T.bit_count); @@ -164,8 +180,13 @@ pub const Rational = struct { try self.reduce(); } - // Translated from golang.go/src/math/big/rat.go. + /// Return a floating-point value that is the closest value to a Rational. + /// + /// The result may not be exact if the Rational is too precise or too large for the + /// target type. pub fn toFloat(self: Rational, comptime T: type) !T { + // Translated from golang.go/src/math/big/rat.go. + // TODO: Indicate whether the result is not exact. debug.assert(@typeId(T) == builtin.TypeId.Float); const fsize = T.bit_count; @@ -259,6 +280,7 @@ pub const Rational = struct { return if (self.p.isPositive()) f else -f; } + /// Set a rational from an integer ratio. pub fn setRatio(self: *Rational, p: var, q: var) !void { try self.p.set(p); try self.q.set(q); @@ -273,11 +295,13 @@ pub const Rational = struct { } } + /// Set a Rational directly from an Int. pub fn copyInt(self: *Rational, a: Int) !void { try self.p.copy(a); try self.q.set(1); } + /// Set a Rational directly from a ratio of two Int's. pub fn copyRatio(self: *Rational, a: Int, b: Int) !void { try self.p.copy(a); try self.q.copy(b); @@ -288,23 +312,29 @@ pub const Rational = struct { try self.reduce(); } + /// Make a Rational positive. pub fn abs(r: *Rational) void { r.p.abs(); } + /// Negate the sign of a Rational. pub fn negate(r: *Rational) void { r.p.negate(); } + /// Efficiently swap a Rational with another. This swaps the limb pointers and a full copy is not + /// performed. The address of the limbs field will not be the same after this function. pub fn swap(r: *Rational, other: *Rational) void { r.p.swap(&other.p); r.q.swap(&other.q); } + /// Returns -1, 0, 1 if a < b, a == b or a > b respectively. pub fn cmp(a: Rational, b: Rational) !i8 { return cmpInternal(a, b, true); } + /// Returns -1, 0, 1 if |a| < |b|, |a| == |b| or |a| > |b| respectively. pub fn cmpAbs(a: Rational, b: Rational) !i8 { return cmpInternal(a, b, false); } @@ -325,9 +355,11 @@ pub const Rational = struct { return if (is_abs) q.cmpAbs(p) else q.cmp(p); } - // r/q = ap/aq + bp/bq = (ap*bq + bp*aq) / (aq*bq) - // - // For best performance, rma should not alias a or b. + /// rma = a + b. + /// + /// rma, a and b may be aliases. However, it is more efficient if rma does not alias a or b. + /// + /// Returns an error if memory could not be allocated. pub fn add(rma: *Rational, a: Rational, b: Rational) !void { var r = rma; var aliased = rma.p.limbs.ptr == a.p.limbs.ptr or rma.p.limbs.ptr == b.p.limbs.ptr; @@ -351,9 +383,11 @@ pub const Rational = struct { try r.reduce(); } - // r/q = ap/aq - bp/bq = (ap*bq - bp*aq) / (aq*bq) - // - // For best performance, rma should not alias a or b. + /// rma = a - b. + /// + /// rma, a and b may be aliases. However, it is more efficient if rma does not alias a or b. + /// + /// Returns an error if memory could not be allocated. pub fn sub(rma: *Rational, a: Rational, b: Rational) !void { var r = rma; var aliased = rma.p.limbs.ptr == a.p.limbs.ptr or rma.p.limbs.ptr == b.p.limbs.ptr; @@ -377,14 +411,22 @@ pub const Rational = struct { try r.reduce(); } - // r/q = ap/aq * bp/bq = ap*bp / aq*bq + /// rma = a * b. + /// + /// rma, a and b may be aliases. However, it is more efficient if rma does not alias a or b. + /// + /// Returns an error if memory could not be allocated. pub fn mul(r: *Rational, a: Rational, b: Rational) !void { try r.p.mul(a.p, b.p); try r.q.mul(a.q, b.q); try r.reduce(); } - // r/q = (ap/aq) / (bp/bq) = ap*bq / bp*aq + /// rma = a / b. + /// + /// rma, a and b may be aliases. However, it is more efficient if rma does not alias a or b. + /// + /// Returns an error if memory could not be allocated. pub fn div(r: *Rational, a: Rational, b: Rational) !void { if (b.p.eqZero()) { @panic("division by zero"); @@ -395,7 +437,7 @@ pub const Rational = struct { try r.reduce(); } - // r/q = q/r + /// Invert the numerator and denominator fields of a Rational. p/q => q/p. pub fn invert(r: *Rational) void { Int.swap(&r.p, &r.q); } diff --git a/std/math/cbrt.zig b/std/math/cbrt.zig index 949725526..5241e3132 100644 --- a/std/math/cbrt.zig +++ b/std/math/cbrt.zig @@ -1,13 +1,19 @@ -// Special Cases: +// Ported from musl, which is licensed under the MIT license: +// https://git.musl-libc.org/cgit/musl/tree/COPYRIGHT // -// - cbrt(+-0) = +-0 -// - cbrt(+-inf) = +-inf -// - cbrt(nan) = nan +// https://git.musl-libc.org/cgit/musl/tree/src/math/cbrtf.c +// https://git.musl-libc.org/cgit/musl/tree/src/math/cbrt.c const std = @import("../std.zig"); const math = std.math; const expect = std.testing.expect; +/// Returns the cube root of x. +/// +/// Special Cases: +/// - cbrt(+-0) = +-0 +/// - cbrt(+-inf) = +-inf +/// - cbrt(nan) = nan pub fn cbrt(x: var) @typeOf(x) { const T = @typeOf(x); return switch (T) { diff --git a/std/math/ceil.zig b/std/math/ceil.zig index da83e0ec5..5f86093a6 100644 --- a/std/math/ceil.zig +++ b/std/math/ceil.zig @@ -1,14 +1,20 @@ -// Special Cases: +// Ported from musl, which is licensed under the MIT license: +// https://git.musl-libc.org/cgit/musl/tree/COPYRIGHT // -// - ceil(+-0) = +-0 -// - ceil(+-inf) = +-inf -// - ceil(nan) = nan +// https://git.musl-libc.org/cgit/musl/tree/src/math/ceilf.c +// https://git.musl-libc.org/cgit/musl/tree/src/math/ceil.c const builtin = @import("builtin"); const std = @import("../std.zig"); const math = std.math; const expect = std.testing.expect; +/// Returns the least integer value greater than of equal to x. +/// +/// Special Cases: +/// - ceil(+-0) = +-0 +/// - ceil(+-inf) = +-inf +/// - ceil(nan) = nan pub fn ceil(x: var) @typeOf(x) { const T = @typeOf(x); return switch (T) { diff --git a/std/math/complex.zig b/std/math/complex.zig index cc0573b22..e5574f9ce 100644 --- a/std/math/complex.zig +++ b/std/math/complex.zig @@ -23,13 +23,18 @@ pub const sqrt = @import("complex/sqrt.zig").sqrt; pub const tanh = @import("complex/tanh.zig").tanh; pub const tan = @import("complex/tan.zig").tan; +/// A complex number consisting of a real an imaginary part. T must be a floating-point value. pub fn Complex(comptime T: type) type { return struct { const Self = @This(); + /// Real part. re: T, + + /// Imaginary part. im: T, + /// Create a new Complex number from the given real and imaginary parts. pub fn new(re: T, im: T) Self { return Self{ .re = re, @@ -37,6 +42,7 @@ pub fn Complex(comptime T: type) type { }; } + /// Returns the sum of two complex numbers. pub fn add(self: Self, other: Self) Self { return Self{ .re = self.re + other.re, @@ -44,6 +50,7 @@ pub fn Complex(comptime T: type) type { }; } + /// Returns the subtraction of two complex numbers. pub fn sub(self: Self, other: Self) Self { return Self{ .re = self.re - other.re, @@ -51,6 +58,7 @@ pub fn Complex(comptime T: type) type { }; } + /// Returns the product of two complex numbers. pub fn mul(self: Self, other: Self) Self { return Self{ .re = self.re * other.re - self.im * other.im, @@ -58,6 +66,7 @@ pub fn Complex(comptime T: type) type { }; } + /// Returns the quotient of two complex numbers. pub fn div(self: Self, other: Self) Self { const re_num = self.re * other.re + self.im * other.im; const im_num = self.im * other.re - self.re * other.im; @@ -69,6 +78,7 @@ pub fn Complex(comptime T: type) type { }; } + /// Returns the complex conjugate of a number. pub fn conjugate(self: Self) Self { return Self{ .re = self.re, @@ -76,6 +86,7 @@ pub fn Complex(comptime T: type) type { }; } + /// Returns the reciprocal of a complex number. pub fn reciprocal(self: Self) Self { const m = self.re * self.re + self.im * self.im; return Self{ @@ -84,6 +95,7 @@ pub fn Complex(comptime T: type) type { }; } + /// Returns the magnitude of a complex number. pub fn magnitude(self: Self) T { return math.sqrt(self.re * self.re + self.im * self.im); } diff --git a/std/math/complex/abs.zig b/std/math/complex/abs.zig index e1368d6ef..8105f5721 100644 --- a/std/math/complex/abs.zig +++ b/std/math/complex/abs.zig @@ -4,6 +4,7 @@ const math = std.math; const cmath = math.complex; const Complex = cmath.Complex; +/// Returns the absolute value (modulus) of z. pub fn abs(z: var) @typeOf(z.re) { const T = @typeOf(z.re); return math.hypot(T, z.re, z.im); diff --git a/std/math/complex/acos.zig b/std/math/complex/acos.zig index 8aed26a71..f3526cc9f 100644 --- a/std/math/complex/acos.zig +++ b/std/math/complex/acos.zig @@ -4,6 +4,7 @@ const math = std.math; const cmath = math.complex; const Complex = cmath.Complex; +/// Returns the arc-cosine of z. pub fn acos(z: var) Complex(@typeOf(z.re)) { const T = @typeOf(z.re); const q = cmath.asin(z); diff --git a/std/math/complex/acosh.zig b/std/math/complex/acosh.zig index e72bf431f..6f0fd2e36 100644 --- a/std/math/complex/acosh.zig +++ b/std/math/complex/acosh.zig @@ -4,6 +4,7 @@ const math = std.math; const cmath = math.complex; const Complex = cmath.Complex; +/// Returns the hyperbolic arc-cosine of z. pub fn acosh(z: var) Complex(@typeOf(z.re)) { const T = @typeOf(z.re); const q = cmath.acos(z); diff --git a/std/math/complex/arg.zig b/std/math/complex/arg.zig index 0a2441d1f..d0c9588b8 100644 --- a/std/math/complex/arg.zig +++ b/std/math/complex/arg.zig @@ -4,6 +4,7 @@ const math = std.math; const cmath = math.complex; const Complex = cmath.Complex; +/// Returns the angular component (in radians) of z. pub fn arg(z: var) @typeOf(z.re) { const T = @typeOf(z.re); return math.atan2(T, z.im, z.re); diff --git a/std/math/complex/asin.zig b/std/math/complex/asin.zig index 6be775d74..76f94a286 100644 --- a/std/math/complex/asin.zig +++ b/std/math/complex/asin.zig @@ -4,6 +4,7 @@ const math = std.math; const cmath = math.complex; const Complex = cmath.Complex; +// Returns the arc-sine of z. pub fn asin(z: var) Complex(@typeOf(z.re)) { const T = @typeOf(z.re); const x = z.re; diff --git a/std/math/complex/asinh.zig b/std/math/complex/asinh.zig index 8e0903675..da065aad0 100644 --- a/std/math/complex/asinh.zig +++ b/std/math/complex/asinh.zig @@ -4,6 +4,7 @@ const math = std.math; const cmath = math.complex; const Complex = cmath.Complex; +/// Returns the hyperbolic arc-sine of z. pub fn asinh(z: var) Complex(@typeOf(z.re)) { const T = @typeOf(z.re); const q = Complex(T).new(-z.im, z.re); diff --git a/std/math/complex/atan.zig b/std/math/complex/atan.zig index 6b83adbd9..89bc8dfaf 100644 --- a/std/math/complex/atan.zig +++ b/std/math/complex/atan.zig @@ -1,9 +1,16 @@ +// Ported from musl, which is licensed under the MIT license: +// https://git.musl-libc.org/cgit/musl/tree/COPYRIGHT +// +// https://git.musl-libc.org/cgit/musl/tree/src/complex/catanf.c +// https://git.musl-libc.org/cgit/musl/tree/src/complex/catan.c + const std = @import("../../std.zig"); const testing = std.testing; const math = std.math; const cmath = math.complex; const Complex = cmath.Complex; +/// Returns the arc-tangent of z. pub fn atan(z: var) @typeOf(z) { const T = @typeOf(z.re); return switch (T) { diff --git a/std/math/complex/atanh.zig b/std/math/complex/atanh.zig index 8edfb6e78..225e7c61d 100644 --- a/std/math/complex/atanh.zig +++ b/std/math/complex/atanh.zig @@ -4,6 +4,7 @@ const math = std.math; const cmath = math.complex; const Complex = cmath.Complex; +/// Returns the hyperbolic arc-tangent of z. pub fn atanh(z: var) Complex(@typeOf(z.re)) { const T = @typeOf(z.re); const q = Complex(T).new(-z.im, z.re); diff --git a/std/math/complex/conj.zig b/std/math/complex/conj.zig index 7a42d365e..bd71ca3c0 100644 --- a/std/math/complex/conj.zig +++ b/std/math/complex/conj.zig @@ -4,6 +4,7 @@ const math = std.math; const cmath = math.complex; const Complex = cmath.Complex; +/// Returns the complex conjugate of z. pub fn conj(z: var) Complex(@typeOf(z.re)) { const T = @typeOf(z.re); return Complex(T).new(z.re, -z.im); diff --git a/std/math/complex/cos.zig b/std/math/complex/cos.zig index 71f9603c7..332009ffe 100644 --- a/std/math/complex/cos.zig +++ b/std/math/complex/cos.zig @@ -4,6 +4,7 @@ const math = std.math; const cmath = math.complex; const Complex = cmath.Complex; +/// Returns the cosine of z. pub fn cos(z: var) Complex(@typeOf(z.re)) { const T = @typeOf(z.re); const p = Complex(T).new(-z.im, z.re); diff --git a/std/math/complex/cosh.zig b/std/math/complex/cosh.zig index 9806e4117..be7bfde96 100644 --- a/std/math/complex/cosh.zig +++ b/std/math/complex/cosh.zig @@ -1,3 +1,9 @@ +// Ported from musl, which is licensed under the MIT license: +// https://git.musl-libc.org/cgit/musl/tree/COPYRIGHT +// +// https://git.musl-libc.org/cgit/musl/tree/src/complex/ccoshf.c +// https://git.musl-libc.org/cgit/musl/tree/src/complex/ccosh.c + const std = @import("../../std.zig"); const testing = std.testing; const math = std.math; @@ -6,6 +12,7 @@ const Complex = cmath.Complex; const ldexp_cexp = @import("ldexp.zig").ldexp_cexp; +/// Returns the hyperbolic arc-cosine of z. pub fn cosh(z: var) Complex(@typeOf(z.re)) { const T = @typeOf(z.re); return switch (T) { diff --git a/std/math/complex/exp.zig b/std/math/complex/exp.zig index c74ac2fc0..9b686bebc 100644 --- a/std/math/complex/exp.zig +++ b/std/math/complex/exp.zig @@ -1,3 +1,9 @@ +// Ported from musl, which is licensed under the MIT license: +// https://git.musl-libc.org/cgit/musl/tree/COPYRIGHT +// +// https://git.musl-libc.org/cgit/musl/tree/src/complex/cexpf.c +// https://git.musl-libc.org/cgit/musl/tree/src/complex/cexp.c + const std = @import("../../std.zig"); const testing = std.testing; const math = std.math; @@ -6,6 +12,7 @@ const Complex = cmath.Complex; const ldexp_cexp = @import("ldexp.zig").ldexp_cexp; +/// Returns e raised to the power of z (e^z). pub fn exp(z: var) @typeOf(z) { const T = @typeOf(z.re); diff --git a/std/math/complex/ldexp.zig b/std/math/complex/ldexp.zig index 6b4306bf7..d6f810793 100644 --- a/std/math/complex/ldexp.zig +++ b/std/math/complex/ldexp.zig @@ -1,9 +1,16 @@ +// Ported from musl, which is licensed under the MIT license: +// https://git.musl-libc.org/cgit/musl/tree/COPYRIGHT +// +// https://git.musl-libc.org/cgit/musl/tree/src/complex/__cexpf.c +// https://git.musl-libc.org/cgit/musl/tree/src/complex/__cexp.c + const std = @import("../../std.zig"); const debug = std.debug; const math = std.math; const cmath = math.complex; const Complex = cmath.Complex; +/// Returns exp(z) scaled to avoid overflow. pub fn ldexp_cexp(z: var, expt: i32) @typeOf(z) { const T = @typeOf(z.re); diff --git a/std/math/complex/log.zig b/std/math/complex/log.zig index 2b43a6970..762b4fde9 100644 --- a/std/math/complex/log.zig +++ b/std/math/complex/log.zig @@ -4,6 +4,7 @@ const math = std.math; const cmath = math.complex; const Complex = cmath.Complex; +/// Returns the natural logarithm of z. pub fn log(z: var) Complex(@typeOf(z.re)) { const T = @typeOf(z.re); const r = cmath.abs(z); diff --git a/std/math/complex/pow.zig b/std/math/complex/pow.zig index 9174bb362..a2480453f 100644 --- a/std/math/complex/pow.zig +++ b/std/math/complex/pow.zig @@ -4,6 +4,7 @@ const math = std.math; const cmath = math.complex; const Complex = cmath.Complex; +/// Returns z raised to the complex power of c. pub fn pow(comptime T: type, z: T, c: T) T { const p = cmath.log(z); const q = c.mul(p); diff --git a/std/math/complex/proj.zig b/std/math/complex/proj.zig index aadcff6ff..c8f2d9fc6 100644 --- a/std/math/complex/proj.zig +++ b/std/math/complex/proj.zig @@ -4,6 +4,7 @@ const math = std.math; const cmath = math.complex; const Complex = cmath.Complex; +/// Returns the projection of z onto the riemann sphere. pub fn proj(z: var) Complex(@typeOf(z.re)) { const T = @typeOf(z.re); diff --git a/std/math/complex/sin.zig b/std/math/complex/sin.zig index 049631f31..9ddc3a7a8 100644 --- a/std/math/complex/sin.zig +++ b/std/math/complex/sin.zig @@ -4,6 +4,7 @@ const math = std.math; const cmath = math.complex; const Complex = cmath.Complex; +/// Returns the sine of z. pub fn sin(z: var) Complex(@typeOf(z.re)) { const T = @typeOf(z.re); const p = Complex(T).new(-z.im, z.re); diff --git a/std/math/complex/sinh.zig b/std/math/complex/sinh.zig index 0b656e535..6286d8447 100644 --- a/std/math/complex/sinh.zig +++ b/std/math/complex/sinh.zig @@ -1,3 +1,9 @@ +// Ported from musl, which is licensed under the MIT license: +// https://git.musl-libc.org/cgit/musl/tree/COPYRIGHT +// +// https://git.musl-libc.org/cgit/musl/tree/src/complex/csinhf.c +// https://git.musl-libc.org/cgit/musl/tree/src/complex/csinh.c + const std = @import("../../std.zig"); const testing = std.testing; const math = std.math; @@ -6,6 +12,7 @@ const Complex = cmath.Complex; const ldexp_cexp = @import("ldexp.zig").ldexp_cexp; +/// Returns the hyperbolic sine of z. pub fn sinh(z: var) @typeOf(z) { const T = @typeOf(z.re); return switch (T) { diff --git a/std/math/complex/sqrt.zig b/std/math/complex/sqrt.zig index e935d0b23..36f4c28e2 100644 --- a/std/math/complex/sqrt.zig +++ b/std/math/complex/sqrt.zig @@ -1,9 +1,17 @@ +// Ported from musl, which is licensed under the MIT license: +// https://git.musl-libc.org/cgit/musl/tree/COPYRIGHT +// +// https://git.musl-libc.org/cgit/musl/tree/src/complex/csqrtf.c +// https://git.musl-libc.org/cgit/musl/tree/src/complex/csqrt.c + const std = @import("../../std.zig"); const testing = std.testing; const math = std.math; const cmath = math.complex; const Complex = cmath.Complex; +/// Returns the square root of z. The real and imaginary parts of the result have the same sign +/// as the imaginary part of z. pub fn sqrt(z: var) @typeOf(z) { const T = @typeOf(z.re); diff --git a/std/math/complex/tan.zig b/std/math/complex/tan.zig index 45e2873eb..398b8295c 100644 --- a/std/math/complex/tan.zig +++ b/std/math/complex/tan.zig @@ -4,6 +4,7 @@ const math = std.math; const cmath = math.complex; const Complex = cmath.Complex; +/// Returns the tanget of z. pub fn tan(z: var) Complex(@typeOf(z.re)) { const T = @typeOf(z.re); const q = Complex(T).new(-z.im, z.re); diff --git a/std/math/complex/tanh.zig b/std/math/complex/tanh.zig index de905ee3f..5c14ec66f 100644 --- a/std/math/complex/tanh.zig +++ b/std/math/complex/tanh.zig @@ -1,9 +1,16 @@ +// Ported from musl, which is licensed under the MIT license: +// https://git.musl-libc.org/cgit/musl/tree/COPYRIGHT +// +// https://git.musl-libc.org/cgit/musl/tree/src/complex/ctanhf.c +// https://git.musl-libc.org/cgit/musl/tree/src/complex/ctanh.c + const std = @import("../../std.zig"); const testing = std.testing; const math = std.math; const cmath = math.complex; const Complex = cmath.Complex; +/// Returns the hyperbolic tangent of z. pub fn tanh(z: var) @typeOf(z) { const T = @typeOf(z.re); return switch (T) { diff --git a/std/math/copysign.zig b/std/math/copysign.zig index ff8140b3a..e4d90c395 100644 --- a/std/math/copysign.zig +++ b/std/math/copysign.zig @@ -1,8 +1,15 @@ +// Ported from musl, which is licensed under the MIT license: +// https://git.musl-libc.org/cgit/musl/tree/COPYRIGHT +// +// https://git.musl-libc.org/cgit/musl/tree/src/math/copysignf.c +// https://git.musl-libc.org/cgit/musl/tree/src/math/copysign.c + const std = @import("../std.zig"); const math = std.math; const expect = std.testing.expect; const maxInt = std.math.maxInt; +/// Returns a value with the magnitude of x and the sign of y. pub fn copysign(comptime T: type, x: T, y: T) T { return switch (T) { f16 => copysign16(x, y), diff --git a/std/math/cosh.zig b/std/math/cosh.zig index eb3082e5f..75c5c15ec 100644 --- a/std/math/cosh.zig +++ b/std/math/cosh.zig @@ -1,8 +1,8 @@ -// Special Cases: +// Ported from musl, which is licensed under the MIT license: +// https://git.musl-libc.org/cgit/musl/tree/COPYRIGHT // -// - cosh(+-0) = 1 -// - cosh(+-inf) = +inf -// - cosh(nan) = nan +// https://git.musl-libc.org/cgit/musl/tree/src/math/coshf.c +// https://git.musl-libc.org/cgit/musl/tree/src/math/cosh.c const builtin = @import("builtin"); const std = @import("../std.zig"); @@ -11,6 +11,12 @@ const expo2 = @import("expo2.zig").expo2; const expect = std.testing.expect; const maxInt = std.math.maxInt; +/// Returns the hyperbolic cosine of x. +/// +/// Special Cases: +/// - cosh(+-0) = 1 +/// - cosh(+-inf) = +inf +/// - cosh(nan) = nan pub fn cosh(x: var) @typeOf(x) { const T = @typeOf(x); return switch (T) { diff --git a/std/math/exp.zig b/std/math/exp.zig index aabccffd0..ad058646a 100644 --- a/std/math/exp.zig +++ b/std/math/exp.zig @@ -1,13 +1,19 @@ -// Special Cases: +// Ported from musl, which is licensed under the MIT license: +// https://git.musl-libc.org/cgit/musl/tree/COPYRIGHT // -// - exp(+inf) = +inf -// - exp(nan) = nan +// https://git.musl-libc.org/cgit/musl/tree/src/math/expf.c +// https://git.musl-libc.org/cgit/musl/tree/src/math/exp.c const std = @import("../std.zig"); const math = std.math; const assert = std.debug.assert; const builtin = @import("builtin"); +/// Returns e raised to the power of x (e^x). +/// +/// Special Cases: +/// - exp(+inf) = +inf +/// - exp(nan) = nan pub fn exp(x: var) @typeOf(x) { const T = @typeOf(x); return switch (T) { diff --git a/std/math/exp2.zig b/std/math/exp2.zig index 392d45bf6..07a39576b 100644 --- a/std/math/exp2.zig +++ b/std/math/exp2.zig @@ -1,12 +1,18 @@ -// Special Cases: +// Ported from musl, which is licensed under the MIT license: +// https://git.musl-libc.org/cgit/musl/tree/COPYRIGHT // -// - exp2(+inf) = +inf -// - exp2(nan) = nan +// https://git.musl-libc.org/cgit/musl/tree/src/math/exp2f.c +// https://git.musl-libc.org/cgit/musl/tree/src/math/exp2.c const std = @import("../std.zig"); const math = std.math; const expect = std.testing.expect; +/// Returns 2 raised to the power of x (2^x). +/// +/// Special Cases: +/// - exp2(+inf) = +inf +/// - exp2(nan) = nan pub fn exp2(x: var) @typeOf(x) { const T = @typeOf(x); return switch (T) { diff --git a/std/math/expm1.zig b/std/math/expm1.zig index b83cc3e82..5e347f86f 100644 --- a/std/math/expm1.zig +++ b/std/math/expm1.zig @@ -1,14 +1,23 @@ -// Special Cases: +// Ported from musl, which is licensed under the MIT license: +// https://git.musl-libc.org/cgit/musl/tree/COPYRIGHT // -// - expm1(+inf) = +inf -// - expm1(-inf) = -1 -// - expm1(nan) = nan +// https://git.musl-libc.org/cgit/musl/tree/src/math/expmf.c +// https://git.musl-libc.org/cgit/musl/tree/src/math/expm.c + +// TODO: Updated recently. const builtin = @import("builtin"); const std = @import("../std.zig"); const math = std.math; const expect = std.testing.expect; +/// Returns e raised to the power of x, minus 1 (e^x - 1). This is more accurate than exp(e, x) - 1 +/// when x is near 0. +/// +/// Special Cases: +/// - expm1(+inf) = +inf +/// - expm1(-inf) = -1 +/// - expm1(nan) = nan pub fn expm1(x: var) @typeOf(x) { const T = @typeOf(x); return switch (T) { diff --git a/std/math/expo2.zig b/std/math/expo2.zig index 57e2bf34c..c00098a5a 100644 --- a/std/math/expo2.zig +++ b/std/math/expo2.zig @@ -1,5 +1,12 @@ +// Ported from musl, which is licensed under the MIT license: +// https://git.musl-libc.org/cgit/musl/tree/COPYRIGHT +// +// https://git.musl-libc.org/cgit/musl/tree/src/math/__expo2f.c +// https://git.musl-libc.org/cgit/musl/tree/src/math/__expo2.c + const math = @import("../math.zig"); +/// Returns exp(x) / 2 for x >= log(maxFloat(T)). pub fn expo2(x: var) @typeOf(x) { const T = @typeOf(x); return switch (T) { diff --git a/std/math/fabs.zig b/std/math/fabs.zig index e30f788ae..6469f3883 100644 --- a/std/math/fabs.zig +++ b/std/math/fabs.zig @@ -1,13 +1,19 @@ -// Special Cases: +// Ported from musl, which is licensed under the MIT license: +// https://git.musl-libc.org/cgit/musl/tree/COPYRIGHT // -// - fabs(+-inf) = +inf -// - fabs(nan) = nan +// https://git.musl-libc.org/cgit/musl/tree/src/math/fabsf.c +// https://git.musl-libc.org/cgit/musl/tree/src/math/fabs.c const std = @import("../std.zig"); const math = std.math; const expect = std.testing.expect; const maxInt = std.math.maxInt; +/// Returns the absolute value of x. +/// +/// Special Cases: +/// - fabs(+-inf) = +inf +/// - fabs(nan) = nan pub fn fabs(x: var) @typeOf(x) { const T = @typeOf(x); return switch (T) { diff --git a/std/math/floor.zig b/std/math/floor.zig index ab45a8fee..e5ff2b1fc 100644 --- a/std/math/floor.zig +++ b/std/math/floor.zig @@ -1,14 +1,20 @@ -// Special Cases: +// Ported from musl, which is licensed under the MIT license: +// https://git.musl-libc.org/cgit/musl/tree/COPYRIGHT // -// - floor(+-0) = +-0 -// - floor(+-inf) = +-inf -// - floor(nan) = nan +// https://git.musl-libc.org/cgit/musl/tree/src/math/floorf.c +// https://git.musl-libc.org/cgit/musl/tree/src/math/floor.c const builtin = @import("builtin"); const expect = std.testing.expect; const std = @import("../std.zig"); const math = std.math; +/// Returns the greatest integer value less than or equal to x. +/// +/// Special Cases: +/// - floor(+-0) = +-0 +/// - floor(+-inf) = +-inf +/// - floor(nan) = nan pub fn floor(x: var) @typeOf(x) { const T = @typeOf(x); return switch (T) { diff --git a/std/math/frexp.zig b/std/math/frexp.zig index 35eec315d..2759cd649 100644 --- a/std/math/frexp.zig +++ b/std/math/frexp.zig @@ -1,8 +1,8 @@ -// Special Cases: +// Ported from musl, which is licensed under the MIT license: +// https://git.musl-libc.org/cgit/musl/tree/COPYRIGHT // -// - frexp(+-0) = +-0, 0 -// - frexp(+-inf) = +-inf, 0 -// - frexp(nan) = nan, undefined +// https://git.musl-libc.org/cgit/musl/tree/src/math/frexpf.c +// https://git.musl-libc.org/cgit/musl/tree/src/math/frexp.c const std = @import("../std.zig"); const math = std.math; @@ -17,6 +17,13 @@ fn frexp_result(comptime T: type) type { pub const frexp32_result = frexp_result(f32); pub const frexp64_result = frexp_result(f64); +/// Breaks x into a normalized fraction and an integral power of two. +/// f == frac * 2^exp, with |frac| in the interval [0.5, 1). +/// +/// Special Cases: +/// - frexp(+-0) = +-0, 0 +/// - frexp(+-inf) = +-inf, 0 +/// - frexp(nan) = nan, undefined pub fn frexp(x: var) frexp_result(@typeOf(x)) { const T = @typeOf(x); return switch (T) { diff --git a/std/math/hypot.zig b/std/math/hypot.zig index fddbe7c06..c15da1495 100644 --- a/std/math/hypot.zig +++ b/std/math/hypot.zig @@ -1,15 +1,21 @@ -// Special Cases: +// Ported from musl, which is licensed under the MIT license: +// https://git.musl-libc.org/cgit/musl/tree/COPYRIGHT // -// - hypot(+-inf, y) = +inf -// - hypot(x, +-inf) = +inf -// - hypot(nan, y) = nan -// - hypot(x, nan) = nan +// https://git.musl-libc.org/cgit/musl/tree/src/math/hypotf.c +// https://git.musl-libc.org/cgit/musl/tree/src/math/hypot.c const std = @import("../std.zig"); const math = std.math; const expect = std.testing.expect; const maxInt = std.math.maxInt; +/// Returns sqrt(x * x + y * y), avoiding unncessary overflow and underflow. +/// +/// Special Cases: +/// - hypot(+-inf, y) = +inf +/// - hypot(x, +-inf) = +inf +/// - hypot(nan, y) = nan +/// - hypot(x, nan) = nan pub fn hypot(comptime T: type, x: T, y: T) T { return switch (T) { f32 => hypot32(x, y), diff --git a/std/math/ilogb.zig b/std/math/ilogb.zig index 2dfd42a62..fe4158a6d 100644 --- a/std/math/ilogb.zig +++ b/std/math/ilogb.zig @@ -1,8 +1,8 @@ -// Special Cases: +// Ported from musl, which is licensed under the MIT license: +// https://git.musl-libc.org/cgit/musl/tree/COPYRIGHT // -// - ilogb(+-inf) = maxInt(i32) -// - ilogb(0) = maxInt(i32) -// - ilogb(nan) = maxInt(i32) +// https://git.musl-libc.org/cgit/musl/tree/src/math/ilogbf.c +// https://git.musl-libc.org/cgit/musl/tree/src/math/ilogb.c const std = @import("../std.zig"); const math = std.math; @@ -10,6 +10,12 @@ const expect = std.testing.expect; const maxInt = std.math.maxInt; const minInt = std.math.minInt; +/// Returns the binary exponent of x as an integer. +/// +/// Special Cases: +/// - ilogb(+-inf) = maxInt(i32) +/// - ilogb(0) = maxInt(i32) +/// - ilogb(nan) = maxInt(i32) pub fn ilogb(x: var) i32 { const T = @typeOf(x); return switch (T) { diff --git a/std/math/inf.zig b/std/math/inf.zig index e1bfbb197..86ff24553 100644 --- a/std/math/inf.zig +++ b/std/math/inf.zig @@ -1,6 +1,7 @@ const std = @import("../std.zig"); const math = std.math; +/// Returns value inf for the type T. pub fn inf(comptime T: type) T { return switch (T) { f16 => math.inf_f16, diff --git a/std/math/isfinite.zig b/std/math/isfinite.zig index ee8a5ff59..99eba668f 100644 --- a/std/math/isfinite.zig +++ b/std/math/isfinite.zig @@ -3,6 +3,7 @@ const math = std.math; const expect = std.testing.expect; const maxInt = std.math.maxInt; +/// Returns whether x is a finite value. pub fn isFinite(x: var) bool { const T = @typeOf(x); switch (T) { diff --git a/std/math/isinf.zig b/std/math/isinf.zig index 1b1759bd3..37934f4cf 100644 --- a/std/math/isinf.zig +++ b/std/math/isinf.zig @@ -3,6 +3,7 @@ const math = std.math; const expect = std.testing.expect; const maxInt = std.math.maxInt; +/// Returns whether x is an infinity, ignoring sign. pub fn isInf(x: var) bool { const T = @typeOf(x); switch (T) { @@ -28,6 +29,7 @@ pub fn isInf(x: var) bool { } } +/// Returns whether x is an infinity with a positive sign. pub fn isPositiveInf(x: var) bool { const T = @typeOf(x); switch (T) { @@ -49,6 +51,7 @@ pub fn isPositiveInf(x: var) bool { } } +/// Returns whether x is an infinity with a negative sign. pub fn isNegativeInf(x: var) bool { const T = @typeOf(x); switch (T) { diff --git a/std/math/isnan.zig b/std/math/isnan.zig index 9e541bf0a..cf8cd2e1c 100644 --- a/std/math/isnan.zig +++ b/std/math/isnan.zig @@ -3,13 +3,15 @@ const math = std.math; const expect = std.testing.expect; const maxInt = std.math.maxInt; +/// Returns whether x is a nan. pub fn isNan(x: var) bool { return x != x; } -/// Note: A signalling nan is identical to a standard nan right now but may have a different bit -/// representation in the future when required. +/// Returns whether x is a signalling nan. pub fn isSignalNan(x: var) bool { + // Note: A signalling nan is identical to a standard nan right now but may have a different bit + // representation in the future when required. return isNan(x); } diff --git a/std/math/isnormal.zig b/std/math/isnormal.zig index cddcada1d..f8611ef80 100644 --- a/std/math/isnormal.zig +++ b/std/math/isnormal.zig @@ -3,6 +3,7 @@ const math = std.math; const expect = std.testing.expect; const maxInt = std.math.maxInt; +// Returns whether x has a normalized representation (i.e. integer part of mantissa is 1). pub fn isNormal(x: var) bool { const T = @typeOf(x); switch (T) { diff --git a/std/math/ln.zig b/std/math/ln.zig index 82b212f00..c5d4c9ff2 100644 --- a/std/math/ln.zig +++ b/std/math/ln.zig @@ -1,9 +1,8 @@ -// Special Cases: +// Ported from musl, which is licensed under the MIT license: +// https://git.musl-libc.org/cgit/musl/tree/COPYRIGHT // -// - ln(+inf) = +inf -// - ln(0) = -inf -// - ln(x) = nan if x < 0 -// - ln(nan) = nan +// https://git.musl-libc.org/cgit/musl/tree/src/math/lnf.c +// https://git.musl-libc.org/cgit/musl/tree/src/math/ln.c const std = @import("../std.zig"); const math = std.math; @@ -11,6 +10,13 @@ const expect = std.testing.expect; const builtin = @import("builtin"); const TypeId = builtin.TypeId; +/// Returns the natural logarithm of x. +/// +/// Special Cases: +/// - ln(+inf) = +inf +/// - ln(0) = -inf +/// - ln(x) = nan if x < 0 +/// - ln(nan) = nan pub fn ln(x: var) @typeOf(x) { const T = @typeOf(x); switch (@typeId(T)) { diff --git a/std/math/log.zig b/std/math/log.zig index 100dc2fb7..77f3639fd 100644 --- a/std/math/log.zig +++ b/std/math/log.zig @@ -1,9 +1,16 @@ +// Ported from musl, which is licensed under the MIT license: +// https://git.musl-libc.org/cgit/musl/tree/COPYRIGHT +// +// https://git.musl-libc.org/cgit/musl/tree/src/math/logf.c +// https://git.musl-libc.org/cgit/musl/tree/src/math/log.c + const std = @import("../std.zig"); const math = std.math; const builtin = @import("builtin"); const TypeId = builtin.TypeId; const expect = std.testing.expect; +/// Returns the logarithm of x for the provided base. pub fn log(comptime T: type, base: T, x: T) T { if (base == 2) { return math.log2(x); diff --git a/std/math/log10.zig b/std/math/log10.zig index 7311778dd..9b0bc3ac5 100644 --- a/std/math/log10.zig +++ b/std/math/log10.zig @@ -1,9 +1,8 @@ -// Special Cases: +// Ported from musl, which is licensed under the MIT license: +// https://git.musl-libc.org/cgit/musl/tree/COPYRIGHT // -// - log10(+inf) = +inf -// - log10(0) = -inf -// - log10(x) = nan if x < 0 -// - log10(nan) = nan +// https://git.musl-libc.org/cgit/musl/tree/src/math/log10f.c +// https://git.musl-libc.org/cgit/musl/tree/src/math/log10.c const std = @import("../std.zig"); const math = std.math; @@ -12,6 +11,13 @@ const builtin = @import("builtin"); const TypeId = builtin.TypeId; const maxInt = std.math.maxInt; +/// Returns the base-10 logarithm of x. +/// +/// Special Cases: +/// - log10(+inf) = +inf +/// - log10(0) = -inf +/// - log10(x) = nan if x < 0 +/// - log10(nan) = nan pub fn log10(x: var) @typeOf(x) { const T = @typeOf(x); switch (@typeId(T)) { diff --git a/std/math/log1p.zig b/std/math/log1p.zig index c9be1132b..bae6deb53 100644 --- a/std/math/log1p.zig +++ b/std/math/log1p.zig @@ -1,16 +1,22 @@ -// Special Cases: +// Ported from musl, which is licensed under the MIT license: +// https://git.musl-libc.org/cgit/musl/tree/COPYRIGHT // -// - log1p(+inf) = +inf -// - log1p(+-0) = +-0 -// - log1p(-1) = -inf -// - log1p(x) = nan if x < -1 -// - log1p(nan) = nan +// https://git.musl-libc.org/cgit/musl/tree/src/math/log1pf.c +// https://git.musl-libc.org/cgit/musl/tree/src/math/log1p.c const builtin = @import("builtin"); const std = @import("../std.zig"); const math = std.math; const expect = std.testing.expect; +/// Returns the natural logarithm of 1 + x with greater accuracy when x is near zero. +/// +/// Special Cases: +/// - log1p(+inf) = +inf +/// - log1p(+-0) = +-0 +/// - log1p(-1) = -inf +/// - log1p(x) = nan if x < -1 +/// - log1p(nan) = nan pub fn log1p(x: var) @typeOf(x) { const T = @typeOf(x); return switch (T) { diff --git a/std/math/log2.zig b/std/math/log2.zig index e2dbf4105..88450a7ff 100644 --- a/std/math/log2.zig +++ b/std/math/log2.zig @@ -1,9 +1,8 @@ -// Special Cases: +// Ported from musl, which is licensed under the MIT license: +// https://git.musl-libc.org/cgit/musl/tree/COPYRIGHT // -// - log2(+inf) = +inf -// - log2(0) = -inf -// - log2(x) = nan if x < 0 -// - log2(nan) = nan +// https://git.musl-libc.org/cgit/musl/tree/src/math/log2f.c +// https://git.musl-libc.org/cgit/musl/tree/src/math/log2.c const std = @import("../std.zig"); const math = std.math; @@ -12,6 +11,13 @@ const builtin = @import("builtin"); const TypeId = builtin.TypeId; const maxInt = std.math.maxInt; +/// Returns the base-2 logarithm of x. +/// +/// Special Cases: +/// - log2(+inf) = +inf +/// - log2(0) = -inf +/// - log2(x) = nan if x < 0 +/// - log2(nan) = nan pub fn log2(x: var) @typeOf(x) { const T = @typeOf(x); switch (@typeId(T)) { diff --git a/std/math/modf.zig b/std/math/modf.zig index e5a4964e6..92194d4c7 100644 --- a/std/math/modf.zig +++ b/std/math/modf.zig @@ -1,7 +1,8 @@ -// Special Cases: +// Ported from musl, which is licensed under the MIT license: +// https://git.musl-libc.org/cgit/musl/tree/COPYRIGHT // -// - modf(+-inf) = +-inf, nan -// - modf(nan) = nan, nan +// https://git.musl-libc.org/cgit/musl/tree/src/math/modff.c +// https://git.musl-libc.org/cgit/musl/tree/src/math/modf.c const std = @import("../std.zig"); const math = std.math; @@ -17,6 +18,12 @@ fn modf_result(comptime T: type) type { pub const modf32_result = modf_result(f32); pub const modf64_result = modf_result(f64); +/// Returns the integer and fractional floating-point numbers that sum to x. The sign of each +/// result is the same as the sign of x. +/// +/// Special Cases: +/// - modf(+-inf) = +-inf, nan +/// - modf(nan) = nan, nan pub fn modf(x: var) modf_result(@typeOf(x)) { const T = @typeOf(x); return switch (T) { diff --git a/std/math/nan.zig b/std/math/nan.zig index 1a11a141d..5a01a5b3b 100644 --- a/std/math/nan.zig +++ b/std/math/nan.zig @@ -1,5 +1,6 @@ const math = @import("../math.zig"); +/// Returns the nan representation for type T. pub fn nan(comptime T: type) T { return switch (T) { f16 => math.nan_f16, @@ -10,9 +11,10 @@ pub fn nan(comptime T: type) T { }; } -// Note: A signalling nan is identical to a standard right now by may have a different bit -// representation in the future when required. +/// Returns the signalling nan representation for type T. pub fn snan(comptime T: type) T { + // Note: A signalling nan is identical to a standard right now by may have a different bit + // representation in the future when required. return switch (T) { f16 => @bitCast(f16, math.nan_u16), f32 => @bitCast(f32, math.nan_u32), diff --git a/std/math/powi.zig b/std/math/powi.zig index b7212efcb..d80700e5c 100644 --- a/std/math/powi.zig +++ b/std/math/powi.zig @@ -1,12 +1,7 @@ -// Special Cases: +// Based on Rust, which is licensed under the MIT license. +// https://github.com/rust-lang/rust/blob/360432f1e8794de58cd94f34c9c17ad65871e5b5/LICENSE-MIT // -// powi(x, +-0) = 1 for any x -// powi(0, y) = 0 for any y -// powi(1, y) = 1 for any y -// powi(-1, y) = -1 for for y an odd integer -// powi(-1, y) = 1 for for y an even integer -// powi(x, y) = Overflow for for y >= @sizeOf(x) - 1 y > 0 -// powi(x, y) = Underflow for for y > @sizeOf(x) - 1 y < 0 +// https://github.com/rust-lang/rust/blob/360432f1e8794de58cd94f34c9c17ad65871e5b5/src/libcore/num/mod.rs#L3423 const builtin = @import("builtin"); const std = @import("../std.zig"); @@ -14,7 +9,16 @@ const math = std.math; const assert = std.debug.assert; const testing = std.testing; -// This implementation is based on that from the rust stlib +/// Returns the power of x raised by the integer y (x^y). +/// +/// Special Cases: +/// - powi(x, +-0) = 1 for any x +/// - powi(0, y) = 0 for any y +/// - powi(1, y) = 1 for any y +/// - powi(-1, y) = -1 for y an odd integer +/// - powi(-1, y) = 1 for y an even integer +/// - powi(x, y) = Overflow for y >= @sizeOf(x) - 1 or y > 0 +/// - powi(x, y) = Underflow for y > @sizeOf(x) - 1 or y < 0 pub fn powi(comptime T: type, x: T, y: T) (error{ Overflow, Underflow, diff --git a/std/math/round.zig b/std/math/round.zig index 39ff56ca7..0b80a46ce 100644 --- a/std/math/round.zig +++ b/std/math/round.zig @@ -1,14 +1,20 @@ -// Special Cases: +// Ported from musl, which is licensed under the MIT license: +// https://git.musl-libc.org/cgit/musl/tree/COPYRIGHT // -// - round(+-0) = +-0 -// - round(+-inf) = +-inf -// - round(nan) = nan +// https://git.musl-libc.org/cgit/musl/tree/src/math/roundf.c +// https://git.musl-libc.org/cgit/musl/tree/src/math/round.c const builtin = @import("builtin"); const expect = std.testing.expect; const std = @import("../std.zig"); const math = std.math; +/// Returns x rounded to the nearest integer, rounding half away from zero. +/// +/// Special Cases: +/// - round(+-0) = +-0 +/// - round(+-inf) = +-inf +/// - round(nan) = nan pub fn round(x: var) @typeOf(x) { const T = @typeOf(x); return switch (T) { diff --git a/std/math/scalbn.zig b/std/math/scalbn.zig index d1338f5ac..d5716d621 100644 --- a/std/math/scalbn.zig +++ b/std/math/scalbn.zig @@ -1,7 +1,14 @@ +// Ported from musl, which is licensed under the MIT license: +// https://git.musl-libc.org/cgit/musl/tree/COPYRIGHT +// +// https://git.musl-libc.org/cgit/musl/tree/src/math/scalbnf.c +// https://git.musl-libc.org/cgit/musl/tree/src/math/scalbn.c + const std = @import("../std.zig"); const math = std.math; const expect = std.testing.expect; +/// Returns x * 2^n. pub fn scalbn(x: var, n: i32) @typeOf(x) { const T = @typeOf(x); return switch (T) { diff --git a/std/math/signbit.zig b/std/math/signbit.zig index 9727152b0..e5c590929 100644 --- a/std/math/signbit.zig +++ b/std/math/signbit.zig @@ -2,6 +2,7 @@ const std = @import("../std.zig"); const math = std.math; const expect = std.testing.expect; +/// Returns whether x is negative or negative 0. pub fn signbit(x: var) bool { const T = @typeOf(x); return switch (T) { diff --git a/std/math/sinh.zig b/std/math/sinh.zig index cf4363c4a..73ee65ea6 100644 --- a/std/math/sinh.zig +++ b/std/math/sinh.zig @@ -1,8 +1,8 @@ -// Special Cases: +// Ported from musl, which is licensed under the MIT license: +// https://git.musl-libc.org/cgit/musl/tree/COPYRIGHT // -// - sinh(+-0) = +-0 -// - sinh(+-inf) = +-inf -// - sinh(nan) = nan +// https://git.musl-libc.org/cgit/musl/tree/src/math/sinhf.c +// https://git.musl-libc.org/cgit/musl/tree/src/math/sinh.c const builtin = @import("builtin"); const std = @import("../std.zig"); @@ -11,6 +11,12 @@ const expect = std.testing.expect; const expo2 = @import("expo2.zig").expo2; const maxInt = std.math.maxInt; +/// Returns the hyperbolic sine of x. +/// +/// Special Cases: +/// - sinh(+-0) = +-0 +/// - sinh(+-inf) = +-inf +/// - sinh(nan) = nan pub fn sinh(x: var) @typeOf(x) { const T = @typeOf(x); return switch (T) { diff --git a/std/math/sqrt.zig b/std/math/sqrt.zig index 9062f598a..30af5915d 100644 --- a/std/math/sqrt.zig +++ b/std/math/sqrt.zig @@ -1,10 +1,3 @@ -// Special Cases: -// -// - sqrt(+inf) = +inf -// - sqrt(+-0) = +-0 -// - sqrt(x) = nan if x < 0 -// - sqrt(nan) = nan - const std = @import("../std.zig"); const math = std.math; const expect = std.testing.expect; @@ -12,6 +5,13 @@ const builtin = @import("builtin"); const TypeId = builtin.TypeId; const maxInt = std.math.maxInt; +/// Returns the square root of x. +/// +/// Special Cases: +/// - sqrt(+inf) = +inf +/// - sqrt(+-0) = +-0 +/// - sqrt(x) = nan if x < 0 +/// - sqrt(nan) = nan pub fn sqrt(x: var) (if (@typeId(@typeOf(x)) == TypeId.Int) @IntType(false, @typeOf(x).bit_count / 2) else @typeOf(x)) { const T = @typeOf(x); switch (@typeId(T)) { diff --git a/std/math/tanh.zig b/std/math/tanh.zig index f88ecfdc9..48d26d091 100644 --- a/std/math/tanh.zig +++ b/std/math/tanh.zig @@ -1,8 +1,8 @@ -// Special Cases: +// Ported from musl, which is licensed under the MIT license: +// https://git.musl-libc.org/cgit/musl/tree/COPYRIGHT // -// - sinh(+-0) = +-0 -// - sinh(+-inf) = +-1 -// - sinh(nan) = nan +// https://git.musl-libc.org/cgit/musl/tree/src/math/tanhf.c +// https://git.musl-libc.org/cgit/musl/tree/src/math/tanh.c const builtin = @import("builtin"); const std = @import("../std.zig"); @@ -11,6 +11,12 @@ const expect = std.testing.expect; const expo2 = @import("expo2.zig").expo2; const maxInt = std.math.maxInt; +/// Returns the hyperbolic tangent of x. +/// +/// Special Cases: +/// - sinh(+-0) = +-0 +/// - sinh(+-inf) = +-1 +/// - sinh(nan) = nan pub fn tanh(x: var) @typeOf(x) { const T = @typeOf(x); return switch (T) { diff --git a/std/math/trunc.zig b/std/math/trunc.zig index 9449d0e7e..219bcd491 100644 --- a/std/math/trunc.zig +++ b/std/math/trunc.zig @@ -1,14 +1,20 @@ -// Special Cases: +// Ported from musl, which is licensed under the MIT license: +// https://git.musl-libc.org/cgit/musl/tree/COPYRIGHT // -// - trunc(+-0) = +-0 -// - trunc(+-inf) = +-inf -// - trunc(nan) = nan +// https://git.musl-libc.org/cgit/musl/tree/src/math/truncf.c +// https://git.musl-libc.org/cgit/musl/tree/src/math/trunc.c const std = @import("../std.zig"); const math = std.math; const expect = std.testing.expect; const maxInt = std.math.maxInt; +/// Returns the integer value of x. +/// +/// Special Cases: +/// - trunc(+-0) = +-0 +/// - trunc(+-inf) = +-inf +/// - trunc(nan) = nan pub fn trunc(x: var) @typeOf(x) { const T = @typeOf(x); return switch (T) { From 3370e60dd96828db6f9d1da36e71064303e97de6 Mon Sep 17 00:00:00 2001 From: Marc Tiehuis Date: Thu, 2 May 2019 19:03:49 +1200 Subject: [PATCH 3/3] std.math: Correct math.nan usage in cos --- std/math/cos.zig | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/std/math/cos.zig b/std/math/cos.zig index 6d0cc80c3..dc4aff59d 100644 --- a/std/math/cos.zig +++ b/std/math/cos.zig @@ -48,7 +48,7 @@ fn cos_(comptime T: type, x_: T) T { var x = x_; if (math.isNan(x) or math.isInf(x)) { - return math.nan(f32); + return math.nan(T); } var sign = false;