0
# Built-in Type Support
1

2
Comprehensive serialization and deserialization support for Kotlin-specific types including unsigned numbers, sequences, and value classes.
3

4
## Capabilities
5

6
### Unsigned Number Types
7

8
Full serialization and deserialization support for Kotlin's unsigned integer types.
9

10
#### Unsigned Number Serializers
11

12
```kotlin { .api }
13
/**
14
 * Serializer for UByte values
15
 */
16
object UByteSerializer : StdSerializer<UByte>
17

18
/**
19
 * Serializer for UShort values  
20
 */
21
object UShortSerializer : StdSerializer<UShort>
22

23
/**
24
 * Serializer for UInt values
25
 */
26
object UIntSerializer : StdSerializer<UInt>
27

28
/**
29
 * Serializer for ULong values
30
 */
31
object ULongSerializer : StdSerializer<ULong>
32
```
33

34
#### Unsigned Number Deserializers
35

36
```kotlin { .api }
37
/**
38
 * Deserializer for UByte values
39
 */
40
object UByteDeserializer : StdDeserializer<UByte>
41

42
/**
43
 * Deserializer for UShort values
44
 */
45
object UShortDeserializer : StdDeserializer<UShort>
46

47
/**
48
 * Deserializer for UInt values
49
 */
50
object UIntDeserializer : StdDeserializer<UInt>
51

52
/**
53
 * Deserializer for ULong values
54
 */
55
object ULongDeserializer : StdDeserializer<ULong>
56
```
57

58
#### Unsigned Number Conversion Extensions
59

60
Safe conversion functions for unsigned number types.
61

62
```kotlin { .api }
63
/**
64
 * Convert Short to UByte safely
65
 * @return UByte value or null if out of range
66
 */
67
fun Short.asUByte(): UByte?
68

69
/**
70
 * Convert Int to UShort safely
71
 * @return UShort value or null if out of range
72
 */
73
fun Int.asUShort(): UShort?
74

75
/**
76
 * Convert Long to UInt safely
77
 * @return UInt value or null if out of range
78
 */
79
fun Long.asUInt(): UInt?
80

81
/**
82
 * Convert BigInteger to ULong safely
83
 * @return ULong value or null if out of range
84
 */
85
fun BigInteger.asULong(): ULong?
86
```
87

88
**Usage Examples:**
89

90
```kotlin
91
import com.fasterxml.jackson.module.kotlin.jacksonObjectMapper
92
import com.fasterxml.jackson.module.kotlin.readValue
93

94
data class UnsignedData(
95
    val smallNumber: UByte,
96
    val mediumNumber: UShort, 
97
    val largeNumber: UInt,
98
    val veryLargeNumber: ULong
99
)
100

101
val mapper = jacksonObjectMapper()
102

103
// Serialize unsigned numbers
104
val data = UnsignedData(
105
    smallNumber = 255u,
106
    mediumNumber = 65535u,
107
    largeNumber = 4294967295u,
108
    veryLargeNumber = 18446744073709551615u
109
)
110

111
val json = mapper.writeValueAsString(data)
112
println(json)
113
// Output: {"smallNumber":255,"mediumNumber":65535,"largeNumber":4294967295,"veryLargeNumber":18446744073709551615}
114

115
// Deserialize unsigned numbers
116
val deserialized = mapper.readValue<UnsignedData>(json)
117
println(deserialized)
118

119
// Safe conversion examples
120
val shortValue: Short = 200
121
val ubyteValue = shortValue.asUByte() // UByte(200)
122

123
val intValue: Int = 70000
124
val ushortValue = intValue.asUShort() // null (out of range)
125
```
126

127
### Kotlin Collection Types
128

129
Built-in support for Kotlin-specific collection types.
130

131
#### Sequence Deserializer
132

133
```kotlin { .api }
134
/**
135
 * Deserializer for Kotlin Sequence type
136
 * Converts JSON arrays to lazy Kotlin sequences
137
 */
138
object SequenceDeserializer : StdDeserializer<Sequence<*>>
139
```
140

141
**Usage Examples:**
142

143
```kotlin
144
import com.fasterxml.jackson.module.kotlin.jacksonObjectMapper
145
import com.fasterxml.jackson.module.kotlin.readValue
146

147
data class SequenceData(val numbers: Sequence<Int>)
148

149
val mapper = jacksonObjectMapper()
150

151
// JSON with array
152
val json = """{"numbers":[1,2,3,4,5]}"""
153

154
// Deserialize to Sequence
155
val data = mapper.readValue<SequenceData>(json)
156

157
// Use sequence (lazy evaluation)
158
val evenNumbers = data.numbers
159
    .filter { it % 2 == 0 }
160
    .map { it * 2 }
161
    .toList()
162

163
println(evenNumbers) // [4, 8]
164
```
165

166
### Regex Support
167

168
Built-in serialization and deserialization for Kotlin's Regex class.
169

170
#### Regex Deserializer
171

172
```kotlin { .api }
173
/**
174
 * Deserializer for Kotlin Regex type
175
 * Converts JSON strings to Regex instances
176
 */
177
object RegexDeserializer : StdDeserializer<Regex>
178
```
179

180
**Usage Examples:**
181

182
```kotlin
183
import com.fasterxml.jackson.module.kotlin.jacksonObjectMapper
184
import com.fasterxml.jackson.module.kotlin.readValue
185

186
data class ValidationRules(
187
    val emailPattern: Regex,
188
    val phonePattern: Regex
189
)
190

191
val mapper = jacksonObjectMapper()
192

193
// JSON with regex patterns
194
val json = """
195
{
196
    "emailPattern": "[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}",
197
    "phonePattern": "\\d{3}-\\d{3}-\\d{4}"
198
}
199
""".trimIndent()
200

201
// Deserialize to Regex objects
202
val rules = mapper.readValue<ValidationRules>(json)
203

204
// Use regex patterns
205
val email = "test@example.com"
206
val isValidEmail = rules.emailPattern.matches(email)
207
println("Email valid: $isValidEmail") // true
208

209
val phone = "123-456-7890"
210
val isValidPhone = rules.phonePattern.matches(phone)
211
println("Phone valid: $isValidPhone") // true
212
```
213

214
### Value Class Support
215

216
Support for Kotlin value classes (inline classes) with automatic boxing/unboxing.
217

218
#### Value Class Serializer
219

220
```kotlin { .api }
221
/**
222
 * Serializer for Kotlin value classes
223
 * Automatically unboxes value classes during serialization
224
 */
225
object ValueClassUnboxSerializer : StdSerializer<Any>
226
```
227

228
**Usage Examples:**
229

230
```kotlin
231
import com.fasterxml.jackson.module.kotlin.jacksonObjectMapper
232
import com.fasterxml.jackson.module.kotlin.readValue
233

234
// Define value classes
235
@JvmInline
236
value class UserId(val value: Long)
237

238
@JvmInline
239
value class Email(val value: String)
240

241
data class User(
242
    val id: UserId,
243
    val email: Email,
244
    val name: String
245
)
246

247
val mapper = jacksonObjectMapper()
248

249
// Serialize with value class unboxing
250
val user = User(
251
    id = UserId(12345L),
252
    email = Email("alice@example.com"),
253
    name = "Alice"
254
)
255

256
val json = mapper.writeValueAsString(user)
257
println(json)
258
// Output: {"id":12345,"email":"alice@example.com","name":"Alice"}
259

260
// Deserialize with value class boxing
261
val deserializedUser = mapper.readValue<User>(json)
262
println(deserializedUser.id.value) // 12345
263
println(deserializedUser.email.value) // alice@example.com
264
```
265

266
### SimpleModule Extensions
267

268
Type-safe extensions for adding custom serializers and deserializers.
269

270
```kotlin { .api }
271
/**
272
 * Add serializer for Kotlin class
273
 * @param kClass Kotlin class to serialize
274
 * @param serializer JsonSerializer for the class
275
 * @return SimpleModule for method chaining
276
 */
277
fun <T : Any> SimpleModule.addSerializer(kClass: KClass<T>, serializer: JsonSerializer<T>): SimpleModule
278

279
/**
280
 * Add deserializer for Kotlin class
281
 * @param kClass Kotlin class to deserialize
282
 * @param deserializer JsonDeserializer for the class
283
 * @return SimpleModule for method chaining
284
 */
285
fun <T : Any> SimpleModule.addDeserializer(kClass: KClass<T>, deserializer: JsonDeserializer<T>): SimpleModule
286
```
287

288
**Usage Examples:**
289

290
```kotlin
291
import com.fasterxml.jackson.core.JsonGenerator
292
import com.fasterxml.jackson.core.JsonParser
293
import com.fasterxml.jackson.databind.*
294
import com.fasterxml.jackson.databind.module.SimpleModule
295
import com.fasterxml.jackson.module.kotlin.addSerializer
296
import com.fasterxml.jackson.module.kotlin.addDeserializer
297
import kotlin.reflect.KClass
298

299
// Custom type
300
data class CustomId(val prefix: String, val number: Int) {
301
    override fun toString() = "$prefix-$number"
302
}
303

304
// Custom serializer
305
class CustomIdSerializer : JsonSerializer<CustomId>() {
306
    override fun serialize(value: CustomId, gen: JsonGenerator, serializers: SerializerProvider) {
307
        gen.writeString(value.toString())
308
    }
309
}
310

311
// Custom deserializer
312
class CustomIdDeserializer : JsonDeserializer<CustomId>() {
313
    override fun deserialize(p: JsonParser, ctxt: DeserializationContext): CustomId {
314
        val text = p.text
315
        val parts = text.split("-")
316
        return CustomId(parts[0], parts[1].toInt())
317
    }
318
}
319

320
// Register with module
321
val module = SimpleModule()
322
    .addSerializer(CustomId::class, CustomIdSerializer())
323
    .addDeserializer(CustomId::class, CustomIdDeserializer())
324

325
val mapper = jacksonObjectMapper().registerModule(module)
326

327
// Test custom serialization
328
val customId = CustomId("USER", 123)
329
val json = mapper.writeValueAsString(customId)
330
println(json) // "USER-123"
331

332
val deserialized = mapper.readValue<CustomId>(json)
333
println(deserialized) // CustomId(prefix=USER, number=123)
334
```
335

336
### Kotlin Range Support
337

338
Built-in support for Kotlin range types.
339

340
**Supported Range Types:**
341
- `IntRange` - serialized with `start` and `end` properties
342
- `LongRange` - serialized with `start` and `end` properties  
343
- `CharRange` - serialized with `start` and `end` properties
344

345
**Usage Examples:**
346

347
```kotlin
348
import com.fasterxml.jackson.module.kotlin.jacksonObjectMapper
349
import com.fasterxml.jackson.module.kotlin.readValue
350

351
data class RangeData(
352
    val intRange: IntRange,
353
    val longRange: LongRange,
354
    val charRange: CharRange
355
)
356

357
val mapper = jacksonObjectMapper()
358

359
val data = RangeData(
360
    intRange = 1..10,
361
    longRange = 100L..200L,
362
    charRange = 'A'..'Z'
363
)
364

365
val json = mapper.writeValueAsString(data)
366
println(json)
367
// Output: {"intRange":{"start":1,"end":10},"longRange":{"start":100,"end":200},"charRange":{"start":"A","end":"Z"}}
368

369
val deserialized = mapper.readValue<RangeData>(json)
370
println(deserialized.intRange.toList()) // [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
371
```
372

373
### Built-in Kotlin Types
374

375
The module automatically supports these Kotlin built-in types:
376

377
- **Pair** - serialized as `{"first": value1, "second": value2}`
378
- **Triple** - serialized as `{"first": value1, "second": value2, "third": value3}`
379
- **kotlin.time.Duration** - with JavaTimeModule integration when `UseJavaDurationConversion` is enabled
380

381
**Usage Examples:**
382

383
```kotlin
384
data class TupleData(
385
    val coordinates: Pair<Double, Double>,
386
    val rgb: Triple<Int, Int, Int>
387
)
388

389
val mapper = jacksonObjectMapper()
390

391
val data = TupleData(
392
    coordinates = 40.7128 to -74.0060,  // New York coordinates
393
    rgb = Triple(255, 128, 0)  // Orange color
394
)
395

396
val json = mapper.writeValueAsString(data)
397
val deserialized = mapper.readValue<TupleData>(json)
398
```