This is an automated email from the ASF dual-hosted git repository.
humbedooh pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/incubator-tuweni-website.git
commit 069d401f1ae6950f06c89f737e6609f6a80f4c1e
Author: Antoine Toulme <anto...@lunar-ocean.com>
AuthorDate: Sat Jan 2 23:19:14 2021 -0800
Add uints operations
---
tutorials/creating-uints.md | 36 ++++++++++++++++++++++++-
tutorials/uints-operations.md | 61 +++++++++++++++++++++++++++++++++++++++++++
2 files changed, 96 insertions(+), 1 deletion(-)
diff --git a/tutorials/creating-uints.md b/tutorials/creating-uints.md
index 49827cc..4e00855 100644
--- a/tutorials/creating-uints.md
+++ b/tutorials/creating-uints.md
@@ -5,6 +5,40 @@ description: Creating Uints
group: nav-right
categories: ["units", "bigints"]
previous: getting-started-with-units.md
+next: uints-operations.md
---
-TODO
\ No newline at end of file
+NOTE: We are going to use the [`UInt256`
class](/docs/org.apache.tuweni.units.bigints/-u-int256/index.html) for all
examples, but the same behaviors are possible with the
[`UInt384`](/docs/org.apache.tuweni.units.bigints/-u-int384/index.html),
[`UInt64`](/docs/org.apache.tuweni.units.bigints/-u-int64/index.html),
[`UInt32`](/docs/org.apache.tuweni.units.bigints/-u-int32/index.html) classes.
+
+We refer to those classes as `UInt`.
+
+# Creating Uints
+
+## `valueOf`
+
+You can initialize a `UInt` with the [static method
`valueOf`](/docs/org.apache.tuweni.units.bigints/-u-int256/value-of.html), with
an integer, a long, or a BigInteger object. This only accepts positive values.
+
+{%highlight java%}
+// from an int
+UInt256 value = UInt256.valueOf(42);
+// from a long
+UInt256 value = UInt256.valueOf(42L);
+// from a BigInteger
+UInt256 value = UInt256.valueOf(BigInteger.ONE);
+{%endhighlight%}
+
+## `fromBytes`
+
+You can initialize a `UInt` from a `Bytes` object, using the [`fromBytes`
method](/docs/org.apache.tuweni.units.bigints/-u-int256/from-bytes.html).
+
+{%highlight java%}
+UInt256 value = UInt256.fromBytes(Bytes.wrap(new byte[] {0x01, 0x02, 0x03}));
+{%endhighlight%}
+
+## `fromHexString`
+
+You can initialize a `UInt` from a string representing a hexadecimal encoding
of bytes, with an optional prefix of `0x`.
+
+{%highlight java%}
+UInt256 value = UInt256.fromHexString("0xdeadbeef");
+{%endhighlight%}
diff --git a/tutorials/uints-operations.md b/tutorials/uints-operations.md
new file mode 100644
index 0000000..4180c6a
--- /dev/null
+++ b/tutorials/uints-operations.md
@@ -0,0 +1,61 @@
+---
+layout: tutorial
+title: Unsigned Integers operations
+description: Unsigned Integers operations
+group: nav-right
+categories: ["units", "bigints"]
+previous: creating-uints.md
+---
+
+`Uints` are immutable, so all operations create a new object as the result of
the operation.
+
+# Arithmetic operations
+
+## Adding and subtracting
+
+*
[`add(other)`](/docs/org.apache.tuweni.units.bigints/-u-int256-value/add.html)
+*
[`substract(other)`](/docs/org.apache.tuweni.units.bigints/-u-int256-value/subtract.html)
+
+Since these are bound integers, they will overflow and underflow if the
operation returns a value outside the boundaries - for a `Uint256`, 0 to 2^256.
+
+For this reason, the API also contains `exact` methods that throw exceptions
if the operations overflows or underflows.
+
+*
[`addExact(other)`](/docs/org.apache.tuweni.units.bigints/-u-int256-value/add-exact.html)
+*
[`subtractExact(other)`](/docs/org.apache.tuweni.units.bigints/-u-int256-value/subtract-exact.html)
+
+## Multiplying and dividing
+
+*
[`multiply(other)`](/docs/org.apache.tuweni.units.bigints/-u-int256-value/multiply.html)
+*
[`divide(other)`](/docs/org.apache.tuweni.units.bigints/-u-int256-value/divide.html)
+
+Additionally, the [method
`divideCeil(other)`](/docs/org.apache.tuweni.units.bigints/-u-int256-value/divide-ceil.html)
divides integers but returns the ceiling of the rounding.
+
+{%highlight java%}
+UInt256 result = UInt256.valueOf(12L).divide(UInt256.valueOf(5L)); // returns 2
+UInt256 resultCeiling = UInt256.valueOf(12L).divideCeil(UInt256.valueOf(5L));
// returns 3
+{%endhighlight%}
+
+## Modulus
+
+You can use the [method
`mod(divisor)`](/docs/org.apache.tuweni.units.bigints/-u-int256-value/mod.html)
to get the modulus of the value by the divisor.
+
+The [method
`mod0`](/docs/org.apache.tuweni.units.bigints/-u-int256-value/mod0.html) is
more forgiving - if you divide by zero, it will return zero instead of throwing
an exception.
+
+## Power
+
+The [method
`pow(exponent)`](/docs/org.apache.tuweni.units.bigints/-u-int256-value/pow.html)
returns a value that is `value^exponent mod 2^256.
+
+# Boolean operations
+
+You can use the following methods to perform boolean operations:
+
+* [`not()`: bit-wise NOT of this
value.](/docs/org.apache.tuweni.units.bigints/-u-int256/not.html)
+* [`and(other)`: bit-wise AND of this value and the supplied
value.](/docs/org.apache.tuweni.units.bigints/-u-int256/and.html)
+* [`or(other)`: bit-wise OR of this value and the supplied
value.](/docs/org.apache.tuweni.units.bigints/-u-int256/or.html)
+* [`xor(other)`: bit-wise XOR of this value and the supplied
value.](/docs/org.apache.tuweni.units.bigints/-u-int256/xor.html)
+
+# Shifting bytes
+
+You can shift
[right](/docs/org.apache.tuweni.units.bigints/-u-int256/shift-right.html) and
[left](/docs/org.apache.tuweni.units.bigints/-u-int256/shift-left.html) the
bits of the underlying bytes object by a given distance.
+
+This is equivalent to the `<<<` or `>>>` operators in Java.
\ No newline at end of file
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscr...@tuweni.apache.org
For additional commands, e-mail: commits-h...@tuweni.apache.org
