diff --git a/README.md b/README.md index a28cf44ef3..2085f50dec 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/doc/langref.md b/doc/langref.md index cc4f5001d3..aee6f513f3 100644 --- a/doc/langref.md +++ b/doc/langref.md @@ -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 - \\ - \\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 - 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` diff --git a/doc/style.md b/doc/style.md deleted file mode 100644 index a5a3ef5dec..0000000000 --- a/doc/style.md +++ /dev/null @@ -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 = - \\ - \\ - \\ -; -struct XmlParser {} - -// The initials BE (Big Endian) are just another word in Zig identifier names. -fn readU32Be() -> u32 {} -``` - -See Zig standard library for examples.