feat: bind ZSTD_getDictID_fromDict and add ZstdDictionaryId value type (#29)

Adds Zstd.dictId(byte[]) / Zstd.dictId(MemorySegment), the core-libzstd reader
for the dictionary id stamped in raw dictionary bytes — the counterpart to
ZstdFrame.dictId (which reads a frame) and the no-wrapper alternative to
ZstdDictionary.id() (which uses the equivalent ZDICT reader). Binds
ZSTD_getDictID_fromDict.

Introduces ZstdDictionaryId, a record wrapping the 32-bit id with an unsigned
value(), isPresent(), and a NONE sentinel for "no id" (0). Every dictionary-id
accessor now returns it instead of int: ZstdDictionary.id(),
ZstdCompressDict.id(), ZstdDecompressDict.id(), ZstdFrame.dictId(...), and the
ZstdFrameHeader.dictId() component. This makes the unsigned semantics and the
0-means-absent sentinel explicit at every call site.

docs/supported.md: ZSTD_getDictID_fromDict now bound (Dictionary 10 -> 11/23).
CHANGELOG Unreleased updated.

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: dfa1

CHANGELOG.md

@@ -15,6 +15,17 @@ git tags, which trigger publication to Maven Central.
   same prefix to decode. Binds `ZSTD_CCtx_refPrefix` / `ZSTD_DCtx_refPrefix`.
   Segment-only by design — heap callers that need a copy should use
   `loadDictionary` instead.
+- `Zstd.dictId(byte[])` / `Zstd.dictId(MemorySegment)` — read the dictionary id
+  stamped in raw dictionary bytes without wrapping them in a `ZstdDictionary`.
+  Binds `ZSTD_getDictID_fromDict`.
+- `ZstdDictionaryId` value type — a `record` wrapping the 32-bit dictionary id
+  with an unsigned `value()`, `isPresent()`, and the `NONE` sentinel for "no id".
+
+### Changed
+- Every dictionary-id accessor now returns `ZstdDictionaryId` instead of `int`:
+  `ZstdDictionary.id()`, `ZstdCompressDict.id()`, `ZstdDecompressDict.id()`,
+  `ZstdFrame.dictId(...)`, and `ZstdFrameHeader.dictId()`. The `0` sentinel is now
+  `ZstdDictionaryId.NONE`, and the id reads as unsigned via `value()`.
 
 ## [0.5]
 

docs/supported.md

@@ -29,7 +29,7 @@ rather than the deprecated `ZSTD_getDecompressedSize`.
 | Version | 2 / 2 | complete |
 | Errors | 4 / 4 | complete: name, typed `ZstdErrorCode`, and `description()` |
 | Reusable contexts | 6 / 8 | CCtx/DCtx create/free/compress/decompress |
-| Dictionary — simple | 10 / 23 | raw + digested (CDict/DDict) + dict-id queries; `_advanced`/`_byReference`/`Begin` variants not bound |
+| Dictionary — simple | 11 / 23 | raw + digested (CDict/DDict) + dict-id queries; `_advanced`/`_byReference`/`Begin` variants not bound |
 | Dictionary training (ZDICT) | 8 / 12 | trainFromBuffer, cover/fastCover optimizers, finalizeDictionary, getDictHeaderSize |
 | Streaming — compress | 3 / 22 | `ZstdOutputStream` (compressStream2 + buffer sizes) |
 | Streaming — decompress | 3 / 15 | `ZstdInputStream` (decompressStream + buffer sizes) |
@@ -141,7 +141,7 @@ sequence-producer hooks vs this library's frame-inspection and typed-error surfa
 | `ZSTD_createCCtx_advanced` | — | — |
 | `ZSTD_createDCtx_advanced` | — | — |
 
-### Dictionary — simple (10/23)
+### Dictionary — simple (11/23)
 
 | Symbol | Bound | zstd-jni |
 |---|:---:|:---:|
@@ -166,7 +166,7 @@ sequence-producer hooks vs this library's frame-inspection and typed-error surfa
 | `ZSTD_decompressBegin_usingDict` | — | — |
 | `ZSTD_getDictID_fromCDict` | ✅ | — |
 | `ZSTD_getDictID_fromDDict` | ✅ | — |
-| `ZSTD_getDictID_fromDict` | — | ✅ |
+| `ZSTD_getDictID_fromDict` | ✅ | ✅ |
 | `ZSTD_getDictID_fromFrame` | ✅ | ✅ |
 
 ### Dictionary training, ZDICT (8/12)

integration-tests/src/test/java/io/github/dfa1/zstd/it/GoldenCorpusTest.java

@@ -1,5 +1,6 @@
 package io.github.dfa1.zstd.it;
 
+import io.github.dfa1.zstd.ZstdDictionaryId;
 import io.github.dfa1.zstd.Zstd;
 import io.github.dfa1.zstd.ZstdCompressCtx;
 import io.github.dfa1.zstd.ZstdDecompressCtx;
@@ -250,11 +251,11 @@ void dictIdRidesWithFrame(Path file) {
             }
 
             // When
-            int frameDictId = ZstdFrame.dictId(frame);
+            ZstdDictionaryId frameDictId = ZstdFrame.dictId(frame);
 
             // Then
             assertThat(frameDictId).isEqualTo(dict.id());
-            assertThat(frameDictId).isNotZero();
+            assertThat(frameDictId).isNotEqualTo(ZstdDictionaryId.NONE);
         }
     }
 }

integration-tests/src/test/java/io/github/dfa1/zstd/it/ZstdInteropExtrasTest.java

@@ -1,6 +1,7 @@
 package io.github.dfa1.zstd.it;
 
 import com.github.luben.zstd.ZstdCompressCtx;
+import io.github.dfa1.zstd.ZstdDictionaryId;
 import io.github.dfa1.zstd.Zstd;
 import io.github.dfa1.zstd.ZstdDictionary;
 import io.github.dfa1.zstd.ZstdException;
@@ -219,11 +220,11 @@ void javaReadsDictIdFromJniDictFrame() {
             byte[] frame = com.github.luben.zstd.Zstd.compress(record(7), jniDict);
 
             // When
-            int dictId = ZstdFrame.dictId(frame);
+            ZstdDictionaryId dictId = ZstdFrame.dictId(frame);
 
             // Then
             assertThat(dictId).isEqualTo(dict.id());
-            assertThat(dictId).isNotZero();
+            assertThat(dictId).isNotEqualTo(ZstdDictionaryId.NONE);
         }
 
         private ZstdDictionary trainDict() {

zstd/src/main/java/io/github/dfa1/zstd/Bindings.java

@@ -170,6 +170,10 @@ final class Bindings {
     // unsigned ZSTD_getDictID_fromDDict(const ZSTD_DDict*)
     static final MethodHandle GET_DICT_ID_FROM_DDICT =
             NativeLibrary.lookup("ZSTD_getDictID_fromDDict", FunctionDescriptor.of(JAVA_INT, ADDRESS));
+    // unsigned ZSTD_getDictID_fromDict(const void* dict, size_t dictSize)
+    static final MethodHandle GET_DICT_ID_FROM_DICT =
+            NativeLibrary.lookup("ZSTD_getDictID_fromDict",
+                    FunctionDescriptor.of(JAVA_INT, ADDRESS, JAVA_LONG));
 
     // ZSTD_bounds { size_t error; int lowerBound; int upperBound; } — returned by value
     static final MemoryLayout BOUNDS_LAYOUT =

zstd/src/main/java/io/github/dfa1/zstd/Zstd.java

@@ -111,6 +111,42 @@ public static long decompressedSize(MemorySegment frame) {
         return size;
     }
 
+    /// Dictionary id stamped in raw dictionary `bytes`, read with the core
+    /// `libzstd` reader.
+    ///
+    /// This reads the id a *dictionary* records, not the id a frame references —
+    /// for the latter use [ZstdFrame#dictId(byte[])]. It returns the same value as
+    /// [ZstdDictionary#id()] (which uses the equivalent `ZDICT` reader); prefer this
+    /// when you only hold raw bytes and do not want to wrap them in a
+    /// [ZstdDictionary].
+    ///
+    /// @param bytes raw dictionary content
+    /// @return the dictionary id, or [ZstdDictionaryId#NONE] if `bytes` is not a standard zstd
+    ///         dictionary (for example a raw/content-only dictionary with no header)
+    public static ZstdDictionaryId dictId(byte[] bytes) {
+        try (Arena arena = Arena.ofConfined()) {
+            return dictId(copyIn(arena, bytes), bytes.length);
+        }
+    }
+
+    /// Dictionary id stamped in native dictionary `bytes`, read with no copy.
+    /// Otherwise identical to [#dictId(byte[])].
+    ///
+    /// @param bytes native dictionary content
+    /// @return the dictionary id, or [ZstdDictionaryId#NONE] if `bytes` is not a standard zstd dictionary
+    public static ZstdDictionaryId dictId(MemorySegment bytes) {
+        NativeCall.requireNative(bytes, "bytes");
+        return dictId(bytes, bytes.byteSize());
+    }
+
+    private static ZstdDictionaryId dictId(MemorySegment bytes, long size) {
+        try {
+            return ZstdDictionaryId.of((int) Bindings.GET_DICT_ID_FROM_DICT.invokeExact(bytes, size));
+        } catch (Throwable t) {
+            throw NativeCall.rethrow(t);
+        }
+    }
+
     /// Maximum compressed size for an input of `srcSize` bytes — the buffer
     /// size guaranteed to never overflow during compression.
     ///

zstd/src/main/java/io/github/dfa1/zstd/ZstdCompressDict.java

@@ -81,10 +81,10 @@ public int level() {
 
     /// The dictionary id stamped into frames compressed with this dictionary.
     ///
-    /// @return the dictionary id, or `0` for a content-only dictionary
-    public int id() {
+    /// @return the dictionary id, or [ZstdDictionaryId#NONE] for a content-only dictionary
+    public ZstdDictionaryId id() {
         try {
-            return (int) Bindings.GET_DICT_ID_FROM_CDICT.invokeExact(ptr());
+            return ZstdDictionaryId.of((int) Bindings.GET_DICT_ID_FROM_CDICT.invokeExact(ptr()));
         } catch (Throwable t) {
             throw NativeCall.rethrow(t);
         }

zstd/src/main/java/io/github/dfa1/zstd/ZstdDecompressDict.java

@@ -51,10 +51,10 @@ private static MemorySegment create(MemorySegment dict) {
 
     /// The dictionary id this dictionary decodes frames for.
     ///
-    /// @return the dictionary id, or `0` for a content-only dictionary
-    public int id() {
+    /// @return the dictionary id, or [ZstdDictionaryId#NONE] for a content-only dictionary
+    public ZstdDictionaryId id() {
         try {
-            return (int) Bindings.GET_DICT_ID_FROM_DDICT.invokeExact(ptr());
+            return ZstdDictionaryId.of((int) Bindings.GET_DICT_ID_FROM_DDICT.invokeExact(ptr()));
         } catch (Throwable t) {
             throw NativeCall.rethrow(t);
         }

zstd/src/main/java/io/github/dfa1/zstd/ZstdDictionary.java

@@ -253,13 +253,13 @@ private static ZstdDictionary toDictionary(MemorySegment dictBuf, long produced,
     }
 
     /// The dictionary id zstd stamps into frames compressed with this dictionary,
-    /// or `0` for a raw/content-only dictionary with no header.
+    /// or [ZstdDictionaryId#NONE] for a raw/content-only dictionary with no header.
     ///
-    /// @return the dictionary id, or `0` if none
-    public int id() {
+    /// @return the dictionary id, or [ZstdDictionaryId#NONE] if none
+    public ZstdDictionaryId id() {
         try (Arena arena = Arena.ofConfined()) {
             MemorySegment seg = Zstd.copyIn(arena, bytes);
-            return (int) Bindings.ZDICT_GET_DICT_ID.invokeExact(seg, (long) bytes.length);
+            return ZstdDictionaryId.of((int) Bindings.ZDICT_GET_DICT_ID.invokeExact(seg, (long) bytes.length));
         } catch (Throwable t) {
             throw NativeCall.rethrow(t);
         }

zstd/src/main/java/io/github/dfa1/zstd/ZstdDictionaryId.java

@@ -0,0 +1,41 @@
+package io.github.dfa1.zstd;
+
+/// A zstd dictionary id: the 32-bit value a dictionary stamps into the frames it
+/// compresses, letting a decompressor pick the matching dictionary.
+///
+/// zstd treats the id as a C `unsigned`, so the wire value can exceed
+/// [Integer#MAX_VALUE]. The raw 32-bit pattern is kept in [#raw()]; read it as an
+/// unsigned magnitude with [#value()]. The value `0` is the sentinel for "no
+/// dictionary id" — a raw/content-only dictionary, or a frame that records none —
+/// exposed as [#NONE] and tested with [#isPresent()].
+///
+/// @param raw the 32-bit id as zstd stores it, possibly negative when read as a
+///            signed `int`; `0` means no id
+public record ZstdDictionaryId(int raw) {
+
+    /// The absent id: no dictionary, or a dictionary with no recorded id.
+    public static final ZstdDictionaryId NONE = new ZstdDictionaryId(0);
+
+    /// Wraps a raw 32-bit id, returning [#NONE] for `0`.
+    ///
+    /// @param raw the 32-bit id as zstd stores it
+    /// @return the wrapped id, or [#NONE] if `raw` is `0`
+    public static ZstdDictionaryId of(int raw) {
+        return raw == 0 ? NONE : new ZstdDictionaryId(raw);
+    }
+
+    /// Whether an id is present (non-zero).
+    ///
+    /// @return `true` unless this is [#NONE]
+    public boolean isPresent() {
+        return raw != 0;
+    }
+
+    /// The id as an unsigned magnitude in `[0, 2^32)`, widening the raw 32-bit
+    /// pattern without sign extension.
+    ///
+    /// @return the unsigned id value
+    public long value() {
+        return Integer.toUnsignedLong(raw);
+    }
+}