Functions

functions.zig

  1. const assert = @import("std").debug.assert;
  2. // Functions are declared like this
  3. fn add(a: i8, b: i8) i8 {
  4. if (a == 0) {
  5. return b;
  6. }
  7. return a + b;
  8. }
  9. // The export specifier makes a function externally visible in the generated
  10. // object file, and makes it use the C ABI.
  11. export fn sub(a: i8, b: i8) i8 { return a - b; }
  12. // The extern specifier is used to declare a function that will be resolved
  13. // at link time, when linking statically, or at runtime, when linking
  14. // dynamically.
  15. // The stdcallcc specifier changes the calling convention of the function.
  16. extern "kernel32" stdcallcc fn ExitProcess(exit_code: u32) noreturn;
  17. extern "c" fn atan2(a: f64, b: f64) f64;
  18. // The @setCold builtin tells the optimizer that a function is rarely called.
  19. fn abort() noreturn {
  20. @setCold(true);
  21. while (true) {}
  22. }
  23. // The nakedcc specifier makes a function not have any function prologue or epilogue.
  24. // This can be useful when integrating with assembly.
  25. nakedcc fn _start() noreturn {
  26. abort();
  27. }
  28. // The inline specifier forces a function to be inlined at all call sites.
  29. // If the function cannot be inlined, it is a compile-time error.
  30. inline fn shiftLeftOne(a: u32) u32 {
  31. return a << 1;
  32. }
  33. // The pub specifier allows the function to be visible when importing.
  34. // Another file can use @import and call sub2
  35. pub fn sub2(a: i8, b: i8) i8 { return a - b; }
  36. // Functions can be used as values and are equivalent to pointers.
  37. const call2_op = fn (a: i8, b: i8) i8;
  38. fn do_op(fn_call: call2_op, op1: i8, op2: i8) i8 {
  39. return fn_call(op1, op2);
  40. }
  41. test "function" {
  42. assert(do_op(add, 5, 6) == 11);
  43. assert(do_op(sub2, 5, 6) == -1);
  44. }
  1. $ zig test functions.zig
  2. Test 1/1 function...OK
  3. All tests passed.

Function values are like pointers:

test.zig

  1. const assert = @import("std").debug.assert;
  2. comptime {
  3. assert(@typeOf(foo) == fn()void);
  4. assert(@sizeOf(fn()void) == @sizeOf(?fn()void));
  5. }
  6. fn foo() void { }
  1. $ zig build-obj test.zig

Pass-by-value Parameters

Primitive types such as Integers and Floats passed as parameters are copied, and then the copy is available in the function body. This is called "passing by value". Copying a primitive type is essentially free and typically involves nothing more than setting a register.

Structs, unions, and arrays can sometimes be more efficiently passed as a reference, since a copy could be arbitrarily expensive depending on the size. When these types are passed as parameters, Zig may choose to copy and pass by value, or pass by reference, whichever way Zig decides will be faster. This is made possible, in part, by the fact that parameters are immutable.

test.zig

  1. const Point = struct {
  2. x: i32,
  3. y: i32,
  4. };
  5. fn foo(point: Point) i32 {
  6. // Here, `point` could be a reference, or a copy. The function body
  7. // can ignore the difference and treat it as a value. Be very careful
  8. // taking the address of the parameter - it should be treated as if
  9. // the address will become invalid when the function returns.
  10. return point.x + point.y;
  11. }
  12. const assert = @import("std").debug.assert;
  13. test "pass struct to function" {
  14. assert(foo(Point{ .x = 1, .y = 2 }) == 3);
  15. }
  1. $ zig test test.zig
  2. Test 1/1 pass struct to function...OK
  3. All tests passed.

For extern functions, Zig follows the C ABI for passing structs and unions by value.

Function Reflection

test.zig

  1. const assert = @import("std").debug.assert;
  2. test "fn reflection" {
  3. assert(@typeOf(assert).ReturnType == void);
  4. assert(@typeOf(assert).is_var_args == false);
  5. }
  1. $ zig test test.zig
  2. Test 1/1 fn reflection...OK
  3. All tests passed.