master
1const builtin = @import("builtin");
2const std = @import("std.zig");
3const float = @import("math/float.zig");
4const assert = std.debug.assert;
5const mem = std.mem;
6const testing = std.testing;
7const Alignment = std.mem.Alignment;
8
9/// Euler's number (e)
10pub const e = 2.71828182845904523536028747135266249775724709369995;
11
12/// Archimedes' constant (π)
13pub const pi = 3.14159265358979323846264338327950288419716939937510;
14
15/// Phi or Golden ratio constant (Φ) = (1 + sqrt(5))/2
16pub const phi = 1.6180339887498948482045868343656381177203091798057628621;
17
18/// Circle constant (τ)
19pub const tau = 2 * pi;
20
21/// log2(e)
22pub const log2e = 1.442695040888963407359924681001892137;
23
24/// log10(e)
25pub const log10e = 0.434294481903251827651128918916605082;
26
27/// ln(2)
28pub const ln2 = 0.693147180559945309417232121458176568;
29
30/// ln(10)
31pub const ln10 = 2.302585092994045684017991454684364208;
32
33/// 2/sqrt(π)
34pub const two_sqrtpi = 1.128379167095512573896158903121545172;
35
36/// sqrt(2)
37pub const sqrt2 = 1.414213562373095048801688724209698079;
38
39/// 1/sqrt(2)
40pub const sqrt1_2 = 0.707106781186547524400844362104849039;
41
42/// pi/180.0
43pub const rad_per_deg = 0.0174532925199432957692369076848861271344287188854172545609719144;
44
45/// 180.0/pi
46pub const deg_per_rad = 57.295779513082320876798154814105170332405472466564321549160243861;
47
48pub const Sign = enum(u1) { positive, negative };
49pub const FloatRepr = float.FloatRepr;
50pub const floatExponentBits = float.floatExponentBits;
51pub const floatMantissaBits = float.floatMantissaBits;
52pub const floatFractionalBits = float.floatFractionalBits;
53pub const floatExponentMin = float.floatExponentMin;
54pub const floatExponentMax = float.floatExponentMax;
55pub const floatTrueMin = float.floatTrueMin;
56pub const floatMin = float.floatMin;
57pub const floatMax = float.floatMax;
58pub const floatEps = float.floatEps;
59pub const floatEpsAt = float.floatEpsAt;
60pub const inf = float.inf;
61pub const nan = float.nan;
62pub const snan = float.snan;
63
64/// Performs an approximate comparison of two floating point values `x` and `y`.
65/// Returns true if the absolute difference between them is less or equal than
66/// the specified tolerance.
67///
68/// The `tolerance` parameter is the absolute tolerance used when determining if
69/// the two numbers are close enough; a good value for this parameter is a small
70/// multiple of `floatEps(T)`.
71///
72/// Note that this function is recommended for comparing small numbers
73/// around zero; using `approxEqRel` is suggested otherwise.
74///
75/// NaN values are never considered equal to any value.
76pub fn approxEqAbs(comptime T: type, x: T, y: T, tolerance: T) bool {
77 assert(@typeInfo(T) == .float or @typeInfo(T) == .comptime_float);
78 assert(tolerance >= 0);
79
80 // Fast path for equal values (and signed zeros and infinites).
81 if (x == y)
82 return true;
83
84 if (isNan(x) or isNan(y))
85 return false;
86
87 return @abs(x - y) <= tolerance;
88}
89
90/// Performs an approximate comparison of two floating point values `x` and `y`.
91/// Returns true if the absolute difference between them is less or equal than
92/// `max(|x|, |y|) * tolerance`, where `tolerance` is a positive number greater
93/// than zero.
94///
95/// The `tolerance` parameter is the relative tolerance used when determining if
96/// the two numbers are close enough; a good value for this parameter is usually
97/// `sqrt(floatEps(T))`, meaning that the two numbers are considered equal if at
98/// least half of the digits are equal.
99///
100/// Note that for comparisons of small numbers around zero this function won't
101/// give meaningful results, use `approxEqAbs` instead.
102///
103/// NaN values are never considered equal to any value.
104pub fn approxEqRel(comptime T: type, x: T, y: T, tolerance: T) bool {
105 assert(@typeInfo(T) == .float or @typeInfo(T) == .comptime_float);
106 assert(tolerance > 0);
107
108 // Fast path for equal values (and signed zeros and infinites).
109 if (x == y)
110 return true;
111
112 if (isNan(x) or isNan(y))
113 return false;
114
115 return @abs(x - y) <= @max(@abs(x), @abs(y)) * tolerance;
116}
117
118test approxEqAbs {
119 inline for ([_]type{ f16, f32, f64, f128 }) |T| {
120 const eps_value = comptime floatEps(T);
121 const min_value = comptime floatMin(T);
122
123 try testing.expect(approxEqAbs(T, 0.0, 0.0, eps_value));
124 try testing.expect(approxEqAbs(T, -0.0, -0.0, eps_value));
125 try testing.expect(approxEqAbs(T, 0.0, -0.0, eps_value));
126 try testing.expect(!approxEqAbs(T, 1.0 + 2 * eps_value, 1.0, eps_value));
127 try testing.expect(approxEqAbs(T, 1.0 + 1 * eps_value, 1.0, eps_value));
128 try testing.expect(approxEqAbs(T, min_value, 0.0, eps_value * 2));
129 try testing.expect(approxEqAbs(T, -min_value, 0.0, eps_value * 2));
130 }
131
132 comptime {
133 // `comptime_float` is guaranteed to have the same precision and operations of
134 // the largest other floating point type, which is f128 but it doesn't have a
135 // defined layout so we can't rely on `@bitCast` to construct the smallest
136 // possible epsilon value like we do in the tests above. In the same vein, we
137 // also can't represent a max/min, `NaN` or `Inf` values.
138 const eps_value = 1e-4;
139
140 try testing.expect(approxEqAbs(comptime_float, 0.0, 0.0, eps_value));
141 try testing.expect(approxEqAbs(comptime_float, -0.0, -0.0, eps_value));
142 try testing.expect(approxEqAbs(comptime_float, 0.0, -0.0, eps_value));
143 try testing.expect(!approxEqAbs(comptime_float, 1.0 + 2 * eps_value, 1.0, eps_value));
144 try testing.expect(approxEqAbs(comptime_float, 1.0 + 1 * eps_value, 1.0, eps_value));
145 }
146}
147
148test approxEqRel {
149 inline for ([_]type{ f16, f32, f64, f128 }) |T| {
150 const eps_value = comptime floatEps(T);
151 const sqrt_eps_value = comptime sqrt(eps_value);
152 const nan_value = comptime nan(T);
153 const inf_value = comptime inf(T);
154 const min_value = comptime floatMin(T);
155
156 try testing.expect(approxEqRel(T, 1.0, 1.0, sqrt_eps_value));
157 try testing.expect(!approxEqRel(T, 1.0, 0.0, sqrt_eps_value));
158 try testing.expect(!approxEqRel(T, 1.0, nan_value, sqrt_eps_value));
159 try testing.expect(!approxEqRel(T, nan_value, nan_value, sqrt_eps_value));
160 try testing.expect(approxEqRel(T, inf_value, inf_value, sqrt_eps_value));
161 try testing.expect(approxEqRel(T, min_value, min_value, sqrt_eps_value));
162 try testing.expect(approxEqRel(T, -min_value, -min_value, sqrt_eps_value));
163 }
164
165 comptime {
166 // `comptime_float` is guaranteed to have the same precision and operations of
167 // the largest other floating point type, which is f128 but it doesn't have a
168 // defined layout so we can't rely on `@bitCast` to construct the smallest
169 // possible epsilon value like we do in the tests above. In the same vein, we
170 // also can't represent a max/min, `NaN` or `Inf` values.
171 const eps_value = 1e-4;
172 const sqrt_eps_value = sqrt(eps_value);
173
174 try testing.expect(approxEqRel(comptime_float, 1.0, 1.0, sqrt_eps_value));
175 try testing.expect(!approxEqRel(comptime_float, 1.0, 0.0, sqrt_eps_value));
176 }
177}
178
179pub fn raiseInvalid() void {
180 // Raise INVALID fpu exception
181}
182
183pub fn raiseUnderflow() void {
184 // Raise UNDERFLOW fpu exception
185}
186
187pub fn raiseOverflow() void {
188 // Raise OVERFLOW fpu exception
189}
190
191pub fn raiseInexact() void {
192 // Raise INEXACT fpu exception
193}
194
195pub fn raiseDivByZero() void {
196 // Raise INEXACT fpu exception
197}
198
199pub const isNan = @import("math/isnan.zig").isNan;
200pub const isSignalNan = @import("math/isnan.zig").isSignalNan;
201pub const frexp = @import("math/frexp.zig").frexp;
202pub const Frexp = @import("math/frexp.zig").Frexp;
203pub const modf = @import("math/modf.zig").modf;
204pub const Modf = @import("math/modf.zig").Modf;
205pub const copysign = @import("math/copysign.zig").copysign;
206pub const isFinite = @import("math/isfinite.zig").isFinite;
207pub const isInf = @import("math/isinf.zig").isInf;
208pub const isPositiveInf = @import("math/isinf.zig").isPositiveInf;
209pub const isNegativeInf = @import("math/isinf.zig").isNegativeInf;
210pub const isPositiveZero = @import("math/iszero.zig").isPositiveZero;
211pub const isNegativeZero = @import("math/iszero.zig").isNegativeZero;
212pub const isNormal = @import("math/isnormal.zig").isNormal;
213pub const nextAfter = @import("math/nextafter.zig").nextAfter;
214pub const signbit = @import("math/signbit.zig").signbit;
215pub const scalbn = @import("math/scalbn.zig").scalbn;
216pub const ldexp = @import("math/ldexp.zig").ldexp;
217pub const pow = @import("math/pow.zig").pow;
218pub const powi = @import("math/powi.zig").powi;
219pub const sqrt = @import("math/sqrt.zig").sqrt;
220pub const cbrt = @import("math/cbrt.zig").cbrt;
221pub const acos = @import("math/acos.zig").acos;
222pub const asin = @import("math/asin.zig").asin;
223pub const atan = @import("math/atan.zig").atan;
224pub const atan2 = @import("math/atan2.zig").atan2;
225pub const hypot = @import("math/hypot.zig").hypot;
226pub const expm1 = @import("math/expm1.zig").expm1;
227pub const ilogb = @import("math/ilogb.zig").ilogb;
228pub const log = @import("math/log.zig").log;
229pub const log2 = @import("math/log2.zig").log2;
230pub const log10 = @import("math/log10.zig").log10;
231pub const log10_int = @import("math/log10.zig").log10_int;
232pub const log_int = @import("math/log_int.zig").log_int;
233pub const log1p = @import("math/log1p.zig").log1p;
234pub const asinh = @import("math/asinh.zig").asinh;
235pub const acosh = @import("math/acosh.zig").acosh;
236pub const atanh = @import("math/atanh.zig").atanh;
237pub const sinh = @import("math/sinh.zig").sinh;
238pub const cosh = @import("math/cosh.zig").cosh;
239pub const tanh = @import("math/tanh.zig").tanh;
240pub const gcd = @import("math/gcd.zig").gcd;
241pub const lcm = @import("math/lcm.zig").lcm;
242pub const gamma = @import("math/gamma.zig").gamma;
243pub const lgamma = @import("math/gamma.zig").lgamma;
244
245/// Sine trigonometric function on a floating point number.
246/// Uses a dedicated hardware instruction when available.
247/// This is the same as calling the builtin @sin
248pub inline fn sin(value: anytype) @TypeOf(value) {
249 return @sin(value);
250}
251
252/// Cosine trigonometric function on a floating point number.
253/// Uses a dedicated hardware instruction when available.
254/// This is the same as calling the builtin @cos
255pub inline fn cos(value: anytype) @TypeOf(value) {
256 return @cos(value);
257}
258
259/// Tangent trigonometric function on a floating point number.
260/// Uses a dedicated hardware instruction when available.
261/// This is the same as calling the builtin @tan
262pub inline fn tan(value: anytype) @TypeOf(value) {
263 return @tan(value);
264}
265
266/// Converts an angle in radians to degrees. T must be a float or comptime number or a vector of floats.
267pub fn radiansToDegrees(ang: anytype) if (@TypeOf(ang) == comptime_int) comptime_float else @TypeOf(ang) {
268 const T = @TypeOf(ang);
269 switch (@typeInfo(T)) {
270 .float, .comptime_float, .comptime_int => return ang * deg_per_rad,
271 .vector => |V| if (@typeInfo(V.child) == .float) return ang * @as(T, @splat(deg_per_rad)),
272 else => {},
273 }
274 @compileError("Input must be float or a comptime number, or a vector of floats.");
275}
276
277test radiansToDegrees {
278 const zero: f32 = 0;
279 const half_pi: f32 = pi / 2.0;
280 const neg_quart_pi: f32 = -pi / 4.0;
281 const one_pi: f32 = pi;
282 const two_pi: f32 = 2.0 * pi;
283 try std.testing.expectApproxEqAbs(@as(f32, 0), radiansToDegrees(zero), 1e-6);
284 try std.testing.expectApproxEqAbs(@as(f32, 90), radiansToDegrees(half_pi), 1e-6);
285 try std.testing.expectApproxEqAbs(@as(f32, -45), radiansToDegrees(neg_quart_pi), 1e-6);
286 try std.testing.expectApproxEqAbs(@as(f32, 180), radiansToDegrees(one_pi), 1e-6);
287 try std.testing.expectApproxEqAbs(@as(f32, 360), radiansToDegrees(two_pi), 1e-6);
288
289 const result = radiansToDegrees(@Vector(4, f32){
290 half_pi,
291 neg_quart_pi,
292 one_pi,
293 two_pi,
294 });
295 try std.testing.expectApproxEqAbs(@as(f32, 90), result[0], 1e-6);
296 try std.testing.expectApproxEqAbs(@as(f32, -45), result[1], 1e-6);
297 try std.testing.expectApproxEqAbs(@as(f32, 180), result[2], 1e-6);
298 try std.testing.expectApproxEqAbs(@as(f32, 360), result[3], 1e-6);
299}
300
301/// Converts an angle in degrees to radians. T must be a float or comptime number or a vector of floats.
302pub fn degreesToRadians(ang: anytype) if (@TypeOf(ang) == comptime_int) comptime_float else @TypeOf(ang) {
303 const T = @TypeOf(ang);
304 switch (@typeInfo(T)) {
305 .float, .comptime_float, .comptime_int => return ang * rad_per_deg,
306 .vector => |V| if (@typeInfo(V.child) == .float) return ang * @as(T, @splat(rad_per_deg)),
307 else => {},
308 }
309 @compileError("Input must be float or a comptime number, or a vector of floats.");
310}
311
312test degreesToRadians {
313 const ninety: f32 = 90;
314 const neg_two_seventy: f32 = -270;
315 const three_sixty: f32 = 360;
316 try std.testing.expectApproxEqAbs(@as(f32, pi / 2.0), degreesToRadians(ninety), 1e-6);
317 try std.testing.expectApproxEqAbs(@as(f32, -3 * pi / 2.0), degreesToRadians(neg_two_seventy), 1e-6);
318 try std.testing.expectApproxEqAbs(@as(f32, 2 * pi), degreesToRadians(three_sixty), 1e-6);
319
320 const result = degreesToRadians(@Vector(3, f32){
321 ninety,
322 neg_two_seventy,
323 three_sixty,
324 });
325 try std.testing.expectApproxEqAbs(@as(f32, pi / 2.0), result[0], 1e-6);
326 try std.testing.expectApproxEqAbs(@as(f32, -3 * pi / 2.0), result[1], 1e-6);
327 try std.testing.expectApproxEqAbs(@as(f32, 2 * pi), result[2], 1e-6);
328}
329
330/// Base-e exponential function on a floating point number.
331/// Uses a dedicated hardware instruction when available.
332/// This is the same as calling the builtin @exp
333pub inline fn exp(value: anytype) @TypeOf(value) {
334 return @exp(value);
335}
336
337/// Base-2 exponential function on a floating point number.
338/// Uses a dedicated hardware instruction when available.
339/// This is the same as calling the builtin @exp2
340pub inline fn exp2(value: anytype) @TypeOf(value) {
341 return @exp2(value);
342}
343
344pub const complex = @import("math/complex.zig");
345pub const Complex = complex.Complex;
346
347pub const big = @import("math/big.zig");
348
349test {
350 _ = floatExponentBits;
351 _ = floatMantissaBits;
352 _ = floatFractionalBits;
353 _ = floatExponentMin;
354 _ = floatExponentMax;
355 _ = floatTrueMin;
356 _ = floatMin;
357 _ = floatMax;
358 _ = floatEps;
359 _ = inf;
360 _ = nan;
361 _ = snan;
362 _ = isNan;
363 _ = isSignalNan;
364 _ = frexp;
365 _ = Frexp;
366 _ = modf;
367 _ = Modf;
368 _ = copysign;
369 _ = isFinite;
370 _ = isInf;
371 _ = isPositiveInf;
372 _ = isNegativeInf;
373 _ = isNormal;
374 _ = nextAfter;
375 _ = signbit;
376 _ = scalbn;
377 _ = ldexp;
378 _ = pow;
379 _ = powi;
380 _ = sqrt;
381 _ = cbrt;
382 _ = acos;
383 _ = asin;
384 _ = atan;
385 _ = atan2;
386 _ = hypot;
387 _ = expm1;
388 _ = ilogb;
389 _ = log;
390 _ = log2;
391 _ = log10;
392 _ = log10_int;
393 _ = log_int;
394 _ = log1p;
395 _ = asinh;
396 _ = acosh;
397 _ = atanh;
398 _ = sinh;
399 _ = cosh;
400 _ = tanh;
401 _ = gcd;
402 _ = lcm;
403 _ = gamma;
404 _ = lgamma;
405
406 _ = complex;
407 _ = Complex;
408
409 _ = big;
410}
411
412/// Given two types, returns the smallest one which is capable of holding the
413/// full range of the minimum value.
414pub fn Min(comptime A: type, comptime B: type) type {
415 switch (@typeInfo(A)) {
416 .int => |a_info| switch (@typeInfo(B)) {
417 .int => |b_info| if (a_info.signedness == .unsigned and b_info.signedness == .unsigned) {
418 if (a_info.bits < b_info.bits) {
419 return A;
420 } else {
421 return B;
422 }
423 },
424 else => {},
425 },
426 else => {},
427 }
428 return @TypeOf(@as(A, 0) + @as(B, 0));
429}
430
431/// Odd sawtooth function
432/// ```
433/// |
434/// / | / /
435/// / |/ /
436/// --/----/----/--
437/// / /| /
438/// / / | /
439/// |
440/// ```
441/// Limit x to the half-open interval [-r, r).
442pub fn wrap(x: anytype, r: anytype) @TypeOf(x) {
443 const info_x = @typeInfo(@TypeOf(x));
444 const info_r = @typeInfo(@TypeOf(r));
445 if (info_x == .int and info_x.int.signedness != .signed) {
446 @compileError("x must be floating point, comptime integer, or signed integer.");
447 }
448 switch (info_r) {
449 .int => {
450 // in the rare usecase of r not being comptime_int or float,
451 // take the penalty of having an intermediary type conversion,
452 // otherwise the alternative is to unwind iteratively to avoid overflow
453 const R = @Int(.signed, info_r.int.bits + 1);
454 const radius: if (info_r.int.signedness == .signed) @TypeOf(r) else R = r;
455 return @intCast(@mod(x - radius, 2 * @as(R, r)) - r); // provably impossible to overflow
456 },
457 else => {
458 return @mod(x - r, 2 * r) - r;
459 },
460 }
461}
462test wrap {
463 // Within range
464 try testing.expect(wrap(@as(i32, -75), @as(i32, 180)) == -75);
465 try testing.expect(wrap(@as(i32, -75), @as(i32, -180)) == -75);
466 // Below
467 try testing.expect(wrap(@as(i32, -225), @as(i32, 180)) == 135);
468 try testing.expect(wrap(@as(i32, -225), @as(i32, -180)) == 135);
469 // Above
470 try testing.expect(wrap(@as(i32, 361), @as(i32, 180)) == 1);
471 try testing.expect(wrap(@as(i32, 361), @as(i32, -180)) == 1);
472
473 // One period, right limit, positive r
474 try testing.expect(wrap(@as(i32, 180), @as(i32, 180)) == -180);
475 // One period, left limit, positive r
476 try testing.expect(wrap(@as(i32, -180), @as(i32, 180)) == -180);
477 // One period, right limit, negative r
478 try testing.expect(wrap(@as(i32, 180), @as(i32, -180)) == 180);
479 // One period, left limit, negative r
480 try testing.expect(wrap(@as(i32, -180), @as(i32, -180)) == 180);
481
482 // Two periods, right limit, positive r
483 try testing.expect(wrap(@as(i32, 540), @as(i32, 180)) == -180);
484 // Two periods, left limit, positive r
485 try testing.expect(wrap(@as(i32, -540), @as(i32, 180)) == -180);
486 // Two periods, right limit, negative r
487 try testing.expect(wrap(@as(i32, 540), @as(i32, -180)) == 180);
488 // Two periods, left limit, negative r
489 try testing.expect(wrap(@as(i32, -540), @as(i32, -180)) == 180);
490
491 // Floating point
492 try testing.expect(wrap(@as(f32, 1.125), @as(f32, 1.0)) == -0.875);
493 try testing.expect(wrap(@as(f32, -127.5), @as(f32, 180)) == -127.5);
494
495 // Mix of comptime and non-comptime
496 var i: i32 = 1;
497 _ = &i;
498 try testing.expect(wrap(i, 10) == 1);
499
500 const limit: i32 = 180;
501 // Within range
502 try testing.expect(wrap(@as(i32, -75), limit) == -75);
503 // Below
504 try testing.expect(wrap(@as(i32, -225), limit) == 135);
505 // Above
506 try testing.expect(wrap(@as(i32, 361), limit) == 1);
507}
508
509/// Odd ramp function
510/// ```
511/// | _____
512/// | /
513/// |/
514/// -------/-------
515/// /|
516/// _____/ |
517/// |
518/// ```
519/// Limit val to the inclusive range [lower, upper].
520pub fn clamp(val: anytype, lower: anytype, upper: anytype) @TypeOf(val, lower, upper) {
521 const T = @TypeOf(val, lower, upper);
522 switch (@typeInfo(T)) {
523 .int, .float, .comptime_int, .comptime_float => assert(lower <= upper),
524 .vector => |vinfo| switch (@typeInfo(vinfo.child)) {
525 .int, .float => assert(@reduce(.And, lower <= upper)),
526 else => @compileError("Expected vector of ints or floats, found " ++ @typeName(T)),
527 },
528 else => @compileError("Expected an int, float or vector of one, found " ++ @typeName(T)),
529 }
530 return @max(lower, @min(val, upper));
531}
532test clamp {
533 // Within range
534 try testing.expect(std.math.clamp(@as(i32, -1), @as(i32, -4), @as(i32, 7)) == -1);
535 // Below
536 try testing.expect(std.math.clamp(@as(i32, -5), @as(i32, -4), @as(i32, 7)) == -4);
537 // Above
538 try testing.expect(std.math.clamp(@as(i32, 8), @as(i32, -4), @as(i32, 7)) == 7);
539
540 // Floating point
541 try testing.expect(std.math.clamp(@as(f32, 1.1), @as(f32, 0.0), @as(f32, 1.0)) == 1.0);
542 try testing.expect(std.math.clamp(@as(f32, -127.5), @as(f32, -200), @as(f32, -100)) == -127.5);
543
544 // Vector
545 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 })));
546
547 // Mix of comptime and non-comptime
548 var i: i32 = 1;
549 _ = &i;
550 try testing.expect(std.math.clamp(i, 0, 1) == 1);
551}
552
553/// Returns the product of a and b. Returns an error on overflow.
554pub fn mul(comptime T: type, a: T, b: T) (error{Overflow}!T) {
555 if (T == comptime_int) return a * b;
556 const ov = @mulWithOverflow(a, b);
557 if (ov[1] != 0) return error.Overflow;
558 return ov[0];
559}
560
561/// Returns the sum of a and b. Returns an error on overflow.
562pub fn add(comptime T: type, a: T, b: T) (error{Overflow}!T) {
563 if (T == comptime_int) return a + b;
564 const ov = @addWithOverflow(a, b);
565 if (ov[1] != 0) return error.Overflow;
566 return ov[0];
567}
568
569/// Returns a - b, or an error on overflow.
570pub fn sub(comptime T: type, a: T, b: T) (error{Overflow}!T) {
571 if (T == comptime_int) return a - b;
572 const ov = @subWithOverflow(a, b);
573 if (ov[1] != 0) return error.Overflow;
574 return ov[0];
575}
576
577pub fn negate(x: anytype) !@TypeOf(x) {
578 return sub(@TypeOf(x), 0, x);
579}
580
581/// Shifts a left by shift_amt. Returns an error on overflow. shift_amt
582/// is unsigned.
583pub fn shlExact(comptime T: type, a: T, shift_amt: Log2Int(T)) !T {
584 if (T == comptime_int) return a << shift_amt;
585 const ov = @shlWithOverflow(a, shift_amt);
586 if (ov[1] != 0) return error.Overflow;
587 return ov[0];
588}
589
590/// Shifts left. Overflowed bits are truncated.
591/// A negative shift amount results in a right shift.
592pub fn shl(comptime T: type, a: T, shift_amt: anytype) T {
593 const is_shl = shift_amt >= 0;
594 const abs_shift_amt = @abs(shift_amt);
595 const casted_shift_amt = casted_shift_amt: switch (@typeInfo(T)) {
596 .int => |info| {
597 if (abs_shift_amt < info.bits) break :casted_shift_amt @as(
598 Log2Int(T),
599 @intCast(abs_shift_amt),
600 );
601 if (info.signedness == .unsigned or is_shl) return 0;
602 return a >> (info.bits - 1);
603 },
604 .vector => |info| {
605 const Child = info.child;
606 const child_info = @typeInfo(Child).int;
607 if (abs_shift_amt < child_info.bits) break :casted_shift_amt @as(
608 @Vector(info.len, Log2Int(Child)),
609 @splat(@as(Log2Int(Child), @intCast(abs_shift_amt))),
610 );
611 if (child_info.signedness == .unsigned or is_shl) return @splat(0);
612 return a >> @splat(child_info.bits - 1);
613 },
614 else => comptime unreachable,
615 };
616 return if (is_shl) a << casted_shift_amt else a >> casted_shift_amt;
617}
618
619test shl {
620 try testing.expect(shl(u8, 0b11111111, @as(usize, 3)) == 0b11111000);
621 try testing.expect(shl(u8, 0b11111111, @as(usize, 8)) == 0);
622 try testing.expect(shl(u8, 0b11111111, @as(usize, 9)) == 0);
623 try testing.expect(shl(u8, 0b11111111, @as(isize, -2)) == 0b00111111);
624 try testing.expect(shl(u8, 0b11111111, 3) == 0b11111000);
625 try testing.expect(shl(u8, 0b11111111, 8) == 0);
626 try testing.expect(shl(u8, 0b11111111, 9) == 0);
627 try testing.expect(shl(u8, 0b11111111, -2) == 0b00111111);
628 try testing.expect(shl(@Vector(1, u32), @Vector(1, u32){42}, @as(usize, 1))[0] == @as(u32, 42) << 1);
629 try testing.expect(shl(@Vector(1, u32), @Vector(1, u32){42}, @as(isize, -1))[0] == @as(u32, 42) >> 1);
630 try testing.expect(shl(@Vector(1, u32), @Vector(1, u32){42}, 33)[0] == 0);
631
632 try testing.expect(shl(i8, -1, -100) == -1);
633 try testing.expect(shl(i8, -1, 100) == 0);
634 if (builtin.cpu.arch == .hexagon and builtin.zig_backend == .stage2_llvm) return error.SkipZigTest;
635 try testing.expect(@reduce(.And, shl(@Vector(2, i8), .{ -1, 1 }, -100) == @Vector(2, i8){ -1, 0 }));
636 try testing.expect(@reduce(.And, shl(@Vector(2, i8), .{ -1, 1 }, 100) == @Vector(2, i8){ 0, 0 }));
637}
638
639/// Shifts right. Overflowed bits are truncated.
640/// A negative shift amount results in a left shift.
641pub fn shr(comptime T: type, a: T, shift_amt: anytype) T {
642 const is_shl = shift_amt < 0;
643 const abs_shift_amt = @abs(shift_amt);
644 const casted_shift_amt = casted_shift_amt: switch (@typeInfo(T)) {
645 .int => |info| {
646 if (abs_shift_amt < info.bits) break :casted_shift_amt @as(
647 Log2Int(T),
648 @intCast(abs_shift_amt),
649 );
650 if (info.signedness == .unsigned or is_shl) return 0;
651 return a >> (info.bits - 1);
652 },
653 .vector => |info| {
654 const Child = info.child;
655 const child_info = @typeInfo(Child).int;
656 if (abs_shift_amt < child_info.bits) break :casted_shift_amt @as(
657 @Vector(info.len, Log2Int(Child)),
658 @splat(@as(Log2Int(Child), @intCast(abs_shift_amt))),
659 );
660 if (child_info.signedness == .unsigned or is_shl) return @splat(0);
661 return a >> @splat(child_info.bits - 1);
662 },
663 else => comptime unreachable,
664 };
665 return if (is_shl) a << casted_shift_amt else a >> casted_shift_amt;
666}
667
668test shr {
669 try testing.expect(shr(u8, 0b11111111, @as(usize, 3)) == 0b00011111);
670 try testing.expect(shr(u8, 0b11111111, @as(usize, 8)) == 0);
671 try testing.expect(shr(u8, 0b11111111, @as(usize, 9)) == 0);
672 try testing.expect(shr(u8, 0b11111111, @as(isize, -2)) == 0b11111100);
673 try testing.expect(shr(u8, 0b11111111, 3) == 0b00011111);
674 try testing.expect(shr(u8, 0b11111111, 8) == 0);
675 try testing.expect(shr(u8, 0b11111111, 9) == 0);
676 try testing.expect(shr(u8, 0b11111111, -2) == 0b11111100);
677 try testing.expect(shr(@Vector(1, u32), @Vector(1, u32){42}, @as(usize, 1))[0] == @as(u32, 42) >> 1);
678 try testing.expect(shr(@Vector(1, u32), @Vector(1, u32){42}, @as(isize, -1))[0] == @as(u32, 42) << 1);
679 try testing.expect(shr(@Vector(1, u32), @Vector(1, u32){42}, 33)[0] == 0);
680
681 try testing.expect(shr(i8, -1, -100) == 0);
682 try testing.expect(shr(i8, -1, 100) == -1);
683 if (builtin.cpu.arch == .hexagon and builtin.zig_backend == .stage2_llvm) return error.SkipZigTest;
684 try testing.expect(@reduce(.And, shr(@Vector(2, i8), .{ -1, 1 }, -100) == @Vector(2, i8){ 0, 0 }));
685 try testing.expect(@reduce(.And, shr(@Vector(2, i8), .{ -1, 1 }, 100) == @Vector(2, i8){ -1, 0 }));
686}
687
688/// Rotates right. Only unsigned values can be rotated. Negative shift
689/// values result in shift modulo the bit count.
690pub fn rotr(comptime T: type, x: T, r: anytype) T {
691 if (@typeInfo(T) == .vector) {
692 const C = @typeInfo(T).vector.child;
693 if (C == u0) return @splat(0);
694
695 if (@typeInfo(C).int.signedness == .signed) {
696 @compileError("cannot rotate signed integers");
697 }
698 const ar: Log2Int(C) = @intCast(@mod(r, @typeInfo(C).int.bits));
699 return (x >> @splat(ar)) | (x << @splat(1 + ~ar));
700 } else if (@typeInfo(T).int.signedness == .signed) {
701 @compileError("cannot rotate signed integer");
702 } else {
703 if (T == u0) return 0;
704
705 if (comptime isPowerOfTwo(@typeInfo(T).int.bits)) {
706 const ar: Log2Int(T) = @intCast(@mod(r, @typeInfo(T).int.bits));
707 return x >> ar | x << (1 +% ~ar);
708 } else {
709 const ar = @mod(r, @typeInfo(T).int.bits);
710 return shr(T, x, ar) | shl(T, x, @typeInfo(T).int.bits - ar);
711 }
712 }
713}
714
715test rotr {
716 try testing.expect(rotr(u0, 0b0, @as(usize, 3)) == 0b0);
717 try testing.expect(rotr(u5, 0b00001, @as(usize, 0)) == 0b00001);
718 try testing.expect(rotr(u6, 0b000001, @as(usize, 7)) == 0b100000);
719 try testing.expect(rotr(u8, 0b00000001, @as(usize, 0)) == 0b00000001);
720 try testing.expect(rotr(u8, 0b00000001, @as(usize, 9)) == 0b10000000);
721 try testing.expect(rotr(u8, 0b00000001, @as(usize, 8)) == 0b00000001);
722 try testing.expect(rotr(u8, 0b00000001, @as(usize, 4)) == 0b00010000);
723 try testing.expect(rotr(u8, 0b00000001, @as(isize, -1)) == 0b00000010);
724 try testing.expect(rotr(u12, 0o7777, 1) == 0o7777);
725 try testing.expect(rotr(@Vector(1, u32), .{1}, @as(usize, 1))[0] == @as(u32, 1) << 31);
726 try testing.expect(rotr(@Vector(1, u32), .{1}, @as(isize, -1))[0] == @as(u32, 1) << 1);
727 try std.testing.expect(@reduce(.And, rotr(@Vector(2, u0), .{ 0, 0 }, @as(usize, 42)) ==
728 @Vector(2, u0){ 0, 0 }));
729}
730
731/// Rotates left. Only unsigned values can be rotated. Negative shift
732/// values result in shift modulo the bit count.
733pub fn rotl(comptime T: type, x: T, r: anytype) T {
734 if (@typeInfo(T) == .vector) {
735 const C = @typeInfo(T).vector.child;
736 if (C == u0) return @splat(0);
737
738 if (@typeInfo(C).int.signedness == .signed) {
739 @compileError("cannot rotate signed integers");
740 }
741 const ar: Log2Int(C) = @intCast(@mod(r, @typeInfo(C).int.bits));
742 return (x << @splat(ar)) | (x >> @splat(1 +% ~ar));
743 } else if (@typeInfo(T).int.signedness == .signed) {
744 @compileError("cannot rotate signed integer");
745 } else {
746 if (T == u0) return 0;
747
748 if (comptime isPowerOfTwo(@typeInfo(T).int.bits)) {
749 const ar: Log2Int(T) = @intCast(@mod(r, @typeInfo(T).int.bits));
750 return x << ar | x >> 1 +% ~ar;
751 } else {
752 const ar = @mod(r, @typeInfo(T).int.bits);
753 return shl(T, x, ar) | shr(T, x, @typeInfo(T).int.bits - ar);
754 }
755 }
756}
757
758test rotl {
759 try testing.expect(rotl(u0, 0b0, @as(usize, 3)) == 0b0);
760 try testing.expect(rotl(u5, 0b00001, @as(usize, 0)) == 0b00001);
761 try testing.expect(rotl(u6, 0b000001, @as(usize, 7)) == 0b000010);
762 try testing.expect(rotl(u8, 0b00000001, @as(usize, 0)) == 0b00000001);
763 try testing.expect(rotl(u8, 0b00000001, @as(usize, 9)) == 0b00000010);
764 try testing.expect(rotl(u8, 0b00000001, @as(usize, 8)) == 0b00000001);
765 try testing.expect(rotl(u8, 0b00000001, @as(usize, 4)) == 0b00010000);
766 try testing.expect(rotl(u8, 0b00000001, @as(isize, -1)) == 0b10000000);
767 try testing.expect(rotl(u12, 0o7777, 1) == 0o7777);
768 try testing.expect(rotl(@Vector(1, u32), .{1 << 31}, @as(usize, 1))[0] == 1);
769 try testing.expect(rotl(@Vector(1, u32), .{1 << 31}, @as(isize, -1))[0] == @as(u32, 1) << 30);
770 try std.testing.expect(@reduce(.And, rotl(@Vector(2, u0), .{ 0, 0 }, @as(usize, 42)) ==
771 @Vector(2, u0){ 0, 0 }));
772}
773
774/// Returns an unsigned int type that can hold the number of bits in T - 1.
775/// Suitable for 0-based bit indices of T.
776pub fn Log2Int(comptime T: type) type {
777 // comptime ceil log2
778 if (T == comptime_int) return comptime_int;
779 const bits: u16 = @typeInfo(T).int.bits;
780 const log2_bits = 16 - @clz(bits - 1);
781 return std.meta.Int(.unsigned, log2_bits);
782}
783
784/// Returns an unsigned int type that can hold the number of bits in T.
785pub fn Log2IntCeil(comptime T: type) type {
786 // comptime ceil log2
787 if (T == comptime_int) return comptime_int;
788 const bits: u16 = @typeInfo(T).int.bits;
789 const log2_bits = 16 - @clz(bits);
790 return std.meta.Int(.unsigned, log2_bits);
791}
792
793/// Returns the smallest integer type that can hold both from and to.
794pub fn IntFittingRange(comptime from: comptime_int, comptime to: comptime_int) type {
795 assert(from <= to);
796 const signedness: std.builtin.Signedness = if (from < 0) .signed else .unsigned;
797 return @Int(
798 signedness,
799 @as(u16, @intFromBool(signedness == .signed)) +
800 switch (if (from < 0) @max(@abs(from) - 1, to) else to) {
801 0 => 0,
802 else => |pos_max| 1 + log2(pos_max),
803 },
804 );
805}
806
807test IntFittingRange {
808 try testing.expect(IntFittingRange(0, 0) == u0);
809 try testing.expect(IntFittingRange(0, 1) == u1);
810 try testing.expect(IntFittingRange(0, 2) == u2);
811 try testing.expect(IntFittingRange(0, 3) == u2);
812 try testing.expect(IntFittingRange(0, 4) == u3);
813 try testing.expect(IntFittingRange(0, 7) == u3);
814 try testing.expect(IntFittingRange(0, 8) == u4);
815 try testing.expect(IntFittingRange(0, 9) == u4);
816 try testing.expect(IntFittingRange(0, 15) == u4);
817 try testing.expect(IntFittingRange(0, 16) == u5);
818 try testing.expect(IntFittingRange(0, 17) == u5);
819 try testing.expect(IntFittingRange(0, 4095) == u12);
820 try testing.expect(IntFittingRange(2000, 4095) == u12);
821 try testing.expect(IntFittingRange(0, 4096) == u13);
822 try testing.expect(IntFittingRange(2000, 4096) == u13);
823 try testing.expect(IntFittingRange(0, 4097) == u13);
824 try testing.expect(IntFittingRange(2000, 4097) == u13);
825 try testing.expect(IntFittingRange(0, 123456789123456798123456789) == u87);
826 try testing.expect(IntFittingRange(0, 123456789123456798123456789123456789123456798123456789) == u177);
827
828 try testing.expect(IntFittingRange(-1, -1) == i1);
829 try testing.expect(IntFittingRange(-1, 0) == i1);
830 try testing.expect(IntFittingRange(-1, 1) == i2);
831 try testing.expect(IntFittingRange(-2, -2) == i2);
832 try testing.expect(IntFittingRange(-2, -1) == i2);
833 try testing.expect(IntFittingRange(-2, 0) == i2);
834 try testing.expect(IntFittingRange(-2, 1) == i2);
835 try testing.expect(IntFittingRange(-2, 2) == i3);
836 try testing.expect(IntFittingRange(-1, 2) == i3);
837 try testing.expect(IntFittingRange(-1, 3) == i3);
838 try testing.expect(IntFittingRange(-1, 4) == i4);
839 try testing.expect(IntFittingRange(-1, 7) == i4);
840 try testing.expect(IntFittingRange(-1, 8) == i5);
841 try testing.expect(IntFittingRange(-1, 9) == i5);
842 try testing.expect(IntFittingRange(-1, 15) == i5);
843 try testing.expect(IntFittingRange(-1, 16) == i6);
844 try testing.expect(IntFittingRange(-1, 17) == i6);
845 try testing.expect(IntFittingRange(-1, 4095) == i13);
846 try testing.expect(IntFittingRange(-4096, 4095) == i13);
847 try testing.expect(IntFittingRange(-1, 4096) == i14);
848 try testing.expect(IntFittingRange(-4097, 4095) == i14);
849 try testing.expect(IntFittingRange(-1, 4097) == i14);
850 try testing.expect(IntFittingRange(-1, 123456789123456798123456789) == i88);
851 try testing.expect(IntFittingRange(-1, 123456789123456798123456789123456789123456798123456789) == i178);
852}
853
854test "overflow functions" {
855 try testOverflow();
856 try comptime testOverflow();
857}
858
859fn testOverflow() !void {
860 try testing.expect((mul(i32, 3, 4) catch unreachable) == 12);
861 try testing.expect((add(i32, 3, 4) catch unreachable) == 7);
862 try testing.expect((sub(i32, 3, 4) catch unreachable) == -1);
863 try testing.expect((shlExact(i32, 0b11, 4) catch unreachable) == 0b110000);
864}
865
866/// Divide numerator by denominator, rounding toward zero. Returns an
867/// error on overflow or when denominator is zero.
868pub fn divTrunc(comptime T: type, numerator: T, denominator: T) !T {
869 @setRuntimeSafety(false);
870 if (denominator == 0) return error.DivisionByZero;
871 if (@typeInfo(T) == .int and @typeInfo(T).int.signedness == .signed and numerator == minInt(T) and denominator == -1) return error.Overflow;
872 return @divTrunc(numerator, denominator);
873}
874
875test divTrunc {
876 try testDivTrunc();
877 try comptime testDivTrunc();
878}
879fn testDivTrunc() !void {
880 try testing.expect((divTrunc(i32, 5, 3) catch unreachable) == 1);
881 try testing.expect((divTrunc(i32, -5, 3) catch unreachable) == -1);
882 try testing.expectError(error.DivisionByZero, divTrunc(i8, -5, 0));
883 try testing.expectError(error.Overflow, divTrunc(i8, -128, -1));
884
885 try testing.expect((divTrunc(f32, 5.0, 3.0) catch unreachable) == 1.0);
886 try testing.expect((divTrunc(f32, -5.0, 3.0) catch unreachable) == -1.0);
887}
888
889/// Divide numerator by denominator, rounding toward negative
890/// infinity. Returns an error on overflow or when denominator is
891/// zero.
892pub fn divFloor(comptime T: type, numerator: T, denominator: T) !T {
893 @setRuntimeSafety(false);
894 if (denominator == 0) return error.DivisionByZero;
895 if (@typeInfo(T) == .int and @typeInfo(T).int.signedness == .signed and numerator == minInt(T) and denominator == -1) return error.Overflow;
896 return @divFloor(numerator, denominator);
897}
898
899test divFloor {
900 try testDivFloor();
901 try comptime testDivFloor();
902}
903fn testDivFloor() !void {
904 try testing.expect((divFloor(i32, 5, 3) catch unreachable) == 1);
905 try testing.expect((divFloor(i32, -5, 3) catch unreachable) == -2);
906 try testing.expectError(error.DivisionByZero, divFloor(i8, -5, 0));
907 try testing.expectError(error.Overflow, divFloor(i8, -128, -1));
908
909 try testing.expect((divFloor(f32, 5.0, 3.0) catch unreachable) == 1.0);
910 try testing.expect((divFloor(f32, -5.0, 3.0) catch unreachable) == -2.0);
911}
912
913/// Divide numerator by denominator, rounding toward positive
914/// infinity. Returns an error on overflow or when denominator is
915/// zero.
916pub fn divCeil(comptime T: type, numerator: T, denominator: T) !T {
917 @setRuntimeSafety(false);
918 if (denominator == 0) return error.DivisionByZero;
919 const info = @typeInfo(T);
920 switch (info) {
921 .comptime_float, .float => return @ceil(numerator / denominator),
922 .comptime_int, .int => {
923 if (numerator < 0 and denominator < 0) {
924 if (info == .int and numerator == minInt(T) and denominator == -1)
925 return error.Overflow;
926 return @divFloor(numerator + 1, denominator) + 1;
927 }
928 if (numerator > 0 and denominator > 0)
929 return @divFloor(numerator - 1, denominator) + 1;
930 return @divTrunc(numerator, denominator);
931 },
932 else => @compileError("divCeil unsupported on " ++ @typeName(T)),
933 }
934}
935
936test divCeil {
937 try testDivCeil();
938 try comptime testDivCeil();
939}
940fn testDivCeil() !void {
941 try testing.expectEqual(@as(i32, 2), divCeil(i32, 5, 3) catch unreachable);
942 try testing.expectEqual(@as(i32, -1), divCeil(i32, -5, 3) catch unreachable);
943 try testing.expectEqual(@as(i32, -1), divCeil(i32, 5, -3) catch unreachable);
944 try testing.expectEqual(@as(i32, 2), divCeil(i32, -5, -3) catch unreachable);
945 try testing.expectEqual(@as(i32, 0), divCeil(i32, 0, 5) catch unreachable);
946 try testing.expectEqual(@as(u32, 0), divCeil(u32, 0, 5) catch unreachable);
947 try testing.expectError(error.DivisionByZero, divCeil(i8, -5, 0));
948 try testing.expectError(error.Overflow, divCeil(i8, -128, -1));
949
950 try testing.expectEqual(@as(f32, 0.0), divCeil(f32, 0.0, 5.0) catch unreachable);
951 try testing.expectEqual(@as(f32, 2.0), divCeil(f32, 5.0, 3.0) catch unreachable);
952 try testing.expectEqual(@as(f32, -1.0), divCeil(f32, -5.0, 3.0) catch unreachable);
953 try testing.expectEqual(@as(f32, -1.0), divCeil(f32, 5.0, -3.0) catch unreachable);
954 try testing.expectEqual(@as(f32, 2.0), divCeil(f32, -5.0, -3.0) catch unreachable);
955
956 try testing.expectEqual(6, divCeil(comptime_int, 23, 4) catch unreachable);
957 try testing.expectEqual(-5, divCeil(comptime_int, -23, 4) catch unreachable);
958 try testing.expectEqual(-5, divCeil(comptime_int, 23, -4) catch unreachable);
959 try testing.expectEqual(6, divCeil(comptime_int, -23, -4) catch unreachable);
960 try testing.expectError(error.DivisionByZero, divCeil(comptime_int, 23, 0));
961
962 try testing.expectEqual(6.0, divCeil(comptime_float, 23.0, 4.0) catch unreachable);
963 try testing.expectEqual(-5.0, divCeil(comptime_float, -23.0, 4.0) catch unreachable);
964 try testing.expectEqual(-5.0, divCeil(comptime_float, 23.0, -4.0) catch unreachable);
965 try testing.expectEqual(6.0, divCeil(comptime_float, -23.0, -4.0) catch unreachable);
966 try testing.expectError(error.DivisionByZero, divCeil(comptime_float, 23.0, 0.0));
967}
968
969/// Divide numerator by denominator. Return an error if quotient is
970/// not an integer, denominator is zero, or on overflow.
971pub fn divExact(comptime T: type, numerator: T, denominator: T) !T {
972 @setRuntimeSafety(false);
973 if (denominator == 0) return error.DivisionByZero;
974 if (@typeInfo(T) == .int and @typeInfo(T).int.signedness == .signed and numerator == minInt(T) and denominator == -1) return error.Overflow;
975 const result = @divTrunc(numerator, denominator);
976 if (result * denominator != numerator) return error.UnexpectedRemainder;
977 return result;
978}
979
980test divExact {
981 try testDivExact();
982 try comptime testDivExact();
983}
984fn testDivExact() !void {
985 try testing.expect((divExact(i32, 10, 5) catch unreachable) == 2);
986 try testing.expect((divExact(i32, -10, 5) catch unreachable) == -2);
987 try testing.expectError(error.DivisionByZero, divExact(i8, -5, 0));
988 try testing.expectError(error.Overflow, divExact(i8, -128, -1));
989 try testing.expectError(error.UnexpectedRemainder, divExact(i32, 5, 2));
990
991 try testing.expect((divExact(f32, 10.0, 5.0) catch unreachable) == 2.0);
992 try testing.expect((divExact(f32, -10.0, 5.0) catch unreachable) == -2.0);
993 try testing.expectError(error.UnexpectedRemainder, divExact(f32, 5.0, 2.0));
994}
995
996/// Returns numerator modulo denominator, or an error if denominator is
997/// zero or negative. Negative numerators never result in negative
998/// return values.
999pub fn mod(comptime T: type, numerator: T, denominator: T) !T {
1000 @setRuntimeSafety(false);
1001 if (denominator == 0) return error.DivisionByZero;
1002 if (denominator < 0) return error.NegativeDenominator;
1003 return @mod(numerator, denominator);
1004}
1005
1006test mod {
1007 try testMod();
1008 try comptime testMod();
1009}
1010fn testMod() !void {
1011 try testing.expect((mod(i32, -5, 3) catch unreachable) == 1);
1012 try testing.expect((mod(i32, 5, 3) catch unreachable) == 2);
1013 try testing.expectError(error.NegativeDenominator, mod(i32, 10, -1));
1014 try testing.expectError(error.DivisionByZero, mod(i32, 10, 0));
1015
1016 try testing.expect((mod(f32, -5, 3) catch unreachable) == 1);
1017 try testing.expect((mod(f32, 5, 3) catch unreachable) == 2);
1018 try testing.expectError(error.NegativeDenominator, mod(f32, 10, -1));
1019 try testing.expectError(error.DivisionByZero, mod(f32, 10, 0));
1020}
1021
1022/// Returns the remainder when numerator is divided by denominator, or
1023/// an error if denominator is zero or negative. Negative numerators
1024/// can give negative results.
1025pub fn rem(comptime T: type, numerator: T, denominator: T) !T {
1026 @setRuntimeSafety(false);
1027 if (denominator == 0) return error.DivisionByZero;
1028 if (denominator < 0) return error.NegativeDenominator;
1029 return @rem(numerator, denominator);
1030}
1031
1032test rem {
1033 try testRem();
1034 try comptime testRem();
1035}
1036fn testRem() !void {
1037 try testing.expect((rem(i32, -5, 3) catch unreachable) == -2);
1038 try testing.expect((rem(i32, 5, 3) catch unreachable) == 2);
1039 try testing.expectError(error.NegativeDenominator, rem(i32, 10, -1));
1040 try testing.expectError(error.DivisionByZero, rem(i32, 10, 0));
1041
1042 try testing.expect((rem(f32, -5, 3) catch unreachable) == -2);
1043 try testing.expect((rem(f32, 5, 3) catch unreachable) == 2);
1044 try testing.expectError(error.NegativeDenominator, rem(f32, 10, -1));
1045 try testing.expectError(error.DivisionByZero, rem(f32, 10, 0));
1046}
1047
1048/// Returns the negation of the integer parameter.
1049/// Result is a signed integer.
1050pub fn negateCast(x: anytype) !std.meta.Int(.signed, @bitSizeOf(@TypeOf(x))) {
1051 if (@typeInfo(@TypeOf(x)).int.signedness == .signed) return negate(x);
1052
1053 const int = std.meta.Int(.signed, @bitSizeOf(@TypeOf(x)));
1054 if (x > -minInt(int)) return error.Overflow;
1055
1056 if (x == -minInt(int)) return minInt(int);
1057
1058 return -@as(int, @intCast(x));
1059}
1060
1061test negateCast {
1062 try testing.expect((negateCast(@as(u32, 999)) catch unreachable) == -999);
1063 try testing.expect(@TypeOf(negateCast(@as(u32, 999)) catch unreachable) == i32);
1064
1065 try testing.expect((negateCast(@as(u32, -minInt(i32))) catch unreachable) == minInt(i32));
1066 try testing.expect(@TypeOf(negateCast(@as(u32, -minInt(i32))) catch unreachable) == i32);
1067
1068 try testing.expectError(error.Overflow, negateCast(@as(u32, maxInt(i32) + 10)));
1069}
1070
1071/// Cast an integer to a different integer type. If the value doesn't fit,
1072/// return null.
1073pub fn cast(comptime T: type, x: anytype) ?T {
1074 comptime assert(@typeInfo(T) == .int); // must pass an integer
1075 const is_comptime = @TypeOf(x) == comptime_int;
1076 comptime assert(is_comptime or @typeInfo(@TypeOf(x)) == .int); // must pass an integer
1077 if ((is_comptime or maxInt(@TypeOf(x)) > maxInt(T)) and x > maxInt(T)) {
1078 return null;
1079 } else if ((is_comptime or minInt(@TypeOf(x)) < minInt(T)) and x < minInt(T)) {
1080 return null;
1081 } else {
1082 return @as(T, @intCast(x));
1083 }
1084}
1085
1086test cast {
1087 try testing.expect(cast(u8, 300) == null);
1088 try testing.expect(cast(u8, @as(u32, 300)) == null);
1089 try testing.expect(cast(i8, -200) == null);
1090 try testing.expect(cast(i8, @as(i32, -200)) == null);
1091 try testing.expect(cast(u8, -1) == null);
1092 try testing.expect(cast(u8, @as(i8, -1)) == null);
1093 try testing.expect(cast(u64, -1) == null);
1094 try testing.expect(cast(u64, @as(i8, -1)) == null);
1095
1096 try testing.expect(cast(u8, 255).? == @as(u8, 255));
1097 try testing.expect(cast(u8, @as(u32, 255)).? == @as(u8, 255));
1098 try testing.expect(@TypeOf(cast(u8, 255).?) == u8);
1099 try testing.expect(@TypeOf(cast(u8, @as(u32, 255)).?) == u8);
1100}
1101
1102pub const AlignCastError = error{UnalignedMemory};
1103
1104fn AlignCastResult(comptime alignment: Alignment, comptime Ptr: type) type {
1105 const orig = @typeInfo(Ptr).pointer;
1106 return @Pointer(orig.size, .{
1107 .@"const" = orig.is_const,
1108 .@"volatile" = orig.is_volatile,
1109 .@"allowzero" = orig.is_allowzero,
1110 .@"align" = alignment.toByteUnits(),
1111 .@"addrspace" = orig.address_space,
1112 }, orig.child, orig.sentinel());
1113}
1114
1115/// Align cast a pointer but return an error if it's the wrong alignment
1116pub fn alignCast(comptime alignment: Alignment, ptr: anytype) AlignCastError!AlignCastResult(alignment, @TypeOf(ptr)) {
1117 if (alignment.check(@intFromPtr(ptr))) return @alignCast(ptr);
1118 return error.UnalignedMemory;
1119}
1120
1121/// Asserts `int > 0`.
1122pub fn isPowerOfTwo(int: anytype) bool {
1123 assert(int > 0);
1124 return (int & (int - 1)) == 0;
1125}
1126
1127test isPowerOfTwo {
1128 try testing.expect(isPowerOfTwo(@as(u8, 1)));
1129 try testing.expect(isPowerOfTwo(2));
1130 try testing.expect(!isPowerOfTwo(@as(i16, 3)));
1131 try testing.expect(isPowerOfTwo(4));
1132 try testing.expect(!isPowerOfTwo(@as(u32, 31)));
1133 try testing.expect(isPowerOfTwo(32));
1134 try testing.expect(!isPowerOfTwo(@as(i64, 63)));
1135 try testing.expect(isPowerOfTwo(128));
1136 try testing.expect(isPowerOfTwo(@as(u128, 256)));
1137}
1138
1139/// Aligns the given integer type bit width to a width divisible by 8.
1140pub fn ByteAlignedInt(comptime T: type) type {
1141 const info = @typeInfo(T).int;
1142 const bits = (info.bits + 7) / 8 * 8;
1143 const extended_type = std.meta.Int(info.signedness, bits);
1144 return extended_type;
1145}
1146
1147test ByteAlignedInt {
1148 try testing.expect(ByteAlignedInt(u0) == u0);
1149 try testing.expect(ByteAlignedInt(i0) == i0);
1150 try testing.expect(ByteAlignedInt(u3) == u8);
1151 try testing.expect(ByteAlignedInt(u8) == u8);
1152 try testing.expect(ByteAlignedInt(i111) == i112);
1153 try testing.expect(ByteAlignedInt(u129) == u136);
1154}
1155
1156/// Rounds the given floating point number to the nearest integer.
1157/// If two integers are equally close, rounds away from zero.
1158/// Uses a dedicated hardware instruction when available.
1159/// This is the same as calling the builtin @round
1160pub inline fn round(value: anytype) @TypeOf(value) {
1161 return @round(value);
1162}
1163
1164/// Rounds the given floating point number to an integer, towards zero.
1165/// Uses a dedicated hardware instruction when available.
1166/// This is the same as calling the builtin @trunc
1167pub inline fn trunc(value: anytype) @TypeOf(value) {
1168 return @trunc(value);
1169}
1170
1171/// Returns the largest integral value not greater than the given floating point number.
1172/// Uses a dedicated hardware instruction when available.
1173/// This is the same as calling the builtin @floor
1174pub inline fn floor(value: anytype) @TypeOf(value) {
1175 return @floor(value);
1176}
1177
1178/// Returns the nearest power of two less than or equal to value, or
1179/// zero if value is less than or equal to zero.
1180pub fn floorPowerOfTwo(comptime T: type, value: T) T {
1181 const uT = std.meta.Int(.unsigned, @typeInfo(T).int.bits);
1182 if (value <= 0) return 0;
1183 return @as(T, 1) << log2_int(uT, @as(uT, @intCast(value)));
1184}
1185
1186test floorPowerOfTwo {
1187 try testFloorPowerOfTwo();
1188 try comptime testFloorPowerOfTwo();
1189}
1190
1191fn testFloorPowerOfTwo() !void {
1192 try testing.expect(floorPowerOfTwo(u32, 63) == 32);
1193 try testing.expect(floorPowerOfTwo(u32, 64) == 64);
1194 try testing.expect(floorPowerOfTwo(u32, 65) == 64);
1195 try testing.expect(floorPowerOfTwo(u32, 0) == 0);
1196 try testing.expect(floorPowerOfTwo(u4, 7) == 4);
1197 try testing.expect(floorPowerOfTwo(u4, 8) == 8);
1198 try testing.expect(floorPowerOfTwo(u4, 9) == 8);
1199 try testing.expect(floorPowerOfTwo(u4, 0) == 0);
1200 try testing.expect(floorPowerOfTwo(i4, 7) == 4);
1201 try testing.expect(floorPowerOfTwo(i4, -8) == 0);
1202 try testing.expect(floorPowerOfTwo(i4, -1) == 0);
1203 try testing.expect(floorPowerOfTwo(i4, 0) == 0);
1204}
1205
1206/// Returns the smallest integral value not less than the given floating point number.
1207/// Uses a dedicated hardware instruction when available.
1208/// This is the same as calling the builtin @ceil
1209pub inline fn ceil(value: anytype) @TypeOf(value) {
1210 return @ceil(value);
1211}
1212
1213/// Returns the next power of two (if the value is not already a power of two).
1214/// Only unsigned integers can be used. Zero is not an allowed input.
1215/// Result is a type with 1 more bit than the input type.
1216pub fn ceilPowerOfTwoPromote(comptime T: type, value: T) std.meta.Int(@typeInfo(T).int.signedness, @typeInfo(T).int.bits + 1) {
1217 comptime assert(@typeInfo(T) == .int);
1218 comptime assert(@typeInfo(T).int.signedness == .unsigned);
1219 assert(value != 0);
1220 const PromotedType = std.meta.Int(@typeInfo(T).int.signedness, @typeInfo(T).int.bits + 1);
1221 const ShiftType = std.math.Log2Int(PromotedType);
1222 return @as(PromotedType, 1) << @as(ShiftType, @intCast(@typeInfo(T).int.bits - @clz(value - 1)));
1223}
1224
1225/// Returns the next power of two (if the value is not already a power of two).
1226/// Only unsigned integers can be used. Zero is not an allowed input.
1227/// If the value doesn't fit, returns an error.
1228pub fn ceilPowerOfTwo(comptime T: type, value: T) (error{Overflow}!T) {
1229 comptime assert(@typeInfo(T) == .int);
1230 const info = @typeInfo(T).int;
1231 comptime assert(info.signedness == .unsigned);
1232 const PromotedType = std.meta.Int(info.signedness, info.bits + 1);
1233 const overflowBit = @as(PromotedType, 1) << info.bits;
1234 const x = ceilPowerOfTwoPromote(T, value);
1235 if (overflowBit & x != 0) {
1236 return error.Overflow;
1237 }
1238 return @as(T, @intCast(x));
1239}
1240
1241/// Returns the next power of two (if the value is not already a power
1242/// of two). Only unsigned integers can be used. Zero is not an
1243/// allowed input. Asserts that the value fits.
1244pub fn ceilPowerOfTwoAssert(comptime T: type, value: T) T {
1245 return ceilPowerOfTwo(T, value) catch unreachable;
1246}
1247
1248test ceilPowerOfTwoPromote {
1249 try testCeilPowerOfTwoPromote();
1250 try comptime testCeilPowerOfTwoPromote();
1251}
1252
1253fn testCeilPowerOfTwoPromote() !void {
1254 try testing.expectEqual(@as(u33, 1), ceilPowerOfTwoPromote(u32, 1));
1255 try testing.expectEqual(@as(u33, 2), ceilPowerOfTwoPromote(u32, 2));
1256 try testing.expectEqual(@as(u33, 64), ceilPowerOfTwoPromote(u32, 63));
1257 try testing.expectEqual(@as(u33, 64), ceilPowerOfTwoPromote(u32, 64));
1258 try testing.expectEqual(@as(u33, 128), ceilPowerOfTwoPromote(u32, 65));
1259 try testing.expectEqual(@as(u6, 8), ceilPowerOfTwoPromote(u5, 7));
1260 try testing.expectEqual(@as(u6, 8), ceilPowerOfTwoPromote(u5, 8));
1261 try testing.expectEqual(@as(u6, 16), ceilPowerOfTwoPromote(u5, 9));
1262 try testing.expectEqual(@as(u5, 16), ceilPowerOfTwoPromote(u4, 9));
1263}
1264
1265test ceilPowerOfTwo {
1266 try testCeilPowerOfTwo();
1267 try comptime testCeilPowerOfTwo();
1268}
1269
1270fn testCeilPowerOfTwo() !void {
1271 try testing.expectEqual(@as(u32, 1), try ceilPowerOfTwo(u32, 1));
1272 try testing.expectEqual(@as(u32, 2), try ceilPowerOfTwo(u32, 2));
1273 try testing.expectEqual(@as(u32, 64), try ceilPowerOfTwo(u32, 63));
1274 try testing.expectEqual(@as(u32, 64), try ceilPowerOfTwo(u32, 64));
1275 try testing.expectEqual(@as(u32, 128), try ceilPowerOfTwo(u32, 65));
1276 try testing.expectEqual(@as(u5, 8), try ceilPowerOfTwo(u5, 7));
1277 try testing.expectEqual(@as(u5, 8), try ceilPowerOfTwo(u5, 8));
1278 try testing.expectEqual(@as(u5, 16), try ceilPowerOfTwo(u5, 9));
1279 try testing.expectError(error.Overflow, ceilPowerOfTwo(u4, 9));
1280}
1281
1282/// Return the log base 2 of integer value x, rounding down to the
1283/// nearest integer.
1284pub fn log2_int(comptime T: type, x: T) Log2Int(T) {
1285 if (@typeInfo(T) != .int or @typeInfo(T).int.signedness != .unsigned)
1286 @compileError("log2_int requires an unsigned integer, found " ++ @typeName(T));
1287 assert(x != 0);
1288 return @as(Log2Int(T), @intCast(@typeInfo(T).int.bits - 1 - @clz(x)));
1289}
1290
1291test log2_int {
1292 try testing.expect(log2_int(u32, 1) == 0);
1293 try testing.expect(log2_int(u32, 2) == 1);
1294 try testing.expect(log2_int(u32, 3) == 1);
1295 try testing.expect(log2_int(u32, 4) == 2);
1296 try testing.expect(log2_int(u32, 5) == 2);
1297 try testing.expect(log2_int(u32, 6) == 2);
1298 try testing.expect(log2_int(u32, 7) == 2);
1299 try testing.expect(log2_int(u32, 8) == 3);
1300 try testing.expect(log2_int(u32, 9) == 3);
1301 try testing.expect(log2_int(u32, 10) == 3);
1302}
1303
1304/// Return the log base 2 of integer value x, rounding up to the
1305/// nearest integer.
1306pub fn log2_int_ceil(comptime T: type, x: T) Log2IntCeil(T) {
1307 if (@typeInfo(T) != .int or @typeInfo(T).int.signedness != .unsigned)
1308 @compileError("log2_int_ceil requires an unsigned integer, found " ++ @typeName(T));
1309 assert(x != 0);
1310 if (x == 1) return 0;
1311 const log2_val: Log2IntCeil(T) = log2_int(T, x - 1);
1312 return log2_val + 1;
1313}
1314
1315test log2_int_ceil {
1316 try testing.expect(log2_int_ceil(u32, 1) == 0);
1317 try testing.expect(log2_int_ceil(u32, 2) == 1);
1318 try testing.expect(log2_int_ceil(u32, 3) == 2);
1319 try testing.expect(log2_int_ceil(u32, 4) == 2);
1320 try testing.expect(log2_int_ceil(u32, 5) == 3);
1321 try testing.expect(log2_int_ceil(u32, 6) == 3);
1322 try testing.expect(log2_int_ceil(u32, 7) == 3);
1323 try testing.expect(log2_int_ceil(u32, 8) == 3);
1324 try testing.expect(log2_int_ceil(u32, 9) == 4);
1325 try testing.expect(log2_int_ceil(u32, 10) == 4);
1326}
1327
1328/// Cast a value to a different type. If the value doesn't fit in, or
1329/// can't be perfectly represented by, the new type, it will be
1330/// converted to the closest possible representation.
1331pub fn lossyCast(comptime T: type, value: anytype) T {
1332 switch (@typeInfo(T)) {
1333 .float => {
1334 switch (@typeInfo(@TypeOf(value))) {
1335 .int => return @floatFromInt(value),
1336 .float => return @floatCast(value),
1337 .comptime_int => return value,
1338 .comptime_float => return value,
1339 else => @compileError("bad type"),
1340 }
1341 },
1342 .int => {
1343 switch (@typeInfo(@TypeOf(value))) {
1344 .int, .comptime_int => {
1345 if (value >= maxInt(T)) {
1346 return maxInt(T);
1347 } else if (value <= minInt(T)) {
1348 return minInt(T);
1349 } else {
1350 return @intCast(value);
1351 }
1352 },
1353 .float, .comptime_float => {
1354 // In extreme cases, we probably need a language enhancement to be able to
1355 // specify a rounding mode here to prevent `@intFromFloat` panics.
1356 const max: @TypeOf(value) = @floatFromInt(maxInt(T));
1357 const min: @TypeOf(value) = @floatFromInt(minInt(T));
1358 if (isNan(value)) {
1359 return 0;
1360 } else if (value >= max) {
1361 return maxInt(T);
1362 } else if (value <= min) {
1363 return minInt(T);
1364 } else {
1365 return @intFromFloat(value);
1366 }
1367 },
1368 else => @compileError("bad type"),
1369 }
1370 },
1371 else => @compileError("bad result type"),
1372 }
1373}
1374
1375test lossyCast {
1376 try testing.expect(lossyCast(i16, 70000.0) == @as(i16, 32767));
1377 try testing.expect(lossyCast(u32, @as(i16, -255)) == @as(u32, 0));
1378 try testing.expect(lossyCast(i9, @as(u32, 200)) == @as(i9, 200));
1379 try testing.expect(lossyCast(u32, @as(f32, @floatFromInt(maxInt(u32)))) == maxInt(u32));
1380 try testing.expect(lossyCast(u32, nan(f32)) == 0);
1381}
1382
1383/// Performs linear interpolation between *a* and *b* based on *t*.
1384/// *t* ranges from 0.0 to 1.0, but may exceed these bounds.
1385/// Supports floats and vectors of floats.
1386///
1387/// This does not guarantee returning *b* if *t* is 1 due to floating-point errors.
1388/// This is monotonic.
1389pub fn lerp(a: anytype, b: anytype, t: anytype) @TypeOf(a, b, t) {
1390 const Type = @TypeOf(a, b, t);
1391 return @mulAdd(Type, b - a, t, a);
1392}
1393
1394test lerp {
1395 if (builtin.zig_backend == .stage2_c) return error.SkipZigTest; // https://github.com/ziglang/zig/issues/17884
1396 if (builtin.zig_backend == .stage2_x86_64 and !comptime builtin.cpu.has(.x86, .fma)) return error.SkipZigTest; // https://github.com/ziglang/zig/issues/17884
1397
1398 try testing.expectEqual(@as(f64, 75), lerp(50, 100, 0.5));
1399 try testing.expectEqual(@as(f32, 43.75), lerp(50, 25, 0.25));
1400 try testing.expectEqual(@as(f64, -31.25), lerp(-50, 25, 0.25));
1401
1402 try testing.expectEqual(@as(f64, 30), lerp(10, 20, 2.0));
1403 try testing.expectEqual(@as(f64, 5), lerp(10, 20, -0.5));
1404
1405 try testing.expectApproxEqRel(@as(f32, -7.16067345e+03), lerp(-10000.12345, -5000.12345, 0.56789), 1e-19);
1406 try testing.expectApproxEqRel(@as(f64, 7.010987590521e+62), lerp(0.123456789e-64, 0.123456789e64, 0.56789), 1e-33);
1407
1408 try testing.expectEqual(@as(f32, 0.0), lerp(@as(f32, 1.0e8), 1.0, 1.0));
1409 try testing.expectEqual(@as(f64, 0.0), lerp(@as(f64, 1.0e16), 1.0, 1.0));
1410 try testing.expectEqual(@as(f32, 1.0), lerp(@as(f32, 1.0e7), 1.0, 1.0));
1411 try testing.expectEqual(@as(f64, 1.0), lerp(@as(f64, 1.0e15), 1.0, 1.0));
1412
1413 {
1414 const a: @Vector(3, f32) = @splat(0);
1415 const b: @Vector(3, f32) = @splat(50);
1416 const t: @Vector(3, f32) = @splat(0.5);
1417 try testing.expectEqual(
1418 @Vector(3, f32){ 25, 25, 25 },
1419 lerp(a, b, t),
1420 );
1421 }
1422 {
1423 const a: @Vector(3, f64) = @splat(50);
1424 const b: @Vector(3, f64) = @splat(100);
1425 const t: @Vector(3, f64) = @splat(0.5);
1426 try testing.expectEqual(
1427 @Vector(3, f64){ 75, 75, 75 },
1428 lerp(a, b, t),
1429 );
1430 }
1431 {
1432 const a: @Vector(2, f32) = @splat(40);
1433 const b: @Vector(2, f32) = @splat(80);
1434 const t: @Vector(2, f32) = @Vector(2, f32){ 0.25, 0.75 };
1435 try testing.expectEqual(
1436 @Vector(2, f32){ 50, 70 },
1437 lerp(a, b, t),
1438 );
1439 }
1440}
1441
1442/// Returns the maximum value of integer type T.
1443pub fn maxInt(comptime T: type) comptime_int {
1444 const info = @typeInfo(T);
1445 const bit_count = info.int.bits;
1446 if (bit_count == 0) return 0;
1447 return (1 << (bit_count - @intFromBool(info.int.signedness == .signed))) - 1;
1448}
1449
1450/// Returns the minimum value of integer type T.
1451pub fn minInt(comptime T: type) comptime_int {
1452 const info = @typeInfo(T);
1453 const bit_count = info.int.bits;
1454 if (info.int.signedness == .unsigned) return 0;
1455 if (bit_count == 0) return 0;
1456 return -(1 << (bit_count - 1));
1457}
1458
1459test maxInt {
1460 try testing.expect(maxInt(u0) == 0);
1461 try testing.expect(maxInt(u1) == 1);
1462 try testing.expect(maxInt(u8) == 255);
1463 try testing.expect(maxInt(u16) == 65535);
1464 try testing.expect(maxInt(u32) == 4294967295);
1465 try testing.expect(maxInt(u64) == 18446744073709551615);
1466 try testing.expect(maxInt(u128) == 340282366920938463463374607431768211455);
1467
1468 try testing.expect(maxInt(i0) == 0);
1469 try testing.expect(maxInt(i1) == 0);
1470 try testing.expect(maxInt(i8) == 127);
1471 try testing.expect(maxInt(i16) == 32767);
1472 try testing.expect(maxInt(i32) == 2147483647);
1473 try testing.expect(maxInt(i63) == 4611686018427387903);
1474 try testing.expect(maxInt(i64) == 9223372036854775807);
1475 try testing.expect(maxInt(i128) == 170141183460469231731687303715884105727);
1476}
1477
1478test minInt {
1479 try testing.expect(minInt(u0) == 0);
1480 try testing.expect(minInt(u1) == 0);
1481 try testing.expect(minInt(u8) == 0);
1482 try testing.expect(minInt(u16) == 0);
1483 try testing.expect(minInt(u32) == 0);
1484 try testing.expect(minInt(u63) == 0);
1485 try testing.expect(minInt(u64) == 0);
1486 try testing.expect(minInt(u128) == 0);
1487
1488 try testing.expect(minInt(i0) == 0);
1489 try testing.expect(minInt(i1) == -1);
1490 try testing.expect(minInt(i8) == -128);
1491 try testing.expect(minInt(i16) == -32768);
1492 try testing.expect(minInt(i32) == -2147483648);
1493 try testing.expect(minInt(i63) == -4611686018427387904);
1494 try testing.expect(minInt(i64) == -9223372036854775808);
1495 try testing.expect(minInt(i128) == -170141183460469231731687303715884105728);
1496}
1497
1498test "max value type" {
1499 const x: u32 = maxInt(i32);
1500 try testing.expect(x == 2147483647);
1501}
1502
1503/// Multiply a and b. Return type is wide enough to guarantee no
1504/// overflow.
1505pub fn mulWide(comptime T: type, a: T, b: T) std.meta.Int(
1506 @typeInfo(T).int.signedness,
1507 @typeInfo(T).int.bits * 2,
1508) {
1509 const ResultInt = std.meta.Int(
1510 @typeInfo(T).int.signedness,
1511 @typeInfo(T).int.bits * 2,
1512 );
1513 return @as(ResultInt, a) * @as(ResultInt, b);
1514}
1515
1516test mulWide {
1517 try testing.expect(mulWide(u8, 5, 5) == 25);
1518 try testing.expect(mulWide(i8, 5, -5) == -25);
1519 try testing.expect(mulWide(u8, 100, 100) == 10000);
1520}
1521
1522/// See also `CompareOperator`.
1523pub const Order = enum {
1524 /// Greater than (`>`)
1525 gt,
1526
1527 /// Less than (`<`)
1528 lt,
1529
1530 /// Equal (`==`)
1531 eq,
1532
1533 pub fn invert(self: Order) Order {
1534 return switch (self) {
1535 .lt => .gt,
1536 .eq => .eq,
1537 .gt => .lt,
1538 };
1539 }
1540
1541 test invert {
1542 try testing.expect(Order.invert(order(0, 0)) == .eq);
1543 try testing.expect(Order.invert(order(1, 0)) == .lt);
1544 try testing.expect(Order.invert(order(-1, 0)) == .gt);
1545 }
1546
1547 pub fn differ(self: Order) ?Order {
1548 return if (self != .eq) self else null;
1549 }
1550
1551 test differ {
1552 const neg: i32 = -1;
1553 const zero: i32 = 0;
1554 const pos: i32 = 1;
1555 try testing.expect(order(zero, neg).differ() orelse
1556 order(pos, zero) == .gt);
1557 try testing.expect(order(zero, zero).differ() orelse
1558 order(zero, zero) == .eq);
1559 try testing.expect(order(pos, pos).differ() orelse
1560 order(neg, zero) == .lt);
1561 try testing.expect(order(zero, zero).differ() orelse
1562 order(pos, neg).differ() orelse
1563 order(neg, zero) == .gt);
1564 try testing.expect(order(pos, pos).differ() orelse
1565 order(pos, pos).differ() orelse
1566 order(neg, neg) == .eq);
1567 try testing.expect(order(zero, pos).differ() orelse
1568 order(neg, pos).differ() orelse
1569 order(pos, neg) == .lt);
1570 }
1571
1572 pub fn compare(self: Order, op: CompareOperator) bool {
1573 return switch (self) {
1574 .lt => switch (op) {
1575 .lt => true,
1576 .lte => true,
1577 .eq => false,
1578 .gte => false,
1579 .gt => false,
1580 .neq => true,
1581 },
1582 .eq => switch (op) {
1583 .lt => false,
1584 .lte => true,
1585 .eq => true,
1586 .gte => true,
1587 .gt => false,
1588 .neq => false,
1589 },
1590 .gt => switch (op) {
1591 .lt => false,
1592 .lte => false,
1593 .eq => false,
1594 .gte => true,
1595 .gt => true,
1596 .neq => true,
1597 },
1598 };
1599 }
1600
1601 // https://github.com/ziglang/zig/issues/19295
1602 test "compare" {
1603 try testing.expect(order(-1, 0).compare(.lt));
1604 try testing.expect(order(-1, 0).compare(.lte));
1605 try testing.expect(order(0, 0).compare(.lte));
1606 try testing.expect(order(0, 0).compare(.eq));
1607 try testing.expect(order(0, 0).compare(.gte));
1608 try testing.expect(order(1, 0).compare(.gte));
1609 try testing.expect(order(1, 0).compare(.gt));
1610 try testing.expect(order(1, 0).compare(.neq));
1611 }
1612};
1613
1614/// Given two numbers, this function returns the order they are with respect to each other.
1615pub fn order(a: anytype, b: anytype) Order {
1616 if (a == b) {
1617 return .eq;
1618 } else if (a < b) {
1619 return .lt;
1620 } else if (a > b) {
1621 return .gt;
1622 } else {
1623 unreachable;
1624 }
1625}
1626
1627/// See also `Order`.
1628pub const CompareOperator = enum {
1629 /// Less than (`<`)
1630 lt,
1631 /// Less than or equal (`<=`)
1632 lte,
1633 /// Equal (`==`)
1634 eq,
1635 /// Greater than or equal (`>=`)
1636 gte,
1637 /// Greater than (`>`)
1638 gt,
1639 /// Not equal (`!=`)
1640 neq,
1641
1642 /// Reverse the direction of the comparison.
1643 /// Use when swapping the left and right hand operands.
1644 pub fn reverse(op: CompareOperator) CompareOperator {
1645 return switch (op) {
1646 .lt => .gt,
1647 .lte => .gte,
1648 .gt => .lt,
1649 .gte => .lte,
1650 .eq => .eq,
1651 .neq => .neq,
1652 };
1653 }
1654
1655 test reverse {
1656 inline for (@typeInfo(CompareOperator).@"enum".fields) |op_field| {
1657 const op = @as(CompareOperator, @enumFromInt(op_field.value));
1658 try testing.expect(compare(2, op, 3) == compare(3, op.reverse(), 2));
1659 try testing.expect(compare(3, op, 3) == compare(3, op.reverse(), 3));
1660 try testing.expect(compare(4, op, 3) == compare(3, op.reverse(), 4));
1661 }
1662 }
1663};
1664
1665/// This function does the same thing as comparison operators, however the
1666/// operator is a runtime-known enum value. Works on any operands that
1667/// support comparison operators.
1668pub fn compare(a: anytype, op: CompareOperator, b: anytype) bool {
1669 return switch (op) {
1670 .lt => a < b,
1671 .lte => a <= b,
1672 .eq => a == b,
1673 .neq => a != b,
1674 .gt => a > b,
1675 .gte => a >= b,
1676 };
1677}
1678
1679test compare {
1680 try testing.expect(compare(@as(i8, -1), .lt, @as(u8, 255)));
1681 try testing.expect(compare(@as(i8, 2), .gt, @as(u8, 1)));
1682 try testing.expect(!compare(@as(i8, -1), .gte, @as(u8, 255)));
1683 try testing.expect(compare(@as(u8, 255), .gt, @as(i8, -1)));
1684 try testing.expect(!compare(@as(u8, 255), .lte, @as(i8, -1)));
1685 try testing.expect(compare(@as(i8, -1), .lt, @as(u9, 255)));
1686 try testing.expect(!compare(@as(i8, -1), .gte, @as(u9, 255)));
1687 try testing.expect(compare(@as(u9, 255), .gt, @as(i8, -1)));
1688 try testing.expect(!compare(@as(u9, 255), .lte, @as(i8, -1)));
1689 try testing.expect(compare(@as(i9, -1), .lt, @as(u8, 255)));
1690 try testing.expect(!compare(@as(i9, -1), .gte, @as(u8, 255)));
1691 try testing.expect(compare(@as(u8, 255), .gt, @as(i9, -1)));
1692 try testing.expect(!compare(@as(u8, 255), .lte, @as(i9, -1)));
1693 try testing.expect(compare(@as(u8, 1), .lt, @as(u8, 2)));
1694 try testing.expect(@as(u8, @bitCast(@as(i8, -1))) == @as(u8, 255));
1695 try testing.expect(!compare(@as(u8, 255), .eq, @as(i8, -1)));
1696 try testing.expect(compare(@as(u8, 1), .eq, @as(u8, 1)));
1697}
1698
1699test order {
1700 try testing.expect(order(0, 0) == .eq);
1701 try testing.expect(order(1, 0) == .gt);
1702 try testing.expect(order(-1, 0) == .lt);
1703}
1704
1705/// Returns a mask of all ones if value is true,
1706/// and a mask of all zeroes if value is false.
1707/// Compiles to one instruction for register sized integers.
1708pub inline fn boolMask(comptime MaskInt: type, value: bool) MaskInt {
1709 if (@typeInfo(MaskInt) != .int)
1710 @compileError("boolMask requires an integer mask type.");
1711
1712 if (MaskInt == u0 or MaskInt == i0)
1713 @compileError("boolMask cannot convert to u0 or i0, they are too small.");
1714
1715 // The u1 and i1 cases tend to overflow,
1716 // so we special case them here.
1717 if (MaskInt == u1) return @intFromBool(value);
1718 if (MaskInt == i1) {
1719 // The @as here is a workaround for #7950
1720 return @as(i1, @bitCast(@as(u1, @intFromBool(value))));
1721 }
1722
1723 return -%@as(MaskInt, @intCast(@intFromBool(value)));
1724}
1725
1726test boolMask {
1727 const runTest = struct {
1728 fn runTest() !void {
1729 try testing.expectEqual(@as(u1, 0), boolMask(u1, false));
1730 try testing.expectEqual(@as(u1, 1), boolMask(u1, true));
1731
1732 try testing.expectEqual(@as(i1, 0), boolMask(i1, false));
1733 try testing.expectEqual(@as(i1, -1), boolMask(i1, true));
1734
1735 try testing.expectEqual(@as(u13, 0), boolMask(u13, false));
1736 try testing.expectEqual(@as(u13, 0x1FFF), boolMask(u13, true));
1737
1738 try testing.expectEqual(@as(i13, 0), boolMask(i13, false));
1739 try testing.expectEqual(@as(i13, -1), boolMask(i13, true));
1740
1741 try testing.expectEqual(@as(u32, 0), boolMask(u32, false));
1742 try testing.expectEqual(@as(u32, 0xFFFF_FFFF), boolMask(u32, true));
1743
1744 try testing.expectEqual(@as(i32, 0), boolMask(i32, false));
1745 try testing.expectEqual(@as(i32, -1), boolMask(i32, true));
1746 }
1747 }.runTest;
1748 try runTest();
1749 try comptime runTest();
1750}
1751
1752/// Return the mod of `num` with the smallest integer type
1753pub fn comptimeMod(num: anytype, comptime denom: comptime_int) IntFittingRange(0, denom - 1) {
1754 return @as(IntFittingRange(0, denom - 1), @intCast(@mod(num, denom)));
1755}
1756
1757pub const F80 = struct {
1758 fraction: u64,
1759 exp: u16,
1760
1761 pub fn toFloat(self: F80) f80 {
1762 const int = (@as(u80, self.exp) << 64) | self.fraction;
1763 return @as(f80, @bitCast(int));
1764 }
1765
1766 pub fn fromFloat(x: f80) F80 {
1767 const int = @as(u80, @bitCast(x));
1768 return .{
1769 .fraction = @as(u64, @truncate(int)),
1770 .exp = @as(u16, @truncate(int >> 64)),
1771 };
1772 }
1773};
1774
1775/// Returns -1, 0, or 1.
1776/// Supports integer and float types and vectors of integer and float types.
1777/// Unsigned integer types will always return 0 or 1.
1778/// Branchless.
1779pub inline fn sign(i: anytype) @TypeOf(i) {
1780 const T = @TypeOf(i);
1781 return switch (@typeInfo(T)) {
1782 .int, .comptime_int => @as(T, @intFromBool(i > 0)) - @as(T, @intFromBool(i < 0)),
1783 .float, .comptime_float => @as(T, @floatFromInt(@intFromBool(i > 0))) - @as(T, @floatFromInt(@intFromBool(i < 0))),
1784 .vector => |vinfo| blk: {
1785 switch (@typeInfo(vinfo.child)) {
1786 .int, .float => {
1787 const zero: T = @splat(0);
1788 const one: T = @splat(1);
1789 break :blk @select(vinfo.child, i > zero, one, zero) - @select(vinfo.child, i < zero, one, zero);
1790 },
1791 else => @compileError("Expected vector of ints or floats, found " ++ @typeName(T)),
1792 }
1793 },
1794 else => @compileError("Expected an int, float or vector of one, found " ++ @typeName(T)),
1795 };
1796}
1797
1798fn testSign() !void {
1799 // each of the following blocks checks the inputs
1800 // 2, -2, 0, { 2, -2, 0 } provide expected output
1801 // 1, -1, 0, { 1, -1, 0 } for the given T
1802 // (negative values omitted for unsigned types)
1803 {
1804 const T = i8;
1805 try std.testing.expectEqual(@as(T, 1), sign(@as(T, 2)));
1806 try std.testing.expectEqual(@as(T, -1), sign(@as(T, -2)));
1807 try std.testing.expectEqual(@as(T, 0), sign(@as(T, 0)));
1808 try std.testing.expectEqual(@Vector(3, T){ 1, -1, 0 }, sign(@Vector(3, T){ 2, -2, 0 }));
1809 }
1810 {
1811 const T = i32;
1812 try std.testing.expectEqual(@as(T, 1), sign(@as(T, 2)));
1813 try std.testing.expectEqual(@as(T, -1), sign(@as(T, -2)));
1814 try std.testing.expectEqual(@as(T, 0), sign(@as(T, 0)));
1815 try std.testing.expectEqual(@Vector(3, T){ 1, -1, 0 }, sign(@Vector(3, T){ 2, -2, 0 }));
1816 }
1817 {
1818 const T = i64;
1819 try std.testing.expectEqual(@as(T, 1), sign(@as(T, 2)));
1820 try std.testing.expectEqual(@as(T, -1), sign(@as(T, -2)));
1821 try std.testing.expectEqual(@as(T, 0), sign(@as(T, 0)));
1822 try std.testing.expectEqual(@Vector(3, T){ 1, -1, 0 }, sign(@Vector(3, T){ 2, -2, 0 }));
1823 }
1824 {
1825 const T = u8;
1826 try std.testing.expectEqual(@as(T, 1), sign(@as(T, 2)));
1827 try std.testing.expectEqual(@as(T, 0), sign(@as(T, 0)));
1828 try std.testing.expectEqual(@Vector(2, T){ 1, 0 }, sign(@Vector(2, T){ 2, 0 }));
1829 }
1830 {
1831 const T = u32;
1832 try std.testing.expectEqual(@as(T, 1), sign(@as(T, 2)));
1833 try std.testing.expectEqual(@as(T, 0), sign(@as(T, 0)));
1834 try std.testing.expectEqual(@Vector(2, T){ 1, 0 }, sign(@Vector(2, T){ 2, 0 }));
1835 }
1836 {
1837 const T = u64;
1838 try std.testing.expectEqual(@as(T, 1), sign(@as(T, 2)));
1839 try std.testing.expectEqual(@as(T, 0), sign(@as(T, 0)));
1840 try std.testing.expectEqual(@Vector(2, T){ 1, 0 }, sign(@Vector(2, T){ 2, 0 }));
1841 }
1842 {
1843 const T = f16;
1844 try std.testing.expectEqual(@as(T, 1), sign(@as(T, 2)));
1845 try std.testing.expectEqual(@as(T, -1), sign(@as(T, -2)));
1846 try std.testing.expectEqual(@as(T, 0), sign(@as(T, 0)));
1847 try std.testing.expectEqual(@Vector(3, T){ 1, -1, 0 }, sign(@Vector(3, T){ 2, -2, 0 }));
1848 }
1849 {
1850 const T = f32;
1851 try std.testing.expectEqual(@as(T, 1), sign(@as(T, 2)));
1852 try std.testing.expectEqual(@as(T, -1), sign(@as(T, -2)));
1853 try std.testing.expectEqual(@as(T, 0), sign(@as(T, 0)));
1854 try std.testing.expectEqual(@Vector(3, T){ 1, -1, 0 }, sign(@Vector(3, T){ 2, -2, 0 }));
1855 }
1856 {
1857 const T = f64;
1858 try std.testing.expectEqual(@as(T, 1), sign(@as(T, 2)));
1859 try std.testing.expectEqual(@as(T, -1), sign(@as(T, -2)));
1860 try std.testing.expectEqual(@as(T, 0), sign(@as(T, 0)));
1861 try std.testing.expectEqual(@Vector(3, T){ 1, -1, 0 }, sign(@Vector(3, T){ 2, -2, 0 }));
1862 }
1863
1864 // comptime_int
1865 try std.testing.expectEqual(-1, sign(-10));
1866 try std.testing.expectEqual(1, sign(10));
1867 try std.testing.expectEqual(0, sign(0));
1868 // comptime_float
1869 try std.testing.expectEqual(-1.0, sign(-10.0));
1870 try std.testing.expectEqual(1.0, sign(10.0));
1871 try std.testing.expectEqual(0.0, sign(0.0));
1872}
1873
1874test sign {
1875 try testSign();
1876 try comptime testSign();
1877}