Migrate to new naming scheme

whitfin · whitfin · commit 43376e330a3f · 2026-01-02T11:34:30.000Z
diff --git a/README.md b/README.md
@@ -1,5 +1,5 @@
 # SipHash
-[![Build Status](https://img.shields.io/github/actions/workflow/status/whitfin/siphash-java/ci.yml?branch=main)](https://github.com/whitfin/siphash-java/actions) [![Coverage Status](https://img.shields.io/coveralls/whitfin/siphash-java.svg)](https://coveralls.io/github/whitfin/siphash-java) [![Maven Version](https://img.shields.io//maven-central/v/io.whitfin/siphash-java.svg)](https://central.sonatype.com/artifact/io.whitfin/siphash) 
+[![Build Status](https://img.shields.io/github/actions/workflow/status/whitfin/siphash-java/ci.yml?branch=main)](https://github.com/whitfin/siphash-java/actions) [![Coverage Status](https://img.shields.io/coveralls/whitfin/siphash-java.svg)](https://coveralls.io/github/whitfin/siphash-java) [![Maven Version](https://img.shields.io//maven-central/v/io.whitfin/siphash-java.svg)](https://central.sonatype.com/artifact/io.whitfin/siphash) [![Documentation](https://img.shields.io/badge/docs-latest-blue.svg)](https://www.javadoc.io/doc/io.whitfin/siphash)
 
 A Java implementation of the SipHash cryptographic hash family. Supports any variation, although defaults to the widely used SipHash-2-4. This library offers both a zero-allocation implementation, along with a streaming digest.
 
@@ -9,11 +9,11 @@ This library was heavily influenced by [veorq's C implementation](https://github
 
 `siphash` is available on Maven central, via Sonatype OSS:
 
-```
+```xml
 <dependency>
     <groupId>io.whitfin</groupId>
     <artifactId>siphash</artifactId>
-    <version>2.1.0</version>
+    <version>3.0.0</version>
 </dependency>
 ```
 
@@ -26,32 +26,36 @@ There are three main ways to use this library, and the appropriate choice will d
 The fastest use of this algorithm is to simply call `SipHasher.hash/2` which will call a zero-allocation implementation of the SipHash algorithm. This implementation should be used in most cases; specifically cases where you have frequently differing seed keys.
 
 ```java
+import io.whitfin.siphash.SipHash;
+
 // specify the key and data pair
 String key = "0123456789ABCDEF".getBytes();
 String data = "my-input".getBytes();
 
 // hash using default compression (2-4)
-long hash1 = SipHasher.hash(key, data);
+long hash1 = SipHash.hash(key, data);
 
 // you can also specify compression rounds
-long hash2 = SipHasher.hash(key, data, 2, 4);
+long hash2 = SipHash.hash(key, data, 2, 4);
 ```
 
 ### Contained Hashing
 
 This is an optimized implementation for cases where you have a single key (such as a hash table). In these cases, the seed values can be precomputed and re-used, rather than calculating them repeatedly on each call to hash. Although the initial call to create a container uses an allocation, there are no other allocations inside the container.
 
-
 ```java
+import io.whitfin.siphash.SipHash;
+import io.whitfin.siphash.SipHashContext;
+
 // create a container from our key
 String key = "0123456789ABCDEF".getBytes();
-SipHasherContainer container = SipHasher.container(key);
+SipHashContext ctx = SipHasher.context(key);
 
 // hash using default compression (2-4)
-long hash1 = container.hash(data);
+long hash1 = ctx.hash(data);
 
 // you can also specify compression rounds
-long hash2 = container.hash(data, 2, 4);
+long hash2 = ctx.hash(data, 2, 4);
 ```
 
 ### Streaming Digest
@@ -61,7 +65,7 @@ The final way to use the library is as a streaming digest; meaning that you can
 ```java
 // create a container from our key
 String key = "0123456789ABCDEF".getBytes();
-SipHasherStream hash = SipHasher.init(key);
+SipHashStream hash = SipHasher.init(key);
 
 // update several times
 hash.update("chu".getBytes());
@@ -78,20 +82,16 @@ By default, as of v2.0.0, all hashes are returned as a `long`. However, you can
 
 ```java
 // output will be padded (if necessary) to 16 bytes
-SipHasher.toHexString(-3891084581787974112L); // ca0017304f874620
-SipHasher.toHexString(   77813817455948350L); // 011473413414323e
+SipHash.toHexString(-3891084581787974112L); // ca0017304f874620
+SipHash.toHexString(   77813817455948350L); // 011473413414323e
 ```
 
 ## Contributing
 
-If you wish to contribute (awesome!), please file an issue first! All PRs should pass `mvn clean verify` and maintain 100% test coverage.
-
-## Testing
-
-Tests are run using `mvn`. I aim to maintain 100% coverage where possible (both line and branch).
-
-Tests can be run as follows:
+Tests are run using `mvn`. I aim to maintain 100% coverage where possible (both line and branch):
 
 ```bash
 $ mvn clean verify
 ```
+
+If you wish to contribute (awesome!), please file an issue first! All PRs should pass `mvn clean verify` and maintain 100% test coverage.
diff --git a/src/main/java/io/whitfin/siphash/SipHash.java b/src/main/java/io/whitfin/siphash/SipHash.java
@@ -6,26 +6,26 @@
  * This class offers three main utilities;
  *
  * - A zero-allocation SipHash algorithm.
- * - A container implementation for single-key environments.
+ * - A context implementation for single-key environments.
  * - A streaming SipHash algorithm for unknown input length.
  *
  * In most cases, the zero-allocation (0A) implementation will be desired. This
  * can be called via {@link #hash(byte[], byte[])} on the most basic level.
  *
  * In the case you're using a single key (such as one seeded at application
- * startup), you can make good use of a container which will simply avoid the
+ * startup), you can make good use of a context which will simply avoid the
  * need to recalculate the initial states on each hash call. This is an extremely
  * small optimization, but avoids all possible overhead for the best throughput.
- * Containers can be created via the {@link #container(byte[])} method, and can
- * hash input via {@link SipHasherContainer#hash(byte[])}.
+ * Contexts can be created via the {@link #context(byte[])} method, and can
+ * hash input via {@link SipHashContext#hash(byte[])}.
  *
  * For the case where the input length is unknown, a streaming implementation is
- * available via {@link SipHasherStream}. This can be initialized on a per-hash
+ * available via {@link SipHashStream}. This can be initialized on a per-hash
  * basis via {@link #init(byte[])} and can be updated with bytes multiple times
- * via {@link SipHasherStream#update(byte[])}. Once all input has been updated,
- * a final call to {@link SipHasherStream#digest()} will return the digested data.
+ * via {@link SipHashStream#update(byte[])}. Once all input has been updated,
+ * a final call to {@link SipHashStream#digest()} will return the digested data.
  */
-public final class SipHasher {
+public final class SipHash {
 
     /**
      * Default value for the C rounds of compression.
@@ -58,15 +58,15 @@ public final class SipHasher {
     static final long INITIAL_V3 = 0x7465646279746573L;
 
     /**
-     * Creates a new container, seeded with the provided key.
+     * Creates a new context, seeded with the provided key.
      *
      * @param key
-     *      the key bytes used to seed the container.
+     *      the key bytes used to seed the context.
      * @return
-     *      a {@link SipHasherContainer} instance after initialization.
+     *      a {@link SipHashContext} instance after initialization.
      */
-    public static SipHasherContainer container(byte[] key) {
-        return new SipHasherContainer(key);
+    public static SipHashContext context(byte[] key) {
+        return new SipHashContext(key);
     }
 
     /**
@@ -126,9 +126,9 @@ public static long hash(byte[] key, byte[] data, int c, int d) {
      * @param key
      *      the key to seed the hash with.
      * @return
-     *      a {@link SipHasherStream} instance to update and digest.
+     *      a {@link SipHashStream} instance to update and digest.
      */
-    public static SipHasherStream init(byte[] key) {
+    public static SipHashStream init(byte[] key) {
         return init(key, DEFAULT_C, DEFAULT_D);
     }
 
@@ -145,10 +145,10 @@ public static SipHasherStream init(byte[] key) {
      * @param d
      *      the number of D rounds of compression.
      * @return
-     *      a {@link SipHasherStream} instance to update and digest.
+     *      a {@link SipHashStream} instance to update and digest.
      */
-    public static SipHasherStream init(byte[] key, int c, int d) {
-        return new SipHasherStream(key, c, d);
+    public static SipHashStream init(byte[] key, int c, int d) {
+        return new SipHashStream(key, c, d);
     }
 
     /**
diff --git a/src/main/java/io/whitfin/siphash/SipHashContext.java b/src/main/java/io/whitfin/siphash/SipHashContext.java
@@ -1,6 +1,6 @@
 package io.whitfin.siphash;
 
-import static io.whitfin.siphash.SipHasher.*;
+import static io.whitfin.siphash.SipHash.*;
 
 /**
  * Small container of state to aid SipHash throughput.
@@ -9,7 +9,7 @@
  * hashes. As such, this avoids a small amount of overhead on each hash which
  * might prove useful in the case you have constant keys (hash tables, etc).
  */
-public final class SipHasherContainer {
+public final class SipHashContext {
 
     /**
      * The seeded value for the magic v0 number.
@@ -32,12 +32,12 @@ public final class SipHasherContainer {
     private final long v3;
 
     /**
-     * Initializes a container from a key seed.
+     * Initializes a context from a key seed.
      *
      * @param key
-     *      the key to use to seed this hash container.
+     *      the key to use to seed this hash context.
      */
-    SipHasherContainer(byte[] key) {
+    SipHashContext(byte[] key) {
         if (key.length != 16) {
             throw new IllegalArgumentException("Key must be exactly 16 bytes!");
         }
@@ -76,7 +76,7 @@ public long hash(byte[] data) {
      *      a long value as the output of the hash.
      */
     public long hash(byte[] data, int c, int d) {
-        return SipHasher.hash(
+        return SipHash.hash(
             c, d,
             this.v0,
             this.v1,
diff --git a/src/main/java/io/whitfin/siphash/SipHashStream.java b/src/main/java/io/whitfin/siphash/SipHashStream.java
@@ -1,6 +1,6 @@
 package io.whitfin.siphash;
 
-import static io.whitfin.siphash.SipHasher.*;
+import static io.whitfin.siphash.SipHash.*;
 
 /**
  * Streaming implementation of the SipHash algorithm.
@@ -14,7 +14,7 @@
  * no further allocations - so memory should prove similar to the non-streaming
  * implementation.
  */
-public final class SipHasherStream {
+public final class SipHashStream {
 
     /**
      * The specified rounds of C compression.
@@ -71,7 +71,7 @@ public final class SipHasherStream {
      * @param d
      *      the desired rounds of D compression.
      */
-    SipHasherStream(byte[] key, int c, int d) {
+    SipHashStream(byte[] key, int c, int d) {
         if (key.length != 16) {
             throw new IllegalArgumentException("Key must be exactly 16 bytes!");
         }
@@ -101,9 +101,9 @@ public final class SipHasherStream {
      * @param b
      *      the byte being added to the digest.
      * @return
-     *      the same {@link SipHasherStream} for chaining.
+     *      the same {@link SipHashStream} for chaining.
      */
-    public SipHasherStream update(byte b) {
+    public SipHashStream update(byte b) {
         this.len++;
         this.m |= (((long) b & 0xff) << (this.m_idx++ * 8));
         if (this.m_idx < 8) {
@@ -125,9 +125,9 @@ public SipHasherStream update(byte b) {
      * @param bytes
      *      the bytes being added to the digest.
      * @return
-     *      the same {@link SipHasherStream} for chaining.
+     *      the same {@link SipHashStream} for chaining.
      */
-    public SipHasherStream update(byte[] bytes) {
+    public SipHashStream update(byte[] bytes) {
         for (byte b : bytes) {
             update(b);
         }
diff --git a/src/test/java/io/whitfin/siphash/SipHashContextTest.java b/src/test/java/io/whitfin/siphash/SipHashContextTest.java
@@ -3,27 +3,27 @@
 import org.testng.annotations.Test;
 
 /**
- * Test cases for the {@link SipHasherContainer} class.
+ * Test cases for the {@link SipHashContext} class.
  */
-public class SipHasherContainerTest extends SipHasherTest {
+public class SipHashContextTest extends SipHashTest {
 
     /**
      * Tests invalid key exceptions are thrown.
      */
     @Test(expectedExceptions = IllegalArgumentException.class)
     public void testExceptionOnInvalidKey() {
-        SipHasher.container(new byte[0]).hash(new byte[0]);
+        SipHash.context(new byte[0]).hash(new byte[0]);
     }
 
     /**
-     * Tests all vectors using the container hash implementation.
+     * Tests all vectors using the context hash implementation.
      */
     @Test
     public void testVectorsForContainerHash() {
         testVectors(new Hasher() {
             @Override
             public long hash(byte[] key, byte[] data) {
-                return SipHasher.container(key).hash(data);
+                return SipHash.context(key).hash(data);
             }
         });
     }
diff --git a/src/test/java/io/whitfin/siphash/SipHashStreamTest.java b/src/test/java/io/whitfin/siphash/SipHashStreamTest.java
@@ -3,16 +3,16 @@
 import org.testng.annotations.Test;
 
 /**
- * Test cases for the {@link SipHasherStream} class.
+ * Test cases for the {@link SipHashStream} class.
  */
-public class SipHasherStreamTest extends SipHasherTest {
+public class SipHashStreamTest extends SipHashTest {
 
     /**
      * Tests invalid key exceptions are thrown.
      */
     @Test(expectedExceptions = IllegalArgumentException.class)
     public void testExceptionOnInvalidKey() {
-        SipHasher.init(new byte[0]);
+        SipHash.init(new byte[0]);
     }
 
     /**
@@ -23,7 +23,7 @@ public void testVectorsForStreamHash() {
         testVectors(new Hasher() {
             @Override
             public long hash(byte[] key, byte[] data) {
-                return SipHasher.init(key).update(data).digest();
+                return SipHash.init(key).update(data).digest();
             }
         });
     }
diff --git a/src/test/java/io/whitfin/siphash/SipHashTest.java b/src/test/java/io/whitfin/siphash/SipHashTest.java
@@ -4,12 +4,12 @@
 import org.testng.annotations.Test;
 
 /**
- * Test cases for the {@link SipHasher} class.
+ * Test cases for the {@link SipHash} class.
  *
  * This also contains reference methods which can be used by other
  * implementations in order to make sure of the same vector bootstrap.
  */
-public class SipHasherTest {
+public class SipHashTest {
 
     // test vectors via https://www.131002.net/siphash/siphash24.c
     private static final long[] EXPECTED = new long[] {
@@ -36,7 +36,7 @@ public class SipHasherTest {
      */
     @Test
     public void testConstructorUsage() {
-        new SipHasher();
+        new SipHash();
     }
 
     /**
@@ -47,7 +47,7 @@ public void testVectorsForZeroAllocHash() {
         testVectors(new Hasher() {
             @Override
             public long hash(byte[] key, byte[] data) {
-                return SipHasher.hash(key, data);
+                return SipHash.hash(key, data);
             }
         });
     }
@@ -63,8 +63,8 @@ public void testConversionToHexString() {
         long hash1 = -3891084581787974112L;
         long hash2 =    77813817455948350L;
 
-        String hex1 = SipHasher.toHexString(hash1);
-        String hex2 = SipHasher.toHexString(hash2);
+        String hex1 = SipHash.toHexString(hash1);
+        String hex2 = SipHash.toHexString(hash2);
 
         Assert.assertEquals(hex1, "ca0017304f874620");
         Assert.assertEquals(hex2, "011473413414323e");
@@ -75,7 +75,7 @@ public void testConversionToHexString() {
      */
     @Test(expectedExceptions = IllegalArgumentException.class)
     public void testExceptionOnInvalidKey() {
-        SipHasher.hash(new byte[0], new byte[0]);
+        SipHash.hash(new byte[0], new byte[0]);
     }
 
     /**
