[incubator-tuweni-website] 01/02: Add uints operations

[to...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

toulmean pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-tuweni-website.git

commit 069d401f1ae6950f06c89f737e6609f6a80f4c1e
Author: Antoine Toulme <an...@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-unsubscribe@tuweni.apache.org
For additional commands, e-mail: commits-help@tuweni.apache.org