0
# Utility Functions
1

2
Utility methods for size estimation, error handling, dictionary creation, and accessing Zstd configuration constants. These functions support the main compression operations and provide essential information for proper library usage.
3

4
## Capabilities
5

6
### Size Estimation and Bounds
7

8
Calculate buffer sizes and estimate data sizes for compression operations.
9

10
```java { .api }
11
/**
12
 * Returns maximum possible size of compressed data
13
 * @param srcSize size of input data to be compressed
14
 * @return maximum compressed size (worst case scenario)
15
 */
16
public static long compressBound(long srcSize);
17

18
/**
19
 * Returns original size of compressed data (if stored in frame)
20
 * @param src compressed data
21
 * @return original uncompressed size, or 0 if unknown
22
 */
23
public static long decompressedSize(byte[] src);
24

25
/**
26
 * Returns original size of compressed data from direct ByteBuffer
27
 * @param src compressed data buffer
28
 * @param srcPosition position in buffer where compressed data starts
29
 * @param srcSize size of compressed data
30
 * @return original uncompressed size, or 0 if unknown
31
 */
32
public static long decompressedDirectByteBufferSize(ByteBuffer src, int srcPosition, int srcSize);
33

34
/**
35
 * Returns original size of compressed data from ByteBuffer
36
 * @param srcBuf compressed data buffer (position to limit defines data)
37
 * @return original uncompressed size, or 0 if unknown
38
 */
39
public static long decompressedSize(ByteBuffer srcBuf);
40
```
41

42
**Usage Examples:**
43

44
```java
45
import com.github.luben.zstd.Zstd;
46

47
// Calculate maximum compressed size for buffer allocation
48
byte[] data = "Some data to compress".getBytes();
49
long maxCompressedSize = Zstd.compressBound(data.length);
50
byte[] compressedBuffer = new byte[(int) maxCompressedSize];
51

52
// Compress and get actual size
53
long actualSize = Zstd.compress(compressedBuffer, data, 6);
54
if (Zstd.isError(actualSize)) {
55
    throw new RuntimeException("Compression failed");
56
}
57

58
// Get original size from compressed data (if available)
59
long originalSize = Zstd.decompressedSize(compressedBuffer);
60
if (originalSize > 0) {
61
    // Original size is known - can decompress without size parameter
62
    byte[] decompressed = Zstd.decompress(compressedBuffer, (int) originalSize);
63
} else {
64
    // Original size unknown - must track separately
65
    System.out.println("Original size not stored in compressed data");
66
}
67
```
68

69
### Error Handling
70

71
Check and interpret error codes returned by compression operations.
72

73
```java { .api }
74
/**
75
 * Checks if return code indicates an error
76
 * @param code return code from compression/decompression operations
77
 * @return true if code represents an error
78
 */
79
public static boolean isError(long code);
80

81
/**
82
 * Gets human-readable error message for error code
83
 * @param code error code from failed operation
84
 * @return descriptive error message
85
 */
86
public static String getErrorName(long code);
87
```
88

89
**Usage Examples:**
90

91
```java
92
// Safe compression with error checking
93
long result = Zstd.compress(dst, src, level);
94
if (Zstd.isError(result)) {
95
    String errorMsg = Zstd.getErrorName(result);
96
    throw new RuntimeException("Compression failed: " + errorMsg);
97
}
98

99
// Safe decompression with error checking
100
long decompResult = Zstd.decompress(dst, src);
101
if (Zstd.isError(decompResult)) {
102
    String errorMsg = Zstd.getErrorName(decompResult);
103
    throw new RuntimeException("Decompression failed: " + errorMsg);
104
}
105
```
106

107
### Dictionary Training
108

109
Create optimized dictionaries from sample data for improved compression ratios.
110

111
```java { .api }
112
/**
113
 * Creates a dictionary from sample data
114
 * @param samples array of sample byte arrays representing typical data
115
 * @param dictBuffer buffer to store the created dictionary (pre-allocated)
116
 * @return size of dictionary written to buffer, or error code if failed
117
 */
118
public static long trainFromBuffer(byte[][] samples, byte[] dictBuffer);
119
```
120

121
**Usage Examples:**
122

123
```java
124
import java.util.*;
125

126
// Collect representative sample data
127
List<String> logLines = Arrays.asList(
128
    "[2023-01-01 10:00:00] INFO: Application started",
129
    "[2023-01-01 10:00:01] DEBUG: Configuration loaded", 
130
    "[2023-01-01 10:00:02] INFO: Database connection established",
131
    "[2023-01-01 10:00:03] WARN: Cache miss for key user:123",
132
    "[2023-01-01 10:00:04] ERROR: Failed to process request"
133
);
134

135
// Convert to byte arrays
136
byte[][] samples = logLines.stream()
137
    .map(String::getBytes)
138
    .toArray(byte[][]::new);
139

140
// Create dictionary buffer (typically 1KB to 100KB)
141
byte[] dictBuffer = new byte[4096]; // 4KB dictionary
142

143
// Train dictionary
144
long dictSize = Zstd.trainFromBuffer(samples, dictBuffer);
145
if (Zstd.isError(dictSize)) {
146
    throw new RuntimeException("Dictionary training failed: " + Zstd.getErrorName(dictSize));
147
}
148

149
// Trim dictionary to actual size
150
byte[] dictionary = Arrays.copyOf(dictBuffer, (int) dictSize);
151

152
// Use dictionary for compression
153
byte[] logEntry = "[2023-01-01 10:00:05] INFO: New user registered".getBytes();
154
byte[] compressed = Zstd.compressUsingDict(logEntry, dictionary, 6);
155
```
156

157
### Zstd Configuration Constants
158

159
Access Zstd library constants for configuration and validation.
160

161
```java { .api }
162
/**
163
 * Gets Zstd magic number used in frame headers
164
 * @return magic number constant
165
 */
166
public static int magicNumber();
167

168
/**
169
 * Gets minimum window log size
170
 * @return minimum window log value
171
 */
172
public static int windowLogMin();
173

174
/**
175
 * Gets maximum window log size  
176
 * @return maximum window log value
177
 */
178
public static int windowLogMax();
179

180
/**
181
 * Gets minimum chain log size
182
 * @return minimum chain log value
183
 */
184
public static int chainLogMin();
185

186
/**
187
 * Gets maximum chain log size
188
 * @return maximum chain log value
189
 */
190
public static int chainLogMax();
191

192
/**
193
 * Gets minimum hash log size
194
 * @return minimum hash log value
195
 */
196
public static int hashLogMin();
197

198
/**
199
 * Gets maximum hash log size
200
 * @return maximum hash log value
201
 */
202
public static int hashLogMax();
203

204
/**
205
 * Gets minimum search log size
206
 * @return minimum search log value
207
 */
208
public static int searchLogMin();
209

210
/**
211
 * Gets maximum search log size
212
 * @return maximum search log value
213
 */
214
public static int searchLogMax();
215

216
/**
217
 * Gets minimum search length
218
 * @return minimum search length value
219
 */
220
public static int searchLengthMin();
221

222
/**
223
 * Gets maximum search length
224
 * @return maximum search length value
225
 */
226
public static int searchLengthMax();
227

228
/**
229
 * Gets minimum target length
230
 * @return minimum target length value
231
 */
232
public static int targetLengthMin();
233

234
/**
235
 * Gets maximum target length
236
 * @return maximum target length value
237
 */
238
public static int targetLengthMax();
239

240
/**
241
 * Gets minimum frame header size
242
 * @return minimum frame header size in bytes
243
 */
244
public static int frameHeaderSizeMin();
245

246
/**
247
 * Gets maximum frame header size
248
 * @return maximum frame header size in bytes
249
 */
250
public static int frameHeaderSizeMax();
251

252
/**
253
 * Gets maximum block size
254
 * @return maximum block size in bytes
255
 */
256
public static int blockSizeMax();
257
```
258

259
**Usage Examples:**
260

261
```java
262
// Validate compression parameters
263
int level = 15;
264
if (level < 1 || level > 22) {
265
    throw new IllegalArgumentException("Invalid compression level");
266
}
267

268
// Check frame format
269
byte[] data = ...; // Some compressed data
270
if (data.length >= 4) {
271
    int magic = Zstd.magicNumber();
272
    // Check if data starts with Zstd magic number (platform-dependent byte order)
273
    System.out.println("Zstd magic number: 0x" + Integer.toHexString(magic));
274
}
275

276
// Get configuration limits
277
System.out.println("Window log range: " + Zstd.windowLogMin() + " - " + Zstd.windowLogMax());
278
System.out.println("Maximum block size: " + Zstd.blockSizeMax() + " bytes");
279
System.out.println("Frame header size: " + Zstd.frameHeaderSizeMin() + " - " + Zstd.frameHeaderSizeMax() + " bytes");
280
```
281

282
## Common Usage Patterns
283

284
### Safe Compression with Error Handling
285

286
```java
287
public static byte[] safeCompress(byte[] data, int level) {
288
    // Calculate maximum possible size
289
    long maxSize = Zstd.compressBound(data.length);
290
    if (maxSize > Integer.MAX_VALUE) {
291
        throw new IllegalArgumentException("Data too large for compression");
292
    }
293
    
294
    // Allocate buffer and compress
295
    byte[] compressed = new byte[(int) maxSize];
296
    long actualSize = Zstd.compress(compressed, data, level);
297
    
298
    // Check for errors
299
    if (Zstd.isError(actualSize)) {
300
        throw new RuntimeException("Compression failed: " + Zstd.getErrorName(actualSize));
301
    }
302
    
303
    // Return trimmed array
304
    return Arrays.copyOf(compressed, (int) actualSize);
305
}
306
```
307

308
### Smart Decompression with Size Detection
309

310
```java
311
public static byte[] smartDecompress(byte[] compressed) {
312
    // Try to get original size from frame
313
    long originalSize = Zstd.decompressedSize(compressed);
314
    
315
    if (originalSize > 0) {
316
        // Size is known - decompress directly
317
        return Zstd.decompress(compressed, (int) originalSize);
318
    } else {
319
        // Size unknown - must be provided by caller or use stream API
320
        throw new IllegalArgumentException("Original size not available in compressed data");
321
    }
322
}
323
```
324

325
### Dictionary Training Workflow
326

327
```java
328
public static byte[] createOptimizedDictionary(List<byte[]> samples, int dictSize) {
329
    // Validate inputs
330
    if (samples.isEmpty()) {
331
        throw new IllegalArgumentException("No samples provided");
332
    }
333
    
334
    // Convert to array
335
    byte[][] sampleArray = samples.toArray(new byte[0][]);
336
    
337
    // Create dictionary buffer
338
    byte[] dictBuffer = new byte[dictSize];
339
    
340
    // Train dictionary
341
    long actualDictSize = Zstd.trainFromBuffer(sampleArray, dictBuffer);
342
    
343
    // Check for errors
344
    if (Zstd.isError(actualDictSize)) {
345
        throw new RuntimeException("Dictionary training failed: " + Zstd.getErrorName(actualDictSize));
346
    }
347
    
348
    // Return trimmed dictionary
349
    return Arrays.copyOf(dictBuffer, (int) actualDictSize);
350
}
351
```