slice and array re-work plus some misc. changes

 * `@truncate` builtin allows casting to the same size integer.
   It also performs two's complement casting between signed and
   unsigned integers.
 * The idiomatic way to convert between bytes and numbers is now
   `mem.readInt` and `mem.writeInt` instead of an unsafe cast.
   It works at compile time, is safer, and looks cleaner.
 * Implicitly casting an array to a slice is allowed only if the
   slice is const.
 * Constant pointer values know if their memory is from a compile-
   time constant value or a compile-time variable.
 * Cast from [N]u8 to []T no longer allowed, but [N]u8 to []const T
   still allowed.
 * Fix inability to pass a mutable pointer to comptime variable at
   compile-time to a function and have the function modify the
   memory pointed to by the pointer.
 * Add the `comptime T: type` parameter back to mem.eql. Prevents
   accidentally creating instantiations for arrays.

1 files changed, 19 insertions, 0 deletions

diff --git a/doc/langref.md b/doc/langref.md
index 0aace75996..9b806fc384 100644
--- a/doc/langref.md
+++ b/doc/langref.md
@@ -637,6 +637,25 @@ 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