Commit 304cfb7122
Changed files (3)
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 <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`
doc/style.md
@@ -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.
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