0
# Static Compression and Decompression
1

2
Core compression and decompression functionality using static methods from the Zstd class. These methods provide direct, one-shot compression and decompression operations on byte arrays and ByteBuffers without requiring stream setup.
3

4
## Capabilities
5

6
### Basic Byte Array Compression
7

8
Compress byte arrays with automatic or specified compression levels.
9

10
```java { .api }
11
/**
12
 * Compresses data using default compression level (3)
13
 * @param src source data to compress
14
 * @return compressed data as byte array
15
 */
16
public static byte[] compress(byte[] src);
17

18
/**
19
 * Compresses data using specified compression level
20
 * @param src source data to compress
21
 * @param level compression level (1-22, higher = better compression)
22
 * @return compressed data as byte array
23
 */
24
public static byte[] compress(byte[] src, int level);
25

26
/**
27
 * Compresses source into destination buffer
28
 * @param dst destination buffer (must be sized using compressBound)
29
 * @param src source data to compress
30
 * @param level compression level (1-22)
31
 * @return number of bytes written to dst, or error code (check with isError)
32
 */
33
public static long compress(byte[] dst, byte[] src, int level);
34
```
35

36
**Usage Examples:**
37

38
```java
39
import com.github.luben.zstd.Zstd;
40

41
// Simple compression with default level
42
String text = "This is some text to compress";
43
byte[] data = text.getBytes();
44
byte[] compressed = Zstd.compress(data);
45

46
// Compression with specific level
47
byte[] compressedHigh = Zstd.compress(data, 19); // High compression
48
byte[] compressedFast = Zstd.compress(data, 1);  // Fast compression
49

50
// Pre-allocated destination buffer
51
long maxSize = Zstd.compressBound(data.length);
52
byte[] dst = new byte[(int) maxSize];
53
long actualSize = Zstd.compress(dst, data, 10);
54
if (Zstd.isError(actualSize)) {
55
    throw new RuntimeException("Compression failed: " + Zstd.getErrorName(actualSize));
56
}
57
```
58

59
### Basic Byte Array Decompression
60

61
Decompress byte arrays back to original data.
62

63
```java { .api }
64
/**
65
 * Decompresses data into new byte array
66
 * @param src compressed data
67
 * @param originalSize size of original uncompressed data
68
 * @return decompressed data as byte array
69
 */
70
public static byte[] decompress(byte[] src, int originalSize);
71

72
/**
73
 * Decompresses source into destination buffer
74
 * @param dst destination buffer (must be sized to original size)
75
 * @param src compressed data
76
 * @return number of bytes written to dst, or error code (check with isError)
77
 */
78
public static long decompress(byte[] dst, byte[] src);
79
```
80

81
**Usage Examples:**
82

83
```java
84
// Decompress with known original size
85
int originalSize = data.length; // Saved from before compression
86
byte[] decompressed = Zstd.decompress(compressed, originalSize);
87
String result = new String(decompressed);
88

89
// Decompress with pre-allocated buffer
90
byte[] dst = new byte[originalSize];
91
long actualSize = Zstd.decompress(dst, compressed);
92
if (Zstd.isError(actualSize)) {
93
    throw new RuntimeException("Decompression failed: " + Zstd.getErrorName(actualSize));
94
}
95
```
96

97
### ByteBuffer Compression
98

99
High-performance compression for direct ByteBuffers with minimal copying.
100

101
```java { .api }
102
/**
103
 * Compresses direct ByteBuffer into another direct ByteBuffer
104
 * @param dstBuf destination buffer (must be direct, position marks write start)
105
 * @param srcBuf source buffer (must be direct, position to limit defines data)
106
 * @param level compression level (1-22)
107
 * @return number of bytes written to destination
108
 */
109
public static int compress(ByteBuffer dstBuf, ByteBuffer srcBuf, int level);
110

111
/**
112
 * Compresses direct ByteBuffer and returns new ByteBuffer with result
113
 * @param srcBuf source buffer (must be direct, position to limit defines data)
114
 * @param level compression level (1-22)
115
 * @return new direct ByteBuffer containing compressed data
116
 */
117
public static ByteBuffer compress(ByteBuffer srcBuf, int level);
118

119
/**
120
 * Native direct buffer compression (low-level method)
121
 * @param dst destination buffer
122
 * @param dstOffset offset in destination
123
 * @param dstSize maximum bytes to write
124
 * @param src source buffer  
125
 * @param srcOffset offset in source
126
 * @param srcSize bytes to read from source
127
 * @param level compression level
128
 * @return bytes written or error code
129
 */
130
public static long compressDirectByteBuffer(ByteBuffer dst, int dstOffset, int dstSize, 
131
                                           ByteBuffer src, int srcOffset, int srcSize, int level);
132
```
133

134
**Usage Examples:**
135

136
```java
137
import java.nio.ByteBuffer;
138

139
// Compress direct ByteBuffers
140
ByteBuffer srcBuf = ByteBuffer.allocateDirect(1024);
141
srcBuf.put("Some data to compress".getBytes());
142
srcBuf.flip(); // Set position to 0, limit to data end
143

144
ByteBuffer dstBuf = ByteBuffer.allocateDirect((int) Zstd.compressBound(srcBuf.remaining()));
145
int compressedSize = Zstd.compress(dstBuf, srcBuf, 6);
146

147
// Or get new buffer with compressed data
148
ByteBuffer compressed = Zstd.compress(srcBuf, 6);
149
```
150

151
### ByteBuffer Decompression
152

153
High-performance decompression for direct ByteBuffers.
154

155
```java { .api }
156
/**
157
 * Decompresses direct ByteBuffer into another direct ByteBuffer
158
 * @param dstBuf destination buffer (must be direct, position marks write start)
159
 * @param srcBuf source buffer (must be direct, position to limit defines data)
160
 * @return number of bytes written to destination
161
 */
162
public static int decompress(ByteBuffer dstBuf, ByteBuffer srcBuf);
163

164
/**
165
 * Decompresses direct ByteBuffer and returns new ByteBuffer with result
166
 * @param srcBuf source buffer (must be direct, position to limit defines data)
167
 * @param originalSize size of original uncompressed data
168
 * @return new direct ByteBuffer containing decompressed data
169
 */
170
public static ByteBuffer decompress(ByteBuffer srcBuf, int originalSize);
171

172
/**
173
 * Native direct buffer decompression (low-level method)
174
 * @param dst destination buffer
175
 * @param dstOffset offset in destination
176
 * @param dstSize maximum bytes to write
177
 * @param src source buffer
178
 * @param srcOffset offset in source
179
 * @param srcSize bytes to read from source
180
 * @return bytes written or error code
181
 */
182
public static long decompressDirectByteBuffer(ByteBuffer dst, int dstOffset, int dstSize,
183
                                             ByteBuffer src, int srcOffset, int srcSize);
184
```
185

186
**Usage Examples:**
187

188
```java
189
// Decompress direct ByteBuffers
190
ByteBuffer dstBuf = ByteBuffer.allocateDirect(originalSize);
191
int decompressedSize = Zstd.decompress(dstBuf, compressed);
192

193
// Or get new buffer with decompressed data
194
ByteBuffer decompressed = Zstd.decompress(compressed, originalSize);
195
decompressed.flip(); // Prepare for reading
196
```
197

198
## Error Handling
199

200
All compression and decompression methods can return error codes. Always check for errors using the utility methods:
201

202
```java
203
long result = Zstd.compress(dst, src, level);
204
if (Zstd.isError(result)) {
205
    throw new RuntimeException("Compression failed: " + Zstd.getErrorName(result));
206
}
207
```
208

209
## Performance Considerations
210

211
- **ByteBuffer methods**: Use direct ByteBuffers for best performance with minimal copying
212
- **Pre-allocation**: Use `compressBound()` to pre-allocate destination buffers
213
- **Compression levels**: Level 1-3 for speed, 10+ for better compression ratios
214
- **Buffer reuse**: Reuse ByteBuffers when possible to reduce allocation overhead