You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@tuweni.apache.org by to...@apache.org on 2021/01/02 07:47:31 UTC
[incubator-tuweni-website] branch master updated: add tutorials
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
The following commit(s) were added to refs/heads/master by this push:
new 655fb8a add tutorials
655fb8a is described below
commit 655fb8a81f70f21904bf6bb953a43215268023a9
Author: Antoine Toulme <an...@lunar-ocean.com>
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: commits-unsubscribe@tuweni.apache.org
For additional commands, e-mail: commits-help@tuweni.apache.org