remove error to/from int casting syntax; add `@errorToInt`/`@intToError`

See #1061

1 files changed, 42 insertions, 6 deletions

diff --git a/doc/langref.html.in b/doc/langref.html.in
index 9a3d5e5f17..24bf6e1b16 100644
--- a/doc/langref.html.in
+++ b/doc/langref.html.in
@@ -4658,7 +4658,7 @@ comptime {
       </p>
       <p>
       Attempting to convert a number of bytes with a length that does not evenly divide into a slice of
-      elements results in {#link|Undefined Behavior#}.
+      elements results in safety-protected {#link|Undefined Behavior#}.
       </p>
       {#header_close#}
 
@@ -4935,7 +4935,7 @@ test "main" {
       <pre><code class="zig">@errSetCast(comptime T: DestType, value: var) DestType</code></pre>
       <p>
       Converts an error value from one error set to another error set. Attempting to convert an error
-      which is not in the destination error set results in {#link|Undefined Behavior#}.
+      which is not in the destination error set results in safety-protected {#link|Undefined Behavior#}.
       </p>
       {#header_close#}
 
@@ -4955,6 +4955,7 @@ test "main" {
       error name table will be generated.
       </p>
       {#header_close#}
+
       {#header_open|@errorReturnTrace#}
       <pre><code class="zig">@errorReturnTrace() ?*builtin.StackTrace</code></pre>
       <p>
@@ -4964,6 +4965,25 @@ test "main" {
       </p>
       {#header_close#}
 
+      {#header_open|@errorToInt#}
+      <pre><code class="zig">@errorToInt(err: var) @IntType(false, @sizeOf(error) * 8)</code></pre>
+      <p>
+      Supports the following types:
+      </p>
+      <ul>
+          <li>error unions</li>
+          <li><code>E!void</code></li>
+      </ul>
+      <p>
+      Converts an error to the integer representation of an error.
+      </p>
+      <p>
+      It is generally recommended to avoid this
+      cast, as the integer representation of an error is not stable across source code changes.
+      </p>
+      {#see_also|@intToError#}
+      {#header_close#}
+
       {#header_open|@export#}
       <pre><code class="zig">@export(comptime name: []const u8, target: var, linkage: builtin.GlobalLinkage) []const u8</code></pre>
       <p>
@@ -5071,8 +5091,24 @@ fn add(a: i32, b: i32) i32 { return a + b; }
       <p>
       Converts an integer to another integer while keeping the same numerical value.
       Attempting to convert a number which is out of range of the destination type results in
-      {#link|Undefined Behavior#}.
+      safety-protected {#link|Undefined Behavior#}.
+      </p>
+      {#header_close#}
+
+      {#header_open|@intToError#}
+      <pre><code class="zig">@intToError(value: @IntType(false, @sizeOf(error) * 8)) error</code></pre>
+      <p>
+      Converts from the integer representation of an error into the global error set type.
+      </p>
+      <p>
+      It is generally recommended to avoid this
+      cast, as the integer representation of an error is not stable across source code changes.
+      </p>
+      <p>
+      Attempting to convert an integer that does not correspond to any error results in
+      safety-protected {#link|Undefined Behavior#}.
       </p>
+      {#see_also|@errorToInt#}
       {#header_close#}
 
       {#header_open|@intToFloat#}
@@ -6123,8 +6159,8 @@ fn getNumberOrFail() !i32 {
       {#code_begin|test_err|integer value 11 represents no error#}
 comptime {
     const err = error.AnError;
-    const number = u32(err) + 10;
-    const invalid_err = error(number);
+    const number = @errorToInt(err) + 10;
+    const invalid_err = @intToError(number);
 }
       {#code_end#}
       <p>At runtime crashes with the message <code>invalid error code</code> and a stack trace.</p>
@@ -6831,7 +6867,7 @@ hljs.registerLanguage("zig", function(t) {
         a = t.IR + "\\s*\\(",
         c = {
             keyword: "const align var extern stdcallcc nakedcc volatile export pub noalias inline struct packed enum union break return try catch test continue unreachable comptime and or asm defer errdefer if else switch while for fn use bool f32 f64 void type noreturn error i8 u8 i16 u16 i32 u32 i64 u64 isize usize i8w u8w i16w i32w u32w i64w u64w isizew usizew c_short c_ushort c_int c_uint c_long c_ulong c_longlong c_ulonglong resume cancel await async orelse",
-            built_in: "atomicLoad breakpoint returnAddress frameAddress fieldParentPtr setFloatMode IntType OpaqueType compileError compileLog setCold setRuntimeSafety setEvalBranchQuota offsetOf memcpy inlineCall setGlobalLinkage setGlobalSection divTrunc divFloor enumTagName intToPtr ptrToInt panic ptrCast intCast floatCast intToFloat floatToInt boolToInt bytesToSlice sliceToBytes errSetCast bitCast rem mod memset sizeOf alignOf alignCast maxValue minValue memberCount memberName memberType typeOf addWithOverflow subWithOverflow mulWithOverflow shlWithOverflow shlExact shrExact cInclude cDefine cUndef ctz clz import cImport errorName embedFile cmpxchgStrong cmpxchgWeak fence divExact truncate atomicRmw sqrt field typeInfo typeName newStackCall",
+            built_in: "atomicLoad breakpoint returnAddress frameAddress fieldParentPtr setFloatMode IntType OpaqueType compileError compileLog setCold setRuntimeSafety setEvalBranchQuota offsetOf memcpy inlineCall setGlobalLinkage setGlobalSection divTrunc divFloor enumTagName intToPtr ptrToInt panic ptrCast intCast floatCast intToFloat floatToInt boolToInt bytesToSlice sliceToBytes errSetCast bitCast rem mod memset sizeOf alignOf alignCast maxValue minValue memberCount memberName memberType typeOf addWithOverflow subWithOverflow mulWithOverflow shlWithOverflow shlExact shrExact cInclude cDefine cUndef ctz clz import cImport errorName embedFile cmpxchgStrong cmpxchgWeak fence divExact truncate atomicRmw sqrt field typeInfo typeName newStackCall errorToInt intToError",
             literal: "true false null undefined"
         },
         n = [e, t.CLCM, t.CBCM, s, r];