Where should @builtins be used instead of std.math functions? And how to decide in a general?
In many cases, the std.math functions will be the same in every single way as the builtin equivalent, and the documentation will even state as such. The purpose of these functions is probably to signal to people browsing the documentation that these maths builtins exist.
In some cases, the std.math functions will do mostly the same thing as a builtin, but return an error or null instead of triggering illegal behaviour.
This means that if you have e.g. a program which accepts user input, you can recover from the case where the user specifies a value that’d cause a division by 0, instead of having your whole program crash.
6 Likes
I don’t think there is any general rules for choosing between builtin and std. Need to go with the documentations. For example, for log10, the builtin @log10 supports float and vectors (see here: Documentation - The Zig Programming Language). The std.math.log10 supports float, int, and some special cases such as nan, inf, 0, negative number, etc.. (see here: Zig Documentation).
If I must say a general rule, I would say the std usually provides you with more features, while the builtin is simpler.
1 Like
Use the builtin if it provides the semantics you desire. It will produce less code and likely compile and run faster. Be mindful of how edges cases are handled (NaNs, negative numbers, 0 etc) and use a more fully featured std.math function if you must handle these without crashing.
The builtin will directly map to a hardware accelerated feature when it is available for the target, allowing you to declare your intent most precisely to the compiler that you want that hardware instruction to be used.
When using the std.math functions your intent is the same math, but you also communicate to the compiler the existence of functions, arguments, the stack. Functions can hint the compiler to where code should be reused instead of inlined, for example, but if you don’t need to tell the compiler about how you intend for your code to be reused throughout your application, don’t!
2 Likes