0
# ByteString Extensions
1

2
Kotlin idiomatic extensions for ByteString operations including conversion from strings and byte arrays, concatenation, indexing, and utility functions.
3

4
## Capabilities
5

6
### String to ByteString Conversion
7

8
Converts a Kotlin String to a ByteString using UTF-8 encoding.
9

10
```kotlin { .api }
11
/**
12
 * Encodes this String into a sequence of UTF-8 bytes and returns the result as a ByteString
13
 * @return ByteString containing UTF-8 encoded bytes of this string
14
 */
15
fun String.toByteStringUtf8(): ByteString
16
```
17

18
**Usage Example:**
19

20
```kotlin
21
import com.google.protobuf.kotlin.toByteStringUtf8
22

23
val message = "Hello, World!"
24
val byteString = message.toByteStringUtf8()
25
// Equivalent to: ByteString.copyFromUtf8("Hello, World!")
26
```
27

28
### ByteString Concatenation
29

30
Concatenates two ByteStrings using the plus operator.
31

32
```kotlin { .api }
33
/**
34
 * Concatenates the given ByteString to this one
35
 * @param other the ByteString to concatenate
36
 * @return new ByteString containing both ByteStrings concatenated
37
 */
38
operator fun ByteString.plus(other: ByteString): ByteString
39
```
40

41
**Usage Example:**
42

43
```kotlin
44
import com.google.protobuf.kotlin.plus
45
import com.google.protobuf.kotlin.toByteStringUtf8
46

47
val first = "Hello".toByteStringUtf8()
48
val second = ", World!".toByteStringUtf8()
49
val combined = first + second
50
// Result contains "Hello, World!"
51
```
52

53
### ByteString Indexing
54

55
Gets the byte at a specific index using array-style indexing.
56

57
```kotlin { .api }
58
/**
59
 * Gets the byte at the specified index
60
 * @param index the index of the byte to retrieve
61
 * @return the byte at the specified index
62
 * @throws IndexOutOfBoundsException if index is out of bounds
63
 */
64
operator fun ByteString.get(index: Int): Byte
65
```
66

67
**Usage Example:**
68

69
```kotlin
70
import com.google.protobuf.kotlin.get
71
import com.google.protobuf.kotlin.toByteStringUtf8
72

73
val byteString = "abc".toByteStringUtf8()
74
val firstByte = byteString[0]  // 'a'.code (97)
75
val lastByte = byteString[2]   // 'c'.code (99)
76
```
77

78
### ByteString Non-Empty Check
79

80
Checks if a ByteString contains any data.
81

82
```kotlin { .api }
83
/**
84
 * Checks if this ByteString is not empty
85
 * @return true if this ByteString contains at least one byte, false if empty
86
 */
87
fun ByteString.isNotEmpty(): Boolean
88
```
89

90
**Usage Example:**
91

92
```kotlin
93
import com.google.protobuf.kotlin.isNotEmpty
94
import com.google.protobuf.kotlin.toByteStringUtf8
95
import com.google.protobuf.ByteString
96

97
val emptyString = ByteString.EMPTY
98
val nonEmptyString = "hello".toByteStringUtf8()
99

100
println(emptyString.isNotEmpty())    // false
101
println(nonEmptyString.isNotEmpty()) // true
102
```
103

104
### ByteArray to ByteString Conversion
105

106
Converts a ByteArray to an immutable ByteString.
107

108
```kotlin { .api }
109
/**
110
 * Returns a copy of this ByteArray as an immutable ByteString
111
 * @return ByteString containing a copy of this ByteArray's data
112
 */
113
fun ByteArray.toByteString(): ByteString
114
```
115

116
**Usage Example:**
117

118
```kotlin
119
import com.google.protobuf.kotlin.toByteString
120

121
val byteArray = byteArrayOf(0x48, 0x65, 0x6c, 0x6c, 0x6f) // "Hello"
122
val byteString = byteArray.toByteString()
123
// Equivalent to: ByteString.copyFrom(byteArray)
124
```
125

126
### ByteBuffer to ByteString Conversion
127

128
Copies the remaining bytes from a ByteBuffer to a ByteString.
129

130
```kotlin { .api }
131
/**
132
 * Copies the remaining bytes from this ByteBuffer to a ByteString
133
 * @return ByteString containing the remaining bytes from this ByteBuffer
134
 */
135
fun ByteBuffer.toByteString(): ByteString
136
```
137

138
**Usage Example:**
139

140
```kotlin
141
import com.google.protobuf.kotlin.toByteString
142
import java.nio.ByteBuffer
143

144
val buffer = ByteBuffer.allocate(10)
145
buffer.put("Hello".toByteArray())
146
buffer.flip() // Prepare for reading
147

148
val byteString = buffer.toByteString()
149
// ByteString contains "Hello"
150
```
151

152
## Common Usage Patterns
153

154
### Chaining Operations
155

156
```kotlin
157
import com.google.protobuf.kotlin.*
158

159
val result = "Hello"
160
    .toByteStringUtf8()
161
    .plus(", ".toByteStringUtf8())
162
    .plus("World!".toByteStringUtf8())
163

164
println(result.isNotEmpty()) // true
165
println(result[0])           // 'H'.code (72)
166
```
167

168
### Working with Binary Data
169

170
```kotlin
171
import com.google.protobuf.kotlin.*
172

173
// Create ByteString from binary data
174
val binaryData = byteArrayOf(0xFF.toByte(), 0xFE.toByte(), 0xFD.toByte())
175
val byteString = binaryData.toByteString()
176

177
// Inspect the data
178
if (byteString.isNotEmpty()) {
179
    val firstByte = byteString[0]
180
    println("First byte: 0x${firstByte.toUByte().toString(16)}")
181
}
182
```