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 655fb8a81f70f21904bf6bb953a43215268023a9 Author: Antoine Toulme <[email protected]> AuthorDate: Fri Jan 1 23:47:18 2021 -0800 add tutorials --- _config.yml | 1 + _includes/themes/apache/_navigation.html | 1 + _includes/themes/apache/footer.html | 2 +- _includes/themes/apache/tutorial.html | 77 +++++++++++++++++ _layouts/news_item.md | 3 + _layouts/tutorial.html | 5 ++ publish.sh | 5 ++ tutorials/creating-bytes.md | 138 +++++++++++++++++++++++++++++++ tutorials/extracting-values.md | 48 +++++++++++ tutorials/getting-started-with-bytes.md | 33 ++++++++ tutorials/index.md | 12 +++ tutorials/manipulating-bytes.md | 67 +++++++++++++++ tutorials/mutable-bytes.md | 47 +++++++++++ 13 files changed, 438 insertions(+), 1 deletion(-) diff --git a/_config.yml b/_config.yml index 1325a1d..b54cf99 100644 --- a/_config.yml +++ b/_config.yml @@ -14,6 +14,7 @@ # limitations under the License. # markdown: kramdown +highlighter: rouge permalink: /news/:year/:month/:day/:title/ excerpt_separator: "" diff --git a/_includes/themes/apache/_navigation.html b/_includes/themes/apache/_navigation.html index fcc5015..14c2b40 100644 --- a/_includes/themes/apache/_navigation.html +++ b/_includes/themes/apache/_navigation.html @@ -30,6 +30,7 @@ <li id="docs"> <a href="#" data-toggle="dropdown" class="dropdown-toggle">Docs<b class="caret"></b></a> <ul class="dropdown-menu dropdown-left"> + <li><a href="/tutorials">Tutorials</a></li> <li><a href="/faq">FAQ</a></li> <li><a href="/docs">Javadoc</a></li> </ul> diff --git a/_includes/themes/apache/footer.html b/_includes/themes/apache/footer.html index 4a2d1f6..6d2989e 100644 --- a/_includes/themes/apache/footer.html +++ b/_includes/themes/apache/footer.html @@ -18,7 +18,7 @@ </div> {% endif %} <div> - Copyright © 2019-2020 <a href="http://www.apache.org";>The Apache Software Foundation</a>. + Copyright © 2019-2021 <a href="http://www.apache.org";>The Apache Software Foundation</a>. Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0";>Apache License, Version 2.0</a>. <br> diff --git a/_includes/themes/apache/tutorial.html b/_includes/themes/apache/tutorial.html new file mode 100644 index 0000000..54a086d --- /dev/null +++ b/_includes/themes/apache/tutorial.html @@ -0,0 +1,77 @@ +<div class="page-header"> + <h1>{{ page.title }} {% if page.tagline %}<small>{{page.tagline}}</small>{% endif %}</h1> +</div> + +<div class="row-fluid post-full"> + <div class="span12"> + + {% unless page.categories == empty %} + <ul class="tag_box inline"> + <li><i class="icon-folder-open"></i></li> + {% assign categories_list = page.categories %} + {% include JB/categories_list %} + </ul> + {% endunless %} + + {% unless page.tags == empty %} + <ul class="tag_box inline"> + <li><i class="icon-tags"></i></li> + {% assign tags_list = page.tags %} + {% include JB/tags_list %} + </ul> + {% endunless %} + + <div class="pagination row col-md-12"> + <div class="col-md-6"> + {% if page.previous %} + {% for post in site.pages %} + {% if post.name == page.previous %} + {% assign previous = post %} + <a href="{{ BASE_PATH }}{{ previous.url }}" title="{{ previous.title }}">← {{ previous.title }}</a><br/> + {% endif %} + {% endfor %} + {% endif %} + </div> + <div class="col-md-6" style="text-align: right;"> + {% if page.next %} + {% for post in site.pages %} + {% if post.name == page.next %} + {% assign next = post %} + <a href="{{ BASE_PATH }}{{ next.url }}" title="{{ next.title }}">{{ next.title }} →</a><br/> + {% endif %} + {% endfor %} + {% endif %} + </div> + </div> + <hr> + <div class="date"> + <span>{{ page.date | date_to_long_string }}</span> + </div> + <div class="content"> + {{ content }} + </div> + <div class="pagination row col-md-12"> + <div class="col-md-6"> + {% if page.previous %} + {% for post in site.pages %} + {% if post.name == page.previous %} + {% assign previous = post %} + <a href="{{ BASE_PATH }}{{ previous.url }}" title="{{ previous.title }}">← {{ previous.title }}</a><br/> + {% endif %} + {% endfor %} + {% endif %} + </div> + <div class="col-md-6" style="text-align: right;"> + {% if page.next %} + {% for post in site.pages %} + {% if post.name == page.next %} + {% assign next = post %} + <a href="{{ BASE_PATH }}{{ next.url }}" title="{{ next.title }}">{{ next.title }} →</a><br/> + {% endif %} + {% endfor %} + {% endif %} + </div> + </div> + {% include JB/comments %} + </div> +</div> diff --git a/_layouts/news_item.md b/_layouts/news_item.md new file mode 100644 index 0000000..036c436 --- /dev/null +++ b/_layouts/news_item.md @@ -0,0 +1,3 @@ +--- +layout: default +--- \ No newline at end of file diff --git a/_layouts/tutorial.html b/_layouts/tutorial.html new file mode 100644 index 0000000..f89e5a6 --- /dev/null +++ b/_layouts/tutorial.html @@ -0,0 +1,5 @@ +--- +layout: default +--- +{% include JB/setup %} +{% include themes/apache/tutorial.html %} diff --git a/publish.sh b/publish.sh index 5a4418a..c50958c 100755 --- a/publish.sh +++ b/publish.sh @@ -86,6 +86,11 @@ cp -R build/docs/tuweni/* ../asf-site-branch/content/docs cd .. cd asf-site-branch +# +# Copy favicon to default location +# +cp content/assets/themes/apache/img/tuweni_face.ico content/favicon.ico + # # Commit and push to gitbox diff --git a/tutorials/creating-bytes.md b/tutorials/creating-bytes.md new file mode 100644 index 0000000..399a8ec --- /dev/null +++ b/tutorials/creating-bytes.md @@ -0,0 +1,138 @@ +--- +layout: tutorial +title: Creating Bytes +description: Creating Bytes +group: nav-right +categories: ["bytes"] +previous: getting-started-with-bytes.md +next: manipulating-bytes.md +--- + +# From a bytes array: + +You can create `Bytes` objects by wrapping a native byte array: + +{% highlight java %} +Bytes bytes = Bytes.wrap(new byte[] {1, 2, 3, 4}); +{% endhighlight %} + +Note the underlying array is not copied - any change to the byte array will change the Bytes object's behavior. + +You can also wrap with an offset and a size to select a portion of the array: + +{% highlight java %} +// wrapping with an offset of 2 and a size of one byte +Bytes bytes = Bytes.wrap(new byte[] {1, 2, 3, 4}, 2, 1); +{% endhighlight %} + +# From a hex string: + +You can create `Bytes` objects from a hexadecimal-encoded string with the [`fromHexString`](/docs/org.apache.tuweni.bytes/-bytes/from-hex-string.html) method: + +{% highlight java %} +Bytes bytes = Bytes.fromHexString("0xdeadbeef"); +{% endhighlight %} + +The `"0x"` prefix is optional. + +However, this requires an even-sized string. For example, this succeeds: + +{% highlight java %} +Bytes bytes = Bytes.fromHexString("01FF2A"); +{% endhighlight %} + +This fails: + +{% highlight java %} +Bytes bytes = Bytes.fromHexString("1FF2A"); +{% endhighlight %} + +You can circumvent this with the [`fromHexStringLenient` method](/docs/org.apache.tuweni.bytes/-bytes/from-hex-string-lenient.html): + +{% highlight java %} +Bytes bytes = Bytes.fromHexStringLenient("1FF2A"); +{% endhighlight %} + +# From a base64-encoded string: + +You can create `Bytes` objects from a base64-encoded string with the [`fromBase64String`](/docs/org.apache.tuweni.bytes/-bytes/from-base64-string.html) method: + +{% highlight java %} +Bytes value = Bytes.fromBase64String("deadbeefISDAbest"); +{% endhighlight %} + +# From primitive types + +We also have convenience methods to create `Bytes` objects from primitive types. + +* [Bytes.of()](/docs/org.apache.tuweni.bytes/-bytes/of.html) + +[Bytes.of()](/docs/org.apache.tuweni.bytes/-bytes/of.html) takes a variadic argument of bytes: + +{% highlight java %} +Bytes value = Bytes.of(0x00, 0x01, 0xff, 0x2a); +{% endhighlight %} + +* [Bytes.ofUnsignedInt()](/docs/org.apache.tuweni.bytes/-bytes/of-unsigned-int.html) +* [Bytes.ofUnsignedLong()](/docs/org.apache.tuweni.bytes/-bytes/of-unsigned-long.html) +* [Bytes.ofUnsignedShort()](/docs/org.apache.tuweni.bytes/-bytes/of-unsigned-short.html) + +{% highlight java %} +Bytes value = Bytes.ofUnsignedInt(42); +{% endhighlight %} + +# More wrapping +### Use [`Bytes.wrapByteBuf(buffer)`](/docs/org.apache.tuweni.bytes/-bytes/wrap-byte-buf.html) to wrap a Netty `ByteBuf` object as a `Bytes` object. + +{% highlight java %} +ByteBuf buffer = Unpooled.buffer(42); +Bytes.wrapByteBuf(buffer); +{% endhighlight %} + +You can apply an offset and size parameter: + +{% highlight java %} +Bytes value = Bytes.wrapByteBuf(buffer, 1, 1); +{% endhighlight %} + +### Use [`Bytes.wrapByteBuffer(buffer)`](/docs/org.apache.tuweni.bytes/-bytes/wrap-byte-buffer.html) to wrap a `ByteBuffer` object as a `Bytes` object. + +{% highlight java %} +Bytes.wrapByteBuffer(buffer); +{% endhighlight %} + +You can apply an offset and size parameter: + +{% highlight java %} +Bytes value = Bytes.wrapByteBuffer(buffer, 1, 1); +{% endhighlight %} + + +### Use [`Bytes.wrapBuffer(buffer)`](/docs/org.apache.tuweni.bytes/-bytes/wrap-byte-buffer.html) to wrap a Vert.x `Buffer` object as a `Bytes` object. + +{% highlight java %} +Bytes.wrapBuffer(buffer); +{% endhighlight %} + +You can apply an offset and size parameter: + +{% highlight java %} +Bytes value = Bytes.wrapBuffer(buffer, 1, 1); +{% endhighlight %} + +# Random + +You can create random bytes objects of a given length with the [Bytes.random() method](/docs/org.apache.tuweni.bytes/-bytes/random.html): + +{% highlight java %} +// create a Bytes object of 20 bytes: +Bytes.random(20); +{% endhighlight %} + +Create a Bytes object with our own Random implementation: + +{% highlight java %} +Random random = new SecureRandom(); +... +Bytes.random(20, random); +{% endhighlight %} diff --git a/tutorials/extracting-values.md b/tutorials/extracting-values.md new file mode 100644 index 0000000..f7126f9 --- /dev/null +++ b/tutorials/extracting-values.md @@ -0,0 +1,48 @@ +--- +layout: tutorial +title: Extracting values +description: Extracting values +group: nav-right +categories: ["bytes"] +previous: manipulating-bytes.md +next: mutable-bytes.md +--- + +You can extract values from a bytes object into native Java objects such as ints and longs, bytes, byte arrays and so on. + +Note all the methods here take an optional `ByteOrder` argument, defaulting to big endian by default. + +# toInt() and toLong() + +The [method `toInt()`](docs/org.apache.tuweni.bytes/-bytes/to-int.html) and the [method `toLong()`](/docs/org.apache.tuweni.bytes/-bytes/to-long.html) respectively translate the bytes values into an int or a long, requiring respectively the value to be at most 4 or 8 bytes long. + +# get(i) + +The [`get(i)` method](/docs/org.apache.tuweni.bytes/-bytes/get.html) provides the byte at index `i`. + +# getInt(i) and getLong(i) + +The [method `getInt()`](docs/org.apache.tuweni.bytes/-bytes/get-int.html) and the [method `getLong()`](/docs/org.apache.tuweni.bytes/-bytes/get-long.html) respectively return the next 4 or 8 bytes into an int or a long. + +# toArray() and toArrayUnsafe() + +The [method `toArray`](/docs/org.apache.tuweni.bytes/-bytes/to-array.html) copies the bytes of the object into a new bytes array. + +The [method `toArrayUnsafe`](/docs/org.apache.tuweni.bytes/-bytes/to-array-unsafe.html) makes available the underlying byte array of the object - modifying it changes the Bytes object. Note this is more performant as it doesn't allocate new memory. + +# To BigIntegers + +The [method `toUnsignedBigInteger`](/docs/org.apache.tuweni.bytes/-bytes/to-unsigned-big-integer.html) creates a new unsigned BigInteger object with the contents of the Bytes object. +You can also use the method [`toBigInteger`](/docs/org.apache.tuweni.bytes/-bytes/to-big-integer.html) to represent Bytes as a signed integer, using the two's-complement representation. + +# Transforming Bytes into strings + +There is a sleuth of options to turn bytes into strings, and they all have different use cases. + +* The [method `toHexString`](/docs/org.apache.tuweni.bytes/-bytes/to-hex-string.html) provides the value represented as hexadecimal, starting with "0x". +* The [method `toUnprefixedHexString`](/docs/org.apache.tuweni.bytes/-bytes/to-unprefixed-hex-string.html) provides the value represented as hexadecimal, no "0x" prefix though. +* The [method `toShortHexString`](/docs/org.apache.tuweni.bytes/-bytes/to-short-hex-string.html) provides the value represented as a minimal hexadecimal string (without any leading zero). +* The [method `toQuantityHexString`](/docs/org.apache.tuweni.bytes/-bytes/to-quantity-hex-string.html) provides the value represented as a minimal hexadecimal string (without any leading zero, except if it's valued zero or empty, in which case it returns 0x0). +* The [method `toEllipsisHexString`](/docs/org.apache.tuweni.bytes/-bytes/to-ellipsis-hex-string.html) provides the first 3 bytes and last 3 bytes represented as hexadecimal strings, joined with an ellipsis (`...`). + +By default, `toString()` calls `toHexString()`. \ No newline at end of file diff --git a/tutorials/getting-started-with-bytes.md b/tutorials/getting-started-with-bytes.md new file mode 100644 index 0000000..9e50969 --- /dev/null +++ b/tutorials/getting-started-with-bytes.md @@ -0,0 +1,33 @@ +--- +layout: tutorial +title: Getting Started with Bytes +description: Getting Started with Bytes +group: nav-right +categories: ["bytes"] +previous: index.md +next: creating-bytes.md +--- +Apache Tuweni provides support for manipulating bytes. + +To get started, install the `bytes` library. + +With Maven: + +{% highlight xml %} +<dependency> + <groupId>org.apache.tuweni</groupId> + <artifactId>bytes</artifactId> + <version>{{site.data.project.latest_release}}</version> +</dependency> +{% endhighlight %} + +Or using Gradle: + +{% highlight groovy %} +implementation("org.apache.tuweni:bytes:{{site.data.project.latest_release}}") +{% endhighlight %} + +The [bytes library](/docs/org.apache.tuweni.bytes/index.html) revolves mainly around the [`Bytes`](/docs/org.apache.tuweni.bytes/-bytes/index.html) interface. + +This tutorial goes over the main uses of `Bytes`, from creating them to manipulating them. + diff --git a/tutorials/index.md b/tutorials/index.md new file mode 100644 index 0000000..c7ffe1a --- /dev/null +++ b/tutorials/index.md @@ -0,0 +1,12 @@ +--- +layout: tutorial +title: Tutorials +description: Tutorials +group: nav-right +--- + +# Getting started with bytes + +In this tutorial, we explain in detail how to use the bytes library of Apache Tuweni. + +## [Start tutorial](getting-started-with-bytes) \ No newline at end of file diff --git a/tutorials/manipulating-bytes.md b/tutorials/manipulating-bytes.md new file mode 100644 index 0000000..7a1b8a3 --- /dev/null +++ b/tutorials/manipulating-bytes.md @@ -0,0 +1,67 @@ +--- +layout: tutorial +title: Manipulating Bytes +description: Manipulating Bytes +group: nav-right +categories: ["bytes"] +previous: creating-bytes.md +next: extracting-values.md +--- + +# Concatenating and wrapping + +You can [concatenate](/docs/org.apache.tuweni.bytes/-bytes/concatenate.html) or [wrap](/docs/org.apache.tuweni.bytes/-bytes/wrap.html) bytes objects. + +When concatenating, the underlying objects are copied into a new bytes object. + +When wrapping, you are creating a *view* made of the underlying bytes objects. If their values change, the wrapped view changes as well. + +Of course, wrapping is preferrable to avoid copying bytes in memory. + +# Copying and slicing + +In the same spirit as above, you can [copy](/docs/org.apache.tuweni.bytes/-bytes/copy.html) or [slice](/docs/org.apache.tuweni.bytes/-bytes/slice.html) bytes objects. When you slice a bytes object, you create a view of the original bytes object, and the slice will change if the underlying bytes object changes. If you copy instead, you create a new copy of the bytes. + +{%highlight java%} +// slice from the second byte: +bytes.slice(2); +// slice from the second byte to the fifth byte: +bytes.slice(2, 5); +{%endhighlight%} + +# Shifting bytes + +You can shift [right](/docs/org.apache.tuweni.bytes/-bytes/shift-right.html) and [left](/docs/org.apache.tuweni.bytes/-bytes/shift-left.html) the bits of a bytes object by a given distance. + +This is equivalent to the `<<<` or `>>>` operators in Java. + +# xor, or, and + +You can apply boolean operations to Bytes objects. + +* [xor](/docs/org.apache.tuweni.bytes/-bytes/xor.html) +* [or](/docs/org.apache.tuweni.bytes/-bytes/or.html) +* [and](/docs/org.apache.tuweni.bytes/-bytes/and.html) + +Those methods take as argument the value to compare this value with, and return a new Bytes object that is the result of the boolean operation. + +If the argument and the value are different lengths, then the shorter will be zero-padded to the left. + +{%highlight java%} +Bytes value = Bytes.fromHexString("0x01000001").xor(Bytes.fromHexString("0x01000000")); +assertEquals(Bytes.fromHexString("0x00000001"), value); +{%endhighlight%} + +# not + +The [`not` method](https://tuweni.apache.org/docs/org.apache.tuweni.bytes/-bytes/not.html) returns a bit-wise NOT of the bytes. + +{%highlight java%} +Bytes value = Bytes.fromHexString("0x01000001").not(); +assertEquals(Bytes.fromHexString("0xfefffffe"), value); +{%endhighlight%} + +# commonPrefix + +The [`commonPrefix` method](https://tuweni.apache.org/docs/org.apache.tuweni.bytes/-bytes/common-prefix.html) returns the common bytes both the value and the argument start with. + diff --git a/tutorials/mutable-bytes.md b/tutorials/mutable-bytes.md new file mode 100644 index 0000000..87cc26b --- /dev/null +++ b/tutorials/mutable-bytes.md @@ -0,0 +1,47 @@ +--- +layout: tutorial +title: Mutable Bytes +description: Mutable Bytes +group: nav-right +categories: ["bytes"] +previous: manipulating-bytes.md +--- + + +By default, bytes objects are not mutable. You can use [`MutableBytes` objects](/docs/org.apache.tuweni.bytes/-mutable-bytes/index.html) instead. + +# Creating MutableBytes objects + +The methods described in the [tutorial "Creating Bytes"](/tutorials/creating-bytes) all work in the same way for `MutableBytes`. + +You can call the [method `mutableCopy()`](/docs/org.apache.tuweni.bytes/-mutable-bytes/mutable-copy.html) on any Bytes object to get a copy of the Bytes object as mutable. + +Finally, you can create fresh objects with the [`create()` method](/docs/org.apache.tuweni.bytes/-mutable-bytes/create.html). + +# Fill, Clear + +Fill a MutableBytes with the same byte the [fill method](/docs/org.apache.tuweni.bytes/-mutable-bytes/fill.html): + +{%highlight java%} +MutableBytes bytes = MutableBytes.create(2); +bytes.fill((byte) 34); +assertEquals(Bytes.fromHexString("0x2222"), bytes); +{%endhighlight%} + +You can clear the contents with the [`clear` method](/docs/org.apache.tuweni.bytes/-mutable-bytes/clear.html): + +{%highlight java%} +MutableBytes bytes = MutableBytes.fromHexString("0xdeadbeef"); +bytes.clear(); +{%endhighlight%} + +# Setting values + +You can set values with different arguments: + +* The [`set(int i, byte b)` method](/docs/org.apache.tuweni.bytes/-mutable-bytes/set.html) sets the value of a byte at index `i`. +* The [`setInt(int i, int value)` method](/docs/org.apache.tuweni.bytes/-mutable-bytes/set-int.html) sets the value of the next four bytes at index `i`. +* The [`setLong(int i, long value)` method](/docs/org.apache.tuweni.bytes/-mutable-bytes/set-long.html) sets the value of the next eight bytes at index `i`. +* The [`set(int offset, Bytes bytes)` method](/docs/org.apache.tuweni.bytes/-mutable-bytes/set.html) sets the value of the next bytes at index `i`. + + --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
