From 380c8ec2c95fa8d732c141c705d9940629eb2012 Mon Sep 17 00:00:00 2001
From: Andrew Kelley <andrew@ziglang.org>
Date: Thu, 19 Sep 2019 00:59:04 -0400
Subject: implement runtime `@byteSwap` and other fixups

 * update docs for `@byteSwap`.
 * fix hash & eql functions for ZigLLVMFnIdBswap not updated to
   include vector len. this was causing incorrect bswap function
   being called in unrelated code
 * fix `@byteSwap` behavior tests only testing comptime and not
   runtime operations
 * implement runtime `@byteSwap`
 * fix incorrect logic in ir_render_vector_to_array and
   ir_render_array_to_vector with regards to whether or not to bitcast
 * `@byteSwap` accepts an array operand which it will cast to vector
 * simplify `@byteSwap` semantic analysis code and various fixes
---
 doc/langref.html.in | 11 ++++++++++-
 1 file changed, 10 insertions(+), 1 deletion(-)

(limited to 'doc')

diff --git a/doc/langref.html.in b/doc/langref.html.in
index 8a303640e6..61fc06fd02 100644
--- a/doc/langref.html.in
+++ b/doc/langref.html.in
@@ -6542,12 +6542,21 @@ async fn func(y: *i32) void {
       {#header_close#}
 
       {#header_open|@byteSwap#}
-      <pre>{#syntax#}@byteSwap(comptime T: type, integer: T) T{#endsyntax#}</pre>
+      <pre>{#syntax#}@byteSwap(comptime T: type, operand: T) T{#endsyntax#}</pre>
       <p>{#syntax#}T{#endsyntax#} must be an integer type with bit count evenly divisible by 8.</p>
+      <p>{#syntax#}operand{#endsyntax#} may be an {#link|integer|Integers#} or {#link|vector|Vectors#}.</p>
       <p>
       Swaps the byte order of the integer. This converts a big endian integer to a little endian integer,
       and converts a little endian integer to a big endian integer.
       </p>
+      <p>
+      Note that for the purposes of memory layout with respect to endianness, the integer type should be
+      related to the number of bytes reported by {#link|@sizeOf#} bytes. This is demonstrated with
+      {#syntax#}u24{#endsyntax#}. {#syntax#}@sizeOf(u24) == 4{#endsyntax#}, which means that a
+      {#syntax#}u24{#endsyntax#} stored in memory takes 4 bytes, and those 4 bytes are what are swapped on
+      a little vs big endian system. On the other hand, if {#syntax#}T{#endsyntax#} is specified to
+      be {#syntax#}u24{#endsyntax#}, then only 3 bytes are reversed.
+      </p>
       {#header_close#}
 
       {#header_open|@bitReverse#}
-- 
cgit v1.2.3