0
# ByteString Operations
1

2
ByteString represents an immutable sequence of bytes with utilities for encoding, hashing, and manipulation. It's thread-safe and optimized for sharing across different parts of your application.
3

4
## Capabilities
5

6
### Creating ByteString
7

8
Create ByteString instances from various sources.
9

10
```kotlin { .api }
11
/**
12
 * Creates an empty ByteString
13
 */
14
val EMPTY: ByteString
15

16
/**
17
 * Creates a ByteString from individual bytes
18
 * @param data Variable number of bytes
19
 * @return ByteString containing the specified bytes
20
 */
21
fun of(vararg data: Byte): ByteString
22

23
/**
24
 * Encodes a String to ByteString using UTF-8
25
 * @return ByteString containing UTF-8 encoded bytes
26
 */
27
fun String.encodeUtf8(): ByteString
28

29
/**
30
 * Creates a ByteString from a byte array
31
 * @param offset Starting position in the array (default: 0)
32
 * @param byteCount Number of bytes to copy (default: entire array)
33
 * @return ByteString containing copied bytes
34
 */
35
fun ByteArray.toByteString(offset: Int = 0, byteCount: Int = size): ByteString
36

37
/**
38
 * Decodes a Base64 string to ByteString
39
 * @return ByteString containing decoded bytes, or null if invalid Base64
40
 */
41
fun String.decodeBase64(): ByteString?
42

43
/**
44
 * Decodes a hexadecimal string to ByteString
45
 * @return ByteString containing decoded bytes
46
 * @throws IllegalArgumentException if not valid hex
47
 */
48
fun String.decodeHex(): ByteString
49
```
50

51
**Usage Examples:**
52

53
```kotlin
54
// From String
55
val text = "Hello, World!".encodeUtf8()
56

57
// From bytes
58
val bytes = ByteString.of(72, 101, 108, 108, 111) // "Hello"
59

60
// From byte array
61
val array = byteArrayOf(1, 2, 3, 4, 5)
62
val byteString = array.toByteString()
63

64
// From Base64
65
val decoded = "SGVsbG8gV29ybGQ=".decodeBase64()
66

67
// From hexadecimal
68
val fromHex = "48656c6c6f".decodeHex() // "Hello"
69
```
70

71
### Basic Properties and Operations
72

73
Access ByteString size and individual bytes.
74

75
```kotlin { .api }
76
/**
77
 * Number of bytes in this ByteString
78
 */
79
abstract val size: Int
80

81
/**
82
 * Returns the byte at the specified index
83
 * @param index Position of the byte (0-based)
84
 * @return Byte at the specified position
85
 * @throws IndexOutOfBoundsException if index is out of range
86
 */
87
abstract operator fun get(index: Int): Byte
88

89
/**
90
 * Copies bytes to the destination array
91
 * @param offset Starting position in this ByteString
92
 * @param target Destination byte array
93
 * @param targetOffset Starting position in target array
94
 * @param byteCount Number of bytes to copy
95
 */
96
fun copyInto(
97
    offset: Int,
98
    target: ByteArray,
99
    targetOffset: Int,
100
    byteCount: Int
101
)
102

103
/**
104
 * Returns a copy of this ByteString as a byte array
105
 * @return New byte array containing all bytes
106
 */
107
abstract fun toByteArray(): ByteArray
108
```
109

110
**Usage Examples:**
111

112
```kotlin
113
val bytes = "Hello".encodeUtf8()
114
println(bytes.size) // 5
115
println(bytes[0]) // 72 (ASCII 'H')
116

117
val array = bytes.toByteArray()
118
val copy = ByteArray(3)
119
bytes.copyInto(1, copy, 0, 3) // Copy "ell" to copy array
120
```
121

122
### String Encoding and Decoding
123

124
Convert ByteString to various string representations.
125

126
```kotlin { .api }
127
/**
128
 * Decodes this ByteString as UTF-8
129
 * @return String representation of the UTF-8 bytes
130
 * @throws IllegalArgumentException if bytes are not valid UTF-8
131
 */
132
abstract fun utf8(): String
133

134
/**
135
 * Encodes this ByteString as Base64
136
 * @return Base64 string representation
137
 */
138
abstract fun base64(): String
139

140
/**
141
 * Encodes this ByteString as URL-safe Base64
142
 * @return URL-safe Base64 string representation
143
 */
144
abstract fun base64Url(): String
145

146
/**
147
 * Encodes this ByteString as hexadecimal
148
 * @return Hexadecimal string representation (lowercase)
149
 */
150
abstract fun hex(): String
151
```
152

153
**Usage Examples:**
154

155
```kotlin
156
val bytes = "Hello, World!".encodeUtf8()
157

158
println(bytes.utf8())      // "Hello, World!"
159
println(bytes.base64())    // "SGVsbG8sIFdvcmxkIQ=="
160
println(bytes.base64Url()) // "SGVsbG8sIFdvcmxkIQ=="
161
println(bytes.hex())       // "48656c6c6f2c20576f726c6421"
162
```
163

164
### Hash Functions
165

166
Compute cryptographic hashes of the ByteString content.
167

168
```kotlin { .api }
169
/**
170
 * Computes MD5 hash (deprecated, use sha256 instead)
171
 * @return ByteString containing MD5 hash
172
 */
173
abstract fun md5(): ByteString
174

175
/**
176
 * Computes SHA-1 hash (deprecated, use sha256 instead)
177
 * @return ByteString containing SHA-1 hash
178
 */
179
abstract fun sha1(): ByteString
180

181
/**
182
 * Computes SHA-256 hash
183
 * @return ByteString containing SHA-256 hash
184
 */
185
abstract fun sha256(): ByteString
186

187
/**
188
 * Computes SHA-512 hash
189
 * @return ByteString containing SHA-512 hash
190
 */
191
abstract fun sha512(): ByteString
192

193
/**
194
 * Computes HMAC-SHA1 with the given key (deprecated)
195
 * @param key Secret key for HMAC computation
196
 * @return ByteString containing HMAC-SHA1
197
 */
198
@Deprecated("Use hmacSha256 instead")
199
abstract fun hmacSha1(key: ByteString): ByteString
200

201
/**
202
 * Computes HMAC-SHA256 with the given key
203
 * @param key Secret key for HMAC computation
204
 * @return ByteString containing HMAC-SHA256
205
 */
206
abstract fun hmacSha256(key: ByteString): ByteString
207

208
/**
209
 * Computes HMAC-SHA512 with the given key  
210
 * @param key Secret key for HMAC computation
211
 * @return ByteString containing HMAC-SHA512
212
 */
213
abstract fun hmacSha512(key: ByteString): ByteString
214
```
215

216
**Usage Examples:**
217

218
```kotlin
219
val data = "Hello, World!".encodeUtf8()
220
val key = "secret-key".encodeUtf8()
221

222
val sha256Hash = data.sha256()
223
println(sha256Hash.hex())
224

225
val hmac = data.hmacSha256(key)
226
println(hmac.hex())
227
```
228

229
### String Manipulation
230

231
Perform case conversions and extract substrings.
232

233
```kotlin { .api }
234
/**
235
 * Returns a ByteString with ASCII characters converted to lowercase
236
 * @return New ByteString with lowercase ASCII characters
237
 */
238
abstract fun toAsciiLowercase(): ByteString
239

240
/**
241
 * Returns a ByteString with ASCII characters converted to uppercase
242
 * @return New ByteString with uppercase ASCII characters
243
 */
244
abstract fun toAsciiUppercase(): ByteString
245

246
/**
247
 * Returns a substring of this ByteString
248
 * @param beginIndex Starting index (inclusive)
249
 * @param endIndex Ending index (exclusive, default: size)
250
 * @return New ByteString containing the specified range
251
 */
252
fun substring(beginIndex: Int, endIndex: Int = size): ByteString
253
```
254

255
**Usage Examples:**
256

257
```kotlin
258
val text = "Hello, World!".encodeUtf8()
259

260
val lower = text.toAsciiLowercase()
261
println(lower.utf8()) // "hello, world!"
262

263
val upper = text.toAsciiUppercase()  
264
println(upper.utf8()) // "HELLO, WORLD!"
265

266
val hello = text.substring(0, 5)
267
println(hello.utf8()) // "Hello"
268
```
269

270
### Search and Comparison
271

272
Find bytes and compare ByteString instances.
273

274
```kotlin { .api }
275
/**
276
 * Finds the first occurrence of the specified ByteString
277
 * @param byteString ByteString to search for
278
 * @param fromIndex Starting search index (default: 0)
279
 * @return Index of first occurrence, or -1 if not found
280
 */
281
fun indexOf(byteString: ByteString, fromIndex: Int = 0): Int
282

283
/**
284
 * Finds the last occurrence of the specified ByteString  
285
 * @param byteString ByteString to search for
286
 * @return Index of last occurrence, or -1 if not found
287
 */
288
fun lastIndexOf(byteString: ByteString): Int
289

290
/**
291
 * Checks if this ByteString starts with the specified prefix
292
 * @param prefix ByteString to check for
293
 * @return true if this starts with prefix
294
 */
295
fun startsWith(prefix: ByteString): Boolean
296

297
/**
298
 * Checks if this ByteString ends with the specified suffix
299
 * @param suffix ByteString to check for  
300
 * @return true if this ends with suffix
301
 */
302
fun endsWith(suffix: ByteString): Boolean
303

304
/**
305
 * Compares a range of this ByteString with another ByteString
306
 * @param offset Starting position in this ByteString
307
 * @param other ByteString to compare with
308
 * @param otherOffset Starting position in other ByteString
309
 * @param byteCount Number of bytes to compare
310
 * @return true if the specified ranges are equal
311
 */
312
fun rangeEquals(
313
    offset: Int,
314
    other: ByteString,
315
    otherOffset: Int,
316
    byteCount: Int
317
): Boolean
318
```
319

320
**Usage Examples:**
321

322
```kotlin
323
val text = "Hello, World!".encodeUtf8()
324
val search = "World".encodeUtf8()
325

326
val index = text.indexOf(search)
327
println(index) // 7
328

329
val hasHello = text.startsWith("Hello".encodeUtf8())
330
println(hasHello) // true
331

332
val hasExclamation = text.endsWith("!".encodeUtf8())
333
println(hasExclamation) // true
334
```