Merge pull request #113 from filip26/feat/uvarint-write

Add `uvarint.write(...):int`  & `Multihash.digestLength(byte[]):long`

Author: filip26

pom.xml

@@ -5,7 +5,7 @@
     <modelVersion>4.0.0</modelVersion>
     <groupId>com.apicatalog</groupId>
     <artifactId>copper-multicodec</artifactId>
-    <version>2.2.1-SNAPSHOT</version>
+    <version>2.3.0-SNAPSHOT</version>
     <packaging>jar</packaging>
     <url>https://github.com/filip26/copper-multicodec</url>
     <scm>
@@ -28,7 +28,7 @@
     <name>Copper Multicodec &amp; Multihash</name>
 
     <description>
-        Multicodec & Multihash - encoder/decoder for self-describing data formats.
+        Multicodec &amp; Multihash - encoder/decoder for self-describing data formats.
     </description>
 
     <licenses>
@@ -166,7 +166,6 @@
                 <extensions>true</extensions>
                   <configuration>
                     <publishingServerId>central</publishingServerId>
-                    <tokenAuth>true</tokenAuth>
                     <autoPublish>true</autoPublish>
                   </configuration>
                 </plugin>                    

src/main/java/com/apicatalog/multihash/Multihash.java

@@ -242,6 +242,68 @@ public byte[] decode(byte[] encoded, int index, int length) {
                 length + index);
     }
 
+    /**
+     * Returns the digest length (in bytes) declared by the given multihash-encoded
+     * value, starting at offset {@code 0}.
+     *
+     * <p>
+     * This is a convenience method equivalent to {@link #digestLength(byte[], int)
+     * hashLength(encoded, 0)}.
+     * </p>
+     *
+     * @param encoded the multihash-encoded byte array
+     * @return the declared digest length, in bytes
+     *
+     * @throws NullPointerException     if {@code encoded} is {@code null}
+     * @throws IllegalArgumentException if the input is shorter than
+     *                                  {@code codeVarint.length + 2} bytes, or if
+     *                                  the bytes at offset {@code 0} do not start
+     *                                  with this multihash's code
+     */
+    public long digestLength(byte[] encoded) {
+        return digestLength(encoded, 0);
+    }
+
+    /**
+     * Returns the digest length (in bytes) declared by the given multihash-encoded
+     * value.
+     *
+     * <p>
+     * The method validates that the input begins at {@code index} with this
+     * multihash's varint code, then decodes the varint length that immediately
+     * follows the code.
+     * </p>
+     *
+     * @param encoded the multihash-encoded byte array
+     * @param index   the starting offset within {@code encoded} at which the
+     *                multihash begins
+     * @return the declared digest length, in bytes
+     *
+     * @throws NullPointerException      if {@code encoded} is {@code null}
+     * @throws IllegalArgumentException  if the input is shorter than
+     *                                   {@code codeVarint.length + 2} bytes, or if
+     *                                   the bytes at {@code index} do not start
+     *                                   with this multihash's code
+     * @throws IndexOutOfBoundsException if {@code index} is negative or exceeds the
+     *                                   available range
+     */
+    public long digestLength(byte[] encoded, int index) {
+        Objects.requireNonNull(encoded);
+
+        if (encoded.length < (codeVarint.length + 2)) {
+            throw new IllegalArgumentException(
+                    "The value to decode must be a non-empty byte array with a minimum length of "
+                            + (codeVarint.length + 2) + " bytes, but the actual length is " + encoded.length + " bytes.");
+        }
+
+        if (!IntStream.range(0, codeVarint.length).allMatch(i -> codeVarint[i] == encoded[i + index])) {
+            throw new IllegalArgumentException(
+                    "The provided value is not encoded with this multihash: " + toString() + ".");
+        }
+
+        return UVarInt.decode(encoded, index + codeVarint.length);
+    }
+
     @Override
     public String toString() {
         return "Multihash [name=" + name + ", tag=" + tag + ", code=" + code + "]";

src/main/java/com/apicatalog/uvarint/UVarInt.java

@@ -1,5 +1,7 @@
 package com.apicatalog.uvarint;
 
+import java.util.Objects;
+
 /**
  * Utility class for encoding and decoding
  * <a href="https://en.wikipedia.org/wiki/LEB128">unsigned variable-length
@@ -70,17 +72,38 @@ public static final byte[] encode(final long value) {
     }
 
     /**
-     * Writes the UVarInt encoding of the given value into the target array starting
-     * at the given index.
+     * Writes the UVarInt-encoded form of the given non-negative value into the
+     * target array starting at the specified index.
      *
-     * @param value   the value to encode
-     * @param uvarint the target byte array
-     * @param index   the starting index
-     * @throws IllegalArgumentException if {@code value} cannot be encoded within
-     *                                  {@link #MAX_VAR_LENGTH} bytes
-     * @throws NullPointerException     if {@code uvarint} is {@code null}
+     * <p>
+     * The encoding uses seven data bits per byte. The most significant bit (MSB) of
+     * each byte is set if more bytes follow. The method returns the number of bytes
+     * written.
+     * </p>
+     *
+     * @param value   the value to encode (must be {@code >= 0})
+     * @param uvarint the destination byte array
+     * @param index   the starting index in {@code uvarint}
+     * @return the number of bytes written
+     *
+     * @throws NullPointerException      if {@code uvarint} is {@code null}
+     * @throws IllegalArgumentException  if {@code value} is negative
+     * @throws IndexOutOfBoundsException if {@code index} is negative, or if the
+     *                                   destination array does not have enough
+     *                                   space to hold the encoding
      */
-    public static final void write(final long value, final byte[] uvarint, final int index) {
+    public static final int write(final long value, final byte[] uvarint, final int index) {
+
+        Objects.requireNonNull(uvarint, "Target array must not be null.");
+
+        if (value < 0) {
+            throw new IllegalArgumentException("Value must be non-negative.");
+        }
+
+        if (index < 0) {
+            throw new IndexOutOfBoundsException("Index must be non-negative: " + index + ".");
+        }
+
         int offset = 0;
         long bytes = value;
         boolean next = false;
@@ -90,12 +113,20 @@ public static final void write(final long value, final byte[] uvarint, final int
                 uvarint[offset + index - 1] |= CONTINUE_BIT;
             }
 
+            if ((index + offset) >= uvarint.length) {
+                throw new IndexOutOfBoundsException(
+                        "Insufficient space at position " + (index + offset) +
+                                " (array length: " + uvarint.length + ").");
+            }
+
             uvarint[offset + index] = (byte) (bytes & SEGMENT_BITS);
 
             bytes >>>= 7;
             next = bytes != 0;
             offset++;
         } while (next);
+
+        return offset;
     }
 
     /**

src/test/java/com/apicatalog/multihash/MultihashTest.java

@@ -11,8 +11,8 @@
 import org.junit.jupiter.params.provider.Arguments;
 import org.junit.jupiter.params.provider.MethodSource;
 
-import com.apicatalog.multicodec.MulticodecDecoder;
 import com.apicatalog.multicodec.Multicodec.Tag;
+import com.apicatalog.multicodec.MulticodecDecoder;
 import com.apicatalog.multicodec.codec.MultihashCodec;
 
 class MultihashTest {
@@ -94,6 +94,12 @@ void testDecoderGet(byte[] input, Multihash expected) {
         assertEquals(expected, DECODER.getCodec(input).orElseThrow(IllegalArgumentException::new));
     }
 
+    @ParameterizedTest(name = "{index}")
+    @MethodSource("testData")
+    void testDigestLength(byte[] input, Multihash codec, byte[] expected) {
+        assertEquals(expected.length, codec.digestLength(input));
+    }
+
     static Stream<Arguments> testData() {
         return Stream.of(
                 Arguments.of(Base64.getDecoder().decode("ERSIwvEfss45KstbKYbmQCEcRpAHPg=="),