mirror/zig
1
0
Fork 0
mirror of https://github.com/ziglang/zig.git synced 2025-12-06 06:13:07 +00:00
Code Issues Packages Projects Releases Wiki Activity

move docs to ziglang.org

Browse Source
This commit is contained in:
Andrew Kelley 2017-05-08 00:13:54 -04:00
parent 2f20fe6ecd
commit 304cfb7122
3 changed files with 2 additions and 575 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
README.md
View File

@ -5,6 +5,8 @@ clarity.
[ziglang.org](http://ziglang.org)
[Documentation](http://ziglang.org/documentation/)
## Feature Highlights
* Small, simple language. Focus on debugging your application rather than

500
doc/langref.md
View File

@ -177,503 +177,3 @@ or
?? %%
= *= /= %= += -= <<= >>= &= ^= |=
```
## Types
### Numeric Types
```
Type name C equivalent Description
i8 int8_t signed 8-bit integer
u8 uint8_t unsigned 8-bit integer
i16 int16_t signed 16-bit integer
u16 uint16_t unsigned 16-bit integer
i32 int32_t signed 32-bit integer
u32 uint32_t unsigned 32-bit integer
i64 int64_t signed 64-bit integer
u64 uint64_t unsigned 64-bit integer
isize intptr_t signed pointer sized integer
usize uintptr_t unsigned pointer sized integer
c_short short for ABI compatibility with C
c_ushort unsigned short for ABI compatibility with C
c_int int for ABI compatibility with C
c_uint unsigned int for ABI compatibility with C
c_long long for ABI compatibility with C
c_ulong unsigned long for ABI compatibility with C
c_longlong long long for ABI compatibility with C
c_ulonglong unsigned long long for ABI compatibility with C
c_longdouble long double for ABI compatibility with C
c_void void for ABI compatibility with C
f32 float 32-bit floating point
f64 double 64-bit floating point
```
## Expressions
### Literals
#### Character and String Literals
```
Literal Example Characters Escapes Null Term Type
Byte 'H' All ASCII Byte No u8
UTF-8 Bytes "hello" All Unicode Byte & Unicode No [5]u8
UTF-8 C string c"hello" All Unicode Byte & Unicode Yes &const u8
```
### Escapes
Escape | Name
----------|-------------------------------------------------------------------
\n | Newline
\r | Carriage Return
\t | Tab
\\ | Backslash
\' | Single Quote
\" | Double Quote
\xNN | hexadecimal 8-bit character code (2 digits)
\uNNNN | hexadecimal 16-bit Unicode character code UTF-8 encoded (4 digits)
\UNNNNNN | hexadecimal 24-bit Unicode character code UTF-8 encoded (6 digits)
Note that the maximum valid Unicode point is 0x10ffff.
##### Multiline String Literals
Multiline string literals have no escapes and can span across multiple lines.
To start a multiline string literal, use the `\\` token. Just like a comment,
the string literal goes until the end of the line. The end of the line is not
included in the string literal.
However, if the next line begins with `\\` then a newline is appended and
the string literal continues.
Example:
```zig
const hello_world_in_c =
\\#include <stdio.h>
\\
\\int main(int argc, char **argv) {
\\ printf("hello world\n");
\\ return 0;
\\}
;
```
For a multiline C string literal, prepend `c` to each `\\`. Example:
```zig
const c_string_literal =
c\\#include <stdio.h>
c\\
c\\int main(int argc, char **argv) {
c\\ printf("hello world\n");
c\\ return 0;
c\\}
;
```
In this example the variable `c_string_literal` has type `&const char` and
has a terminating null byte.
#### Number Literals
Number literals | Example | Exponentiation
--------------------|-------------|--------------
Decimal integer | 98222 | N/A
Hex integer | 0xff | N/A
Octal integer | 0o77 | N/A
Binary integer | 0b11110000 | N/A
Floating point | 123.0E+77 | Optional
Hex floating point | 0x103.70p-5 | Optional
## Built-in Functions
Built-in functions are prefixed with `@`. Remember that the `comptime` keyword on
a parameter means that the parameter must be known at compile time.
### @typeOf(expression) -> type
This function returns a compile-time constant, which is the type of the
expression passed as an argument. The expression is *not evaluated*.
### @sizeOf(comptime T: type) -> (number literal)
This function returns the number of bytes it takes to store T in memory.
The result is a target-specific compile time constant.
### @alignOf(comptime T: type) -> (number literal)
This function returns the number of bytes that this type should be aligned to
for the current target.
The result is a target-specific compile time constant.
### @offsetOf(comptime T: type, comptime field_name: [] const u8) -> (number literal)
This function returns the byte offset of a field relative to its containing struct.
### Overflow Arithmetic
These functions take an integer type, two variables of the specified type,
and a pointer to memory of the specified type where the result is stored.
The functions return a boolean value: true if overflow or underflow occurred,
false otherwise.
```
Function Operation
@addWithOverflow(comptime T: type, a: T, b: T, result: &T) -> bool *x = a + b
@subWithOverflow(comptime T: type, a: T, b: T, result: &T) -> bool *x = a - b
@mulWithOverflow(comptime T: type, a: T, b: T, result: &T) -> bool *x = a * b
@shlWithOverflow(comptime T: type, a: T, b: T, result: &T) -> bool *x = a << b
```
### @memset(dest: &u8, c: u8, byte_count: usize)
This function sets a region of memory to `c`. `dest` is a pointer.
This function is a low level intrinsic with no safety mechanisms. Most higher
level code will not use this function, instead using something like this:
```zig
for (destSlice) |*b| *b = c;
```
The optimizer is intelligent enough to turn the above snippet into a memset.
### @memcpy(noalias dest: &u8, noalias source: &const u8, byte_count: usize)
This function copies bytes from one region of memory to another. `dest` and
`source` are both pointers and must not overlap.
This function is a low level intrinsic with no safety mechanisms. Most higher
level code will not use this function, instead using something like this:
```zig
const mem = @import("std").mem;
mem.copy(destSlice, sourceSlice);
```
The optimizer is intelligent enough to turn the above snippet into a memcpy.
### @breakpoint()
This function inserts a platform-specific debug trap instruction which causes
debuggers to break there.
This function is only valid within function scope.
### @returnAddress()
This function returns a pointer to the return address of the current stack
frame.
The implications of this are target specific and not consistent across
all platforms.
This function is only valid within function scope.
### @frameAddress()
This function returns the base pointer of the current stack frame.
The implications of this are target specific and not consistent across all
platforms. The frame address may not be available in release mode due to
aggressive optimizations.
This function is only valid within function scope.
### @maxValue(comptime T: type) -> (number literal)
This function returns the maximum integer value of the integer type T.
The result is a compile time constant. For some types such as `c_long`, the
result is marked as depending on a compile variable.
### @minValue(comptime T: type) -> (number literal)
This function returns the minimum integer value of the integer type T.
The result is a compile time constant. For some types such as `c_long`, the
result is marked as depending on a compile variable.
### @memberCount(comptime T: type) -> (number literal)
This function returns the number of enum values in an enum type.
The result is a compile time constant.
### @import(comptime path: []u8) -> (namespace)
This function finds a zig file corresponding to `path` and imports all the
public top level declarations into the resulting namespace.
`path` can be a relative or absolute path, or it can be the name of a package,
such as "std".
This function is only valid at top level scope.
### @cImport(expression) -> (namespace)
This function parses C code and imports the functions, types, variables, and
compatible macro definitions into the result namespace.
`expression` is interpreted at compile time. The builtin functions
`@c_include`, `@c_define`, and `@c_undef` work within this expression,
appending to a temporary buffer which is then parsed as C code.
This function is only valid at top level scope.
### @cInclude(comptime path: []u8)
This function can only occur inside `@c_import`.
This appends `#include <$path>\n` to the `c_import` temporary buffer.
### @cDefine(comptime name: []u8, value)
This function can only occur inside `@c_import`.
This appends `#define $name $value` to the `c_import` temporary buffer.
### @cUndef(comptime name: []u8)
This function can only occur inside `@c_import`.
This appends `#undef $name` to the `c_import` temporary buffer.
### @generatedCode(expression) -> @typeOf(expression)
This function wraps an expression and returns the result of the expression
unmodified.
Inside the expression, code is considered generated, which means that the
following compile errors are disabled:
* unnecessary if statement error
The result of the expression is marked as depending on a compile variable.
### @ctz(x: T) -> T
This function counts the number of trailing zeroes in x which is an integer
type T.
### @clz(x: T) -> T
This function counts the number of leading zeroes in x which is an integer
type T.
### @errorName(err: error) -> []u8
This function returns the string representation of an error. If an error
declaration is:
```zig
error OutOfMem;
```
Then the string representation is "OutOfMem".
If there are no calls to `@errorName` in an entire application, then no error
name table will be generated.
### @typeName(T: type) -> []u8
This function returns the string representation of a type.
### @embedFile(comptime path: []u8) -> [X]u8
This function returns a compile time constant fixed-size array with length
equal to the byte count of the file given by `path`. The contents of the array
are the contents of the file.
### @cmpxchg(ptr: &T, cmp: T, new: T, success_order: MemoryOrder, fail_order: MemoryOrder) -> bool
This function performs an atomic compare exchange operation.
### @fence(order: MemoryOrder)
The `fence` function is used to introduce happens-before edges between operations.
### @truncate(comptime T: type, integer) -> T
This function truncates bits from an integer type, resulting in a smaller
integer type.
The following produces a crash in debug mode and undefined behavior in
release mode:
```zig
const a: u16 = 0xabcd;
const b: u8 = u8(a);
```
However this is well defined and working code:
```zig
const a: u16 = 0xabcd;
const b: u8 = @truncate(u8, a);
// b is now 0xcd
```
This function always truncates the significant bits of the integer, regardless
of endianness on the target platform.
This function also performs a twos complement cast. For example, the following
produces a crash in debug mode and undefined behavior in release mode:
```zig
const a = i16(-1);
const b = u16(a);
```
However this is well defined and working code:
```zig
const a = i16(-1);
const b = @truncate(u16, a);
// b is now 0xffff
```
### @compileError(comptime msg: []u8)
This function, when semantically analyzed, causes a compile error with the
message `msg`.
There are several ways that code avoids being semantically checked, such as
using `if` or `switch` with compile time constants, and comptime functions.
### @compileLog(args: ...)
This function, when semantically analyzed, causes a compile error, but it does
not prevent compile-time code from continuing to run, and it otherwise does not
interfere with analysis.
Each of the arguments will be serialized to a printable debug value and output
to stderr, and then a newline at the end.
This function can be used to do "printf debugging" on compile-time executing
code.
### @IntType(comptime is_signed: bool, comptime bit_count: u8) -> type
This function returns an integer type with the given signness and bit count.
### @setDebugSafety(scope, safety_on: bool)
Sets a whether we want debug safety checks on for a given scope.
### @isInteger(comptime T: type) -> bool
Returns whether a given type is an integer.
### @isFloat(comptime T: type) -> bool
Returns whether a given type is a float.
### @canImplicitCast(comptime T: type, value) -> bool
Returns whether a value can be implicitly casted to a given type.
### @setGlobalAlign(global_variable_name, byte_count: usize) -> bool
Sets the alignment property of a global variable.
### @setGlobalSection(global_variable_name, section_name: []u8) -> bool
Puts the global variable in the specified section.
### @panic(message: []const u8) -> noreturn
Invokes the panic handler function. By default the panic handler function
calls the public `panic` function exposed in the root source file, or
if there is not one specified, invokes the one provided in
`std/special/panic.zig`.
### @ptrCast(comptime DestType: type, value: var) -> DestType
Converts a pointer of one type to a pointer of another type.
### @intToPtr(comptime DestType: type, int: usize) -> DestType
Converts an integer to a pointer. To convert the other way, use `usize(ptr)`.
### @enumTagName(value: var) -> []const u8
Converts an enum tag name to a slice of bytes. Example:
### @fieldParentPtr(comptime ParentType: type, comptime field_name: []const u8, field_ptr: &T) -> &ParentType
Given a pointer to a field, returns the base pointer of a struct.
### @rem(numerator: T, denominator: T) -> T
Remainder division. For unsigned integers this is the same as
`numerator % denominator`. Caller guarantees `denominator > 0`.
* `@rem(-5, 3) == -2`
* `@divTrunc(a, b) + @rem(a, b) == a`
See also:
* `std.math.rem`
* `@mod`
### @mod(numerator: T, denominator: T) -> T
Modulus division. For unsigned integers this is the same as
`numerator % denominator`. Caller guarantees `denominator > 0`.
* `@mod(-5, 3) == 1`
* `@divFloor(a, b) + @mod(a, b) == a`
See also:
* `std.math.mod`
* `@rem`
### @divTrunc(numerator: T, denominator: T) -> T
Truncated division. Rounds toward zero. For unsigned integers it is
the same as `numerator / denominator`. Caller guarantees `denominator != 0` and
`!(@isInteger(T) and T.is_signed and numerator == @minValue(T) and denominator == -1)`.
* `@divTrunc(-5, 3) == -1`
* `@divTrunc(a, b) + @rem(a, b) == a`
See also:
* `std.math.divTrunc`
* `@divFloor`
* `@divExact`
### @divFloor(numerator: T, denominator: T) -> T
Floored division. Rounds toward negative infinity. For unsigned integers it is
the same as `numerator / denominator`. Caller guarantees `denominator != 0` and
`!(@isInteger(T) and T.is_signed and numerator == @minValue(T) and denominator == -1)`.
* `@divFloor(-5, 3) == -2`
* `@divFloor(a, b) + @mod(a, b) == a`
See also:
* `std.math.divFloor`
* `@divTrunc`
* `@divExact`
### @divExact(numerator: T, denominator: T) -> T
Exact division. Caller guarantees `denominator != 0` and
`@divTrunc(numerator, denominator) * denominator == numerator`.
* `@divExact(6, 3) == 2`
* `@divExact(a, b) * b == a`
See also:
* `std.math.divExact`
* `@divTrunc`
* `@divFloor`

75
doc/style.md
View File

@ -1,75 +0,0 @@
# Official Style Guide
These conventions are not enforced by the compiler, but they are shipped in
this documentation along with the compiler in order to provide a point of
reference, should anyone wish to point to an authority on agreed upon Zig
coding style.
## Whitespace
* 4 space indentation
* Open braces on same line, unless you need to wrap.
* If a list of things is longer than 2, put each item on its own line and
exercise the abilty to put an extra comma at the end.
* Line length: aim for 100; use common sense.
## Names
Roughly speaking: `camelCaseFunctionName`, `TitleCaseTypeName`,
`snake_case_variable_name`. More precisely:
* If `x` is a `struct` (or an alias of a `struct`), then `x` should be `TitleCase`.
* If `x` otherwise identifies a type, `x` should have `snake_case`.
* If `x` is callable, and `x`'s return type is `type`, then `x` should be `TitleCase`.
* If `x` is otherwise callable, then `x` should be `camelCase`.
* Otherwise, `x` should be `snake_case`.
Acronyms, initialisms, proper nouns, or any other word that has capitalization
rules in written English are subject to naming conventions just like any other
word. Even acronyms that are only 2 letters long are subject to these
conventions.
These are general rules of thumb; if it makes sense to do something different,
do what makes sense.
Examples:
```zig
const namespace_name = @import("dir_name/file_name.zig");
var global_var: i32;
const const_name = 42;
const primitive_type_alias = f32;
const string_alias = []u8;
struct StructName {}
const StructAlias = StructName;
fn functionName(param_name: TypeName) {
var functionPointer = functionName;
functionPointer();
functionPointer = otherFunction;
functionPointer();
}
const functionAlias = functionName;
fn ListTemplateFunction(ChildType: type, inline fixed_size: usize) -> type {
struct ShortList(T: type, n: usize) {
field_name: [n]T,
fn methodName() {}
}
return List(ChildType, fixed_size);
}
// The word XML loses its casing when used in Zig identifiers.
const xml_document =
\\<?xml version="1.0" encoding="UTF-8"?>
\\<document>
\\</document>
;
struct XmlParser {}
// The initials BE (Big Endian) are just another word in Zig identifier names.
fn readU32Be() -> u32 {}
```
See Zig standard library for examples.