authorgravatar for twostepted@gmail.comTravis Staloch <twostepted@gmail.com> 2021-09-08 20:59:55-07:00
committergravatar for andrew@ziglang.orgAndrew Kelley <andrew@ziglang.org> 2021-09-28 17:03:43-07:00
log0f246257be5029e7bb73ac9a5ff356171007bc7a
tree278481a38ac58ff5e724c045b912a9c9bf12a3e7
parent6ba9f7474f6999e9239ce6459549667439945bf2

sat-arithmetic: update langref

1 files changed, 91 insertions(+), 6 deletions(-)

doc/langref.html.in+91-6
......@@ -1244,8 +1244,9 @@ fn divide(a: i32, b: i32) i32 {
12441244 </p>
12451245 <p>
12461246 Operators such as {#syntax#}+{#endsyntax#} and {#syntax#}-{#endsyntax#} cause undefined behavior on
1247 integer overflow. Also available are operations such as {#syntax#}+%{#endsyntax#} and
1248 {#syntax#}-%{#endsyntax#} which are defined to have wrapping arithmetic on all targets.
1247 integer overflow. Alternative operators are provided for wrapping and saturating arithmetic on all targets.
1248 {#syntax#}+%{#endsyntax#} and {#syntax#}-%{#endsyntax#} perform wrapping arithmetic
1249 while {#syntax#}+|{#endsyntax#} and {#syntax#}-|{#endsyntax#} perform saturating arithmetic.
12491250 </p>
12501251 <p>
12511252 Zig supports arbitrary bit-width integers, referenced by using
......@@ -1395,6 +1396,24 @@ a +%= b{#endsyntax#}</pre></th>
13951396 <pre>{#syntax#}@as(u32, std.math.maxInt(u32)) +% 1 == 0{#endsyntax#}</pre>
13961397 </td>
13971398 </tr>
1399 <tr>
1400 <td><pre>{#syntax#}a +| b
1401a +|= b{#endsyntax#}</pre></td>
1402 <td>
1403 <ul>
1404 <li>{#link|Integers#}</li>
1405 </ul>
1406 </td>
1407 <td>Saturating Addition.
1408 <ul>
1409 <li>Invokes {#link|Peer Type Resolution#} for the operands.</li>
1410 <li>See also {#link|@addWithSaturation#}.</li>
1411 </ul>
1412 </td>
1413 <td>
1414 <pre>{#syntax#}@as(u32, std.math.maxInt(u32)) +| 1 == @as(u32, std.math.maxInt(u32)){#endsyntax#}</pre>
1415 </td>
1416 </tr>
13981417 <tr>
13991418 <th scope="row"><pre>{#syntax#}a - b
14001419a -= b{#endsyntax#}</pre></th>
......@@ -1434,6 +1453,24 @@ a -%= b{#endsyntax#}</pre></th>
14341453 <pre>{#syntax#}@as(u32, 0) -% 1 == std.math.maxInt(u32){#endsyntax#}</pre>
14351454 </td>
14361455 </tr>
1456 <tr>
1457 <td><pre>{#syntax#}a -| b
1458a -|= b{#endsyntax#}</pre></td>
1459 <td>
1460 <ul>
1461 <li>{#link|Integers#}</li>
1462 </ul>
1463 </td>
1464 <td>Saturating Subtraction.
1465 <ul>
1466 <li>Invokes {#link|Peer Type Resolution#} for the operands.</li>
1467 <li>See also {#link|@subWithSaturation#}.</li>
1468 </ul>
1469 </td>
1470 <td>
1471 <pre>{#syntax#}@as(u32, 0) -| 1 == 0{#endsyntax#}</pre>
1472 </td>
1473 </tr>
14371474 <tr>
14381475 <th scope="row"><pre>{#syntax#}-a{#endsyntax#}</pre></th>
14391476 <td>
......@@ -1508,6 +1545,24 @@ a *%= b{#endsyntax#}</pre></th>
15081545 <pre>{#syntax#}@as(u8, 200) *% 2 == 144{#endsyntax#}</pre>
15091546 </td>
15101547 </tr>
1548 <tr>
1549 <td><pre>{#syntax#}a *| b
1550a *|= b{#endsyntax#}</pre></td>
1551 <td>
1552 <ul>
1553 <li>{#link|Integers#}</li>
1554 </ul>
1555 </td>
1556 <td>Saturating Multiplication.
1557 <ul>
1558 <li>Invokes {#link|Peer Type Resolution#} for the operands.</li>
1559 <li>See also {#link|@mulWithSaturation#}.</li>
1560 </ul>
1561 </td>
1562 <td>
1563 <pre>{#syntax#}@as(u8, 200) *| 2 == 255{#endsyntax#}</pre>
1564 </td>
1565 </tr>
15111566 <tr>
15121567 <th scope="row"><pre>{#syntax#}a / b
15131568a /= b{#endsyntax#}</pre></th>
......@@ -1577,6 +1632,24 @@ a <<= b{#endsyntax#}</pre></th>
15771632 <pre>{#syntax#}1 << 8 == 256{#endsyntax#}</pre>
15781633 </td>
15791634 </tr>
1635 <tr>
1636 <td><pre>{#syntax#}a <<| b
1637a <<|= b{#endsyntax#}</pre></td>
1638 <td>
1639 <ul>
1640 <li>{#link|Integers#}</li>
1641 </ul>
1642 </td>
1643 <td>Saturating Bit Shift Left.
1644 <ul>
1645 <li>See also {#link|@shlExact#}.</li>
1646 <li>See also {#link|@shlWithOverflow#}.</li>
1647 </ul>
1648 </td>
1649 <td>
1650 <pre>{#syntax#}@as(u8, 1) <<| 8 == 255{#endsyntax#}</pre>
1651 </td>
1652 </tr>
15801653 <tr>
15811654 <th scope="row"><pre>{#syntax#}a >> b
15821655a >>= b{#endsyntax#}</pre></th>
......@@ -1968,14 +2041,14 @@ const B = error{Two};
19682041a!b
19692042x{}
19702043!x -x -%x ~x &x ?x
1971* / % ** *% ||
1972+ - ++ +% -%
1973<< >>
2044* / % ** *% *| ||
2045+ - ++ +% -% +| -|
2046<< >> <<|
19742047& ^ | orelse catch
19752048== != < > <= >=
19762049and
19772050or
1978= *= /= %= += -= <<= >>= &= ^= |={#endsyntax#}</pre>
2051= *= *%= *|= /= %= += +%= +|= -= -%= -|= <<= <<|= >>= &= ^= |={#endsyntax#}</pre>
19792052 {#header_close#}
19802053 {#header_close#}
19812054 {#header_open|Arrays#}
......@@ -11839,6 +11912,7 @@ AssignOp
1183911912 / PLUSEQUAL
1184011913 / MINUSEQUAL
1184111914 / LARROW2EQUAL
11915 / LARROW2PIPEEQUAL
1184211916 / RARROW2EQUAL
1184311917 / AMPERSANDEQUAL
1184411918 / CARETEQUAL
......@@ -11873,6 +11947,8 @@ AdditionOp
1187311947 / PLUS2
1187411948 / PLUSPERCENT
1187511949 / MINUSPERCENT
11950 / PLUSPIPE
11951 / MINUSPIPE
1187611952
1187711953MultiplyOp
1187811954 &lt;- PIPE2
......@@ -11881,6 +11957,7 @@ MultiplyOp
1188111957 / PERCENT
1188211958 / ASTERISK2
1188311959 / ASTERISKPERCENT
11960 / ASTERISKPIPE
1188411961
1188511962PrefixOp
1188611963 &lt;- EXCLAMATIONMARK
......@@ -12044,6 +12121,8 @@ ASTERISK2 &lt;- '**' skip
1204412121ASTERISKEQUAL &lt;- '*=' skip
1204512122ASTERISKPERCENT &lt;- '*%' ![=] skip
1204612123ASTERISKPERCENTEQUAL &lt;- '*%=' skip
12124ASTERISKPIPE &lt;- '*|' ![=] skip
12125ASTERISKPIPEEQUAL &lt;- '*|=' skip
1204712126CARET &lt;- '^' ![=] skip
1204812127CARETEQUAL &lt;- '^=' skip
1204912128COLON &lt;- ':' skip
......@@ -12060,6 +12139,8 @@ EXCLAMATIONMARK &lt;- '!' ![=] skip
1206012139EXCLAMATIONMARKEQUAL &lt;- '!=' skip
1206112140LARROW &lt;- '&lt;' ![&lt;=] skip
1206212141LARROW2 &lt;- '&lt;&lt;' ![=] skip
12142LARROW2PIPE &lt;- '&lt;&lt;|' ![=] skip
12143LARROW2PIPEEQUAL &lt;- '&lt;&lt;|=' ![=] skip
1206312144LARROW2EQUAL &lt;- '&lt;&lt;=' skip
1206412145LARROWEQUAL &lt;- '&lt;=' skip
1206512146LBRACE &lt;- '{' skip
......@@ -12069,6 +12150,8 @@ MINUS &lt;- '-' ![%=&gt;] skip
1206912150MINUSEQUAL &lt;- '-=' skip
1207012151MINUSPERCENT &lt;- '-%' ![=] skip
1207112152MINUSPERCENTEQUAL &lt;- '-%=' skip
12153MINUSPIPE &lt;- '-|' ![=] skip
12154MINUSPIPEEQUAL &lt;- '-|=' skip
1207212155MINUSRARROW &lt;- '-&gt;' skip
1207312156PERCENT &lt;- '%' ![=] skip
1207412157PERCENTEQUAL &lt;- '%=' skip
......@@ -12080,6 +12163,8 @@ PLUS2 &lt;- '++' skip
1208012163PLUSEQUAL &lt;- '+=' skip
1208112164PLUSPERCENT &lt;- '+%' ![=] skip
1208212165PLUSPERCENTEQUAL &lt;- '+%=' skip
12166PLUSPIPE &lt;- '+|' ![=] skip
12167PLUSPIPEEQUAL &lt;- '+|=' skip
1208312168LETTERC &lt;- 'c' skip
1208412169QUESTIONMARK &lt;- '?' skip
1208512170RARROW &lt;- '&gt;' ![&gt;=] skip