Added some basic usage example

Author: mrotteveel

README.md

@@ -40,6 +40,73 @@ This library explicitly does not include mathematical operations on decimal.
 As an alternative, consider using `BigDecimal` with `MathContext.DECIMAL128`,
 `MathContext.DECIMAL64`, or `MathContext.DECIMAL32`.
 
+Usage
+-----
+
+Decoding a 4-byte Decimal32 to a `java.math.BigDecimal`:
+
+```java
+byte[] bytes = {(byte) 0xc7, (byte) 0xf4, (byte) 0xd2, (byte) 0xe7};
+Decimal32 decimal32 = Decimal32.parseBytes(bytes);
+BigDecimal bigDecimal = decimal32.toBigDecimal();
+assertEquals(new BigDecimal("-1.234567E+96"), bigDecimal);
+```
+
+The method `toBigDecimal` throws `DecimalInconvertibleException` if the decimal
+value is an infinity or NaN value. The actual type and sign can be obtained from
+the exception.
+
+Encoding a `java.math.BigDecimal` to Decimal32 byte array:
+
+```java
+BigDecimal bigDecimal = new BigDecimal("-7.50E-7");
+Decimal32 decimal32 = Decimal32.valueOf(bigDecimal);
+byte[] bytes = decimal32.toBytes();
+assertArrayEquals(new byte[] {(byte) 0xa1, (byte) 0xc0, 0x03, (byte) 0xd0}, bytes);
+```
+
+This will apply rounding if `bigDecimal` value doesn't fit a Decimal32, and
+overflow will 'round' to infinity.
+
+If overflow to infinity is unwanted, then use:
+
+```java
+BigDecimal bigDecimal = new BigDecimal("-7.50E-7");
+Decimal32 decimal32 = Decimal32.valueOf(bigDecimal, OverflowHandling.THROW_EXCEPTION);
+byte[] bytes = decimal32.toBytes();
+assertArrayEquals(new byte[] {(byte) 0xa1, (byte) 0xc0, 0x03, (byte) 0xd0}, bytes);
+```
+
+Conversion works the same for `Decimal64` and `Decimal128`.
+
+The `valueOf` methods exists for:
+
+- `BigDecimal`
+- `BigInteger`
+ - In addition there is `valueOfExact(BigInteger)` which throws 
+ `DecimalOverflowException` if the `BigInteger` needs to be rounded to fit the
+ target decimal type.
+- `String`
+- `double`
+- `Decimal` (parent class of `Decimal32`, `Decimal64` and `Decimal128`) to allow
+conversion between decimal types
+
+The `valueOf` methods will round values to fit the target decimal type, and -
+depending on the specified overflow handling - will either return +/- infinity
+or throw an exception on overflow.
+
+Conversion to a type is provided by:
+
+- `toBytes()`
+- `toBigDecimal()` - will throw `DecimalInconvertibleException` if the value is
+an infinity or NaN value
+- `toString()`
+- `doubleValue()`
+- `toDecimal(Class)` and `toDecimal(Class, OverflowHandling)`
+
+To obtain a `BigInteger`, use `toBigDecimal().toBigInteger()` but be aware that 
+large values (especially of `Decimal128`) can result in significant memory use. 
+
 Background
 ----------
 
@@ -69,6 +136,6 @@ References
     -   [Decimal Arithmetic Encodings](http://speleotrove.com/decimal/decbits.html)
     -   [A Summary of Densely Packed Decimal encoding](http://speleotrove.com/decimal/DPDecimal.html)
     -   [The decNumber Library](http://speleotrove.com/decimal/decnumber.html)
--   [Firebird 4 alpha 1 release notes](http://web.firebirdsql.org/downloads/prerelease/v40alpha1/Firebird-4.0.0_Alpha1-ReleaseNotes.pdf)
+-   [Firebird 4 beta 1 release notes](http://web.firebirdsql.org/downloads/prerelease/v40beta1/Firebird-4.0.0_Beta1-ReleaseNotes.pdf)
 
 

devdoc/deploy.md

@@ -27,3 +27,6 @@ In addition, you need to set the following credentials
 ./gradlew addCredentials --key signing.password --value <your secret key password> -PcredentialsPassphrase=<credentials password> 
 ./gradlew addCredentials --key ossrhPassword --value <your sonatyp OSSRH password> -PcredentialsPassphrase=<credentials password> 
 ```
+
+See https://github.com/etiennestuder/gradle-credentials-plugin for details on
+credentials.

src/test/java/org/firebirdsql/decimal/ExamplesTest.java

@@ -0,0 +1,62 @@
+/*
+ * Copyright (c) 2019 Firebird development team and individual contributors
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+package org.firebirdsql.decimal;
+
+import org.junit.Test;
+
+import java.math.BigDecimal;
+
+import static org.junit.Assert.assertArrayEquals;
+import static org.junit.Assert.assertEquals;
+
+/**
+ * Tests for the examples in README.md.
+ *
+ * @author <a href="mailto:mark@lawinegevaar.nl">Mark Rotteveel</a>
+ */
+public class ExamplesTest {
+
+    @Test
+    public void decimal32ParseBytes() {
+        byte[] bytes = {(byte) 0xc7, (byte) 0xf4, (byte) 0xd2, (byte) 0xe7};
+        Decimal32 decimal32 = Decimal32.parseBytes(bytes);
+        BigDecimal bigDecimal = decimal32.toBigDecimal();
+        assertEquals(new BigDecimal("-1.234567E+96"), bigDecimal);
+    }
+
+    @Test
+    public void decimal32ToBytes() {
+        BigDecimal bigDecimal = new BigDecimal("-7.50E-7");
+        Decimal32 decimal32 = Decimal32.valueOf(bigDecimal);
+        byte[] bytes = decimal32.toBytes();
+        assertArrayEquals(new byte[] {(byte) 0xa1, (byte) 0xc0, 0x03, (byte) 0xd0}, bytes);
+    }
+
+    @Test
+    public void decimal32ToBytes_overflowThrowException() {
+        BigDecimal bigDecimal = new BigDecimal("-7.50E-7");
+        Decimal32 decimal32 = Decimal32.valueOf(bigDecimal, OverflowHandling.THROW_EXCEPTION);
+        byte[] bytes = decimal32.toBytes();
+        assertArrayEquals(new byte[] {(byte) 0xa1, (byte) 0xc0, 0x03, (byte) 0xd0}, bytes);
+    }
+}