| ... | @@ -349,45 +349,255 @@ TODO | ... | @@ -349,45 +349,255 @@ TODO |
| 349 | | 349 | |
| 350 | ## Built-in Functions | 350 | ## Built-in Functions |
| 351 | | 351 | |
| 352 | Built-in functions are prefixed with `@`. | 352 | Built-in functions are prefixed with `@`. Remember that the `inline` keyword on |
| | 353 | a parameter means that the parameter must be known at compile time. |
| 353 | | 354 | |
| 354 | ### @typeof | 355 | ### @typeof(expression) -> type |
| 355 | | 356 | |
| 356 | `@typeof(expression)` | 357 | This function returns a compile-time constant, which is the type of the |
| | 358 | expression passed as an argument. The expression is *not evaluated*. |
| 357 | | 359 | |
| 358 | ### @sizeof | 360 | ### @sizeof(inline T: type) -> (number literal) |
| 359 | | 361 | |
| 360 | `@sizeof(type)` | 362 | This function returns the number of bytes it takes to store T in memory. |
| | 363 | |
| | 364 | The result is a target-specific compile time constant. |
| | 365 | |
| | 366 | ### @alignof(inline T: type) -> (number literal) |
| | 367 | |
| | 368 | This function returns the number of bytes that this type should be aligned to |
| | 369 | for the current target. |
| | 370 | |
| | 371 | The result is a target-specific compile time constant. |
| 361 | | 372 | |
| 362 | ### Overflow Arithmetic | 373 | ### Overflow Arithmetic |
| 363 | | 374 | |
| 364 | Overflow arithmetic functions have defined behavior on overflow or underflow. | 375 | These functions take an integer type, two variables of the specified type, |
| | 376 | and a pointer to memory of the specified type where the result is stored. |
| 365 | | 377 | |
| 366 | The functions take an integer type, two variables of the specified type, and a | 378 | The functions return a boolean value: true if overflow or underflow occurred, |
| 367 | pointer to a variable of the specified type where the result is stored. The | 379 | false otherwise. |
| 368 | functions return a boolean value: true of overflow/underflow occurred, false | | |
| 369 | otherwise. | | |
| 370 | | 380 | |
| 371 | ``` | 381 | ``` |
| 372 | Function Operation | 382 | Function Operation |
| 373 | @add_with_overflow(T: type, a: T, b: T, x: &T) -> bool *x = a + b | 383 | @add_with_overflow(inline T: type, a: T, b: T, result: &T) -> bool *x = a + b |
| 374 | @sub_with_overflow(T: type, a: T, b: T, x: &T) -> bool *x = a - b | 384 | @sub_with_overflow(inline T: type, a: T, b: T, result: &T) -> bool *x = a - b |
| 375 | @mul_with_overflow(T: type, a: T, b: T, x: &T) -> bool *x = a * b | 385 | @mul_with_overflow(inline T: type, a: T, b: T, result: &T) -> bool *x = a * b |
| | 386 | @shl_with_overflow(inline T: type, a: T, b: T, result: &T) -> bool *x = a << b |
| | 387 | ``` |
| | 388 | |
| | 389 | ### @memset(dest, c: u8, byte_count: isize) |
| | 390 | |
| | 391 | This function sets a region of memory to `c`. `dest` is a pointer. |
| | 392 | |
| | 393 | This function is a low level intrinsic with no safety mechanisms. Most higher |
| | 394 | level code will not use this function, instead using something like this: |
| | 395 | |
| | 396 | ```zig |
| | 397 | // assume dest is a slice |
| | 398 | for (dest) |*b| *b = c; |
| | 399 | ``` |
| | 400 | |
| | 401 | ### @memcpy(dest, source, byte_count: isize) |
| | 402 | |
| | 403 | This function copies bytes from one region of memory to another. `dest` and |
| | 404 | `source` are both pointers and must not overlap. |
| | 405 | |
| | 406 | This function is a low level intrinsic with no safety mechanisms. Most higher |
| | 407 | level code will not use this function, instead using something like this: |
| | 408 | |
| | 409 | ```zig |
| | 410 | const mem = @import("std").mem; |
| | 411 | // assume dest and source are slices |
| | 412 | mem.copy(dest, source); |
| | 413 | ``` |
| | 414 | |
| | 415 | ### @breakpoint() |
| | 416 | |
| | 417 | This function inserts a platform-specific debug trap instruction which causes |
| | 418 | debuggers to break there. |
| | 419 | |
| | 420 | This function is only valid within function scope. |
| | 421 | |
| | 422 | ### @return_address() |
| | 423 | |
| | 424 | This function returns a pointer to the return address of the current stack |
| | 425 | frame. |
| | 426 | |
| | 427 | The implications of this are target specific and not consistent across |
| | 428 | all platforms. |
| | 429 | |
| | 430 | This function is only valid within function scope. |
| | 431 | |
| | 432 | ### @frame_address() |
| | 433 | |
| | 434 | This function returns the base pointer of the current stack frame. |
| | 435 | |
| | 436 | The implications of this are target specific and not consistent across all |
| | 437 | platforms. The frame address may not be available in release mode due to |
| | 438 | aggressive optimizations. |
| | 439 | |
| | 440 | This function is only valid within function scope. |
| | 441 | |
| | 442 | ### @max_value(inline T: type) -> (number literal) |
| | 443 | |
| | 444 | This function returns the maximum integer value of the integer type T. |
| | 445 | |
| | 446 | The result is a compile time constant. For some types such as `c_long`, the |
| | 447 | result is marked as depending on a compile variable. |
| | 448 | |
| | 449 | ### @min_value(inline T: type) -> (number literal) |
| | 450 | |
| | 451 | This function returns the minimum integer value of the integer type T. |
| | 452 | |
| | 453 | The result is a compile time constant. For some types such as `c_long`, the |
| | 454 | result is marked as depending on a compile variable. |
| | 455 | |
| | 456 | ### @member_count(inline T: type) -> (number literal) |
| | 457 | |
| | 458 | This function returns the number of enum values in an enum type. |
| | 459 | |
| | 460 | The result is a compile time constant. |
| | 461 | |
| | 462 | ### @import(inline path: []u8) -> (namespace) |
| | 463 | |
| | 464 | This function finds a zig file corresponding to `path` and imports all the |
| | 465 | public top level declarations into the resulting namespace. |
| | 466 | |
| | 467 | `path` can be a relative or absolute path, or it can be the name of a package, |
| | 468 | such as "std". |
| | 469 | |
| | 470 | This function is only valid at top level scope. |
| | 471 | |
| | 472 | ### @c_import(expression) -> (namespace) |
| | 473 | |
| | 474 | This function parses C code and imports the functions, types, variables, and |
| | 475 | compatible macro definitions into the result namespace. |
| | 476 | |
| | 477 | `expression` is interpreted at compile time. The builtin functions |
| | 478 | `@c_include`, `@c_define`, and `@c_undef` work within this expression, |
| | 479 | appending to a temporary buffer which is then parsed as C code. |
| | 480 | |
| | 481 | This function is only valid at top level scope. |
| | 482 | |
| | 483 | ### @c_include(inline path: []u8) |
| | 484 | |
| | 485 | This function can only occur inside `@c_import`. |
| | 486 | |
| | 487 | This appends `#include <$path>\n` to the `c_import` temporary buffer. |
| | 488 | |
| | 489 | ### @c_define(inline name: []u8, value) |
| | 490 | |
| | 491 | This function can only occur inside `@c_import`. |
| | 492 | |
| | 493 | This appends `#define $name $value` to the `c_import` temporary buffer. |
| | 494 | |
| | 495 | ### @c_undef(inline name: []u8) |
| | 496 | |
| | 497 | This function can only occur inside `@c_import`. |
| | 498 | |
| | 499 | This appends `#undef $name` to the `c_import` temporary buffer. |
| | 500 | |
| | 501 | ### @compile_var(inline name: []u8) -> (varying type) |
| | 502 | |
| | 503 | This function returns a compile-time variable. There are built in compile |
| | 504 | variables: |
| | 505 | |
| | 506 | * "is_big_endian" `bool` - either `true` for big endian or `false` for little endian. |
| | 507 | * "is_release" `bool`- either `true` for release mode builds or `false` for debug mode builds. |
| | 508 | * "is_test" `bool`- either `true` for test builds or `false` otherwise. |
| | 509 | * "os" `@OS` - use `zig targets` to see what enum values are possible here. |
| | 510 | * "arch" `@Arch` - use `zig targets` to see what enum values are possible here. |
| | 511 | * "environ" `@Environ` - use `zig targets` to see what enum values are possible here. |
| | 512 | |
| | 513 | Build scripts can set additional compile variables of any name and type. |
| | 514 | |
| | 515 | The result of this function is a compile time constant that is marked as |
| | 516 | depending on a compile variable. |
| | 517 | |
| | 518 | ### @const_eval(expression) -> @typeof(expression) |
| | 519 | |
| | 520 | This function wraps an expression and generates a compile error if the |
| | 521 | expression is not known at compile time. |
| | 522 | |
| | 523 | The result of the function is the result of the expression. |
| | 524 | |
| | 525 | ### @ctz(inline T: type, x: T) -> T |
| | 526 | |
| | 527 | This function counts the number of trailing zeroes in x which is an integer |
| | 528 | type T. |
| | 529 | |
| | 530 | ### @clz(inline T: type, x: T) -> T |
| | 531 | |
| | 532 | This function counts the number of leading zeroes in x which is an integer |
| | 533 | type T. |
| | 534 | |
| | 535 | ### @err_name(err: error) -> []u8 |
| | 536 | |
| | 537 | This function returns the string representation of an error. If an error |
| | 538 | declaration is: |
| | 539 | |
| | 540 | ```zig |
| | 541 | error OutOfMem; |
| 376 | ``` | 542 | ``` |
| 377 | | 543 | |
| 378 | ### @memset | 544 | Then the string representation is "OutOfMem". |
| | 545 | |
| | 546 | If there are no calls to `@err_name` in an entire application, then no error |
| | 547 | name table will be generated. |
| | 548 | |
| | 549 | ### @embed_file(inline path: []u8) -> [X]u8 |
| | 550 | |
| | 551 | This function returns a compile time constant fixed-size array with length |
| | 552 | equal to the byte count of the file given by `path`. The contents of the array |
| | 553 | are the contents of the file. |
| | 554 | |
| | 555 | ### @cmpxchg(ptr: &T, cmp: T, new: T, success_order: MemoryOrder, fail_order: MemoryOrder) -> bool |
| | 556 | |
| | 557 | This function performs an atomic compare exchange operation. |
| | 558 | |
| | 559 | ### @fence(order: MemoryOrder) |
| | 560 | |
| | 561 | The `fence` function is used to introduce happens-before edges between operations. |
| 379 | | 562 | |
| 380 | `@memset(dest, char, len)` | 563 | ### @div_exact(a: T, b: T) -> T |
| 381 | | 564 | |
| 382 | ### @memcpy | 565 | This function performs integer division `a / b` and returns the result. |
| | 566 | |
| | 567 | The caller guarantees that this operation will have no remainder. |
| | 568 | |
| | 569 | In debug mode, a remainder causes a panic. In release mode, a remainder is |
| | 570 | undefined behavior. |
| | 571 | |
| | 572 | ### @truncate(inline T: type, integer) -> T |
| | 573 | |
| | 574 | This function truncates bits from an integer type, resulting in a smaller |
| | 575 | integer type. |
| | 576 | |
| | 577 | The following produces a crash in debug mode and undefined behavior in |
| | 578 | release mode: |
| | 579 | |
| | 580 | ```zig |
| | 581 | const a: u16 = 0xabcd; |
| | 582 | const b: u8 = u8(a); |
| | 583 | ``` |
| | 584 | |
| | 585 | However this is well defined and working code: |
| | 586 | |
| | 587 | ```zig |
| | 588 | const a: u16 = 0xabcd; |
| | 589 | const b: u8 = @truncate(u8, a); |
| | 590 | // b is now 0xcd |
| | 591 | ``` |
| 383 | | 592 | |
| 384 | `@memcpy(dest, source, len)` | 593 | ### @compile_err(inline msg: []u8) |
| 385 | | 594 | |
| 386 | ### @member_count | 595 | This function, when semantically analyzed, causes a compile error with the message `msg`. |
| 387 | | 596 | |
| 388 | `@member_count(enum_type)` | 597 | There are several ways that code avoids being semantically checked, such as using `if` |
| | 598 | or `switch` with compile variables, and inline functions. |
| 389 | | 599 | |
| 390 | ### Max and Min Value | 600 | ### @int_type(inline is_signed: bool, inline bit_count: u8, inline is_wrapping: bool) -> type |
| 391 | | 601 | |
| 392 | `@max_value(type)` | 602 | This function returns an integer type with the given signness, bit count, and |
| 393 | `@min_value(type)` | 603 | wrapping behavior. |
Andrew Kelley <andrew@ziglang.org> 2016-05-18 16:59:55-07:00