builtinstdfloatassertmemtestingAlignmentepiphitaulog2elog10eln2ln10two_sqrtpisqrt2sqrt1_2rad_per_degdeg_per_radSignFloatReprfloatExponentBitsfloatMantissaBitsfloatFractionalBitsfloatExponentMinfloatExponentMaxfloatTrueMinfloatMinfloatMaxfloatEpsfloatEpsAtinflong_doublenansnanapproxEqAbsapproxEqRelraiseInvalidraiseUnderflowraiseOverflowraiseInexactraiseDivByZeroisNanisSignalNanfrexpFrexpmodfModfcopysignisFiniteisInfisPositiveInfisNegativeInfisPositiveZeroisNegativeZeroisNormalnextAftersignbitscalbnldexppowpowisqrtcbrtacosasinatanatan2hypotexpm1ilogbloglog2log10log10_intlog_intlog1pasinhacoshatanhsinhcoshtanhgcdlcmgammalgammasincostanradiansToDegreesdegreesToRadiansexpexp2complexComplexbigMinwrapclampmuladdsubnegateshlExactshlshrrotrrotlLog2IntLog2IntCeilIntFittingRangetestOverflowdivTrunctestDivTruncdivFloortestDivFloordivCeiltestDivCeildivExacttestDivExactmodtestModremtestRemnegateCastcastAlignCastErrorAlignCastResultalignCastisPowerOfTwoByteAlignedIntroundtruncfloorfloorPowerOfTwotestFloorPowerOfTwoceilceilPowerOfTwoPromoteceilPowerOfTwoceilPowerOfTwoAsserttestCeilPowerOfTwoPromotetestCeilPowerOfTwolog2_intlog2_int_ceillossyCastlerpmaxIntminIntmulWideOrderorderCompareOperatorcompareboolMaskrunTestcomptimeModF80SignOfsigntestSignsignExtend
std.math.acos
alias
Alias of std.math.acos.acos
std.math.acosh
alias
Alias of std.math.acosh.acosh
std.math.add
function
Returns the sum of a and b. Returns an error on overflow.
pub fn add(comptime T: type, a: T, b: T) (error{Overflow}!T)
Parameters
T: type
a: T
b: T
std.math.alignCast
function
Align cast a pointer but return an error if it's the wrong alignment
pub fn alignCast(comptime alignment: Alignment, ptr: anytype) AlignCastError!AlignCastResult(alignment, @TypeOf(ptr))
Parameters
alignment: Alignment
Errors
- UnalignedMemory
std.math.AlignCastError
error-set
Errors
- UnalignedMemory
std.math.AlignCastResult
type-function
fn AlignCastResult(comptime alignment: Alignment, comptime Ptr: type) type
Parameters
alignment: Alignment
Ptr: type
std.math.Alignment
alias
Alias of std.mem.Alignment
std.math.approxEqAbs
function
Performs an approximate comparison of two floating point values x and y.
Returns true if the absolute difference between them is less or equal than
the specified tolerance.
The tolerance parameter is the absolute tolerance used when determining if
the two numbers are close enough; a good value for this parameter is a small
multiple of floatEps(T).
Note that this function is recommended for comparing small numbers
around zero; using approxEqRel is suggested otherwise.
NaN values are never considered equal to any value.
pub fn approxEqAbs(comptime T: type, x: T, y: T, tolerance: T) bool
Parameters
T: type
x: T
y: T
tolerance: T
Example usage
test approxEqAbs {
inline for ([_]type{ f16, f32, f64, f128 }) |T| {
const eps_value = comptime floatEps(T);
const min_value = comptime floatMin(T);
try testing.expect(approxEqAbs(T, 0.0, 0.0, eps_value));
try testing.expect(approxEqAbs(T, -0.0, -0.0, eps_value));
try testing.expect(approxEqAbs(T, 0.0, -0.0, eps_value));
try testing.expect(!approxEqAbs(T, 1.0 + 2 * eps_value, 1.0, eps_value));
try testing.expect(approxEqAbs(T, 1.0 + 1 * eps_value, 1.0, eps_value));
try testing.expect(approxEqAbs(T, min_value, 0.0, eps_value * 2));
try testing.expect(approxEqAbs(T, -min_value, 0.0, eps_value * 2));
}
comptime {
// `comptime_float` is guaranteed to have the same precision and operations of
// the largest other floating point type, which is f128 but it doesn't have a
// defined layout so we can't rely on `@bitCast` to construct the smallest
// possible epsilon value like we do in the tests above. In the same vein, we
// also can't represent a max/min, `NaN` or `Inf` values.
const eps_value = 1e-4;
try testing.expect(approxEqAbs(comptime_float, 0.0, 0.0, eps_value));
try testing.expect(approxEqAbs(comptime_float, -0.0, -0.0, eps_value));
try testing.expect(approxEqAbs(comptime_float, 0.0, -0.0, eps_value));
try testing.expect(!approxEqAbs(comptime_float, 1.0 + 2 * eps_value, 1.0, eps_value));
try testing.expect(approxEqAbs(comptime_float, 1.0 + 1 * eps_value, 1.0, eps_value));
}
}
std.math.approxEqRel
function
Performs an approximate comparison of two floating point values x and y.
Returns true if the absolute difference between them is less or equal than
max(|x|, |y|) * tolerance, where tolerance is a positive number greater
than zero.
The tolerance parameter is the relative tolerance used when determining if
the two numbers are close enough; a good value for this parameter is usually
sqrt(floatEps(T)), meaning that the two numbers are considered equal if at
least half of the digits are equal.
Note that for comparisons of small numbers around zero this function won't
give meaningful results, use approxEqAbs instead.
NaN values are never considered equal to any value.
pub fn approxEqRel(comptime T: type, x: T, y: T, tolerance: T) bool
Parameters
T: type
x: T
y: T
tolerance: T
Example usage
test approxEqRel {
inline for ([_]type{ f16, f32, f64, f128 }) |T| {
const eps_value = comptime floatEps(T);
const sqrt_eps_value = comptime sqrt(eps_value);
const nan_value = comptime nan(T);
const inf_value = comptime inf(T);
const min_value = comptime floatMin(T);
try testing.expect(approxEqRel(T, 1.0, 1.0, sqrt_eps_value));
try testing.expect(!approxEqRel(T, 1.0, 0.0, sqrt_eps_value));
try testing.expect(!approxEqRel(T, 1.0, nan_value, sqrt_eps_value));
try testing.expect(!approxEqRel(T, nan_value, nan_value, sqrt_eps_value));
try testing.expect(approxEqRel(T, inf_value, inf_value, sqrt_eps_value));
try testing.expect(approxEqRel(T, min_value, min_value, sqrt_eps_value));
try testing.expect(approxEqRel(T, -min_value, -min_value, sqrt_eps_value));
}
comptime {
// `comptime_float` is guaranteed to have the same precision and operations of
// the largest other floating point type, which is f128 but it doesn't have a
// defined layout so we can't rely on `@bitCast` to construct the smallest
// possible epsilon value like we do in the tests above. In the same vein, we
// also can't represent a max/min, `NaN` or `Inf` values.
const eps_value = 1e-4;
const sqrt_eps_value = sqrt(eps_value);
try testing.expect(approxEqRel(comptime_float, 1.0, 1.0, sqrt_eps_value));
try testing.expect(!approxEqRel(comptime_float, 1.0, 0.0, sqrt_eps_value));
}
}
std.math.asin
alias
Alias of std.math.asin.asin
std.math.asinh
alias
Alias of std.math.asinh.asinh
std.math.assert
alias
Alias of std.debug.assert
std.math.atan
alias
Alias of std.math.atan.atan
std.math.atan2
alias
Alias of std.math.atan2.atan2
std.math.atanh
alias
Alias of std.math.atanh.atanh
std.math.big
alias
Alias of std.math.big
std.math.boolMask
function
Returns a mask of all ones if value is true, and a mask of all zeroes if value is false. Compiles to one instruction for register sized integers.
pub inline fn boolMask(comptime MaskInt: type, value: bool) MaskInt
Parameters
MaskInt: type
value: bool
Example usage
test boolMask {
const runTest = struct {
fn runTest() !void {
try testing.expectEqual(@as(u1, 0), boolMask(u1, false));
try testing.expectEqual(@as(u1, 1), boolMask(u1, true));
try testing.expectEqual(@as(i1, 0), boolMask(i1, false));
try testing.expectEqual(@as(i1, -1), boolMask(i1, true));
try testing.expectEqual(@as(u13, 0), boolMask(u13, false));
try testing.expectEqual(@as(u13, 0x1FFF), boolMask(u13, true));
try testing.expectEqual(@as(i13, 0), boolMask(i13, false));
try testing.expectEqual(@as(i13, -1), boolMask(i13, true));
try testing.expectEqual(@as(u32, 0), boolMask(u32, false));
try testing.expectEqual(@as(u32, 0xFFFF_FFFF), boolMask(u32, true));
try testing.expectEqual(@as(i32, 0), boolMask(i32, false));
try testing.expectEqual(@as(i32, -1), boolMask(i32, true));
}
}.runTest;
try runTest();
try comptime runTest();
}
std.math.builtin
constant
std.math.ByteAlignedInt
type-function
Aligns the given integer type bit width to a width divisible by 8.
pub fn ByteAlignedInt(comptime T: type) type
Parameters
T: type
Example usage
test ByteAlignedInt {
try testing.expect(ByteAlignedInt(u0) == u0);
try testing.expect(ByteAlignedInt(u3) == u8);
try testing.expect(ByteAlignedInt(u8) == u8);
try testing.expect(ByteAlignedInt(i111) == i112);
try testing.expect(ByteAlignedInt(u129) == u136);
}
std.math.cast
function
Cast an integer to a different integer type. If the value doesn't fit, return null.
pub fn cast(comptime T: type, x: anytype) ?T
Parameters
T: type
Example usage
test cast {
try testing.expect(cast(u8, 300) == null);
try testing.expect(cast(u8, @as(u32, 300)) == null);
try testing.expect(cast(i8, -200) == null);
try testing.expect(cast(i8, @as(i32, -200)) == null);
try testing.expect(cast(u8, -1) == null);
try testing.expect(cast(u8, @as(i8, -1)) == null);
try testing.expect(cast(u64, -1) == null);
try testing.expect(cast(u64, @as(i8, -1)) == null);
try testing.expect(cast(u8, 255).? == @as(u8, 255));
try testing.expect(cast(u8, @as(u32, 255)).? == @as(u8, 255));
try testing.expect(@TypeOf(cast(u8, 255).?) == u8);
try testing.expect(@TypeOf(cast(u8, @as(u32, 255)).?) == u8);
}
std.math.cbrt
alias
Alias of std.math.cbrt.cbrt
std.math.ceil
function
Returns the smallest integral value not less than the given floating point number. Uses a dedicated hardware instruction when available. This is the same as calling the builtin @ceil
pub inline fn ceil(value: anytype) @TypeOf(value)
std.math.ceilPowerOfTwo
function
Returns the next power of two (if the value is not already a power of two). Only unsigned integers can be used. Zero is not an allowed input. If the value doesn't fit, returns an error.
pub fn ceilPowerOfTwo(comptime T: type, value: T) (error{Overflow}!T)
Parameters
T: type
value: T
Example usage
test ceilPowerOfTwo {
try testCeilPowerOfTwo();
try comptime testCeilPowerOfTwo();
}
std.math.ceilPowerOfTwoAssert
function
Returns the next power of two (if the value is not already a power of two). Only unsigned integers can be used. Zero is not an allowed input. Asserts that the value fits.
pub fn ceilPowerOfTwoAssert(comptime T: type, value: T) T
Parameters
T: type
value: T
std.math.ceilPowerOfTwoPromote
function
Returns the next power of two (if the value is not already a power of two). Only unsigned integers can be used. Zero is not an allowed input. Result is a type with 1 more bit than the input type.
pub fn ceilPowerOfTwoPromote(comptime T: type, value: T) @Int(@typeInfo(T).int.signedness, @typeInfo(T).int.bits + 1)
Parameters
T: type
value: T
Example usage
test ceilPowerOfTwoPromote {
try testCeilPowerOfTwoPromote();
try comptime testCeilPowerOfTwoPromote();
}
std.math.clamp
function
Odd ramp function
| _____
| /
|/
-------/-------
/|
_____/ |
|
Limit val to the inclusive range [lower, upper].
pub fn clamp(val: anytype, lower: anytype, upper: anytype) @TypeOf(val, lower, upper)
Example usage
test clamp {
// Within range
try testing.expect(std.math.clamp(@as(i32, -1), @as(i32, -4), @as(i32, 7)) == -1);
// Below
try testing.expect(std.math.clamp(@as(i32, -5), @as(i32, -4), @as(i32, 7)) == -4);
// Above
try testing.expect(std.math.clamp(@as(i32, 8), @as(i32, -4), @as(i32, 7)) == 7);
// Floating point
try testing.expect(std.math.clamp(@as(f32, 1.1), @as(f32, 0.0), @as(f32, 1.0)) == 1.0);
try testing.expect(std.math.clamp(@as(f32, -127.5), @as(f32, -200), @as(f32, -100)) == -127.5);
// Vector
try testing.expect(@reduce(.And, std.math.clamp(@as(@Vector(3, f32), .{ 1.4, 15.23, 28.3 }), @as(@Vector(3, f32), .{ 9.8, 13.2, 15.6 }), @as(@Vector(3, f32), .{ 15.2, 22.8, 26.3 })) == @as(@Vector(3, f32), .{ 9.8, 15.23, 26.3 })));
// Mix of comptime and non-comptime
var i: i32 = 1;
_ = &i;
try testing.expect(std.math.clamp(i, 0, 1) == 1);
}
std.math.compare
function
This function does the same thing as comparison operators, however the operator is a runtime-known enum value. Works on any operands that support comparison operators.
pub fn compare(a: anytype, op: CompareOperator, b: anytype) bool
Parameters
op: CompareOperator
Example usage
test compare {
try testing.expect(compare(@as(i8, -1), .lt, @as(u8, 255)));
try testing.expect(compare(@as(i8, 2), .gt, @as(u8, 1)));
try testing.expect(!compare(@as(i8, -1), .gte, @as(u8, 255)));
try testing.expect(compare(@as(u8, 255), .gt, @as(i8, -1)));
try testing.expect(!compare(@as(u8, 255), .lte, @as(i8, -1)));
try testing.expect(compare(@as(i8, -1), .lt, @as(u9, 255)));
try testing.expect(!compare(@as(i8, -1), .gte, @as(u9, 255)));
try testing.expect(compare(@as(u9, 255), .gt, @as(i8, -1)));
try testing.expect(!compare(@as(u9, 255), .lte, @as(i8, -1)));
try testing.expect(compare(@as(i9, -1), .lt, @as(u8, 255)));
try testing.expect(!compare(@as(i9, -1), .gte, @as(u8, 255)));
try testing.expect(compare(@as(u8, 255), .gt, @as(i9, -1)));
try testing.expect(!compare(@as(u8, 255), .lte, @as(i9, -1)));
try testing.expect(compare(@as(u8, 1), .lt, @as(u8, 2)));
try testing.expect(@as(u8, @bitCast(@as(i8, -1))) == @as(u8, 255));
try testing.expect(!compare(@as(u8, 255), .eq, @as(i8, -1)));
try testing.expect(compare(@as(u8, 1), .eq, @as(u8, 1)));
}
std.math.CompareOperator
container
See also Order.
Fields
ltLess than (<)
lteLess than or equal (<=)
eqEqual (==)
gteGreater than or equal (>=)
gtGreater than (>)
neqNot equal (!=)
std.math.CompareOperator.reverse
function
Reverse the direction of the comparison. Use when swapping the left and right hand operands.
pub fn reverse(op: CompareOperator) CompareOperator
Parameters
op: CompareOperator
Example usage
test reverse {
inline for (@typeInfo(CompareOperator).@"enum".field_values) |op_field_value| {
const op = @as(CompareOperator, @fromBackingInt(@intCast(op_field_value)));
try testing.expect(compare(2, op, 3) == compare(3, op.reverse(), 2));
try testing.expect(compare(3, op, 3) == compare(3, op.reverse(), 3));
try testing.expect(compare(4, op, 3) == compare(3, op.reverse(), 4));
}
}
std.math.complex
alias
Alias of std.math.complex
std.math.Complex
alias
Alias of std.math.complex.Complex
std.math.comptimeMod
function
Return the mod of num with the smallest integer type
pub fn comptimeMod(num: anytype, comptime denom: comptime_int) IntFittingRange(0, denom - 1)
Parameters
denom: comptime_int
std.math.copysign
alias
Alias of std.math.copysign.copysign
std.math.cos
function
Cosine trigonometric function on a floating point number. Uses a dedicated hardware instruction when available. This is the same as calling the builtin @cos
pub inline fn cos(value: anytype) @TypeOf(value)
std.math.cosh
alias
Alias of std.math.cosh.cosh
std.math.deg_per_rad
constant
180.0/pi
std.math.degreesToRadians
function
Converts an angle in degrees to radians. T must be a float or comptime number or a vector of floats.
pub fn degreesToRadians(ang: anytype) if (@TypeOf(ang) == comptime_int) comptime_float else @TypeOf(ang)
Example usage
test degreesToRadians {
const ninety: f32 = 90;
const neg_two_seventy: f32 = -270;
const three_sixty: f32 = 360;
try std.testing.expectApproxEqAbs(@as(f32, pi / 2.0), degreesToRadians(ninety), 1e-6);
try std.testing.expectApproxEqAbs(@as(f32, -3 * pi / 2.0), degreesToRadians(neg_two_seventy), 1e-6);
try std.testing.expectApproxEqAbs(@as(f32, 2 * pi), degreesToRadians(three_sixty), 1e-6);
const result = degreesToRadians(@Vector(3, f32){
ninety,
neg_two_seventy,
three_sixty,
});
try std.testing.expectApproxEqAbs(@as(f32, pi / 2.0), result[0], 1e-6);
try std.testing.expectApproxEqAbs(@as(f32, -3 * pi / 2.0), result[1], 1e-6);
try std.testing.expectApproxEqAbs(@as(f32, 2 * pi), result[2], 1e-6);
}
std.math.divCeil
function
Divide numerator by denominator, rounding toward positive infinity. Returns an error on overflow or when denominator is zero.
pub fn divCeil(comptime T: type, numerator: T, denominator: T) !T
Parameters
T: type
numerator: T
denominator: T
Example usage
test divCeil {
try testDivCeil();
try comptime testDivCeil();
}
std.math.divExact
function
Divide numerator by denominator. Return an error if quotient is not an integer, denominator is zero, or on overflow.
pub fn divExact(comptime T: type, numerator: T, denominator: T) !T
Parameters
T: type
numerator: T
denominator: T
Example usage
test divExact {
try testDivExact();
try comptime testDivExact();
}
std.math.divFloor
function
Divide numerator by denominator, rounding toward negative infinity. Returns an error on overflow or when denominator is zero.
pub fn divFloor(comptime T: type, numerator: T, denominator: T) !T
Parameters
T: type
numerator: T
denominator: T
Example usage
test divFloor {
try testDivFloor();
try comptime testDivFloor();
}
std.math.divTrunc
function
Divide numerator by denominator, rounding toward zero. Returns an error on overflow or when denominator is zero.
pub fn divTrunc(comptime T: type, numerator: T, denominator: T) !T
Parameters
T: type
numerator: T
denominator: T
Example usage
test divTrunc {
try testDivTrunc();
try comptime testDivTrunc();
}
std.math.e
constant
Euler's number (e)
std.math.exp
function
Base-e exponential function on a floating point number. Uses a dedicated hardware instruction when available. This is the same as calling the builtin @exp
pub inline fn exp(value: anytype) @TypeOf(value)
std.math.exp2
function
Base-2 exponential function on a floating point number. Uses a dedicated hardware instruction when available. This is the same as calling the builtin @exp2
pub inline fn exp2(value: anytype) @TypeOf(value)
std.math.expm1
alias
Alias of std.math.expm1.expm1
std.math.F80
container
Fields
fraction: u64
exp: u16
std.math.F80.fromFloat
function
pub fn fromFloat(x: f80) F80
Parameters
x: f80
std.math.F80.toFloat
function
pub fn toFloat(self: F80) f80
Parameters
self: F80
std.math.float
alias
Alias of std.math.float
std.math.floatEps
alias
Alias of std.math.float.floatEps
std.math.floatEpsAt
alias
Alias of std.math.float.floatEpsAt
std.math.floatExponentBits
alias
Alias of std.math.float.floatExponentBits
std.math.floatExponentMax
alias
Alias of std.math.float.floatExponentMax
std.math.floatExponentMin
alias
Alias of std.math.float.floatExponentMin
std.math.floatFractionalBits
alias
Alias of std.math.float.floatFractionalBits
std.math.floatMantissaBits
alias
Alias of std.math.float.floatMantissaBits
std.math.floatMax
alias
Alias of std.math.float.floatMax
std.math.floatMin
alias
Alias of std.math.float.floatMin
std.math.FloatRepr
alias
Alias of std.math.float.FloatRepr
std.math.floatTrueMin
alias
Alias of std.math.float.floatTrueMin
std.math.floor
function
Returns the largest integral value not greater than the given floating point number. Uses a dedicated hardware instruction when available. This is the same as calling the builtin @floor
pub inline fn floor(value: anytype) @TypeOf(value)
std.math.floorPowerOfTwo
function
Returns the nearest power of two less than or equal to value, or zero if value is less than or equal to zero.
pub fn floorPowerOfTwo(comptime T: type, value: T) T
Parameters
T: type
value: T
Example usage
test floorPowerOfTwo {
try testFloorPowerOfTwo();
try comptime testFloorPowerOfTwo();
}
std.math.frexp
alias
Alias of std.math.frexp.frexp
std.math.Frexp
alias
Alias of std.math.frexp.Frexp
std.math.gamma
alias
Alias of std.math.gamma.gamma
std.math.gcd
alias
Alias of std.math.gcd.gcd
std.math.hypot
alias
Alias of std.math.hypot.hypot
std.math.ilogb
alias
Alias of std.math.ilogb.ilogb
std.math.inf
alias
Alias of std.math.float.inf
std.math.IntFittingRange
type-function
Returns the smallest integer type that can hold both from and to.
pub fn IntFittingRange(comptime from: comptime_int, comptime to: comptime_int) type
Parameters
from: comptime_int
to: comptime_int
Example usage
test IntFittingRange {
try testing.expect(IntFittingRange(0, 0) == u0);
try testing.expect(IntFittingRange(0, 1) == u1);
try testing.expect(IntFittingRange(0, 2) == u2);
try testing.expect(IntFittingRange(0, 3) == u2);
try testing.expect(IntFittingRange(0, 4) == u3);
try testing.expect(IntFittingRange(0, 7) == u3);
try testing.expect(IntFittingRange(0, 8) == u4);
try testing.expect(IntFittingRange(0, 9) == u4);
try testing.expect(IntFittingRange(0, 15) == u4);
try testing.expect(IntFittingRange(0, 16) == u5);
try testing.expect(IntFittingRange(0, 17) == u5);
try testing.expect(IntFittingRange(0, 4095) == u12);
try testing.expect(IntFittingRange(2000, 4095) == u12);
try testing.expect(IntFittingRange(0, 4096) == u13);
try testing.expect(IntFittingRange(2000, 4096) == u13);
try testing.expect(IntFittingRange(0, 4097) == u13);
try testing.expect(IntFittingRange(2000, 4097) == u13);
try testing.expect(IntFittingRange(0, 123456789123456798123456789) == u87);
try testing.expect(IntFittingRange(0, 123456789123456798123456789123456789123456798123456789) == u177);
try testing.expect(IntFittingRange(-1, -1) == i1);
try testing.expect(IntFittingRange(-1, 0) == i1);
try testing.expect(IntFittingRange(-1, 1) == i2);
try testing.expect(IntFittingRange(-2, -2) == i2);
try testing.expect(IntFittingRange(-2, -1) == i2);
try testing.expect(IntFittingRange(-2, 0) == i2);
try testing.expect(IntFittingRange(-2, 1) == i2);
try testing.expect(IntFittingRange(-2, 2) == i3);
try testing.expect(IntFittingRange(-1, 2) == i3);
try testing.expect(IntFittingRange(-1, 3) == i3);
try testing.expect(IntFittingRange(-1, 4) == i4);
try testing.expect(IntFittingRange(-1, 7) == i4);
try testing.expect(IntFittingRange(-1, 8) == i5);
try testing.expect(IntFittingRange(-1, 9) == i5);
try testing.expect(IntFittingRange(-1, 15) == i5);
try testing.expect(IntFittingRange(-1, 16) == i6);
try testing.expect(IntFittingRange(-1, 17) == i6);
try testing.expect(IntFittingRange(-1, 4095) == i13);
try testing.expect(IntFittingRange(-4096, 4095) == i13);
try testing.expect(IntFittingRange(-1, 4096) == i14);
try testing.expect(IntFittingRange(-4097, 4095) == i14);
try testing.expect(IntFittingRange(-1, 4097) == i14);
try testing.expect(IntFittingRange(-1, 123456789123456798123456789) == i88);
try testing.expect(IntFittingRange(-1, 123456789123456798123456789123456789123456798123456789) == i178);
}
std.math.isFinite
alias
Alias of std.math.isfinite.isFinite
std.math.isInf
alias
Alias of std.math.isinf.isInf
std.math.isNan
alias
Alias of std.math.isnan.isNan
std.math.isNegativeInf
alias
Alias of std.math.isinf.isNegativeInf
std.math.isNegativeZero
alias
Alias of std.math.iszero.isNegativeZero
std.math.isNormal
alias
Alias of std.math.isnormal.isNormal
std.math.isPositiveInf
alias
Alias of std.math.isinf.isPositiveInf
std.math.isPositiveZero
alias
Alias of std.math.iszero.isPositiveZero
std.math.isPowerOfTwo
function
Asserts int > 0.
pub fn isPowerOfTwo(int: anytype) bool
Example usage
test isPowerOfTwo {
try testing.expect(isPowerOfTwo(@as(u8, 1)));
try testing.expect(isPowerOfTwo(2));
try testing.expect(!isPowerOfTwo(@as(i16, 3)));
try testing.expect(isPowerOfTwo(4));
try testing.expect(!isPowerOfTwo(@as(u32, 31)));
try testing.expect(isPowerOfTwo(32));
try testing.expect(!isPowerOfTwo(@as(i64, 63)));
try testing.expect(isPowerOfTwo(128));
try testing.expect(isPowerOfTwo(@as(u128, 256)));
}
std.math.isSignalNan
alias
Alias of std.math.isnan.isSignalNan
std.math.lcm
alias
Alias of std.math.lcm.lcm
std.math.ldexp
alias
Alias of std.math.ldexp.ldexp
std.math.lerp
function
Performs linear interpolation between a and b based on t. t ranges from 0.0 to 1.0, but may exceed these bounds. Supports floats and vectors of floats.
This does not guarantee returning b if t is 1 due to floating-point errors. This is monotonic.
pub fn lerp(a: anytype, b: anytype, t: anytype) @TypeOf(a, b, t)
Example usage
test lerp {
if (builtin.zig_backend == .stage2_c and builtin.cpu.arch.isArm()) return error.SkipZigTest;
if (builtin.zig_backend == .stage2_c and builtin.cpu.arch.isX86()) return error.SkipZigTest;
if (builtin.zig_backend == .stage2_x86_64 and !comptime builtin.cpu.has(.x86, .fma)) return error.SkipZigTest; // https://github.com/ziglang/zig/issues/17884
try testing.expectEqual(@as(f64, 75), lerp(50, 100, 0.5));
try testing.expectEqual(@as(f32, 43.75), lerp(50, 25, 0.25));
try testing.expectEqual(@as(f64, -31.25), lerp(-50, 25, 0.25));
try testing.expectEqual(@as(f64, 30), lerp(10, 20, 2.0));
try testing.expectEqual(@as(f64, 5), lerp(10, 20, -0.5));
try testing.expectApproxEqRel(@as(f32, -7.16067345e+03), lerp(-10000.12345, -5000.12345, 0.56789), 1e-19);
try testing.expectApproxEqRel(@as(f64, 7.010987590521e+62), lerp(0.123456789e-64, 0.123456789e64, 0.56789), 1e-33);
try testing.expectEqual(@as(f32, 0.0), lerp(@as(f32, 1.0e8), 1.0, 1.0));
try testing.expectEqual(@as(f64, 0.0), lerp(@as(f64, 1.0e16), 1.0, 1.0));
try testing.expectEqual(@as(f32, 1.0), lerp(@as(f32, 1.0e7), 1.0, 1.0));
try testing.expectEqual(@as(f64, 1.0), lerp(@as(f64, 1.0e15), 1.0, 1.0));
{
const a: @Vector(3, f32) = @splat(0);
const b: @Vector(3, f32) = @splat(50);
const t: @Vector(3, f32) = @splat(0.5);
try testing.expectEqual(
@Vector(3, f32){ 25, 25, 25 },
lerp(a, b, t),
);
}
{
const a: @Vector(3, f64) = @splat(50);
const b: @Vector(3, f64) = @splat(100);
const t: @Vector(3, f64) = @splat(0.5);
try testing.expectEqual(
@Vector(3, f64){ 75, 75, 75 },
lerp(a, b, t),
);
}
{
const a: @Vector(2, f32) = @splat(40);
const b: @Vector(2, f32) = @splat(80);
const t: @Vector(2, f32) = @Vector(2, f32){ 0.25, 0.75 };
try testing.expectEqual(
@Vector(2, f32){ 50, 70 },
lerp(a, b, t),
);
}
}
std.math.lgamma
alias
Alias of std.math.gamma.lgamma
std.math.ln10
constant
ln(10)
std.math.ln2
constant
ln(2)
std.math.log
alias
Alias of std.math.log.log
std.math.log_int
alias
Alias of std.math.log_int.log_int
std.math.log10
alias
Alias of std.math.log10.log10
std.math.log10_int
alias
Alias of std.math.log10.log10_int
std.math.log10e
constant
log10(e)
std.math.log1p
alias
Alias of std.math.log1p.log1p
std.math.log2
alias
Alias of std.math.log2.log2
std.math.log2_int
function
Return the log base 2 of integer value x, rounding down to the nearest integer.
pub fn log2_int(comptime T: type, x: T) Log2Int(T)
Parameters
T: type
x: T
Example usage
test log2_int {
try testing.expect(log2_int(u32, 1) == 0);
try testing.expect(log2_int(u32, 2) == 1);
try testing.expect(log2_int(u32, 3) == 1);
try testing.expect(log2_int(u32, 4) == 2);
try testing.expect(log2_int(u32, 5) == 2);
try testing.expect(log2_int(u32, 6) == 2);
try testing.expect(log2_int(u32, 7) == 2);
try testing.expect(log2_int(u32, 8) == 3);
try testing.expect(log2_int(u32, 9) == 3);
try testing.expect(log2_int(u32, 10) == 3);
}
std.math.log2_int_ceil
function
Return the log base 2 of integer value x, rounding up to the nearest integer.
pub fn log2_int_ceil(comptime T: type, x: T) Log2IntCeil(T)
Parameters
T: type
x: T
Example usage
test log2_int_ceil {
try testing.expect(log2_int_ceil(u32, 1) == 0);
try testing.expect(log2_int_ceil(u32, 2) == 1);
try testing.expect(log2_int_ceil(u32, 3) == 2);
try testing.expect(log2_int_ceil(u32, 4) == 2);
try testing.expect(log2_int_ceil(u32, 5) == 3);
try testing.expect(log2_int_ceil(u32, 6) == 3);
try testing.expect(log2_int_ceil(u32, 7) == 3);
try testing.expect(log2_int_ceil(u32, 8) == 3);
try testing.expect(log2_int_ceil(u32, 9) == 4);
try testing.expect(log2_int_ceil(u32, 10) == 4);
}
std.math.log2e
constant
log2(e)
std.math.Log2Int
type-function
Returns an unsigned int type that can hold the number of bits in T - 1. Suitable for 0-based bit indices of T.
pub fn Log2Int(comptime T: type) type
Parameters
T: type
std.math.Log2IntCeil
type-function
Returns an unsigned int type that can hold the number of bits in T.
pub fn Log2IntCeil(comptime T: type) type
Parameters
T: type
std.math.long_double
alias
Alias of std.math.float.long_double
std.math.lossyCast
function
Cast a value to a different type. If the value doesn't fit in, or can't be perfectly represented by, the new type, it will be converted to the closest possible representation.
pub fn lossyCast(comptime T: type, value: anytype) T
Parameters
T: type
Example usage
test lossyCast {
try testing.expect(lossyCast(i16, 70000.0) == @as(i16, 32767));
try testing.expect(lossyCast(u32, @as(i16, -255)) == @as(u32, 0));
try testing.expect(lossyCast(i9, @as(u32, 200)) == @as(i9, 200));
try testing.expect(lossyCast(u32, @as(f32, @floatFromInt(maxInt(u32)))) == maxInt(u32));
try testing.expect(lossyCast(u32, nan(f32)) == 0);
}
std.math.maxInt
function
Returns the maximum value of integer type T.
pub fn maxInt(comptime T: type) comptime_int
Parameters
T: type
Example usage
test maxInt {
try testing.expect(maxInt(u0) == 0);
try testing.expect(maxInt(u1) == 1);
try testing.expect(maxInt(u8) == 255);
try testing.expect(maxInt(u16) == 65535);
try testing.expect(maxInt(u32) == 4294967295);
try testing.expect(maxInt(u64) == 18446744073709551615);
try testing.expect(maxInt(u128) == 340282366920938463463374607431768211455);
try testing.expect(maxInt(i1) == 0);
try testing.expect(maxInt(i8) == 127);
try testing.expect(maxInt(i16) == 32767);
try testing.expect(maxInt(i32) == 2147483647);
try testing.expect(maxInt(i63) == 4611686018427387903);
try testing.expect(maxInt(i64) == 9223372036854775807);
try testing.expect(maxInt(i128) == 170141183460469231731687303715884105727);
}
std.math.mem
alias
Alias of std.mem
std.math.Min
type-function
Given two types, returns the smallest one which is capable of holding the full range of the minimum value.
pub fn Min(comptime A: type, comptime B: type) type
Parameters
A: type
B: type
std.math.minInt
function
Returns the minimum value of integer type T.
pub fn minInt(comptime T: type) comptime_int
Parameters
T: type
Example usage
test minInt {
try testing.expect(minInt(u0) == 0);
try testing.expect(minInt(u1) == 0);
try testing.expect(minInt(u8) == 0);
try testing.expect(minInt(u16) == 0);
try testing.expect(minInt(u32) == 0);
try testing.expect(minInt(u63) == 0);
try testing.expect(minInt(u64) == 0);
try testing.expect(minInt(u128) == 0);
try testing.expect(minInt(i1) == -1);
try testing.expect(minInt(i8) == -128);
try testing.expect(minInt(i16) == -32768);
try testing.expect(minInt(i32) == -2147483648);
try testing.expect(minInt(i63) == -4611686018427387904);
try testing.expect(minInt(i64) == -9223372036854775808);
try testing.expect(minInt(i128) == -170141183460469231731687303715884105728);
}
std.math.mod
function
Returns numerator modulo denominator, or an error if denominator is zero or negative. Negative numerators never result in negative return values.
pub fn mod(comptime T: type, numerator: T, denominator: T) !T
Parameters
T: type
numerator: T
denominator: T
Example usage
test mod {
try testMod();
try comptime testMod();
}
std.math.modf
alias
Alias of std.math.modf.modf
std.math.Modf
alias
Alias of std.math.modf.Modf
std.math.mul
function
Returns the product of a and b. Returns an error on overflow.
pub fn mul(comptime T: type, a: T, b: T) (error{Overflow}!T)
Parameters
T: type
a: T
b: T
std.math.mulWide
function
Multiply a and b. Return type is wide enough to guarantee no overflow.
pub fn mulWide(comptime T: type, a: T, b: T) @Int( @typeInfo(T).int.signedness, @typeInfo(T).int.bits * 2, )
Parameters
T: type
a: T
b: T
Example usage
test mulWide {
try testing.expect(mulWide(u8, 5, 5) == 25);
try testing.expect(mulWide(i8, 5, -5) == -25);
try testing.expect(mulWide(u8, 100, 100) == 10000);
}
std.math.nan
alias
Alias of std.math.float.nan
std.math.negate
function
pub fn negate(x: anytype) !@TypeOf(x)
std.math.negateCast
function
Returns the negation of the integer parameter. Result is a signed integer.
pub fn negateCast(x: anytype) !@Int(.signed, @bitSizeOf(@TypeOf(x)))
Example usage
test negateCast {
try testing.expect((negateCast(@as(u32, 999)) catch unreachable) == -999);
try testing.expect(@TypeOf(negateCast(@as(u32, 999)) catch unreachable) == i32);
try testing.expect((negateCast(@as(u32, -minInt(i32))) catch unreachable) == minInt(i32));
try testing.expect(@TypeOf(negateCast(@as(u32, -minInt(i32))) catch unreachable) == i32);
try testing.expectError(error.Overflow, negateCast(@as(u32, maxInt(i32) + 10)));
}
std.math.nextAfter
alias
Alias of std.math.nextafter.nextAfter
std.math.order
function
Given two numbers, this function returns the order they are with respect to each other.
pub fn order(a: anytype, b: anytype) Order
Example usage
test order {
try testing.expect(order(0, 0) == .eq);
try testing.expect(order(1, 0) == .gt);
try testing.expect(order(-1, 0) == .lt);
}
std.math.Order
container
See also CompareOperator.
Fields
gtGreater than (>)
ltLess than (<)
eqEqual (==)
std.math.Order.compare
function
pub fn compare(self: Order, op: CompareOperator) bool
Parameters
self: Order
op: CompareOperator
std.math.Order.differ
function
pub fn differ(self: Order) ?Order
Parameters
self: Order
Example usage
test differ {
const neg: i32 = -1;
const zero: i32 = 0;
const pos: i32 = 1;
try testing.expect(order(zero, neg).differ() orelse
order(pos, zero) == .gt);
try testing.expect(order(zero, zero).differ() orelse
order(zero, zero) == .eq);
try testing.expect(order(pos, pos).differ() orelse
order(neg, zero) == .lt);
try testing.expect(order(zero, zero).differ() orelse
order(pos, neg).differ() orelse
order(neg, zero) == .gt);
try testing.expect(order(pos, pos).differ() orelse
order(pos, pos).differ() orelse
order(neg, neg) == .eq);
try testing.expect(order(zero, pos).differ() orelse
order(neg, pos).differ() orelse
order(pos, neg) == .lt);
}
std.math.Order.invert
function
pub fn invert(self: Order) Order
Parameters
self: Order
Example usage
test invert {
try testing.expect(Order.invert(order(0, 0)) == .eq);
try testing.expect(Order.invert(order(1, 0)) == .lt);
try testing.expect(Order.invert(order(-1, 0)) == .gt);
}
std.math.phi
constant
Phi or Golden ratio constant (Φ) = (1 + sqrt(5))/2
std.math.pi
constant
Archimedes' constant (π)
std.math.pow
alias
Alias of std.math.pow.pow
std.math.powi
alias
Alias of std.math.powi.powi
std.math.rad_per_deg
constant
pi/180.0
std.math.radiansToDegrees
function
Converts an angle in radians to degrees. T must be a float or comptime number or a vector of floats.
pub fn radiansToDegrees(ang: anytype) if (@TypeOf(ang) == comptime_int) comptime_float else @TypeOf(ang)
Example usage
test radiansToDegrees {
const zero: f32 = 0;
const half_pi: f32 = pi / 2.0;
const neg_quart_pi: f32 = -pi / 4.0;
const one_pi: f32 = pi;
const two_pi: f32 = 2.0 * pi;
try std.testing.expectApproxEqAbs(@as(f32, 0), radiansToDegrees(zero), 1e-6);
try std.testing.expectApproxEqAbs(@as(f32, 90), radiansToDegrees(half_pi), 1e-6);
try std.testing.expectApproxEqAbs(@as(f32, -45), radiansToDegrees(neg_quart_pi), 1e-6);
try std.testing.expectApproxEqAbs(@as(f32, 180), radiansToDegrees(one_pi), 1e-6);
try std.testing.expectApproxEqAbs(@as(f32, 360), radiansToDegrees(two_pi), 1e-6);
const result = radiansToDegrees(@Vector(4, f32){
half_pi,
neg_quart_pi,
one_pi,
two_pi,
});
try std.testing.expectApproxEqAbs(@as(f32, 90), result[0], 1e-6);
try std.testing.expectApproxEqAbs(@as(f32, -45), result[1], 1e-6);
try std.testing.expectApproxEqAbs(@as(f32, 180), result[2], 1e-6);
try std.testing.expectApproxEqAbs(@as(f32, 360), result[3], 1e-6);
}
std.math.raiseDivByZero
function
pub fn raiseDivByZero() void
std.math.raiseInexact
function
pub fn raiseInexact() void
std.math.raiseInvalid
function
pub fn raiseInvalid() void
std.math.raiseOverflow
function
pub fn raiseOverflow() void
std.math.raiseUnderflow
function
pub fn raiseUnderflow() void
std.math.rem
function
Returns the remainder when numerator is divided by denominator, or an error if denominator is zero or negative. Negative numerators can give negative results.
pub fn rem(comptime T: type, numerator: T, denominator: T) !T
Parameters
T: type
numerator: T
denominator: T
Example usage
test rem {
try testRem();
try comptime testRem();
}
std.math.rotl
function
Rotates left. Only unsigned values can be rotated. Negative shift values result in shift modulo the bit count.
pub fn rotl(comptime T: type, x: T, r: anytype) T
Parameters
T: type
x: T
Example usage
test rotl {
try testing.expect(rotl(u0, 0b0, @as(usize, 3)) == 0b0);
try testing.expect(rotl(u5, 0b00001, @as(usize, 0)) == 0b00001);
try testing.expect(rotl(u6, 0b000001, @as(usize, 7)) == 0b000010);
try testing.expect(rotl(u8, 0b00000001, @as(usize, 0)) == 0b00000001);
try testing.expect(rotl(u8, 0b00000001, @as(usize, 9)) == 0b00000010);
try testing.expect(rotl(u8, 0b00000001, @as(usize, 8)) == 0b00000001);
try testing.expect(rotl(u8, 0b00000001, @as(usize, 4)) == 0b00010000);
try testing.expect(rotl(u8, 0b00000001, @as(isize, -1)) == 0b10000000);
try testing.expect(rotl(u12, 0o7777, 1) == 0o7777);
try testing.expect(rotl(@Vector(1, u32), .{1 << 31}, @as(usize, 1))[0] == 1);
try testing.expect(rotl(@Vector(1, u32), .{1 << 31}, @as(isize, -1))[0] == @as(u32, 1) << 30);
try std.testing.expect(@reduce(.And, rotl(@Vector(2, u0), .{ 0, 0 }, @as(usize, 42)) ==
@Vector(2, u0){ 0, 0 }));
}
std.math.rotr
function
Rotates right. Only unsigned values can be rotated. Negative shift values result in shift modulo the bit count.
pub fn rotr(comptime T: type, x: T, r: anytype) T
Parameters
T: type
x: T
Example usage
test rotr {
try testing.expect(rotr(u0, 0b0, @as(usize, 3)) == 0b0);
try testing.expect(rotr(u5, 0b00001, @as(usize, 0)) == 0b00001);
try testing.expect(rotr(u6, 0b000001, @as(usize, 7)) == 0b100000);
try testing.expect(rotr(u8, 0b00000001, @as(usize, 0)) == 0b00000001);
try testing.expect(rotr(u8, 0b00000001, @as(usize, 9)) == 0b10000000);
try testing.expect(rotr(u8, 0b00000001, @as(usize, 8)) == 0b00000001);
try testing.expect(rotr(u8, 0b00000001, @as(usize, 4)) == 0b00010000);
try testing.expect(rotr(u8, 0b00000001, @as(isize, -1)) == 0b00000010);
try testing.expect(rotr(u12, 0o7777, 1) == 0o7777);
try testing.expect(rotr(@Vector(1, u32), .{1}, @as(usize, 1))[0] == @as(u32, 1) << 31);
try testing.expect(rotr(@Vector(1, u32), .{1}, @as(isize, -1))[0] == @as(u32, 1) << 1);
try std.testing.expect(@reduce(.And, rotr(@Vector(2, u0), .{ 0, 0 }, @as(usize, 42)) ==
@Vector(2, u0){ 0, 0 }));
}
std.math.round
function
Rounds the given floating point number to the nearest integer. If two integers are equally close, rounds away from zero. Uses a dedicated hardware instruction when available. This is the same as calling the builtin @round
pub inline fn round(value: anytype) @TypeOf(value)
std.math.runTest
function
fn runTest() !void
std.math.scalbn
alias
Alias of std.math.scalbn.scalbn
std.math.shl
function
Shifts left. Overflowed bits are truncated. A negative shift amount results in a right shift.
pub fn shl(comptime T: type, a: T, shift_amt: anytype) T
Parameters
T: type
a: T
Example usage
test shl {
try testing.expect(shl(u8, 0b11111111, @as(usize, 3)) == 0b11111000);
try testing.expect(shl(u8, 0b11111111, @as(usize, 8)) == 0);
try testing.expect(shl(u8, 0b11111111, @as(usize, 9)) == 0);
try testing.expect(shl(u8, 0b11111111, @as(isize, -2)) == 0b00111111);
try testing.expect(shl(u8, 0b11111111, 3) == 0b11111000);
try testing.expect(shl(u8, 0b11111111, 8) == 0);
try testing.expect(shl(u8, 0b11111111, 9) == 0);
try testing.expect(shl(u8, 0b11111111, -2) == 0b00111111);
try testing.expect(shl(@Vector(1, u32), @Vector(1, u32){42}, @as(usize, 1))[0] == @as(u32, 42) << 1);
try testing.expect(shl(@Vector(1, u32), @Vector(1, u32){42}, @as(isize, -1))[0] == @as(u32, 42) >> 1);
try testing.expect(shl(@Vector(1, u32), @Vector(1, u32){42}, 33)[0] == 0);
try testing.expect(shl(i8, -1, -100) == -1);
try testing.expect(shl(i8, -1, 100) == 0);
if (builtin.cpu.arch == .hexagon and builtin.zig_backend == .stage2_llvm) return error.SkipZigTest;
try testing.expect(@reduce(.And, shl(@Vector(2, i8), .{ -1, 1 }, -100) == @Vector(2, i8){ -1, 0 }));
try testing.expect(@reduce(.And, shl(@Vector(2, i8), .{ -1, 1 }, 100) == @Vector(2, i8){ 0, 0 }));
}
std.math.shlExact
function
Shifts a left by shift_amt. Returns an error on overflow. shift_amt is unsigned.
pub fn shlExact(comptime T: type, a: T, shift_amt: Log2Int(T)) !T
Parameters
std.math.shr
function
Shifts right. Overflowed bits are truncated. A negative shift amount results in a left shift.
pub fn shr(comptime T: type, a: T, shift_amt: anytype) T
Parameters
T: type
a: T
Example usage
test shr {
try testing.expect(shr(u8, 0b11111111, @as(usize, 3)) == 0b00011111);
try testing.expect(shr(u8, 0b11111111, @as(usize, 8)) == 0);
try testing.expect(shr(u8, 0b11111111, @as(usize, 9)) == 0);
try testing.expect(shr(u8, 0b11111111, @as(isize, -2)) == 0b11111100);
try testing.expect(shr(u8, 0b11111111, 3) == 0b00011111);
try testing.expect(shr(u8, 0b11111111, 8) == 0);
try testing.expect(shr(u8, 0b11111111, 9) == 0);
try testing.expect(shr(u8, 0b11111111, -2) == 0b11111100);
try testing.expect(shr(@Vector(1, u32), @Vector(1, u32){42}, @as(usize, 1))[0] == @as(u32, 42) >> 1);
try testing.expect(shr(@Vector(1, u32), @Vector(1, u32){42}, @as(isize, -1))[0] == @as(u32, 42) << 1);
try testing.expect(shr(@Vector(1, u32), @Vector(1, u32){42}, 33)[0] == 0);
try testing.expect(shr(i8, -1, -100) == 0);
try testing.expect(shr(i8, -1, 100) == -1);
if (builtin.cpu.arch == .hexagon and builtin.zig_backend == .stage2_llvm) return error.SkipZigTest;
try testing.expect(@reduce(.And, shr(@Vector(2, i8), .{ -1, 1 }, -100) == @Vector(2, i8){ 0, 0 }));
try testing.expect(@reduce(.And, shr(@Vector(2, i8), .{ -1, 1 }, 100) == @Vector(2, i8){ -1, 0 }));
}
std.math.sign
function
Returns -1, 0, or 1. Supports integer and float types and vectors of integer and float types. Unsigned integer types will always return 0 or 1. The returned integer type is the smallest that fits the possible values. Branchless.
pub inline fn sign(n: anytype) SignOf(@TypeOf(n))
Example usage
test sign {
try testSign();
try comptime testSign();
}
std.math.Sign
container
Fields
positive
negative
std.math.signbit
alias
Alias of std.math.signbit.signbit
std.math.signExtend
function
Increases the bit width of an integer by copying the most significant bit. This results in the input and output having the same arithmetic value, when interpreted as two's complement integers.
pub fn signExtend(To: type, n: anytype) To
Parameters
To: type
Example usage
test signExtend {
const number: u8 = 0x86;
try testing.expectEqual(0xff86, signExtend(u16, number));
try testing.expectEqual(0, signExtend(u1, @as(u0, 0)));
try testing.expectEqual(0, signExtend(u16, @as(u0, 0)));
try testing.expectEqual(0x0000, signExtend(u16, @as(u1, 0b0)));
try testing.expectEqual(0xffff, signExtend(u16, @as(u1, 0b1)));
try testing.expectEqual(0b000, signExtend(u3, @as(u2, 0b00)));
try testing.expectEqual(0b001, signExtend(u3, @as(u2, 0b01)));
try testing.expectEqual(0b110, signExtend(u3, @as(u2, 0b10)));
try testing.expectEqual(0b111, signExtend(u3, @as(u2, 0b11)));
try testing.expectEqual(0b0000_0001, signExtend(u8, @as(u2, 0b01)));
try testing.expectEqual(0b1111_1110, signExtend(u8, @as(u2, 0b10)));
try testing.expectEqual(0x0039, signExtend(u16, @as(u8, 0x39)));
try testing.expectEqual(0xff93, signExtend(u16, @as(u8, 0x93)));
try testing.expectEqual(5, signExtend(i32, @as(i8, 5)));
try testing.expectEqual(-123, signExtend(i16, @as(i8, -123)));
}
std.math.SignOf
type-function
fn SignOf(T: type) type
Parameters
T: type
std.math.sin
function
Sine trigonometric function on a floating point number. Uses a dedicated hardware instruction when available. This is the same as calling the builtin @sin
pub inline fn sin(value: anytype) @TypeOf(value)
std.math.sinh
alias
Alias of std.math.sinh.sinh
std.math.snan
alias
Alias of std.math.float.snan
std.math.sqrt
alias
Alias of std.math.sqrt.sqrt
std.math.sqrt1_2
constant
1/sqrt(2)
std.math.sqrt2
constant
sqrt(2)
std.math.std
alias
Alias of std
std.math.sub
function
Returns a - b, or an error on overflow.
pub fn sub(comptime T: type, a: T, b: T) (error{Overflow}!T)
Parameters
T: type
a: T
b: T
std.math.tan
function
Tangent trigonometric function on a floating point number. Uses a dedicated hardware instruction when available. This is the same as calling the builtin @tan
pub inline fn tan(value: anytype) @TypeOf(value)
std.math.tanh
alias
Alias of std.math.tanh.tanh
std.math.tau
constant
Circle constant (τ)
std.math.testCeilPowerOfTwo
function
fn testCeilPowerOfTwo() !void
std.math.testCeilPowerOfTwoPromote
function
fn testCeilPowerOfTwoPromote() !void
std.math.testDivCeil
function
fn testDivCeil() !void
std.math.testDivExact
function
fn testDivExact() !void
std.math.testDivFloor
function
fn testDivFloor() !void
std.math.testDivTrunc
function
fn testDivTrunc() !void
std.math.testFloorPowerOfTwo
function
fn testFloorPowerOfTwo() !void
std.math.testing
alias
Alias of std.testing
std.math.testMod
function
fn testMod() !void
std.math.testOverflow
function
fn testOverflow() !void
std.math.testRem
function
fn testRem() !void
std.math.testSign
function
fn testSign() !void
std.math.trunc
function
Rounds the given floating point number to an integer, towards zero. Uses a dedicated hardware instruction when available. This is the same as calling the builtin @trunc
pub inline fn trunc(value: anytype) @TypeOf(value)
std.math.two_sqrtpi
constant
2/sqrt(π)
std.math.wrap
function
Odd sawtooth function
|
/ | / /
/ |/ /
--/----/----/--
/ /| /
/ / | /
|
Limit x to the half-open interval [-r, r).
pub fn wrap(x: anytype, r: anytype) @TypeOf(x)
Example usage
test wrap {
if (builtin.os.tag == .windows and builtin.cpu.arch == .x86 and builtin.abi == .msvc) {
// https://codeberg.org/ziglang/zig/issues/35520
return error.SkipZigTest;
}
// Within range
try testing.expect(wrap(@as(i32, -75), @as(i32, 180)) == -75);
try testing.expect(wrap(@as(i32, -75), @as(i32, -180)) == -75);
// Below
try testing.expect(wrap(@as(i32, -225), @as(i32, 180)) == 135);
try testing.expect(wrap(@as(i32, -225), @as(i32, -180)) == 135);
// Above
try testing.expect(wrap(@as(i32, 361), @as(i32, 180)) == 1);
try testing.expect(wrap(@as(i32, 361), @as(i32, -180)) == 1);
// One period, right limit, positive r
try testing.expect(wrap(@as(i32, 180), @as(i32, 180)) == -180);
// One period, left limit, positive r
try testing.expect(wrap(@as(i32, -180), @as(i32, 180)) == -180);
// One period, right limit, negative r
try testing.expect(wrap(@as(i32, 180), @as(i32, -180)) == 180);
// One period, left limit, negative r
try testing.expect(wrap(@as(i32, -180), @as(i32, -180)) == 180);
// Two periods, right limit, positive r
try testing.expect(wrap(@as(i32, 540), @as(i32, 180)) == -180);
// Two periods, left limit, positive r
try testing.expect(wrap(@as(i32, -540), @as(i32, 180)) == -180);
// Two periods, right limit, negative r
try testing.expect(wrap(@as(i32, 540), @as(i32, -180)) == 180);
// Two periods, left limit, negative r
try testing.expect(wrap(@as(i32, -540), @as(i32, -180)) == 180);
// Floating point
try testing.expect(wrap(@as(f32, 1.125), @as(f32, 1.0)) == -0.875);
try testing.expect(wrap(@as(f32, -127.5), @as(f32, 180)) == -127.5);
// Mix of comptime and non-comptime
var i: i32 = 1;
_ = &i;
try testing.expect(wrap(i, 10) == 1);
const limit: i32 = 180;
// Within range
try testing.expect(wrap(@as(i32, -75), limit) == -75);
// Below
try testing.expect(wrap(@as(i32, -225), limit) == 135);
// Above
try testing.expect(wrap(@as(i32, 361), limit) == 1);
}
Source code
std/math.zig
const builtin = @import("builtin");
const std = @import("std.zig");
const float = @import("math/float.zig");
const assert = std.debug.assert;
const mem = std.mem;
const testing = std.testing;
const Alignment = std.mem.Alignment;
/// Euler's number (e)
pub const e = 2.71828182845904523536028747135266249775724709369995;
/// Archimedes' constant (π)
pub const pi = 3.14159265358979323846264338327950288419716939937510;
/// Phi or Golden ratio constant (Φ) = (1 + sqrt(5))/2
pub const phi = 1.6180339887498948482045868343656381177203091798057628621;
/// Circle constant (τ)
pub const tau = 2 * pi;
/// log2(e)
pub const log2e = 1.442695040888963407359924681001892137;
/// log10(e)
pub const log10e = 0.434294481903251827651128918916605082;
/// ln(2)
pub const ln2 = 0.693147180559945309417232121458176568;
/// ln(10)
pub const ln10 = 2.302585092994045684017991454684364208;
/// 2/sqrt(π)
pub const two_sqrtpi = 1.128379167095512573896158903121545172;
/// sqrt(2)
pub const sqrt2 = 1.414213562373095048801688724209698079;
/// 1/sqrt(2)
pub const sqrt1_2 = 0.707106781186547524400844362104849039;
/// pi/180.0
pub const rad_per_deg = 0.0174532925199432957692369076848861271344287188854172545609719144;
/// 180.0/pi
pub const deg_per_rad = 57.295779513082320876798154814105170332405472466564321549160243861;
pub const Sign = enum(u1) { positive, negative };
pub const FloatRepr = float.FloatRepr;
pub const floatExponentBits = float.floatExponentBits;
pub const floatMantissaBits = float.floatMantissaBits;
pub const floatFractionalBits = float.floatFractionalBits;
pub const floatExponentMin = float.floatExponentMin;
pub const floatExponentMax = float.floatExponentMax;
pub const floatTrueMin = float.floatTrueMin;
pub const floatMin = float.floatMin;
pub const floatMax = float.floatMax;
pub const floatEps = float.floatEps;
pub const floatEpsAt = float.floatEpsAt;
pub const inf = float.inf;
pub const long_double = float.long_double;
pub const nan = float.nan;
pub const snan = float.snan;
/// Performs an approximate comparison of two floating point values `x` and `y`.
/// Returns true if the absolute difference between them is less or equal than
/// the specified tolerance.
///
/// The `tolerance` parameter is the absolute tolerance used when determining if
/// the two numbers are close enough; a good value for this parameter is a small
/// multiple of `floatEps(T)`.
///
/// Note that this function is recommended for comparing small numbers
/// around zero; using `approxEqRel` is suggested otherwise.
///
/// NaN values are never considered equal to any value.
pub fn approxEqAbs(comptime T: type, x: T, y: T, tolerance: T) bool {
comptime assert(@typeInfo(T) == .float or @typeInfo(T) == .comptime_float);
assert(tolerance >= 0);
// Fast path for equal values (and signed zeros and infinites).
if (x == y)
return true;
if (isNan(x) or isNan(y))
return false;
return @abs(x - y) <= tolerance;
}
/// Performs an approximate comparison of two floating point values `x` and `y`.
/// Returns true if the absolute difference between them is less or equal than
/// `max(|x|, |y|) * tolerance`, where `tolerance` is a positive number greater
/// than zero.
///
/// The `tolerance` parameter is the relative tolerance used when determining if
/// the two numbers are close enough; a good value for this parameter is usually
/// `sqrt(floatEps(T))`, meaning that the two numbers are considered equal if at
/// least half of the digits are equal.
///
/// Note that for comparisons of small numbers around zero this function won't
/// give meaningful results, use `approxEqAbs` instead.
///
/// NaN values are never considered equal to any value.
pub fn approxEqRel(comptime T: type, x: T, y: T, tolerance: T) bool {
comptime assert(@typeInfo(T) == .float or @typeInfo(T) == .comptime_float);
assert(tolerance > 0);
// Fast path for equal values (and signed zeros and infinites).
if (x == y)
return true;
if (isNan(x) or isNan(y))
return false;
return @abs(x - y) <= @max(@abs(x), @abs(y)) * tolerance;
}
test approxEqAbs {
inline for ([_]type{ f16, f32, f64, f128 }) |T| {
const eps_value = comptime floatEps(T);
const min_value = comptime floatMin(T);
try testing.expect(approxEqAbs(T, 0.0, 0.0, eps_value));
try testing.expect(approxEqAbs(T, -0.0, -0.0, eps_value));
try testing.expect(approxEqAbs(T, 0.0, -0.0, eps_value));
try testing.expect(!approxEqAbs(T, 1.0 + 2 * eps_value, 1.0, eps_value));
try testing.expect(approxEqAbs(T, 1.0 + 1 * eps_value, 1.0, eps_value));
try testing.expect(approxEqAbs(T, min_value, 0.0, eps_value * 2));
try testing.expect(approxEqAbs(T, -min_value, 0.0, eps_value * 2));
}
comptime {
// `comptime_float` is guaranteed to have the same precision and operations of
// the largest other floating point type, which is f128 but it doesn't have a
// defined layout so we can't rely on `@bitCast` to construct the smallest
// possible epsilon value like we do in the tests above. In the same vein, we
// also can't represent a max/min, `NaN` or `Inf` values.
const eps_value = 1e-4;
try testing.expect(approxEqAbs(comptime_float, 0.0, 0.0, eps_value));
try testing.expect(approxEqAbs(comptime_float, -0.0, -0.0, eps_value));
try testing.expect(approxEqAbs(comptime_float, 0.0, -0.0, eps_value));
try testing.expect(!approxEqAbs(comptime_float, 1.0 + 2 * eps_value, 1.0, eps_value));
try testing.expect(approxEqAbs(comptime_float, 1.0 + 1 * eps_value, 1.0, eps_value));
}
}
test approxEqRel {
inline for ([_]type{ f16, f32, f64, f128 }) |T| {
const eps_value = comptime floatEps(T);
const sqrt_eps_value = comptime sqrt(eps_value);
const nan_value = comptime nan(T);
const inf_value = comptime inf(T);
const min_value = comptime floatMin(T);
try testing.expect(approxEqRel(T, 1.0, 1.0, sqrt_eps_value));
try testing.expect(!approxEqRel(T, 1.0, 0.0, sqrt_eps_value));
try testing.expect(!approxEqRel(T, 1.0, nan_value, sqrt_eps_value));
try testing.expect(!approxEqRel(T, nan_value, nan_value, sqrt_eps_value));
try testing.expect(approxEqRel(T, inf_value, inf_value, sqrt_eps_value));
try testing.expect(approxEqRel(T, min_value, min_value, sqrt_eps_value));
try testing.expect(approxEqRel(T, -min_value, -min_value, sqrt_eps_value));
}
comptime {
// `comptime_float` is guaranteed to have the same precision and operations of
// the largest other floating point type, which is f128 but it doesn't have a
// defined layout so we can't rely on `@bitCast` to construct the smallest
// possible epsilon value like we do in the tests above. In the same vein, we
// also can't represent a max/min, `NaN` or `Inf` values.
const eps_value = 1e-4;
const sqrt_eps_value = sqrt(eps_value);
try testing.expect(approxEqRel(comptime_float, 1.0, 1.0, sqrt_eps_value));
try testing.expect(!approxEqRel(comptime_float, 1.0, 0.0, sqrt_eps_value));
}
}
pub fn raiseInvalid() void {
// Raise INVALID fpu exception
}
pub fn raiseUnderflow() void {
// Raise UNDERFLOW fpu exception
}
pub fn raiseOverflow() void {
// Raise OVERFLOW fpu exception
}
pub fn raiseInexact() void {
// Raise INEXACT fpu exception
}
pub fn raiseDivByZero() void {
// Raise INEXACT fpu exception
}
pub const isNan = @import("math/isnan.zig").isNan;
pub const isSignalNan = @import("math/isnan.zig").isSignalNan;
pub const frexp = @import("math/frexp.zig").frexp;
pub const Frexp = @import("math/frexp.zig").Frexp;
pub const modf = @import("math/modf.zig").modf;
pub const Modf = @import("math/modf.zig").Modf;
pub const copysign = @import("math/copysign.zig").copysign;
pub const isFinite = @import("math/isfinite.zig").isFinite;
pub const isInf = @import("math/isinf.zig").isInf;
pub const isPositiveInf = @import("math/isinf.zig").isPositiveInf;
pub const isNegativeInf = @import("math/isinf.zig").isNegativeInf;
pub const isPositiveZero = @import("math/iszero.zig").isPositiveZero;
pub const isNegativeZero = @import("math/iszero.zig").isNegativeZero;
pub const isNormal = @import("math/isnormal.zig").isNormal;
pub const nextAfter = @import("math/nextafter.zig").nextAfter;
pub const signbit = @import("math/signbit.zig").signbit;
pub const scalbn = @import("math/scalbn.zig").scalbn;
pub const ldexp = @import("math/ldexp.zig").ldexp;
pub const pow = @import("math/pow.zig").pow;
pub const powi = @import("math/powi.zig").powi;
pub const sqrt = @import("math/sqrt.zig").sqrt;
pub const cbrt = @import("math/cbrt.zig").cbrt;
pub const acos = @import("math/acos.zig").acos;
pub const asin = @import("math/asin.zig").asin;
pub const atan = @import("math/atan.zig").atan;
pub const atan2 = @import("math/atan2.zig").atan2;
pub const hypot = @import("math/hypot.zig").hypot;
pub const expm1 = @import("math/expm1.zig").expm1;
pub const ilogb = @import("math/ilogb.zig").ilogb;
pub const log = @import("math/log.zig").log;
pub const log2 = @import("math/log2.zig").log2;
pub const log10 = @import("math/log10.zig").log10;
pub const log10_int = @import("math/log10.zig").log10_int;
pub const log_int = @import("math/log_int.zig").log_int;
pub const log1p = @import("math/log1p.zig").log1p;
pub const asinh = @import("math/asinh.zig").asinh;
pub const acosh = @import("math/acosh.zig").acosh;
pub const atanh = @import("math/atanh.zig").atanh;
pub const sinh = @import("math/sinh.zig").sinh;
pub const cosh = @import("math/cosh.zig").cosh;
pub const tanh = @import("math/tanh.zig").tanh;
pub const gcd = @import("math/gcd.zig").gcd;
pub const lcm = @import("math/lcm.zig").lcm;
pub const gamma = @import("math/gamma.zig").gamma;
pub const lgamma = @import("math/gamma.zig").lgamma;
/// Sine trigonometric function on a floating point number.
/// Uses a dedicated hardware instruction when available.
/// This is the same as calling the builtin @sin
pub inline fn sin(value: anytype) @TypeOf(value) {
return @sin(value);
}
/// Cosine trigonometric function on a floating point number.
/// Uses a dedicated hardware instruction when available.
/// This is the same as calling the builtin @cos
pub inline fn cos(value: anytype) @TypeOf(value) {
return @cos(value);
}
/// Tangent trigonometric function on a floating point number.
/// Uses a dedicated hardware instruction when available.
/// This is the same as calling the builtin @tan
pub inline fn tan(value: anytype) @TypeOf(value) {
return @tan(value);
}
/// Converts an angle in radians to degrees. T must be a float or comptime number or a vector of floats.
pub fn radiansToDegrees(ang: anytype) if (@TypeOf(ang) == comptime_int) comptime_float else @TypeOf(ang) {
const T = @TypeOf(ang);
switch (@typeInfo(T)) {
.float, .comptime_float, .comptime_int => return ang * deg_per_rad,
.vector => |V| if (@typeInfo(V.child) == .float) return ang * @as(T, @splat(deg_per_rad)),
else => {},
}
@compileError("Input must be float or a comptime number, or a vector of floats.");
}
test radiansToDegrees {
const zero: f32 = 0;
const half_pi: f32 = pi / 2.0;
const neg_quart_pi: f32 = -pi / 4.0;
const one_pi: f32 = pi;
const two_pi: f32 = 2.0 * pi;
try std.testing.expectApproxEqAbs(@as(f32, 0), radiansToDegrees(zero), 1e-6);
try std.testing.expectApproxEqAbs(@as(f32, 90), radiansToDegrees(half_pi), 1e-6);
try std.testing.expectApproxEqAbs(@as(f32, -45), radiansToDegrees(neg_quart_pi), 1e-6);
try std.testing.expectApproxEqAbs(@as(f32, 180), radiansToDegrees(one_pi), 1e-6);
try std.testing.expectApproxEqAbs(@as(f32, 360), radiansToDegrees(two_pi), 1e-6);
const result = radiansToDegrees(@Vector(4, f32){
half_pi,
neg_quart_pi,
one_pi,
two_pi,
});
try std.testing.expectApproxEqAbs(@as(f32, 90), result[0], 1e-6);
try std.testing.expectApproxEqAbs(@as(f32, -45), result[1], 1e-6);
try std.testing.expectApproxEqAbs(@as(f32, 180), result[2], 1e-6);
try std.testing.expectApproxEqAbs(@as(f32, 360), result[3], 1e-6);
}
/// Converts an angle in degrees to radians. T must be a float or comptime number or a vector of floats.
pub fn degreesToRadians(ang: anytype) if (@TypeOf(ang) == comptime_int) comptime_float else @TypeOf(ang) {
const T = @TypeOf(ang);
switch (@typeInfo(T)) {
.float, .comptime_float, .comptime_int => return ang * rad_per_deg,
.vector => |V| if (@typeInfo(V.child) == .float) return ang * @as(T, @splat(rad_per_deg)),
else => {},
}
@compileError("Input must be float or a comptime number, or a vector of floats.");
}
test degreesToRadians {
const ninety: f32 = 90;
const neg_two_seventy: f32 = -270;
const three_sixty: f32 = 360;
try std.testing.expectApproxEqAbs(@as(f32, pi / 2.0), degreesToRadians(ninety), 1e-6);
try std.testing.expectApproxEqAbs(@as(f32, -3 * pi / 2.0), degreesToRadians(neg_two_seventy), 1e-6);
try std.testing.expectApproxEqAbs(@as(f32, 2 * pi), degreesToRadians(three_sixty), 1e-6);
const result = degreesToRadians(@Vector(3, f32){
ninety,
neg_two_seventy,
three_sixty,
});
try std.testing.expectApproxEqAbs(@as(f32, pi / 2.0), result[0], 1e-6);
try std.testing.expectApproxEqAbs(@as(f32, -3 * pi / 2.0), result[1], 1e-6);
try std.testing.expectApproxEqAbs(@as(f32, 2 * pi), result[2], 1e-6);
}
/// Base-e exponential function on a floating point number.
/// Uses a dedicated hardware instruction when available.
/// This is the same as calling the builtin @exp
pub inline fn exp(value: anytype) @TypeOf(value) {
return @exp(value);
}
/// Base-2 exponential function on a floating point number.
/// Uses a dedicated hardware instruction when available.
/// This is the same as calling the builtin @exp2
pub inline fn exp2(value: anytype) @TypeOf(value) {
return @exp2(value);
}
pub const complex = @import("math/complex.zig");
pub const Complex = complex.Complex;
pub const big = @import("math/big.zig");
test {
_ = floatExponentBits;
_ = floatMantissaBits;
_ = floatFractionalBits;
_ = floatExponentMin;
_ = floatExponentMax;
_ = floatTrueMin;
_ = floatMin;
_ = floatMax;
_ = floatEps;
_ = inf;
_ = nan;
_ = snan;
_ = isNan;
_ = isSignalNan;
_ = frexp;
_ = Frexp;
_ = modf;
_ = Modf;
_ = copysign;
_ = isFinite;
_ = isInf;
_ = isPositiveInf;
_ = isNegativeInf;
_ = isNormal;
_ = nextAfter;
_ = signbit;
_ = scalbn;
_ = ldexp;
_ = pow;
_ = powi;
_ = sqrt;
_ = cbrt;
_ = acos;
_ = asin;
_ = atan;
_ = atan2;
_ = hypot;
_ = expm1;
_ = ilogb;
_ = log;
_ = log2;
_ = log10;
_ = log10_int;
_ = log_int;
_ = log1p;
_ = asinh;
_ = acosh;
_ = atanh;
_ = sinh;
_ = cosh;
_ = tanh;
_ = gcd;
_ = lcm;
_ = gamma;
_ = lgamma;
_ = complex;
_ = Complex;
_ = big;
}
/// Given two types, returns the smallest one which is capable of holding the
/// full range of the minimum value.
pub fn Min(comptime A: type, comptime B: type) type {
switch (@typeInfo(A)) {
.int => |a_info| switch (@typeInfo(B)) {
.int => |b_info| if (a_info.signedness == .unsigned and b_info.signedness == .unsigned) {
if (a_info.bits < b_info.bits) {
return A;
} else {
return B;
}
},
else => {},
},
else => {},
}
return @TypeOf(@as(A, 0) + @as(B, 0));
}
/// Odd sawtooth function
/// ```
/// |
/// / | / /
/// / |/ /
/// --/----/----/--
/// / /| /
/// / / | /
/// |
/// ```
/// Limit x to the half-open interval [-r, r).
pub fn wrap(x: anytype, r: anytype) @TypeOf(x) {
const info_x = @typeInfo(@TypeOf(x));
const info_r = @typeInfo(@TypeOf(r));
if (info_x == .int and info_x.int.signedness != .signed) {
@compileError("x must be floating point, comptime integer, or signed integer.");
}
switch (info_r) {
.int => {
// in the rare usecase of r not being comptime_int or float,
// take the penalty of having an intermediary type conversion,
// otherwise the alternative is to unwind iteratively to avoid overflow
const R = @Int(.signed, info_r.int.bits + 1);
const radius: if (info_r.int.signedness == .signed) @TypeOf(r) else R = r;
return @intCast(@mod(x - radius, 2 * @as(R, r)) - r); // provably impossible to overflow
},
else => {
return @mod(x - r, 2 * r) - r;
},
}
}
test wrap {
if (builtin.os.tag == .windows and builtin.cpu.arch == .x86 and builtin.abi == .msvc) {
// https://codeberg.org/ziglang/zig/issues/35520
return error.SkipZigTest;
}
// Within range
try testing.expect(wrap(@as(i32, -75), @as(i32, 180)) == -75);
try testing.expect(wrap(@as(i32, -75), @as(i32, -180)) == -75);
// Below
try testing.expect(wrap(@as(i32, -225), @as(i32, 180)) == 135);
try testing.expect(wrap(@as(i32, -225), @as(i32, -180)) == 135);
// Above
try testing.expect(wrap(@as(i32, 361), @as(i32, 180)) == 1);
try testing.expect(wrap(@as(i32, 361), @as(i32, -180)) == 1);
// One period, right limit, positive r
try testing.expect(wrap(@as(i32, 180), @as(i32, 180)) == -180);
// One period, left limit, positive r
try testing.expect(wrap(@as(i32, -180), @as(i32, 180)) == -180);
// One period, right limit, negative r
try testing.expect(wrap(@as(i32, 180), @as(i32, -180)) == 180);
// One period, left limit, negative r
try testing.expect(wrap(@as(i32, -180), @as(i32, -180)) == 180);
// Two periods, right limit, positive r
try testing.expect(wrap(@as(i32, 540), @as(i32, 180)) == -180);
// Two periods, left limit, positive r
try testing.expect(wrap(@as(i32, -540), @as(i32, 180)) == -180);
// Two periods, right limit, negative r
try testing.expect(wrap(@as(i32, 540), @as(i32, -180)) == 180);
// Two periods, left limit, negative r
try testing.expect(wrap(@as(i32, -540), @as(i32, -180)) == 180);
// Floating point
try testing.expect(wrap(@as(f32, 1.125), @as(f32, 1.0)) == -0.875);
try testing.expect(wrap(@as(f32, -127.5), @as(f32, 180)) == -127.5);
// Mix of comptime and non-comptime
var i: i32 = 1;
_ = &i;
try testing.expect(wrap(i, 10) == 1);
const limit: i32 = 180;
// Within range
try testing.expect(wrap(@as(i32, -75), limit) == -75);
// Below
try testing.expect(wrap(@as(i32, -225), limit) == 135);
// Above
try testing.expect(wrap(@as(i32, 361), limit) == 1);
}
/// Odd ramp function
/// ```
/// | _____
/// | /
/// |/
/// -------/-------
/// /|
/// _____/ |
/// |
/// ```
/// Limit val to the inclusive range [lower, upper].
pub fn clamp(val: anytype, lower: anytype, upper: anytype) @TypeOf(val, lower, upper) {
const T = @TypeOf(val, lower, upper);
switch (@typeInfo(T)) {
.int, .float, .comptime_int, .comptime_float => assert(lower <= upper),
.vector => |vinfo| switch (@typeInfo(vinfo.child)) {
.int, .float => assert(@reduce(.And, lower <= upper)),
else => @compileError("Expected vector of ints or floats, found " ++ @typeName(T)),
},
else => @compileError("Expected an int, float or vector of one, found " ++ @typeName(T)),
}
return @max(lower, @min(val, upper));
}
test clamp {
// Within range
try testing.expect(std.math.clamp(@as(i32, -1), @as(i32, -4), @as(i32, 7)) == -1);
// Below
try testing.expect(std.math.clamp(@as(i32, -5), @as(i32, -4), @as(i32, 7)) == -4);
// Above
try testing.expect(std.math.clamp(@as(i32, 8), @as(i32, -4), @as(i32, 7)) == 7);
// Floating point
try testing.expect(std.math.clamp(@as(f32, 1.1), @as(f32, 0.0), @as(f32, 1.0)) == 1.0);
try testing.expect(std.math.clamp(@as(f32, -127.5), @as(f32, -200), @as(f32, -100)) == -127.5);
// Vector
try testing.expect(@reduce(.And, std.math.clamp(@as(@Vector(3, f32), .{ 1.4, 15.23, 28.3 }), @as(@Vector(3, f32), .{ 9.8, 13.2, 15.6 }), @as(@Vector(3, f32), .{ 15.2, 22.8, 26.3 })) == @as(@Vector(3, f32), .{ 9.8, 15.23, 26.3 })));
// Mix of comptime and non-comptime
var i: i32 = 1;
_ = &i;
try testing.expect(std.math.clamp(i, 0, 1) == 1);
}
/// Returns the product of a and b. Returns an error on overflow.
pub fn mul(comptime T: type, a: T, b: T) (error{Overflow}!T) {
if (T == comptime_int) return a * b;
const ov = @mulWithOverflow(a, b);
if (ov[1] != 0) return error.Overflow;
return ov[0];
}
/// Returns the sum of a and b. Returns an error on overflow.
pub fn add(comptime T: type, a: T, b: T) (error{Overflow}!T) {
if (T == comptime_int) return a + b;
const ov = @addWithOverflow(a, b);
if (ov[1] != 0) return error.Overflow;
return ov[0];
}
/// Returns a - b, or an error on overflow.
pub fn sub(comptime T: type, a: T, b: T) (error{Overflow}!T) {
if (T == comptime_int) return a - b;
const ov = @subWithOverflow(a, b);
if (ov[1] != 0) return error.Overflow;
return ov[0];
}
pub fn negate(x: anytype) !@TypeOf(x) {
return sub(@TypeOf(x), 0, x);
}
/// Shifts a left by shift_amt. Returns an error on overflow. shift_amt
/// is unsigned.
pub fn shlExact(comptime T: type, a: T, shift_amt: Log2Int(T)) !T {
if (T == comptime_int) return a << shift_amt;
const ov = @shlWithOverflow(a, shift_amt);
if (ov[1] != 0) return error.Overflow;
return ov[0];
}
/// Shifts left. Overflowed bits are truncated.
/// A negative shift amount results in a right shift.
pub fn shl(comptime T: type, a: T, shift_amt: anytype) T {
const is_shl = shift_amt >= 0;
const abs_shift_amt = @abs(shift_amt);
const casted_shift_amt = casted_shift_amt: switch (@typeInfo(T)) {
.int => |info| {
if (abs_shift_amt < info.bits) break :casted_shift_amt @as(
Log2Int(T),
@intCast(abs_shift_amt),
);
if (info.signedness == .unsigned or is_shl) return 0;
return a >> (info.bits - 1);
},
.vector => |info| {
const Child = info.child;
const child_info = @typeInfo(Child).int;
if (abs_shift_amt < child_info.bits) break :casted_shift_amt @as(
@Vector(info.len, Log2Int(Child)),
@splat(@as(Log2Int(Child), @intCast(abs_shift_amt))),
);
if (child_info.signedness == .unsigned or is_shl) return @splat(0);
return a >> @splat(child_info.bits - 1);
},
else => comptime unreachable,
};
return if (is_shl) a << casted_shift_amt else a >> casted_shift_amt;
}
test shl {
try testing.expect(shl(u8, 0b11111111, @as(usize, 3)) == 0b11111000);
try testing.expect(shl(u8, 0b11111111, @as(usize, 8)) == 0);
try testing.expect(shl(u8, 0b11111111, @as(usize, 9)) == 0);
try testing.expect(shl(u8, 0b11111111, @as(isize, -2)) == 0b00111111);
try testing.expect(shl(u8, 0b11111111, 3) == 0b11111000);
try testing.expect(shl(u8, 0b11111111, 8) == 0);
try testing.expect(shl(u8, 0b11111111, 9) == 0);
try testing.expect(shl(u8, 0b11111111, -2) == 0b00111111);
try testing.expect(shl(@Vector(1, u32), @Vector(1, u32){42}, @as(usize, 1))[0] == @as(u32, 42) << 1);
try testing.expect(shl(@Vector(1, u32), @Vector(1, u32){42}, @as(isize, -1))[0] == @as(u32, 42) >> 1);
try testing.expect(shl(@Vector(1, u32), @Vector(1, u32){42}, 33)[0] == 0);
try testing.expect(shl(i8, -1, -100) == -1);
try testing.expect(shl(i8, -1, 100) == 0);
if (builtin.cpu.arch == .hexagon and builtin.zig_backend == .stage2_llvm) return error.SkipZigTest;
try testing.expect(@reduce(.And, shl(@Vector(2, i8), .{ -1, 1 }, -100) == @Vector(2, i8){ -1, 0 }));
try testing.expect(@reduce(.And, shl(@Vector(2, i8), .{ -1, 1 }, 100) == @Vector(2, i8){ 0, 0 }));
}
/// Shifts right. Overflowed bits are truncated.
/// A negative shift amount results in a left shift.
pub fn shr(comptime T: type, a: T, shift_amt: anytype) T {
const is_shl = shift_amt < 0;
const abs_shift_amt = @abs(shift_amt);
const casted_shift_amt = casted_shift_amt: switch (@typeInfo(T)) {
.int => |info| {
if (abs_shift_amt < info.bits) break :casted_shift_amt @as(
Log2Int(T),
@intCast(abs_shift_amt),
);
if (info.signedness == .unsigned or is_shl) return 0;
return a >> (info.bits - 1);
},
.vector => |info| {
const Child = info.child;
const child_info = @typeInfo(Child).int;
if (abs_shift_amt < child_info.bits) break :casted_shift_amt @as(
@Vector(info.len, Log2Int(Child)),
@splat(@as(Log2Int(Child), @intCast(abs_shift_amt))),
);
if (child_info.signedness == .unsigned or is_shl) return @splat(0);
return a >> @splat(child_info.bits - 1);
},
else => comptime unreachable,
};
return if (is_shl) a << casted_shift_amt else a >> casted_shift_amt;
}
test shr {
try testing.expect(shr(u8, 0b11111111, @as(usize, 3)) == 0b00011111);
try testing.expect(shr(u8, 0b11111111, @as(usize, 8)) == 0);
try testing.expect(shr(u8, 0b11111111, @as(usize, 9)) == 0);
try testing.expect(shr(u8, 0b11111111, @as(isize, -2)) == 0b11111100);
try testing.expect(shr(u8, 0b11111111, 3) == 0b00011111);
try testing.expect(shr(u8, 0b11111111, 8) == 0);
try testing.expect(shr(u8, 0b11111111, 9) == 0);
try testing.expect(shr(u8, 0b11111111, -2) == 0b11111100);
try testing.expect(shr(@Vector(1, u32), @Vector(1, u32){42}, @as(usize, 1))[0] == @as(u32, 42) >> 1);
try testing.expect(shr(@Vector(1, u32), @Vector(1, u32){42}, @as(isize, -1))[0] == @as(u32, 42) << 1);
try testing.expect(shr(@Vector(1, u32), @Vector(1, u32){42}, 33)[0] == 0);
try testing.expect(shr(i8, -1, -100) == 0);
try testing.expect(shr(i8, -1, 100) == -1);
if (builtin.cpu.arch == .hexagon and builtin.zig_backend == .stage2_llvm) return error.SkipZigTest;
try testing.expect(@reduce(.And, shr(@Vector(2, i8), .{ -1, 1 }, -100) == @Vector(2, i8){ 0, 0 }));
try testing.expect(@reduce(.And, shr(@Vector(2, i8), .{ -1, 1 }, 100) == @Vector(2, i8){ -1, 0 }));
}
/// Rotates right. Only unsigned values can be rotated. Negative shift
/// values result in shift modulo the bit count.
pub fn rotr(comptime T: type, x: T, r: anytype) T {
if (@typeInfo(T) == .vector) {
const C = @typeInfo(T).vector.child;
if (C == u0) return @splat(0);
if (@typeInfo(C).int.signedness == .signed) {
@compileError("cannot rotate signed integers");
}
const ar: Log2Int(C) = @intCast(@mod(r, @typeInfo(C).int.bits));
return (x >> @splat(ar)) | (x << @splat(1 + ~ar));
} else if (@typeInfo(T).int.signedness == .signed) {
@compileError("cannot rotate signed integer");
} else {
if (T == u0) return 0;
if (comptime isPowerOfTwo(@typeInfo(T).int.bits)) {
const ar: Log2Int(T) = @intCast(@mod(r, @typeInfo(T).int.bits));
return x >> ar | x << (1 +% ~ar);
} else {
const ar = @mod(r, @typeInfo(T).int.bits);
return shr(T, x, ar) | shl(T, x, @typeInfo(T).int.bits - ar);
}
}
}
test rotr {
try testing.expect(rotr(u0, 0b0, @as(usize, 3)) == 0b0);
try testing.expect(rotr(u5, 0b00001, @as(usize, 0)) == 0b00001);
try testing.expect(rotr(u6, 0b000001, @as(usize, 7)) == 0b100000);
try testing.expect(rotr(u8, 0b00000001, @as(usize, 0)) == 0b00000001);
try testing.expect(rotr(u8, 0b00000001, @as(usize, 9)) == 0b10000000);
try testing.expect(rotr(u8, 0b00000001, @as(usize, 8)) == 0b00000001);
try testing.expect(rotr(u8, 0b00000001, @as(usize, 4)) == 0b00010000);
try testing.expect(rotr(u8, 0b00000001, @as(isize, -1)) == 0b00000010);
try testing.expect(rotr(u12, 0o7777, 1) == 0o7777);
try testing.expect(rotr(@Vector(1, u32), .{1}, @as(usize, 1))[0] == @as(u32, 1) << 31);
try testing.expect(rotr(@Vector(1, u32), .{1}, @as(isize, -1))[0] == @as(u32, 1) << 1);
try std.testing.expect(@reduce(.And, rotr(@Vector(2, u0), .{ 0, 0 }, @as(usize, 42)) ==
@Vector(2, u0){ 0, 0 }));
}
/// Rotates left. Only unsigned values can be rotated. Negative shift
/// values result in shift modulo the bit count.
pub fn rotl(comptime T: type, x: T, r: anytype) T {
if (@typeInfo(T) == .vector) {
const C = @typeInfo(T).vector.child;
if (C == u0) return @splat(0);
if (@typeInfo(C).int.signedness == .signed) {
@compileError("cannot rotate signed integers");
}
const ar: Log2Int(C) = @intCast(@mod(r, @typeInfo(C).int.bits));
return (x << @splat(ar)) | (x >> @splat(1 +% ~ar));
} else if (@typeInfo(T).int.signedness == .signed) {
@compileError("cannot rotate signed integer");
} else {
if (T == u0) return 0;
if (comptime isPowerOfTwo(@typeInfo(T).int.bits)) {
const ar: Log2Int(T) = @intCast(@mod(r, @typeInfo(T).int.bits));
return x << ar | x >> 1 +% ~ar;
} else {
const ar = @mod(r, @typeInfo(T).int.bits);
return shl(T, x, ar) | shr(T, x, @typeInfo(T).int.bits - ar);
}
}
}
test rotl {
try testing.expect(rotl(u0, 0b0, @as(usize, 3)) == 0b0);
try testing.expect(rotl(u5, 0b00001, @as(usize, 0)) == 0b00001);
try testing.expect(rotl(u6, 0b000001, @as(usize, 7)) == 0b000010);
try testing.expect(rotl(u8, 0b00000001, @as(usize, 0)) == 0b00000001);
try testing.expect(rotl(u8, 0b00000001, @as(usize, 9)) == 0b00000010);
try testing.expect(rotl(u8, 0b00000001, @as(usize, 8)) == 0b00000001);
try testing.expect(rotl(u8, 0b00000001, @as(usize, 4)) == 0b00010000);
try testing.expect(rotl(u8, 0b00000001, @as(isize, -1)) == 0b10000000);
try testing.expect(rotl(u12, 0o7777, 1) == 0o7777);
try testing.expect(rotl(@Vector(1, u32), .{1 << 31}, @as(usize, 1))[0] == 1);
try testing.expect(rotl(@Vector(1, u32), .{1 << 31}, @as(isize, -1))[0] == @as(u32, 1) << 30);
try std.testing.expect(@reduce(.And, rotl(@Vector(2, u0), .{ 0, 0 }, @as(usize, 42)) ==
@Vector(2, u0){ 0, 0 }));
}
/// Returns an unsigned int type that can hold the number of bits in T - 1.
/// Suitable for 0-based bit indices of T.
pub fn Log2Int(comptime T: type) type {
// comptime ceil log2
if (T == comptime_int) return comptime_int;
const bits: u16 = @typeInfo(T).int.bits;
const log2_bits = 16 - @clz(bits - 1);
return @Int(.unsigned, log2_bits);
}
/// Returns an unsigned int type that can hold the number of bits in T.
pub fn Log2IntCeil(comptime T: type) type {
// comptime ceil log2
if (T == comptime_int) return comptime_int;
const bits: u16 = @typeInfo(T).int.bits;
const log2_bits = 16 - @clz(bits);
return @Int(.unsigned, log2_bits);
}
/// Returns the smallest integer type that can hold both from and to.
pub fn IntFittingRange(comptime from: comptime_int, comptime to: comptime_int) type {
assert(from <= to);
const signedness: std.builtin.Signedness = if (from < 0) .signed else .unsigned;
return @Int(
signedness,
@as(u16, @intFromBool(signedness == .signed)) +
switch (if (from < 0) @max(@abs(from) - 1, to) else to) {
0 => 0,
else => |pos_max| 1 + log2(pos_max),
},
);
}
test IntFittingRange {
try testing.expect(IntFittingRange(0, 0) == u0);
try testing.expect(IntFittingRange(0, 1) == u1);
try testing.expect(IntFittingRange(0, 2) == u2);
try testing.expect(IntFittingRange(0, 3) == u2);
try testing.expect(IntFittingRange(0, 4) == u3);
try testing.expect(IntFittingRange(0, 7) == u3);
try testing.expect(IntFittingRange(0, 8) == u4);
try testing.expect(IntFittingRange(0, 9) == u4);
try testing.expect(IntFittingRange(0, 15) == u4);
try testing.expect(IntFittingRange(0, 16) == u5);
try testing.expect(IntFittingRange(0, 17) == u5);
try testing.expect(IntFittingRange(0, 4095) == u12);
try testing.expect(IntFittingRange(2000, 4095) == u12);
try testing.expect(IntFittingRange(0, 4096) == u13);
try testing.expect(IntFittingRange(2000, 4096) == u13);
try testing.expect(IntFittingRange(0, 4097) == u13);
try testing.expect(IntFittingRange(2000, 4097) == u13);
try testing.expect(IntFittingRange(0, 123456789123456798123456789) == u87);
try testing.expect(IntFittingRange(0, 123456789123456798123456789123456789123456798123456789) == u177);
try testing.expect(IntFittingRange(-1, -1) == i1);
try testing.expect(IntFittingRange(-1, 0) == i1);
try testing.expect(IntFittingRange(-1, 1) == i2);
try testing.expect(IntFittingRange(-2, -2) == i2);
try testing.expect(IntFittingRange(-2, -1) == i2);
try testing.expect(IntFittingRange(-2, 0) == i2);
try testing.expect(IntFittingRange(-2, 1) == i2);
try testing.expect(IntFittingRange(-2, 2) == i3);
try testing.expect(IntFittingRange(-1, 2) == i3);
try testing.expect(IntFittingRange(-1, 3) == i3);
try testing.expect(IntFittingRange(-1, 4) == i4);
try testing.expect(IntFittingRange(-1, 7) == i4);
try testing.expect(IntFittingRange(-1, 8) == i5);
try testing.expect(IntFittingRange(-1, 9) == i5);
try testing.expect(IntFittingRange(-1, 15) == i5);
try testing.expect(IntFittingRange(-1, 16) == i6);
try testing.expect(IntFittingRange(-1, 17) == i6);
try testing.expect(IntFittingRange(-1, 4095) == i13);
try testing.expect(IntFittingRange(-4096, 4095) == i13);
try testing.expect(IntFittingRange(-1, 4096) == i14);
try testing.expect(IntFittingRange(-4097, 4095) == i14);
try testing.expect(IntFittingRange(-1, 4097) == i14);
try testing.expect(IntFittingRange(-1, 123456789123456798123456789) == i88);
try testing.expect(IntFittingRange(-1, 123456789123456798123456789123456789123456798123456789) == i178);
}
test "overflow functions" {
try testOverflow();
try comptime testOverflow();
}
fn testOverflow() !void {
try testing.expect((mul(i32, 3, 4) catch unreachable) == 12);
try testing.expect((add(i32, 3, 4) catch unreachable) == 7);
try testing.expect((sub(i32, 3, 4) catch unreachable) == -1);
try testing.expect((shlExact(i32, 0b11, 4) catch unreachable) == 0b110000);
}
/// Divide numerator by denominator, rounding toward zero. Returns an
/// error on overflow or when denominator is zero.
pub fn divTrunc(comptime T: type, numerator: T, denominator: T) !T {
@setRuntimeSafety(false);
if (denominator == 0) return error.DivisionByZero;
if (@typeInfo(T) == .int and @typeInfo(T).int.signedness == .signed and numerator == minInt(T) and denominator == -1) return error.Overflow;
return @divTrunc(numerator, denominator);
}
test divTrunc {
try testDivTrunc();
try comptime testDivTrunc();
}
fn testDivTrunc() !void {
try testing.expect((divTrunc(i32, 5, 3) catch unreachable) == 1);
try testing.expect((divTrunc(i32, -5, 3) catch unreachable) == -1);
try testing.expectError(error.DivisionByZero, divTrunc(i8, -5, 0));
try testing.expectError(error.Overflow, divTrunc(i8, -128, -1));
try testing.expect((divTrunc(f32, 5.0, 3.0) catch unreachable) == 1.0);
try testing.expect((divTrunc(f32, -5.0, 3.0) catch unreachable) == -1.0);
}
/// Divide numerator by denominator, rounding toward negative
/// infinity. Returns an error on overflow or when denominator is
/// zero.
pub fn divFloor(comptime T: type, numerator: T, denominator: T) !T {
@setRuntimeSafety(false);
if (denominator == 0) return error.DivisionByZero;
if (@typeInfo(T) == .int and @typeInfo(T).int.signedness == .signed and numerator == minInt(T) and denominator == -1) return error.Overflow;
return @divFloor(numerator, denominator);
}
test divFloor {
try testDivFloor();
try comptime testDivFloor();
}
fn testDivFloor() !void {
try testing.expect((divFloor(i32, 5, 3) catch unreachable) == 1);
try testing.expect((divFloor(i32, -5, 3) catch unreachable) == -2);
try testing.expectError(error.DivisionByZero, divFloor(i8, -5, 0));
try testing.expectError(error.Overflow, divFloor(i8, -128, -1));
try testing.expect((divFloor(f32, 5.0, 3.0) catch unreachable) == 1.0);
try testing.expect((divFloor(f32, -5.0, 3.0) catch unreachable) == -2.0);
}
/// Divide numerator by denominator, rounding toward positive
/// infinity. Returns an error on overflow or when denominator is
/// zero.
pub fn divCeil(comptime T: type, numerator: T, denominator: T) !T {
@setRuntimeSafety(false);
if (denominator == 0) return error.DivisionByZero;
if (@typeInfo(T) == .int and numerator == minInt(T) and denominator == -1) {
return error.Overflow;
}
return @divCeil(numerator, denominator);
}
test divCeil {
try testDivCeil();
try comptime testDivCeil();
}
fn testDivCeil() !void {
try testing.expectEqual(@as(i32, 2), divCeil(i32, 5, 3) catch unreachable);
try testing.expectEqual(@as(i32, -1), divCeil(i32, -5, 3) catch unreachable);
try testing.expectEqual(@as(i32, -1), divCeil(i32, 5, -3) catch unreachable);
try testing.expectEqual(@as(i32, 2), divCeil(i32, -5, -3) catch unreachable);
try testing.expectEqual(@as(i32, 0), divCeil(i32, 0, 5) catch unreachable);
try testing.expectEqual(@as(u32, 0), divCeil(u32, 0, 5) catch unreachable);
try testing.expectError(error.DivisionByZero, divCeil(i8, -5, 0));
try testing.expectError(error.Overflow, divCeil(i8, -128, -1));
try testing.expectEqual(@as(f32, 0.0), divCeil(f32, 0.0, 5.0) catch unreachable);
try testing.expectEqual(@as(f32, 2.0), divCeil(f32, 5.0, 3.0) catch unreachable);
try testing.expectEqual(@as(f32, -1.0), divCeil(f32, -5.0, 3.0) catch unreachable);
try testing.expectEqual(@as(f32, -1.0), divCeil(f32, 5.0, -3.0) catch unreachable);
try testing.expectEqual(@as(f32, 2.0), divCeil(f32, -5.0, -3.0) catch unreachable);
try testing.expectEqual(6, divCeil(comptime_int, 23, 4) catch unreachable);
try testing.expectEqual(-5, divCeil(comptime_int, -23, 4) catch unreachable);
try testing.expectEqual(-5, divCeil(comptime_int, 23, -4) catch unreachable);
try testing.expectEqual(6, divCeil(comptime_int, -23, -4) catch unreachable);
try testing.expectError(error.DivisionByZero, divCeil(comptime_int, 23, 0));
try testing.expectEqual(6.0, divCeil(comptime_float, 23.0, 4.0) catch unreachable);
try testing.expectEqual(-5.0, divCeil(comptime_float, -23.0, 4.0) catch unreachable);
try testing.expectEqual(-5.0, divCeil(comptime_float, 23.0, -4.0) catch unreachable);
try testing.expectEqual(6.0, divCeil(comptime_float, -23.0, -4.0) catch unreachable);
try testing.expectError(error.DivisionByZero, divCeil(comptime_float, 23.0, 0.0));
}
/// Divide numerator by denominator. Return an error if quotient is
/// not an integer, denominator is zero, or on overflow.
pub fn divExact(comptime T: type, numerator: T, denominator: T) !T {
@setRuntimeSafety(false);
if (denominator == 0) return error.DivisionByZero;
if (@typeInfo(T) == .int and @typeInfo(T).int.signedness == .signed and numerator == minInt(T) and denominator == -1) return error.Overflow;
const result = @divTrunc(numerator, denominator);
if (result * denominator != numerator) return error.UnexpectedRemainder;
return result;
}
test divExact {
try testDivExact();
try comptime testDivExact();
}
fn testDivExact() !void {
try testing.expect((divExact(i32, 10, 5) catch unreachable) == 2);
try testing.expect((divExact(i32, -10, 5) catch unreachable) == -2);
try testing.expectError(error.DivisionByZero, divExact(i8, -5, 0));
try testing.expectError(error.Overflow, divExact(i8, -128, -1));
try testing.expectError(error.UnexpectedRemainder, divExact(i32, 5, 2));
try testing.expect((divExact(f32, 10.0, 5.0) catch unreachable) == 2.0);
try testing.expect((divExact(f32, -10.0, 5.0) catch unreachable) == -2.0);
try testing.expectError(error.UnexpectedRemainder, divExact(f32, 5.0, 2.0));
}
/// Returns numerator modulo denominator, or an error if denominator is
/// zero or negative. Negative numerators never result in negative
/// return values.
pub fn mod(comptime T: type, numerator: T, denominator: T) !T {
@setRuntimeSafety(false);
if (denominator == 0) return error.DivisionByZero;
if (denominator < 0) return error.NegativeDenominator;
return @mod(numerator, denominator);
}
test mod {
try testMod();
try comptime testMod();
}
fn testMod() !void {
try testing.expect((mod(i32, -5, 3) catch unreachable) == 1);
try testing.expect((mod(i32, 5, 3) catch unreachable) == 2);
try testing.expectError(error.NegativeDenominator, mod(i32, 10, -1));
try testing.expectError(error.DivisionByZero, mod(i32, 10, 0));
try testing.expect((mod(f32, -5, 3) catch unreachable) == 1);
try testing.expect((mod(f32, 5, 3) catch unreachable) == 2);
try testing.expectError(error.NegativeDenominator, mod(f32, 10, -1));
try testing.expectError(error.DivisionByZero, mod(f32, 10, 0));
}
/// Returns the remainder when numerator is divided by denominator, or
/// an error if denominator is zero or negative. Negative numerators
/// can give negative results.
pub fn rem(comptime T: type, numerator: T, denominator: T) !T {
@setRuntimeSafety(false);
if (denominator == 0) return error.DivisionByZero;
if (denominator < 0) return error.NegativeDenominator;
return @rem(numerator, denominator);
}
test rem {
try testRem();
try comptime testRem();
}
fn testRem() !void {
try testing.expect((rem(i32, -5, 3) catch unreachable) == -2);
try testing.expect((rem(i32, 5, 3) catch unreachable) == 2);
try testing.expectError(error.NegativeDenominator, rem(i32, 10, -1));
try testing.expectError(error.DivisionByZero, rem(i32, 10, 0));
try testing.expect((rem(f32, -5, 3) catch unreachable) == -2);
try testing.expect((rem(f32, 5, 3) catch unreachable) == 2);
try testing.expectError(error.NegativeDenominator, rem(f32, 10, -1));
try testing.expectError(error.DivisionByZero, rem(f32, 10, 0));
}
/// Returns the negation of the integer parameter.
/// Result is a signed integer.
pub fn negateCast(x: anytype) !@Int(.signed, @bitSizeOf(@TypeOf(x))) {
if (@typeInfo(@TypeOf(x)).int.signedness == .signed) return negate(x);
const int = @Int(.signed, @bitSizeOf(@TypeOf(x)));
if (x > -minInt(int)) return error.Overflow;
if (x == -minInt(int)) return minInt(int);
return -@as(int, @intCast(x));
}
test negateCast {
try testing.expect((negateCast(@as(u32, 999)) catch unreachable) == -999);
try testing.expect(@TypeOf(negateCast(@as(u32, 999)) catch unreachable) == i32);
try testing.expect((negateCast(@as(u32, -minInt(i32))) catch unreachable) == minInt(i32));
try testing.expect(@TypeOf(negateCast(@as(u32, -minInt(i32))) catch unreachable) == i32);
try testing.expectError(error.Overflow, negateCast(@as(u32, maxInt(i32) + 10)));
}
/// Cast an integer to a different integer type. If the value doesn't fit,
/// return null.
pub fn cast(comptime T: type, x: anytype) ?T {
comptime assert(@typeInfo(T) == .int); // must pass an integer
const is_comptime = @TypeOf(x) == comptime_int;
comptime assert(is_comptime or @typeInfo(@TypeOf(x)) == .int); // must pass an integer
if ((is_comptime or maxInt(@TypeOf(x)) > maxInt(T)) and x > maxInt(T)) {
return null;
} else if ((is_comptime or minInt(@TypeOf(x)) < minInt(T)) and x < minInt(T)) {
return null;
} else {
return @as(T, @intCast(x));
}
}
test cast {
try testing.expect(cast(u8, 300) == null);
try testing.expect(cast(u8, @as(u32, 300)) == null);
try testing.expect(cast(i8, -200) == null);
try testing.expect(cast(i8, @as(i32, -200)) == null);
try testing.expect(cast(u8, -1) == null);
try testing.expect(cast(u8, @as(i8, -1)) == null);
try testing.expect(cast(u64, -1) == null);
try testing.expect(cast(u64, @as(i8, -1)) == null);
try testing.expect(cast(u8, 255).? == @as(u8, 255));
try testing.expect(cast(u8, @as(u32, 255)).? == @as(u8, 255));
try testing.expect(@TypeOf(cast(u8, 255).?) == u8);
try testing.expect(@TypeOf(cast(u8, @as(u32, 255)).?) == u8);
}
pub const AlignCastError = error{UnalignedMemory};
fn AlignCastResult(comptime alignment: Alignment, comptime Ptr: type) type {
const orig = @typeInfo(Ptr).pointer;
return @Pointer(orig.size, .{
.@"const" = orig.is_const,
.@"volatile" = orig.is_volatile,
.@"allowzero" = orig.is_allowzero,
.@"align" = alignment.toByteUnits(),
.@"addrspace" = orig.address_space,
}, orig.child, orig.sentinel());
}
/// Align cast a pointer but return an error if it's the wrong alignment
pub fn alignCast(comptime alignment: Alignment, ptr: anytype) AlignCastError!AlignCastResult(alignment, @TypeOf(ptr)) {
if (alignment.check(@intFromPtr(ptr))) return @alignCast(ptr);
return error.UnalignedMemory;
}
/// Asserts `int > 0`.
pub fn isPowerOfTwo(int: anytype) bool {
assert(int > 0);
return (int & (int - 1)) == 0;
}
test isPowerOfTwo {
try testing.expect(isPowerOfTwo(@as(u8, 1)));
try testing.expect(isPowerOfTwo(2));
try testing.expect(!isPowerOfTwo(@as(i16, 3)));
try testing.expect(isPowerOfTwo(4));
try testing.expect(!isPowerOfTwo(@as(u32, 31)));
try testing.expect(isPowerOfTwo(32));
try testing.expect(!isPowerOfTwo(@as(i64, 63)));
try testing.expect(isPowerOfTwo(128));
try testing.expect(isPowerOfTwo(@as(u128, 256)));
}
/// Aligns the given integer type bit width to a width divisible by 8.
pub fn ByteAlignedInt(comptime T: type) type {
const info = @typeInfo(T).int;
const bits = (info.bits + 7) / 8 * 8;
return @Int(info.signedness, bits);
}
test ByteAlignedInt {
try testing.expect(ByteAlignedInt(u0) == u0);
try testing.expect(ByteAlignedInt(u3) == u8);
try testing.expect(ByteAlignedInt(u8) == u8);
try testing.expect(ByteAlignedInt(i111) == i112);
try testing.expect(ByteAlignedInt(u129) == u136);
}
/// Rounds the given floating point number to the nearest integer.
/// If two integers are equally close, rounds away from zero.
/// Uses a dedicated hardware instruction when available.
/// This is the same as calling the builtin @round
pub inline fn round(value: anytype) @TypeOf(value) {
return @round(value);
}
/// Rounds the given floating point number to an integer, towards zero.
/// Uses a dedicated hardware instruction when available.
/// This is the same as calling the builtin @trunc
pub inline fn trunc(value: anytype) @TypeOf(value) {
return @trunc(value);
}
/// Returns the largest integral value not greater than the given floating point number.
/// Uses a dedicated hardware instruction when available.
/// This is the same as calling the builtin @floor
pub inline fn floor(value: anytype) @TypeOf(value) {
return @floor(value);
}
/// Returns the nearest power of two less than or equal to value, or
/// zero if value is less than or equal to zero.
pub fn floorPowerOfTwo(comptime T: type, value: T) T {
const uT = @Int(.unsigned, @typeInfo(T).int.bits);
if (value <= 0) return 0;
return @as(T, 1) << log2_int(uT, @as(uT, @intCast(value)));
}
test floorPowerOfTwo {
try testFloorPowerOfTwo();
try comptime testFloorPowerOfTwo();
}
fn testFloorPowerOfTwo() !void {
try testing.expect(floorPowerOfTwo(u32, 63) == 32);
try testing.expect(floorPowerOfTwo(u32, 64) == 64);
try testing.expect(floorPowerOfTwo(u32, 65) == 64);
try testing.expect(floorPowerOfTwo(u32, 0) == 0);
try testing.expect(floorPowerOfTwo(u4, 7) == 4);
try testing.expect(floorPowerOfTwo(u4, 8) == 8);
try testing.expect(floorPowerOfTwo(u4, 9) == 8);
try testing.expect(floorPowerOfTwo(u4, 0) == 0);
try testing.expect(floorPowerOfTwo(i4, 7) == 4);
try testing.expect(floorPowerOfTwo(i4, -8) == 0);
try testing.expect(floorPowerOfTwo(i4, -1) == 0);
try testing.expect(floorPowerOfTwo(i4, 0) == 0);
}
/// Returns the smallest integral value not less than the given floating point number.
/// Uses a dedicated hardware instruction when available.
/// This is the same as calling the builtin @ceil
pub inline fn ceil(value: anytype) @TypeOf(value) {
return @ceil(value);
}
/// Returns the next power of two (if the value is not already a power of two).
/// Only unsigned integers can be used. Zero is not an allowed input.
/// Result is a type with 1 more bit than the input type.
pub fn ceilPowerOfTwoPromote(comptime T: type, value: T) @Int(@typeInfo(T).int.signedness, @typeInfo(T).int.bits + 1) {
comptime assert(@typeInfo(T) == .int);
comptime assert(@typeInfo(T).int.signedness == .unsigned);
assert(value != 0);
const PromotedType = @Int(@typeInfo(T).int.signedness, @typeInfo(T).int.bits + 1);
const ShiftType = std.math.Log2Int(PromotedType);
return @as(PromotedType, 1) << @as(ShiftType, @intCast(@typeInfo(T).int.bits - @clz(value - 1)));
}
/// Returns the next power of two (if the value is not already a power of two).
/// Only unsigned integers can be used. Zero is not an allowed input.
/// If the value doesn't fit, returns an error.
pub fn ceilPowerOfTwo(comptime T: type, value: T) (error{Overflow}!T) {
comptime assert(@typeInfo(T) == .int);
const info = @typeInfo(T).int;
comptime assert(info.signedness == .unsigned);
const PromotedType = @Int(info.signedness, info.bits + 1);
const overflowBit = @as(PromotedType, 1) << info.bits;
const x = ceilPowerOfTwoPromote(T, value);
if (overflowBit & x != 0) {
return error.Overflow;
}
return @as(T, @intCast(x));
}
/// Returns the next power of two (if the value is not already a power
/// of two). Only unsigned integers can be used. Zero is not an
/// allowed input. Asserts that the value fits.
pub fn ceilPowerOfTwoAssert(comptime T: type, value: T) T {
return ceilPowerOfTwo(T, value) catch unreachable;
}
test ceilPowerOfTwoPromote {
try testCeilPowerOfTwoPromote();
try comptime testCeilPowerOfTwoPromote();
}
fn testCeilPowerOfTwoPromote() !void {
try testing.expectEqual(@as(u33, 1), ceilPowerOfTwoPromote(u32, 1));
try testing.expectEqual(@as(u33, 2), ceilPowerOfTwoPromote(u32, 2));
try testing.expectEqual(@as(u33, 64), ceilPowerOfTwoPromote(u32, 63));
try testing.expectEqual(@as(u33, 64), ceilPowerOfTwoPromote(u32, 64));
try testing.expectEqual(@as(u33, 128), ceilPowerOfTwoPromote(u32, 65));
try testing.expectEqual(@as(u6, 8), ceilPowerOfTwoPromote(u5, 7));
try testing.expectEqual(@as(u6, 8), ceilPowerOfTwoPromote(u5, 8));
try testing.expectEqual(@as(u6, 16), ceilPowerOfTwoPromote(u5, 9));
try testing.expectEqual(@as(u5, 16), ceilPowerOfTwoPromote(u4, 9));
}
test ceilPowerOfTwo {
try testCeilPowerOfTwo();
try comptime testCeilPowerOfTwo();
}
fn testCeilPowerOfTwo() !void {
try testing.expectEqual(@as(u32, 1), try ceilPowerOfTwo(u32, 1));
try testing.expectEqual(@as(u32, 2), try ceilPowerOfTwo(u32, 2));
try testing.expectEqual(@as(u32, 64), try ceilPowerOfTwo(u32, 63));
try testing.expectEqual(@as(u32, 64), try ceilPowerOfTwo(u32, 64));
try testing.expectEqual(@as(u32, 128), try ceilPowerOfTwo(u32, 65));
try testing.expectEqual(@as(u5, 8), try ceilPowerOfTwo(u5, 7));
try testing.expectEqual(@as(u5, 8), try ceilPowerOfTwo(u5, 8));
try testing.expectEqual(@as(u5, 16), try ceilPowerOfTwo(u5, 9));
try testing.expectError(error.Overflow, ceilPowerOfTwo(u4, 9));
}
/// Return the log base 2 of integer value x, rounding down to the
/// nearest integer.
pub fn log2_int(comptime T: type, x: T) Log2Int(T) {
if (@typeInfo(T) != .int or @typeInfo(T).int.signedness != .unsigned)
@compileError("log2_int requires an unsigned integer, found " ++ @typeName(T));
assert(x != 0);
return @as(Log2Int(T), @intCast(@typeInfo(T).int.bits - 1 - @clz(x)));
}
test log2_int {
try testing.expect(log2_int(u32, 1) == 0);
try testing.expect(log2_int(u32, 2) == 1);
try testing.expect(log2_int(u32, 3) == 1);
try testing.expect(log2_int(u32, 4) == 2);
try testing.expect(log2_int(u32, 5) == 2);
try testing.expect(log2_int(u32, 6) == 2);
try testing.expect(log2_int(u32, 7) == 2);
try testing.expect(log2_int(u32, 8) == 3);
try testing.expect(log2_int(u32, 9) == 3);
try testing.expect(log2_int(u32, 10) == 3);
}
/// Return the log base 2 of integer value x, rounding up to the
/// nearest integer.
pub fn log2_int_ceil(comptime T: type, x: T) Log2IntCeil(T) {
if (@typeInfo(T) != .int or @typeInfo(T).int.signedness != .unsigned)
@compileError("log2_int_ceil requires an unsigned integer, found " ++ @typeName(T));
assert(x != 0);
if (x == 1) return 0;
const log2_val: Log2IntCeil(T) = log2_int(T, x - 1);
return log2_val + 1;
}
test log2_int_ceil {
try testing.expect(log2_int_ceil(u32, 1) == 0);
try testing.expect(log2_int_ceil(u32, 2) == 1);
try testing.expect(log2_int_ceil(u32, 3) == 2);
try testing.expect(log2_int_ceil(u32, 4) == 2);
try testing.expect(log2_int_ceil(u32, 5) == 3);
try testing.expect(log2_int_ceil(u32, 6) == 3);
try testing.expect(log2_int_ceil(u32, 7) == 3);
try testing.expect(log2_int_ceil(u32, 8) == 3);
try testing.expect(log2_int_ceil(u32, 9) == 4);
try testing.expect(log2_int_ceil(u32, 10) == 4);
}
/// Cast a value to a different type. If the value doesn't fit in, or
/// can't be perfectly represented by, the new type, it will be
/// converted to the closest possible representation.
pub fn lossyCast(comptime T: type, value: anytype) T {
switch (@typeInfo(T)) {
.float => {
switch (@typeInfo(@TypeOf(value))) {
.int => return @floatFromInt(value),
.float => return @floatCast(value),
.comptime_int => return value,
.comptime_float => return value,
else => @compileError("bad type"),
}
},
.int => {
switch (@typeInfo(@TypeOf(value))) {
.int, .comptime_int => {
if (value >= maxInt(T)) {
return maxInt(T);
} else if (value <= minInt(T)) {
return minInt(T);
} else {
return @intCast(value);
}
},
.float, .comptime_float => {
// In extreme cases, we probably need a language enhancement to be able to
// specify a rounding mode here to prevent `@intFromFloat` panics.
const max: @TypeOf(value) = @floatFromInt(maxInt(T));
const min: @TypeOf(value) = @floatFromInt(minInt(T));
if (isNan(value)) {
return 0;
} else if (value >= max) {
return maxInt(T);
} else if (value <= min) {
return minInt(T);
} else {
return @intFromFloat(value);
}
},
else => @compileError("bad type"),
}
},
else => @compileError("bad result type"),
}
}
test lossyCast {
try testing.expect(lossyCast(i16, 70000.0) == @as(i16, 32767));
try testing.expect(lossyCast(u32, @as(i16, -255)) == @as(u32, 0));
try testing.expect(lossyCast(i9, @as(u32, 200)) == @as(i9, 200));
try testing.expect(lossyCast(u32, @as(f32, @floatFromInt(maxInt(u32)))) == maxInt(u32));
try testing.expect(lossyCast(u32, nan(f32)) == 0);
}
/// Performs linear interpolation between *a* and *b* based on *t*.
/// *t* ranges from 0.0 to 1.0, but may exceed these bounds.
/// Supports floats and vectors of floats.
///
/// This does not guarantee returning *b* if *t* is 1 due to floating-point errors.
/// This is monotonic.
pub fn lerp(a: anytype, b: anytype, t: anytype) @TypeOf(a, b, t) {
const Type = @TypeOf(a, b, t);
return @mulAdd(Type, b - a, t, a);
}
test lerp {
if (builtin.zig_backend == .stage2_c and builtin.cpu.arch.isArm()) return error.SkipZigTest;
if (builtin.zig_backend == .stage2_c and builtin.cpu.arch.isX86()) return error.SkipZigTest;
if (builtin.zig_backend == .stage2_x86_64 and !comptime builtin.cpu.has(.x86, .fma)) return error.SkipZigTest; // https://github.com/ziglang/zig/issues/17884
try testing.expectEqual(@as(f64, 75), lerp(50, 100, 0.5));
try testing.expectEqual(@as(f32, 43.75), lerp(50, 25, 0.25));
try testing.expectEqual(@as(f64, -31.25), lerp(-50, 25, 0.25));
try testing.expectEqual(@as(f64, 30), lerp(10, 20, 2.0));
try testing.expectEqual(@as(f64, 5), lerp(10, 20, -0.5));
try testing.expectApproxEqRel(@as(f32, -7.16067345e+03), lerp(-10000.12345, -5000.12345, 0.56789), 1e-19);
try testing.expectApproxEqRel(@as(f64, 7.010987590521e+62), lerp(0.123456789e-64, 0.123456789e64, 0.56789), 1e-33);
try testing.expectEqual(@as(f32, 0.0), lerp(@as(f32, 1.0e8), 1.0, 1.0));
try testing.expectEqual(@as(f64, 0.0), lerp(@as(f64, 1.0e16), 1.0, 1.0));
try testing.expectEqual(@as(f32, 1.0), lerp(@as(f32, 1.0e7), 1.0, 1.0));
try testing.expectEqual(@as(f64, 1.0), lerp(@as(f64, 1.0e15), 1.0, 1.0));
{
const a: @Vector(3, f32) = @splat(0);
const b: @Vector(3, f32) = @splat(50);
const t: @Vector(3, f32) = @splat(0.5);
try testing.expectEqual(
@Vector(3, f32){ 25, 25, 25 },
lerp(a, b, t),
);
}
{
const a: @Vector(3, f64) = @splat(50);
const b: @Vector(3, f64) = @splat(100);
const t: @Vector(3, f64) = @splat(0.5);
try testing.expectEqual(
@Vector(3, f64){ 75, 75, 75 },
lerp(a, b, t),
);
}
{
const a: @Vector(2, f32) = @splat(40);
const b: @Vector(2, f32) = @splat(80);
const t: @Vector(2, f32) = @Vector(2, f32){ 0.25, 0.75 };
try testing.expectEqual(
@Vector(2, f32){ 50, 70 },
lerp(a, b, t),
);
}
}
/// Returns the maximum value of integer type T.
pub fn maxInt(comptime T: type) comptime_int {
const info = @typeInfo(T).int;
return (1 << (info.bits - @intFromBool(info.signedness == .signed))) - 1;
}
/// Returns the minimum value of integer type T.
pub fn minInt(comptime T: type) comptime_int {
const info = @typeInfo(T).int;
return switch (info.signedness) {
.unsigned => 0,
.signed => -(1 << (info.bits - 1)),
};
}
test maxInt {
try testing.expect(maxInt(u0) == 0);
try testing.expect(maxInt(u1) == 1);
try testing.expect(maxInt(u8) == 255);
try testing.expect(maxInt(u16) == 65535);
try testing.expect(maxInt(u32) == 4294967295);
try testing.expect(maxInt(u64) == 18446744073709551615);
try testing.expect(maxInt(u128) == 340282366920938463463374607431768211455);
try testing.expect(maxInt(i1) == 0);
try testing.expect(maxInt(i8) == 127);
try testing.expect(maxInt(i16) == 32767);
try testing.expect(maxInt(i32) == 2147483647);
try testing.expect(maxInt(i63) == 4611686018427387903);
try testing.expect(maxInt(i64) == 9223372036854775807);
try testing.expect(maxInt(i128) == 170141183460469231731687303715884105727);
}
test minInt {
try testing.expect(minInt(u0) == 0);
try testing.expect(minInt(u1) == 0);
try testing.expect(minInt(u8) == 0);
try testing.expect(minInt(u16) == 0);
try testing.expect(minInt(u32) == 0);
try testing.expect(minInt(u63) == 0);
try testing.expect(minInt(u64) == 0);
try testing.expect(minInt(u128) == 0);
try testing.expect(minInt(i1) == -1);
try testing.expect(minInt(i8) == -128);
try testing.expect(minInt(i16) == -32768);
try testing.expect(minInt(i32) == -2147483648);
try testing.expect(minInt(i63) == -4611686018427387904);
try testing.expect(minInt(i64) == -9223372036854775808);
try testing.expect(minInt(i128) == -170141183460469231731687303715884105728);
}
test "max value type" {
const x: u32 = maxInt(i32);
try testing.expect(x == 2147483647);
}
/// Multiply a and b. Return type is wide enough to guarantee no
/// overflow.
pub fn mulWide(comptime T: type, a: T, b: T) @Int(
@typeInfo(T).int.signedness,
@typeInfo(T).int.bits * 2,
) {
const ResultInt = @Int(
@typeInfo(T).int.signedness,
@typeInfo(T).int.bits * 2,
);
return @as(ResultInt, a) * @as(ResultInt, b);
}
test mulWide {
try testing.expect(mulWide(u8, 5, 5) == 25);
try testing.expect(mulWide(i8, 5, -5) == -25);
try testing.expect(mulWide(u8, 100, 100) == 10000);
}
/// See also `CompareOperator`.
pub const Order = enum {
/// Greater than (`>`)
gt,
/// Less than (`<`)
lt,
/// Equal (`==`)
eq,
pub fn invert(self: Order) Order {
return switch (self) {
.lt => .gt,
.eq => .eq,
.gt => .lt,
};
}
test invert {
try testing.expect(Order.invert(order(0, 0)) == .eq);
try testing.expect(Order.invert(order(1, 0)) == .lt);
try testing.expect(Order.invert(order(-1, 0)) == .gt);
}
pub fn differ(self: Order) ?Order {
return if (self != .eq) self else null;
}
test differ {
const neg: i32 = -1;
const zero: i32 = 0;
const pos: i32 = 1;
try testing.expect(order(zero, neg).differ() orelse
order(pos, zero) == .gt);
try testing.expect(order(zero, zero).differ() orelse
order(zero, zero) == .eq);
try testing.expect(order(pos, pos).differ() orelse
order(neg, zero) == .lt);
try testing.expect(order(zero, zero).differ() orelse
order(pos, neg).differ() orelse
order(neg, zero) == .gt);
try testing.expect(order(pos, pos).differ() orelse
order(pos, pos).differ() orelse
order(neg, neg) == .eq);
try testing.expect(order(zero, pos).differ() orelse
order(neg, pos).differ() orelse
order(pos, neg) == .lt);
}
pub fn compare(self: Order, op: CompareOperator) bool {
return switch (self) {
.lt => switch (op) {
.lt => true,
.lte => true,
.eq => false,
.gte => false,
.gt => false,
.neq => true,
},
.eq => switch (op) {
.lt => false,
.lte => true,
.eq => true,
.gte => true,
.gt => false,
.neq => false,
},
.gt => switch (op) {
.lt => false,
.lte => false,
.eq => false,
.gte => true,
.gt => true,
.neq => true,
},
};
}
// https://github.com/ziglang/zig/issues/19295
test "compare" {
try testing.expect(order(-1, 0).compare(.lt));
try testing.expect(order(-1, 0).compare(.lte));
try testing.expect(order(0, 0).compare(.lte));
try testing.expect(order(0, 0).compare(.eq));
try testing.expect(order(0, 0).compare(.gte));
try testing.expect(order(1, 0).compare(.gte));
try testing.expect(order(1, 0).compare(.gt));
try testing.expect(order(1, 0).compare(.neq));
}
};
/// Given two numbers, this function returns the order they are with respect to each other.
pub fn order(a: anytype, b: anytype) Order {
if (a == b) {
return .eq;
} else if (a < b) {
return .lt;
} else if (a > b) {
return .gt;
} else {
unreachable;
}
}
/// See also `Order`.
pub const CompareOperator = enum {
/// Less than (`<`)
lt,
/// Less than or equal (`<=`)
lte,
/// Equal (`==`)
eq,
/// Greater than or equal (`>=`)
gte,
/// Greater than (`>`)
gt,
/// Not equal (`!=`)
neq,
/// Reverse the direction of the comparison.
/// Use when swapping the left and right hand operands.
pub fn reverse(op: CompareOperator) CompareOperator {
return switch (op) {
.lt => .gt,
.lte => .gte,
.gt => .lt,
.gte => .lte,
.eq => .eq,
.neq => .neq,
};
}
test reverse {
inline for (@typeInfo(CompareOperator).@"enum".field_values) |op_field_value| {
const op = @as(CompareOperator, @fromBackingInt(@intCast(op_field_value)));
try testing.expect(compare(2, op, 3) == compare(3, op.reverse(), 2));
try testing.expect(compare(3, op, 3) == compare(3, op.reverse(), 3));
try testing.expect(compare(4, op, 3) == compare(3, op.reverse(), 4));
}
}
};
/// This function does the same thing as comparison operators, however the
/// operator is a runtime-known enum value. Works on any operands that
/// support comparison operators.
pub fn compare(a: anytype, op: CompareOperator, b: anytype) bool {
return switch (op) {
.lt => a < b,
.lte => a <= b,
.eq => a == b,
.neq => a != b,
.gt => a > b,
.gte => a >= b,
};
}
test compare {
try testing.expect(compare(@as(i8, -1), .lt, @as(u8, 255)));
try testing.expect(compare(@as(i8, 2), .gt, @as(u8, 1)));
try testing.expect(!compare(@as(i8, -1), .gte, @as(u8, 255)));
try testing.expect(compare(@as(u8, 255), .gt, @as(i8, -1)));
try testing.expect(!compare(@as(u8, 255), .lte, @as(i8, -1)));
try testing.expect(compare(@as(i8, -1), .lt, @as(u9, 255)));
try testing.expect(!compare(@as(i8, -1), .gte, @as(u9, 255)));
try testing.expect(compare(@as(u9, 255), .gt, @as(i8, -1)));
try testing.expect(!compare(@as(u9, 255), .lte, @as(i8, -1)));
try testing.expect(compare(@as(i9, -1), .lt, @as(u8, 255)));
try testing.expect(!compare(@as(i9, -1), .gte, @as(u8, 255)));
try testing.expect(compare(@as(u8, 255), .gt, @as(i9, -1)));
try testing.expect(!compare(@as(u8, 255), .lte, @as(i9, -1)));
try testing.expect(compare(@as(u8, 1), .lt, @as(u8, 2)));
try testing.expect(@as(u8, @bitCast(@as(i8, -1))) == @as(u8, 255));
try testing.expect(!compare(@as(u8, 255), .eq, @as(i8, -1)));
try testing.expect(compare(@as(u8, 1), .eq, @as(u8, 1)));
}
test order {
try testing.expect(order(0, 0) == .eq);
try testing.expect(order(1, 0) == .gt);
try testing.expect(order(-1, 0) == .lt);
}
/// Returns a mask of all ones if value is true,
/// and a mask of all zeroes if value is false.
/// Compiles to one instruction for register sized integers.
pub inline fn boolMask(comptime MaskInt: type, value: bool) MaskInt {
if (@typeInfo(MaskInt) != .int)
@compileError("boolMask requires an integer mask type.");
if (MaskInt == u0)
@compileError("boolMask cannot convert to u0, it is too small.");
// The u1 and i1 cases tend to overflow,
// so we special case them here.
if (MaskInt == u1) return @intFromBool(value);
if (MaskInt == i1) {
// The @as here is a workaround for #7950
return @as(i1, @bitCast(@as(u1, @intFromBool(value))));
}
return -%@as(MaskInt, @intCast(@intFromBool(value)));
}
test boolMask {
const runTest = struct {
fn runTest() !void {
try testing.expectEqual(@as(u1, 0), boolMask(u1, false));
try testing.expectEqual(@as(u1, 1), boolMask(u1, true));
try testing.expectEqual(@as(i1, 0), boolMask(i1, false));
try testing.expectEqual(@as(i1, -1), boolMask(i1, true));
try testing.expectEqual(@as(u13, 0), boolMask(u13, false));
try testing.expectEqual(@as(u13, 0x1FFF), boolMask(u13, true));
try testing.expectEqual(@as(i13, 0), boolMask(i13, false));
try testing.expectEqual(@as(i13, -1), boolMask(i13, true));
try testing.expectEqual(@as(u32, 0), boolMask(u32, false));
try testing.expectEqual(@as(u32, 0xFFFF_FFFF), boolMask(u32, true));
try testing.expectEqual(@as(i32, 0), boolMask(i32, false));
try testing.expectEqual(@as(i32, -1), boolMask(i32, true));
}
}.runTest;
try runTest();
try comptime runTest();
}
/// Return the mod of `num` with the smallest integer type
pub fn comptimeMod(num: anytype, comptime denom: comptime_int) IntFittingRange(0, denom - 1) {
return @as(IntFittingRange(0, denom - 1), @intCast(@mod(num, denom)));
}
pub const F80 = struct {
fraction: u64,
exp: u16,
pub fn toFloat(self: F80) f80 {
const int = (@as(u80, self.exp) << 64) | self.fraction;
return @as(f80, @bitCast(int));
}
pub fn fromFloat(x: f80) F80 {
const int = @as(u80, @bitCast(x));
return .{
.fraction = @as(u64, @truncate(int)),
.exp = @as(u16, @truncate(int >> 64)),
};
}
};
fn SignOf(T: type) type {
return switch (@typeInfo(T)) {
.comptime_int, .comptime_float => comptime_int,
.int => IntFittingRange(@max(minInt(T), -1), @min(maxInt(T), 1)),
.float => IntFittingRange(-1, 1),
.vector => |vec| @Vector(vec.len, SignOf(vec.child)),
else => @compileError("Expected an int, float, or a vector of one, found " ++ @typeName(T)),
};
}
/// Returns -1, 0, or 1.
/// Supports integer and float types and vectors of integer and float types.
/// Unsigned integer types will always return 0 or 1.
/// The returned integer type is the smallest that fits the possible values.
/// Branchless.
pub inline fn sign(n: anytype) SignOf(@TypeOf(n)) {
const T = SignOf(@TypeOf(n));
const zero: T = if (@typeInfo(T) == .vector) @splat(0) else 0;
const pos: T = @intCast(@intFromBool(n > zero));
const neg: T = @intCast(@intFromBool(n < zero));
return pos - neg;
}
fn testSign() !void {
// each of the following blocks checks the inputs
// 2, -2, 0, { 2, -2, 0 } provide expected output
// 1, -1, 0, { 1, -1, 0 } for the given T
// (negative values omitted for unsigned types)
{
const T = i8;
try std.testing.expectEqual(@as(T, 1), sign(@as(T, 2)));
try std.testing.expectEqual(@as(T, -1), sign(@as(T, -2)));
try std.testing.expectEqual(@as(T, 0), sign(@as(T, 0)));
try std.testing.expectEqual(@Vector(3, T){ 1, -1, 0 }, sign(@Vector(3, T){ 2, -2, 0 }));
}
{
const T = i32;
try std.testing.expectEqual(@as(T, 1), sign(@as(T, 2)));
try std.testing.expectEqual(@as(T, -1), sign(@as(T, -2)));
try std.testing.expectEqual(@as(T, 0), sign(@as(T, 0)));
try std.testing.expectEqual(@Vector(3, T){ 1, -1, 0 }, sign(@Vector(3, T){ 2, -2, 0 }));
}
{
const T = i64;
try std.testing.expectEqual(@as(T, 1), sign(@as(T, 2)));
try std.testing.expectEqual(@as(T, -1), sign(@as(T, -2)));
try std.testing.expectEqual(@as(T, 0), sign(@as(T, 0)));
try std.testing.expectEqual(@Vector(3, T){ 1, -1, 0 }, sign(@Vector(3, T){ 2, -2, 0 }));
}
{
const T = u8;
try std.testing.expectEqual(@as(T, 1), sign(@as(T, 2)));
try std.testing.expectEqual(@as(T, 0), sign(@as(T, 0)));
try std.testing.expectEqual(@Vector(2, T){ 1, 0 }, sign(@Vector(2, T){ 2, 0 }));
}
{
const T = u32;
try std.testing.expectEqual(@as(T, 1), sign(@as(T, 2)));
try std.testing.expectEqual(@as(T, 0), sign(@as(T, 0)));
try std.testing.expectEqual(@Vector(2, T){ 1, 0 }, sign(@Vector(2, T){ 2, 0 }));
}
{
const T = u64;
try std.testing.expectEqual(@as(T, 1), sign(@as(T, 2)));
try std.testing.expectEqual(@as(T, 0), sign(@as(T, 0)));
try std.testing.expectEqual(@Vector(2, T){ 1, 0 }, sign(@Vector(2, T){ 2, 0 }));
}
{
const T = f16;
try std.testing.expectEqual(@as(T, 1), sign(@as(T, 2)));
try std.testing.expectEqual(@as(T, -1), sign(@as(T, -2)));
try std.testing.expectEqual(@as(T, 0), sign(@as(T, 0)));
try std.testing.expectEqual(@Vector(3, T){ 1, -1, 0 }, sign(@Vector(3, T){ 2, -2, 0 }));
}
{
const T = f32;
try std.testing.expectEqual(@as(T, 1), sign(@as(T, 2)));
try std.testing.expectEqual(@as(T, -1), sign(@as(T, -2)));
try std.testing.expectEqual(@as(T, 0), sign(@as(T, 0)));
try std.testing.expectEqual(@Vector(3, T){ 1, -1, 0 }, sign(@Vector(3, T){ 2, -2, 0 }));
}
{
const T = f64;
try std.testing.expectEqual(@as(T, 1), sign(@as(T, 2)));
try std.testing.expectEqual(@as(T, -1), sign(@as(T, -2)));
try std.testing.expectEqual(@as(T, 0), sign(@as(T, 0)));
try std.testing.expectEqual(@Vector(3, T){ 1, -1, 0 }, sign(@Vector(3, T){ 2, -2, 0 }));
}
// comptime_int
try std.testing.expectEqual(-1, sign(-10));
try std.testing.expectEqual(1, sign(10));
try std.testing.expectEqual(0, sign(0));
// comptime_float
try std.testing.expectEqual(-1.0, sign(-10.0));
try std.testing.expectEqual(1.0, sign(10.0));
try std.testing.expectEqual(0.0, sign(0.0));
}
test sign {
try testSign();
try comptime testSign();
}
/// Increases the bit width of an integer by copying the most significant bit.
/// This results in the input and output having the same arithmetic value, when
/// interpreted as two's complement integers.
pub fn signExtend(To: type, n: anytype) To {
const From = @TypeOf(n);
if (From == u0) return 0;
const FromSigned = @Int(.signed, @typeInfo(From).int.bits);
const ToSigned = @Int(.signed, @typeInfo(To).int.bits);
return @bitCast(@as(ToSigned, @as(FromSigned, @bitCast(n))));
}
test signExtend {
const number: u8 = 0x86;
try testing.expectEqual(0xff86, signExtend(u16, number));
try testing.expectEqual(0, signExtend(u1, @as(u0, 0)));
try testing.expectEqual(0, signExtend(u16, @as(u0, 0)));
try testing.expectEqual(0x0000, signExtend(u16, @as(u1, 0b0)));
try testing.expectEqual(0xffff, signExtend(u16, @as(u1, 0b1)));
try testing.expectEqual(0b000, signExtend(u3, @as(u2, 0b00)));
try testing.expectEqual(0b001, signExtend(u3, @as(u2, 0b01)));
try testing.expectEqual(0b110, signExtend(u3, @as(u2, 0b10)));
try testing.expectEqual(0b111, signExtend(u3, @as(u2, 0b11)));
try testing.expectEqual(0b0000_0001, signExtend(u8, @as(u2, 0b01)));
try testing.expectEqual(0b1111_1110, signExtend(u8, @as(u2, 0b10)));
try testing.expectEqual(0x0039, signExtend(u16, @as(u8, 0x39)));
try testing.expectEqual(0xff93, signExtend(u16, @as(u8, 0x93)));
try testing.expectEqual(5, signExtend(i32, @as(i8, 5)));
try testing.expectEqual(-123, signExtend(i16, @as(i8, -123)));
}