Add more to readme

Author: patrickfav

README.md

@@ -8,61 +8,84 @@
 
 ## API Description
 
+Per default the instance is **immutable**, which means any transformation will
+create a copy of the internal array (it is, however, possible to get and
+modify the internal array). There is a **mutable** version which supports
+in-place modification for better performance and a **read-only** version which
+restricts the access to the internal array.
+
 ### Constructors
 
-There are 2 basic constructors:
+There are 3 basic constructors:
 
  * `wrap()` which reuses the given array reference; this is equivalent to `ByteBuffer.wrap()`
  * `from()` which always creates a new internal array reference (i.e. a copy of the passed reference)
+ * `parse()` which parses from binary-text-encoded strings (see other section)
 
 Here is a simple example to show the difference
 
-    byte[] myArray = ...
-    Bytes bWrap = Bytes.wrap(myArray);
-    assertSame(myArray, bWrap.array());
+```java
+byte[] myArray = ...
+Bytes bWrap = Bytes.wrap(myArray);
+assertSame(myArray, bWrap.array());
 
-    byte[] myArray2 = ...
-    Bytes bFrom = Bytes.from(myArray2);
-    assertNotSame(myArray2, bFrom.array());
-    assertArrayEquals(myArray2, bFrom.array());
+byte[] myArray2 = ...
+Bytes bFrom = Bytes.from(myArray2);
+assertNotSame(myArray2, bFrom.array());
+assertArrayEquals(myArray2, bFrom.array());
+```
 
 The following code is equivalent:
 
-    Bytes.wrap(myArray).copy() ~ Bytes.from(myArray)
+```java
+Bytes.wrap(myArray).copy() ~ Bytes.from(myArray)
+```
 
-### More Use Cases
+### More Constructors
 
-Concatenating of multiple byte arrays or bytes:
+**Concatenating** of multiple byte arrays or bytes:
 
-    Bytes.from(array1, array2, array3);
-    Bytes.from((byte) 0x01, (byte) 0x02, (byte) 0x03);
+```java
+Bytes.from(array1, array2, array3);
+Bytes.from((byte) 0x01, (byte) 0x02, (byte) 0x03);
+```
 
-Creating byte arrays from primitive integer types:
+Creating byte arrays from **primitive integer** types:
 
-    Bytes.from(8);  //00000000 00000000 00000000 00001000
-    Bytes.from(1897621543227L);
+```java
+Bytes.from(8);  //00000000 00000000 00000000 00001000
+Bytes.from(1897621543227L);
+```
 
-Initializing empty arrays of arbitrary length:
+Initializing **empty arrays** of arbitrary length:
 
-    Bytes.allocate(16);
-    Bytes.allocate(4,(byte) 1); //fill with 0x01
+```java
+Bytes.allocate(16);
+Bytes.allocate(4,(byte) 1); //fill with 0x01
+```
 
-Creating random byte arrays for e.g. testing:
+Creating **random** byte arrays for e.g. testing:
 
-    Bytes.random(12);
+```java
+Bytes.random(12);
+```
 
 Reading byte content of encoded `String`s:
 
-    Bytes.from(utf8String)
-    Bytes.from(utf8StringToNormalize, Normalizer.Form.NFKD) //normalizes unicode
-    Bytes.from(asciiString, StandardCharset.US_ASCII) //any charset
+```java
+Bytes.from(utf8String)
+Bytes.from(utf8StringToNormalize, Normalizer.Form.NFKD) //normalizes unicode
+Bytes.from(asciiString, StandardCharset.US_ASCII) //any charset
+```
 
 And other types:
 
-    Bytes.from(byteInputStream); //any inputStream
-    Bytes.from(byteList); //List<Byte> byteList = ...
-    Bytes.from(myBitSet); //BitSet myBitSet = ...
-    Bytes.from(bigInteger);
+```java
+Bytes.from(byteInputStream); //any inputStream
+Bytes.from(byteList); //List<Byte> byteList = ...
+Bytes.from(myBitSet); //BitSet myBitSet = ...
+Bytes.from(bigInteger);
+```
 
 For parsing binary-text-encoded strings, see below.
 
@@ -71,54 +94,105 @@ For parsing binary-text-encoded strings, see below.
 Transformer transform the internal byte array. It is possible to create
 a custom transformer if a specific use case is required (see `BytesTransformer`).
 
-    Bytes result = Bytes.wrap(array1).transform(myCustomTransformer);
+```java
+Bytes result = Bytes.wrap(array1).transform(myCustomTransformer);
+```
 
 #### Built-In Transformers
 
 For **appending** byte arrays or primitive integer types to current instances.
 Note however, that this will create new copies of byte arrays every time.
 For dynamic growing byte arrays see `ByteArrayOutputStream`
 
-    Bytes result = Bytes.wrap(array1).append(array2);
-    Bytes result = Bytes.wrap(array1).append(1341);
-    Bytes result = Bytes.wrap(array1).append((byte) 3);
+```java
+Bytes result = Bytes.wrap(array1).append(array2);
+Bytes result = Bytes.wrap(array1).append(1341);
+Bytes result = Bytes.wrap(array1).append((byte) 3);
+```
 
-Bitwise operations: XOR, OR, AND, NOT as well as left and right shifts and switching bits:
+**Bitwise operations**: XOR, OR, AND, NOT as well as left and right shifts and switching bits:
 
-    Bytes result = Bytes.wrap(array).xor(array2);
-    Bytes result = Bytes.wrap(array).or(array2);
-    Bytes result = Bytes.wrap(array).and(array2);
-    Bytes result = Bytes.wrap(array).negate();
-    Bytes result = Bytes.wrap(array).leftShift(8);
-    Bytes result = Bytes.wrap(array).rightShift(8);
-    Bytes result = Bytes.wrap(array).switchBit(3, true);
+```java
+Bytes result = Bytes.wrap(array).xor(array2);
+Bytes result = Bytes.wrap(array).or(array2);
+Bytes result = Bytes.wrap(array).and(array2);
+Bytes result = Bytes.wrap(array).negate();
+Bytes result = Bytes.wrap(array).leftShift(8);
+Bytes result = Bytes.wrap(array).rightShift(8);
+Bytes result = Bytes.wrap(array).switchBit(3, true);
+```
 
-Copy operations, which copies the internal byte array to a new instance:
+**Copy** operations, which copies the internal byte array to a new instance:
 
-    Bytes copy = Bytes.wrap(array).copy();
-    Bytes copy = Bytes.wrap(array).copy(3, 17); //copy partial array
+```java
+Bytes copy = Bytes.wrap(array).copy();
+Bytes copy = Bytes.wrap(array).copy(3, 17); //copy partial array
+```
 
-Resizing the internal byte array:
+**Resizing** the internal byte array:
 
-    Bytes resized = Bytes.wrap(array).resize(3); //from {3, 9, 2, 1} to {9, 2, 1}
+```java
+Bytes resized = Bytes.wrap(array).resize(3); //from {3, 9, 2, 1} to {9, 2, 1}
+```
 
 Other transformers:
 
-    Bytes result = Bytes.wrap(array).shuffle();
-    Bytes result = Bytes.wrap(array).sort(myComparator);
-    Bytes result = Bytes.wrap(array).reverse();
+```java
+Bytes result = Bytes.wrap(array).shuffle();
+Bytes result = Bytes.wrap(array).sort(myComparator);
+Bytes result = Bytes.wrap(array).reverse();
+```
+
+### Parser and Encoder for Binary-Text-Encodings
+
+This library can parse and encode a variety of encodings: binary, decimal, ocatal,
+hex, base36 and base64. Additionally custom parsers are supported by providing your own
+implementation:
+
+```java
+Bytes.parse("8sK;S*j=r", base85Decoder);
+Bytes.encode(base85Encoder);
+ ```
+
+**Hex** can be upper and lowercase and also supports `0x` prefix for parsing
+
+```java
+Bytes.parseHex("a0e13eaa1a")
+Bytes.parseHex("0xA0E1")
+
+Bytes.from(array).encodeHex() //a0e13eaa1a
+ ```
+
+This lib has it's own build in **Base64** encoder:
+
+```java
+Bytes.parseBase64("SpT9/x6v7Q==");
+
+Bytes.from(array).encodeBase64(); //"SpT9/x6v7Q=="
+ ```
+
+Additionally the following encodings are supported:
 
-### Parser and Encoder
+```java
+Bytes.from(array).encodeBinary(); //1110110110101111
+Bytes.from(array).encodeDec(); //20992966904426477
+Bytes.from(array).encodeOctal(); //1124517677707527755
+Bytes.from(array).encodeBase36(); //5qpdvuwjvu5
+```
 
 ### Validation
 
 A simple validation framework which can be used to check the internal byte array:
 
-    Bytes.wrap(new byte[]{8, 3, 9}.validate(BytesValidators.atLeast(3)); // true
+```java
+Bytes.wrap(new byte[]{8, 3, 9}.validate(BytesValidators.atLeast(3)); // true
+```
 
 This is especially convenient when combining validators:
 
-    Bytes.wrap(new byte[]{0, 1}.validate(BytesValidators.atMost(2), BytesValidators.notOnlyOf((byte)  0)); // true
+```java
+Bytes.wrap(new byte[]{0, 1}.validate(BytesValidators.atMost(2), BytesValidators.notOnlyOf((byte)  0)); // true
+```
 
 ### Converting