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 {...@@ -1244,8 +1244,9 @@ fn divide(a: i32, b: i32) i32 {
1244 </p>1244 </p>
1245 <p>1245 <p>
1246 Operators such as {#syntax#}+{#endsyntax#} and {#syntax#}-{#endsyntax#} cause undefined behavior on1246 Operators such as {#syntax#}+{#endsyntax#} and {#syntax#}-{#endsyntax#} cause undefined behavior on
1247 integer overflow. Also available are operations such as {#syntax#}+%{#endsyntax#} and1247 integer overflow. Alternative operators are provided for wrapping and saturating arithmetic on all targets.
1248 {#syntax#}-%{#endsyntax#} which are defined to have wrapping arithmetic on all targets.1248 {#syntax#}+%{#endsyntax#} and {#syntax#}-%{#endsyntax#} perform wrapping arithmetic
1249 while {#syntax#}+|{#endsyntax#} and {#syntax#}-|{#endsyntax#} perform saturating arithmetic.
1249 </p>1250 </p>
1250 <p>1251 <p>
1251 Zig supports arbitrary bit-width integers, referenced by using1252 Zig supports arbitrary bit-width integers, referenced by using
...@@ -1395,6 +1396,24 @@ a +%= b{#endsyntax#}</pre></th>...@@ -1395,6 +1396,24 @@ a +%= b{#endsyntax#}</pre></th>
1395 <pre>{#syntax#}@as(u32, std.math.maxInt(u32)) +% 1 == 0{#endsyntax#}</pre>1396 <pre>{#syntax#}@as(u32, std.math.maxInt(u32)) +% 1 == 0{#endsyntax#}</pre>
1396 </td>1397 </td>
1397 </tr>1398 </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>
1398 <tr>1417 <tr>
1399 <th scope="row"><pre>{#syntax#}a - b1418 <th scope="row"><pre>{#syntax#}a - b
1400a -= b{#endsyntax#}</pre></th>1419a -= b{#endsyntax#}</pre></th>
...@@ -1434,6 +1453,24 @@ a -%= b{#endsyntax#}</pre></th>...@@ -1434,6 +1453,24 @@ a -%= b{#endsyntax#}</pre></th>
1434 <pre>{#syntax#}@as(u32, 0) -% 1 == std.math.maxInt(u32){#endsyntax#}</pre>1453 <pre>{#syntax#}@as(u32, 0) -% 1 == std.math.maxInt(u32){#endsyntax#}</pre>
1435 </td>1454 </td>
1436 </tr>1455 </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>
1437 <tr>1474 <tr>
1438 <th scope="row"><pre>{#syntax#}-a{#endsyntax#}</pre></th>1475 <th scope="row"><pre>{#syntax#}-a{#endsyntax#}</pre></th>
1439 <td>1476 <td>
...@@ -1508,6 +1545,24 @@ a *%= b{#endsyntax#}</pre></th>...@@ -1508,6 +1545,24 @@ a *%= b{#endsyntax#}</pre></th>
1508 <pre>{#syntax#}@as(u8, 200) *% 2 == 144{#endsyntax#}</pre>1545 <pre>{#syntax#}@as(u8, 200) *% 2 == 144{#endsyntax#}</pre>
1509 </td>1546 </td>
1510 </tr>1547 </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>
1511 <tr>1566 <tr>
1512 <th scope="row"><pre>{#syntax#}a / b1567 <th scope="row"><pre>{#syntax#}a / b
1513a /= b{#endsyntax#}</pre></th>1568a /= b{#endsyntax#}</pre></th>
...@@ -1577,6 +1632,24 @@ a <<= b{#endsyntax#}</pre></th>...@@ -1577,6 +1632,24 @@ a <<= b{#endsyntax#}</pre></th>
1577 <pre>{#syntax#}1 << 8 == 256{#endsyntax#}</pre>1632 <pre>{#syntax#}1 << 8 == 256{#endsyntax#}</pre>
1578 </td>1633 </td>
1579 </tr>1634 </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>
1580 <tr>1653 <tr>
1581 <th scope="row"><pre>{#syntax#}a >> b1654 <th scope="row"><pre>{#syntax#}a >> b
1582a >>= b{#endsyntax#}</pre></th>1655a >>= b{#endsyntax#}</pre></th>
...@@ -1968,14 +2041,14 @@ const B = error{Two};...@@ -1968,14 +2041,14 @@ const B = error{Two};
1968a!b2041a!b
1969x{}2042x{}
1970!x -x -%x ~x &x ?x2043!x -x -%x ~x &x ?x
1971* / % ** *% ||2044* / % ** *% *| ||
1972+ - ++ +% -%2045+ - ++ +% -% +| -|
1973<< >>2046<< >> <<|
1974& ^ | orelse catch2047& ^ | orelse catch
1975== != < > <= >=2048== != < > <= >=
1976and2049and
1977or2050or
1978= *= /= %= += -= <<= >>= &= ^= |={#endsyntax#}</pre>2051= *= *%= *|= /= %= += +%= +|= -= -%= -|= <<= <<|= >>= &= ^= |={#endsyntax#}</pre>
1979 {#header_close#}2052 {#header_close#}
1980 {#header_close#}2053 {#header_close#}
1981 {#header_open|Arrays#}2054 {#header_open|Arrays#}
...@@ -11839,6 +11912,7 @@ AssignOp...@@ -11839,6 +11912,7 @@ AssignOp
11839 / PLUSEQUAL11912 / PLUSEQUAL
11840 / MINUSEQUAL11913 / MINUSEQUAL
11841 / LARROW2EQUAL11914 / LARROW2EQUAL
11915 / LARROW2PIPEEQUAL
11842 / RARROW2EQUAL11916 / RARROW2EQUAL
11843 / AMPERSANDEQUAL11917 / AMPERSANDEQUAL
11844 / CARETEQUAL11918 / CARETEQUAL
...@@ -11873,6 +11947,8 @@ AdditionOp...@@ -11873,6 +11947,8 @@ AdditionOp
11873 / PLUS211947 / PLUS2
11874 / PLUSPERCENT11948 / PLUSPERCENT
11875 / MINUSPERCENT11949 / MINUSPERCENT
11950 / PLUSPIPE
11951 / MINUSPIPE
1187611952
11877MultiplyOp11953MultiplyOp
11878 &lt;- PIPE211954 &lt;- PIPE2
...@@ -11881,6 +11957,7 @@ MultiplyOp...@@ -11881,6 +11957,7 @@ MultiplyOp
11881 / PERCENT11957 / PERCENT
11882 / ASTERISK211958 / ASTERISK2
11883 / ASTERISKPERCENT11959 / ASTERISKPERCENT
11960 / ASTERISKPIPE
1188411961
11885PrefixOp11962PrefixOp
11886 &lt;- EXCLAMATIONMARK11963 &lt;- EXCLAMATIONMARK
...@@ -12044,6 +12121,8 @@ ASTERISK2 &lt;- '**' skip...@@ -12044,6 +12121,8 @@ ASTERISK2 &lt;- '**' skip
12044ASTERISKEQUAL &lt;- '*=' skip12121ASTERISKEQUAL &lt;- '*=' skip
12045ASTERISKPERCENT &lt;- '*%' ![=] skip12122ASTERISKPERCENT &lt;- '*%' ![=] skip
12046ASTERISKPERCENTEQUAL &lt;- '*%=' skip12123ASTERISKPERCENTEQUAL &lt;- '*%=' skip
12124ASTERISKPIPE &lt;- '*|' ![=] skip
12125ASTERISKPIPEEQUAL &lt;- '*|=' skip
12047CARET &lt;- '^' ![=] skip12126CARET &lt;- '^' ![=] skip
12048CARETEQUAL &lt;- '^=' skip12127CARETEQUAL &lt;- '^=' skip
12049COLON &lt;- ':' skip12128COLON &lt;- ':' skip
...@@ -12060,6 +12139,8 @@ EXCLAMATIONMARK &lt;- '!' ![=] skip...@@ -12060,6 +12139,8 @@ EXCLAMATIONMARK &lt;- '!' ![=] skip
12060EXCLAMATIONMARKEQUAL &lt;- '!=' skip12139EXCLAMATIONMARKEQUAL &lt;- '!=' skip
12061LARROW &lt;- '&lt;' ![&lt;=] skip12140LARROW &lt;- '&lt;' ![&lt;=] skip
12062LARROW2 &lt;- '&lt;&lt;' ![=] skip12141LARROW2 &lt;- '&lt;&lt;' ![=] skip
12142LARROW2PIPE &lt;- '&lt;&lt;|' ![=] skip
12143LARROW2PIPEEQUAL &lt;- '&lt;&lt;|=' ![=] skip
12063LARROW2EQUAL &lt;- '&lt;&lt;=' skip12144LARROW2EQUAL &lt;- '&lt;&lt;=' skip
12064LARROWEQUAL &lt;- '&lt;=' skip12145LARROWEQUAL &lt;- '&lt;=' skip
12065LBRACE &lt;- '{' skip12146LBRACE &lt;- '{' skip
...@@ -12069,6 +12150,8 @@ MINUS &lt;- '-' ![%=&gt;] skip...@@ -12069,6 +12150,8 @@ MINUS &lt;- '-' ![%=&gt;] skip
12069MINUSEQUAL &lt;- '-=' skip12150MINUSEQUAL &lt;- '-=' skip
12070MINUSPERCENT &lt;- '-%' ![=] skip12151MINUSPERCENT &lt;- '-%' ![=] skip
12071MINUSPERCENTEQUAL &lt;- '-%=' skip12152MINUSPERCENTEQUAL &lt;- '-%=' skip
12153MINUSPIPE &lt;- '-|' ![=] skip
12154MINUSPIPEEQUAL &lt;- '-|=' skip
12072MINUSRARROW &lt;- '-&gt;' skip12155MINUSRARROW &lt;- '-&gt;' skip
12073PERCENT &lt;- '%' ![=] skip12156PERCENT &lt;- '%' ![=] skip
12074PERCENTEQUAL &lt;- '%=' skip12157PERCENTEQUAL &lt;- '%=' skip
...@@ -12080,6 +12163,8 @@ PLUS2 &lt;- '++' skip...@@ -12080,6 +12163,8 @@ PLUS2 &lt;- '++' skip
12080PLUSEQUAL &lt;- '+=' skip12163PLUSEQUAL &lt;- '+=' skip
12081PLUSPERCENT &lt;- '+%' ![=] skip12164PLUSPERCENT &lt;- '+%' ![=] skip
12082PLUSPERCENTEQUAL &lt;- '+%=' skip12165PLUSPERCENTEQUAL &lt;- '+%=' skip
12166PLUSPIPE &lt;- '+|' ![=] skip
12167PLUSPIPEEQUAL &lt;- '+|=' skip
12083LETTERC &lt;- 'c' skip12168LETTERC &lt;- 'c' skip
12084QUESTIONMARK &lt;- '?' skip12169QUESTIONMARK &lt;- '?' skip
12085RARROW &lt;- '&gt;' ![&gt;=] skip12170RARROW &lt;- '&gt;' ![&gt;=] skip