Add IonSystem#singleValue(byte[], int, int) (#257)

When ion object resides in the middle of bytearray, this helper
method would help to extract it without memory copy overhead.

Author: zvorygin

src/com/amazon/ion/IonSystem.java

@@ -373,6 +373,27 @@ public SymbolTable newSharedSymbolTable(String name,
      */
     public IonValue singleValue(byte[] ionData);
 
+    /**
+     * Extracts a single value from Ion text or binary data.
+     * <p>
+     * This method will auto-detect and uncompress GZIPped Ion data.
+     *
+     * @param ionData is used only within the range of bytes starting at
+     * {@code offset} for {@code len} bytes.
+     * The data in that range may be either Ion binary data, or UTF-8 Ion text.
+     * @param offset must be non-negative and less than {@code ionData.length}.
+     * @param len must be non-negative and {@code offset+len} must not exceed
+     *
+     * @return the first (and only) user value in the data; not null.
+     *
+     * @throws NullPointerException if {@code ionData} is null.
+     * @throws UnexpectedEofException if the data doesn't contain any user
+     * values.
+     * @throws IonException if the data does not contain exactly one user
+     * value.
+     */
+    public IonValue singleValue(byte[] ionData, int offset, int len);
+
 
     //-------------------------------------------------------------------------
     // IonReader creation

src/com/amazon/ion/impl/lite/IonSystemLite.java

@@ -523,7 +523,12 @@ public IonValue singleValue(String ionText)
 
     public IonValue singleValue(byte[] ionData)
     {
-        IonReader reader = newReader(ionData);
+        return singleValue(ionData, 0, ionData.length);
+    }
+
+    @Override
+    public IonValue singleValue(byte[] ionData, int offset, int len) {
+        IonReader reader = newReader(ionData, offset, len);
         try {
             Iterator<IonValue> it = iterate(reader);
             return singleValue(it);

test/com/amazon/ion/LoaderTest.java

@@ -32,6 +32,8 @@
 import java.io.StringReader;
 import java.util.Arrays;
 import java.util.Iterator;
+
+import org.junit.Assert;
 import org.junit.Test;
 
 
@@ -393,6 +395,53 @@ public void testSingleValue()
         catch (IonException ie) { /* ok */ }
     }
 
+    @Test
+    public void testSubBufferSingleValue()
+    {
+        IonSystem sys = system();
+
+        String image = "(this is a single sexp)";
+        byte[] bytes =  sys.newLoader().load(image).getBytes();
+
+        IonValue singleValue = sys.singleValue(bytes, 0, bytes.length);
+        assertEquals(singleValue.toString(), image);
+
+        byte[] padded = new byte[bytes.length + 20];
+        System.arraycopy(bytes, 0, padded, 10, bytes.length);
+
+        IonValue paddedValue = sys.singleValue(padded, 10, bytes.length);
+        assertEquals(paddedValue.toString(), image);
+
+        bytes = sys.newLoader().load("(two) (values)").getBytes();
+
+        try {
+            sys.singleValue(bytes, 0, bytes.length);
+            fail("Expected IonException");
+        }
+        catch (IonException ie) {
+            Assert.assertTrue(ie.getMessage().contains("not a single value"));
+        }
+
+        padded = new byte[bytes.length + 20];
+        System.arraycopy(bytes, 0, padded, 10, bytes.length);
+
+        try {
+            sys.singleValue(padded, 10, bytes.length);
+            fail("Expected IonException");
+        }
+        catch (IonException ie) {
+            Assert.assertTrue(ie.getMessage().contains("not a single value"));
+        }
+
+        try {
+            sys.singleValue(padded, 15, bytes.length);
+            fail("Expected IonException");
+        }
+        catch (IonException ie) {
+            Assert.assertTrue(ie.getMessage().contains("bad character"));
+        }
+    }
+
     @Test
     public void testCatalogOnLoader() throws Exception {
         IonSystem sys = newSystem(Symtabs.CATALOG);