| ... | ... | @@ -177,503 +177,3 @@ or |
| 177 | 177 | ?? %% |
| 178 | 178 | = *= /= %= += -= <<= >>= &= ^= |= |
| 179 | 179 | ``` |
| 180 | | |
| 181 | | ## Types |
| 182 | | |
| 183 | | ### Numeric Types |
| 184 | | |
| 185 | | ``` |
| 186 | | Type name C equivalent Description |
| 187 | | |
| 188 | | i8 int8_t signed 8-bit integer |
| 189 | | u8 uint8_t unsigned 8-bit integer |
| 190 | | i16 int16_t signed 16-bit integer |
| 191 | | u16 uint16_t unsigned 16-bit integer |
| 192 | | i32 int32_t signed 32-bit integer |
| 193 | | u32 uint32_t unsigned 32-bit integer |
| 194 | | i64 int64_t signed 64-bit integer |
| 195 | | u64 uint64_t unsigned 64-bit integer |
| 196 | | isize intptr_t signed pointer sized integer |
| 197 | | usize uintptr_t unsigned pointer sized integer |
| 198 | | |
| 199 | | c_short short for ABI compatibility with C |
| 200 | | c_ushort unsigned short for ABI compatibility with C |
| 201 | | c_int int for ABI compatibility with C |
| 202 | | c_uint unsigned int for ABI compatibility with C |
| 203 | | c_long long for ABI compatibility with C |
| 204 | | c_ulong unsigned long for ABI compatibility with C |
| 205 | | c_longlong long long for ABI compatibility with C |
| 206 | | c_ulonglong unsigned long long for ABI compatibility with C |
| 207 | | c_longdouble long double for ABI compatibility with C |
| 208 | | c_void void for ABI compatibility with C |
| 209 | | |
| 210 | | f32 float 32-bit floating point |
| 211 | | f64 double 64-bit floating point |
| 212 | | ``` |
| 213 | | |
| 214 | | ## Expressions |
| 215 | | |
| 216 | | ### Literals |
| 217 | | |
| 218 | | #### Character and String Literals |
| 219 | | |
| 220 | | ``` |
| 221 | | Literal Example Characters Escapes Null Term Type |
| 222 | | |
| 223 | | Byte 'H' All ASCII Byte No u8 |
| 224 | | UTF-8 Bytes "hello" All Unicode Byte & Unicode No [5]u8 |
| 225 | | UTF-8 C string c"hello" All Unicode Byte & Unicode Yes &const u8 |
| 226 | | ``` |
| 227 | | |
| 228 | | ### Escapes |
| 229 | | |
| 230 | | Escape | Name |
| 231 | | ----------|------------------------------------------------------------------- |
| 232 | | \n | Newline |
| 233 | | \r | Carriage Return |
| 234 | | \t | Tab |
| 235 | | \\ | Backslash |
| 236 | | \' | Single Quote |
| 237 | | \" | Double Quote |
| 238 | | \xNN | hexadecimal 8-bit character code (2 digits) |
| 239 | | \uNNNN | hexadecimal 16-bit Unicode character code UTF-8 encoded (4 digits) |
| 240 | | \UNNNNNN | hexadecimal 24-bit Unicode character code UTF-8 encoded (6 digits) |
| 241 | | |
| 242 | | Note that the maximum valid Unicode point is 0x10ffff. |
| 243 | | |
| 244 | | ##### Multiline String Literals |
| 245 | | |
| 246 | | Multiline string literals have no escapes and can span across multiple lines. |
| 247 | | To start a multiline string literal, use the `\\` token. Just like a comment, |
| 248 | | the string literal goes until the end of the line. The end of the line is not |
| 249 | | included in the string literal. |
| 250 | | |
| 251 | | However, if the next line begins with `\\` then a newline is appended and |
| 252 | | the string literal continues. |
| 253 | | |
| 254 | | Example: |
| 255 | | |
| 256 | | ```zig |
| 257 | | const hello_world_in_c = |
| 258 | | \\#include <stdio.h> |
| 259 | | \\ |
| 260 | | \\int main(int argc, char **argv) { |
| 261 | | \\ printf("hello world\n"); |
| 262 | | \\ return 0; |
| 263 | | \\} |
| 264 | | ; |
| 265 | | ``` |
| 266 | | |
| 267 | | For a multiline C string literal, prepend `c` to each `\\`. Example: |
| 268 | | |
| 269 | | ```zig |
| 270 | | const c_string_literal = |
| 271 | | c\\#include <stdio.h> |
| 272 | | c\\ |
| 273 | | c\\int main(int argc, char **argv) { |
| 274 | | c\\ printf("hello world\n"); |
| 275 | | c\\ return 0; |
| 276 | | c\\} |
| 277 | | ; |
| 278 | | ``` |
| 279 | | |
| 280 | | In this example the variable `c_string_literal` has type `&const char` and |
| 281 | | has a terminating null byte. |
| 282 | | |
| 283 | | #### Number Literals |
| 284 | | |
| 285 | | Number literals | Example | Exponentiation |
| 286 | | --------------------|-------------|-------------- |
| 287 | | Decimal integer | 98222 | N/A |
| 288 | | Hex integer | 0xff | N/A |
| 289 | | Octal integer | 0o77 | N/A |
| 290 | | Binary integer | 0b11110000 | N/A |
| 291 | | Floating point | 123.0E+77 | Optional |
| 292 | | Hex floating point | 0x103.70p-5 | Optional |
| 293 | | |
| 294 | | ## Built-in Functions |
| 295 | | |
| 296 | | Built-in functions are prefixed with `@`. Remember that the `comptime` keyword on |
| 297 | | a parameter means that the parameter must be known at compile time. |
| 298 | | |
| 299 | | ### @typeOf(expression) -> type |
| 300 | | |
| 301 | | This function returns a compile-time constant, which is the type of the |
| 302 | | expression passed as an argument. The expression is *not evaluated*. |
| 303 | | |
| 304 | | ### @sizeOf(comptime T: type) -> (number literal) |
| 305 | | |
| 306 | | This function returns the number of bytes it takes to store T in memory. |
| 307 | | |
| 308 | | The result is a target-specific compile time constant. |
| 309 | | |
| 310 | | ### @alignOf(comptime T: type) -> (number literal) |
| 311 | | |
| 312 | | This function returns the number of bytes that this type should be aligned to |
| 313 | | for the current target. |
| 314 | | |
| 315 | | The result is a target-specific compile time constant. |
| 316 | | |
| 317 | | ### @offsetOf(comptime T: type, comptime field_name: [] const u8) -> (number literal) |
| 318 | | |
| 319 | | This function returns the byte offset of a field relative to its containing struct. |
| 320 | | |
| 321 | | ### Overflow Arithmetic |
| 322 | | |
| 323 | | These functions take an integer type, two variables of the specified type, |
| 324 | | and a pointer to memory of the specified type where the result is stored. |
| 325 | | |
| 326 | | The functions return a boolean value: true if overflow or underflow occurred, |
| 327 | | false otherwise. |
| 328 | | |
| 329 | | ``` |
| 330 | | Function Operation |
| 331 | | @addWithOverflow(comptime T: type, a: T, b: T, result: &T) -> bool *x = a + b |
| 332 | | @subWithOverflow(comptime T: type, a: T, b: T, result: &T) -> bool *x = a - b |
| 333 | | @mulWithOverflow(comptime T: type, a: T, b: T, result: &T) -> bool *x = a * b |
| 334 | | @shlWithOverflow(comptime T: type, a: T, b: T, result: &T) -> bool *x = a << b |
| 335 | | ``` |
| 336 | | |
| 337 | | ### @memset(dest: &u8, c: u8, byte_count: usize) |
| 338 | | |
| 339 | | This function sets a region of memory to `c`. `dest` is a pointer. |
| 340 | | |
| 341 | | This function is a low level intrinsic with no safety mechanisms. Most higher |
| 342 | | level code will not use this function, instead using something like this: |
| 343 | | |
| 344 | | ```zig |
| 345 | | for (destSlice) |*b| *b = c; |
| 346 | | ``` |
| 347 | | |
| 348 | | The optimizer is intelligent enough to turn the above snippet into a memset. |
| 349 | | |
| 350 | | ### @memcpy(noalias dest: &u8, noalias source: &const u8, byte_count: usize) |
| 351 | | |
| 352 | | This function copies bytes from one region of memory to another. `dest` and |
| 353 | | `source` are both pointers and must not overlap. |
| 354 | | |
| 355 | | This function is a low level intrinsic with no safety mechanisms. Most higher |
| 356 | | level code will not use this function, instead using something like this: |
| 357 | | |
| 358 | | ```zig |
| 359 | | const mem = @import("std").mem; |
| 360 | | mem.copy(destSlice, sourceSlice); |
| 361 | | ``` |
| 362 | | |
| 363 | | The optimizer is intelligent enough to turn the above snippet into a memcpy. |
| 364 | | |
| 365 | | ### @breakpoint() |
| 366 | | |
| 367 | | This function inserts a platform-specific debug trap instruction which causes |
| 368 | | debuggers to break there. |
| 369 | | |
| 370 | | This function is only valid within function scope. |
| 371 | | |
| 372 | | ### @returnAddress() |
| 373 | | |
| 374 | | This function returns a pointer to the return address of the current stack |
| 375 | | frame. |
| 376 | | |
| 377 | | The implications of this are target specific and not consistent across |
| 378 | | all platforms. |
| 379 | | |
| 380 | | This function is only valid within function scope. |
| 381 | | |
| 382 | | ### @frameAddress() |
| 383 | | |
| 384 | | This function returns the base pointer of the current stack frame. |
| 385 | | |
| 386 | | The implications of this are target specific and not consistent across all |
| 387 | | platforms. The frame address may not be available in release mode due to |
| 388 | | aggressive optimizations. |
| 389 | | |
| 390 | | This function is only valid within function scope. |
| 391 | | |
| 392 | | ### @maxValue(comptime T: type) -> (number literal) |
| 393 | | |
| 394 | | This function returns the maximum integer value of the integer type T. |
| 395 | | |
| 396 | | The result is a compile time constant. For some types such as `c_long`, the |
| 397 | | result is marked as depending on a compile variable. |
| 398 | | |
| 399 | | ### @minValue(comptime T: type) -> (number literal) |
| 400 | | |
| 401 | | This function returns the minimum integer value of the integer type T. |
| 402 | | |
| 403 | | The result is a compile time constant. For some types such as `c_long`, the |
| 404 | | result is marked as depending on a compile variable. |
| 405 | | |
| 406 | | ### @memberCount(comptime T: type) -> (number literal) |
| 407 | | |
| 408 | | This function returns the number of enum values in an enum type. |
| 409 | | |
| 410 | | The result is a compile time constant. |
| 411 | | |
| 412 | | ### @import(comptime path: []u8) -> (namespace) |
| 413 | | |
| 414 | | This function finds a zig file corresponding to `path` and imports all the |
| 415 | | public top level declarations into the resulting namespace. |
| 416 | | |
| 417 | | `path` can be a relative or absolute path, or it can be the name of a package, |
| 418 | | such as "std". |
| 419 | | |
| 420 | | This function is only valid at top level scope. |
| 421 | | |
| 422 | | ### @cImport(expression) -> (namespace) |
| 423 | | |
| 424 | | This function parses C code and imports the functions, types, variables, and |
| 425 | | compatible macro definitions into the result namespace. |
| 426 | | |
| 427 | | `expression` is interpreted at compile time. The builtin functions |
| 428 | | `@c_include`, `@c_define`, and `@c_undef` work within this expression, |
| 429 | | appending to a temporary buffer which is then parsed as C code. |
| 430 | | |
| 431 | | This function is only valid at top level scope. |
| 432 | | |
| 433 | | ### @cInclude(comptime path: []u8) |
| 434 | | |
| 435 | | This function can only occur inside `@c_import`. |
| 436 | | |
| 437 | | This appends `#include <$path>\n` to the `c_import` temporary buffer. |
| 438 | | |
| 439 | | ### @cDefine(comptime name: []u8, value) |
| 440 | | |
| 441 | | This function can only occur inside `@c_import`. |
| 442 | | |
| 443 | | This appends `#define $name $value` to the `c_import` temporary buffer. |
| 444 | | |
| 445 | | ### @cUndef(comptime name: []u8) |
| 446 | | |
| 447 | | This function can only occur inside `@c_import`. |
| 448 | | |
| 449 | | This appends `#undef $name` to the `c_import` temporary buffer. |
| 450 | | |
| 451 | | ### @generatedCode(expression) -> @typeOf(expression) |
| 452 | | |
| 453 | | This function wraps an expression and returns the result of the expression |
| 454 | | unmodified. |
| 455 | | |
| 456 | | Inside the expression, code is considered generated, which means that the |
| 457 | | following compile errors are disabled: |
| 458 | | |
| 459 | | * unnecessary if statement error |
| 460 | | |
| 461 | | The result of the expression is marked as depending on a compile variable. |
| 462 | | |
| 463 | | ### @ctz(x: T) -> T |
| 464 | | |
| 465 | | This function counts the number of trailing zeroes in x which is an integer |
| 466 | | type T. |
| 467 | | |
| 468 | | ### @clz(x: T) -> T |
| 469 | | |
| 470 | | This function counts the number of leading zeroes in x which is an integer |
| 471 | | type T. |
| 472 | | |
| 473 | | ### @errorName(err: error) -> []u8 |
| 474 | | |
| 475 | | This function returns the string representation of an error. If an error |
| 476 | | declaration is: |
| 477 | | |
| 478 | | ```zig |
| 479 | | error OutOfMem; |
| 480 | | ``` |
| 481 | | |
| 482 | | Then the string representation is "OutOfMem". |
| 483 | | |
| 484 | | If there are no calls to `@errorName` in an entire application, then no error |
| 485 | | name table will be generated. |
| 486 | | |
| 487 | | ### @typeName(T: type) -> []u8 |
| 488 | | |
| 489 | | This function returns the string representation of a type. |
| 490 | | |
| 491 | | ### @embedFile(comptime path: []u8) -> [X]u8 |
| 492 | | |
| 493 | | This function returns a compile time constant fixed-size array with length |
| 494 | | equal to the byte count of the file given by `path`. The contents of the array |
| 495 | | are the contents of the file. |
| 496 | | |
| 497 | | ### @cmpxchg(ptr: &T, cmp: T, new: T, success_order: MemoryOrder, fail_order: MemoryOrder) -> bool |
| 498 | | |
| 499 | | This function performs an atomic compare exchange operation. |
| 500 | | |
| 501 | | ### @fence(order: MemoryOrder) |
| 502 | | |
| 503 | | The `fence` function is used to introduce happens-before edges between operations. |
| 504 | | |
| 505 | | ### @truncate(comptime T: type, integer) -> T |
| 506 | | |
| 507 | | This function truncates bits from an integer type, resulting in a smaller |
| 508 | | integer type. |
| 509 | | |
| 510 | | The following produces a crash in debug mode and undefined behavior in |
| 511 | | release mode: |
| 512 | | |
| 513 | | ```zig |
| 514 | | const a: u16 = 0xabcd; |
| 515 | | const b: u8 = u8(a); |
| 516 | | ``` |
| 517 | | |
| 518 | | However this is well defined and working code: |
| 519 | | |
| 520 | | ```zig |
| 521 | | const a: u16 = 0xabcd; |
| 522 | | const b: u8 = @truncate(u8, a); |
| 523 | | // b is now 0xcd |
| 524 | | ``` |
| 525 | | |
| 526 | | This function always truncates the significant bits of the integer, regardless |
| 527 | | of endianness on the target platform. |
| 528 | | |
| 529 | | This function also performs a twos complement cast. For example, the following |
| 530 | | produces a crash in debug mode and undefined behavior in release mode: |
| 531 | | |
| 532 | | ```zig |
| 533 | | const a = i16(-1); |
| 534 | | const b = u16(a); |
| 535 | | ``` |
| 536 | | |
| 537 | | However this is well defined and working code: |
| 538 | | |
| 539 | | ```zig |
| 540 | | const a = i16(-1); |
| 541 | | const b = @truncate(u16, a); |
| 542 | | // b is now 0xffff |
| 543 | | ``` |
| 544 | | |
| 545 | | ### @compileError(comptime msg: []u8) |
| 546 | | |
| 547 | | This function, when semantically analyzed, causes a compile error with the |
| 548 | | message `msg`. |
| 549 | | |
| 550 | | There are several ways that code avoids being semantically checked, such as |
| 551 | | using `if` or `switch` with compile time constants, and comptime functions. |
| 552 | | |
| 553 | | ### @compileLog(args: ...) |
| 554 | | |
| 555 | | This function, when semantically analyzed, causes a compile error, but it does |
| 556 | | not prevent compile-time code from continuing to run, and it otherwise does not |
| 557 | | interfere with analysis. |
| 558 | | |
| 559 | | Each of the arguments will be serialized to a printable debug value and output |
| 560 | | to stderr, and then a newline at the end. |
| 561 | | |
| 562 | | This function can be used to do "printf debugging" on compile-time executing |
| 563 | | code. |
| 564 | | |
| 565 | | ### @IntType(comptime is_signed: bool, comptime bit_count: u8) -> type |
| 566 | | |
| 567 | | This function returns an integer type with the given signness and bit count. |
| 568 | | |
| 569 | | ### @setDebugSafety(scope, safety_on: bool) |
| 570 | | |
| 571 | | Sets a whether we want debug safety checks on for a given scope. |
| 572 | | |
| 573 | | ### @isInteger(comptime T: type) -> bool |
| 574 | | |
| 575 | | Returns whether a given type is an integer. |
| 576 | | |
| 577 | | ### @isFloat(comptime T: type) -> bool |
| 578 | | |
| 579 | | Returns whether a given type is a float. |
| 580 | | |
| 581 | | ### @canImplicitCast(comptime T: type, value) -> bool |
| 582 | | |
| 583 | | Returns whether a value can be implicitly casted to a given type. |
| 584 | | |
| 585 | | ### @setGlobalAlign(global_variable_name, byte_count: usize) -> bool |
| 586 | | |
| 587 | | Sets the alignment property of a global variable. |
| 588 | | |
| 589 | | ### @setGlobalSection(global_variable_name, section_name: []u8) -> bool |
| 590 | | |
| 591 | | Puts the global variable in the specified section. |
| 592 | | |
| 593 | | ### @panic(message: []const u8) -> noreturn |
| 594 | | |
| 595 | | Invokes the panic handler function. By default the panic handler function |
| 596 | | calls the public `panic` function exposed in the root source file, or |
| 597 | | if there is not one specified, invokes the one provided in |
| 598 | | `std/special/panic.zig`. |
| 599 | | |
| 600 | | ### @ptrCast(comptime DestType: type, value: var) -> DestType |
| 601 | | |
| 602 | | Converts a pointer of one type to a pointer of another type. |
| 603 | | |
| 604 | | ### @intToPtr(comptime DestType: type, int: usize) -> DestType |
| 605 | | |
| 606 | | Converts an integer to a pointer. To convert the other way, use `usize(ptr)`. |
| 607 | | |
| 608 | | ### @enumTagName(value: var) -> []const u8 |
| 609 | | |
| 610 | | Converts an enum tag name to a slice of bytes. Example: |
| 611 | | |
| 612 | | ### @fieldParentPtr(comptime ParentType: type, comptime field_name: []const u8, field_ptr: &T) -> &ParentType |
| 613 | | |
| 614 | | Given a pointer to a field, returns the base pointer of a struct. |
| 615 | | |
| 616 | | ### @rem(numerator: T, denominator: T) -> T |
| 617 | | |
| 618 | | Remainder division. For unsigned integers this is the same as |
| 619 | | `numerator % denominator`. Caller guarantees `denominator > 0`. |
| 620 | | |
| 621 | | * `@rem(-5, 3) == -2` |
| 622 | | * `@divTrunc(a, b) + @rem(a, b) == a` |
| 623 | | |
| 624 | | See also: |
| 625 | | * `std.math.rem` |
| 626 | | * `@mod` |
| 627 | | |
| 628 | | ### @mod(numerator: T, denominator: T) -> T |
| 629 | | |
| 630 | | Modulus division. For unsigned integers this is the same as |
| 631 | | `numerator % denominator`. Caller guarantees `denominator > 0`. |
| 632 | | |
| 633 | | * `@mod(-5, 3) == 1` |
| 634 | | * `@divFloor(a, b) + @mod(a, b) == a` |
| 635 | | |
| 636 | | See also: |
| 637 | | * `std.math.mod` |
| 638 | | * `@rem` |
| 639 | | |
| 640 | | ### @divTrunc(numerator: T, denominator: T) -> T |
| 641 | | |
| 642 | | Truncated division. Rounds toward zero. For unsigned integers it is |
| 643 | | the same as `numerator / denominator`. Caller guarantees `denominator != 0` and |
| 644 | | `!(@isInteger(T) and T.is_signed and numerator == @minValue(T) and denominator == -1)`. |
| 645 | | |
| 646 | | * `@divTrunc(-5, 3) == -1` |
| 647 | | * `@divTrunc(a, b) + @rem(a, b) == a` |
| 648 | | |
| 649 | | See also: |
| 650 | | * `std.math.divTrunc` |
| 651 | | * `@divFloor` |
| 652 | | * `@divExact` |
| 653 | | |
| 654 | | ### @divFloor(numerator: T, denominator: T) -> T |
| 655 | | |
| 656 | | Floored division. Rounds toward negative infinity. For unsigned integers it is |
| 657 | | the same as `numerator / denominator`. Caller guarantees `denominator != 0` and |
| 658 | | `!(@isInteger(T) and T.is_signed and numerator == @minValue(T) and denominator == -1)`. |
| 659 | | |
| 660 | | * `@divFloor(-5, 3) == -2` |
| 661 | | * `@divFloor(a, b) + @mod(a, b) == a` |
| 662 | | |
| 663 | | See also: |
| 664 | | * `std.math.divFloor` |
| 665 | | * `@divTrunc` |
| 666 | | * `@divExact` |
| 667 | | |
| 668 | | ### @divExact(numerator: T, denominator: T) -> T |
| 669 | | |
| 670 | | Exact division. Caller guarantees `denominator != 0` and |
| 671 | | `@divTrunc(numerator, denominator) * denominator == numerator`. |
| 672 | | |
| 673 | | * `@divExact(6, 3) == 2` |
| 674 | | * `@divExact(a, b) * b == a` |
| 675 | | |
| 676 | | See also: |
| 677 | | * `std.math.divExact` |
| 678 | | * `@divTrunc` |
| 679 | | * `@divFloor` |
Andrew Kelley <andrew@ziglang.org> 2017-05-08 00:13:54-04:00