0
# Built-in Types
1

2
Comprehensive built-in readers and writers for primitive types, collections, and common Scala types. These are automatically available when importing `upickle.default._`.
3

4
## Capabilities
5

6
### Primitive Type Readers
7

8
Built-in readers for all Scala primitive types with automatic type conversion support.
9

10
```scala { .api }
11
implicit val UnitReader: Reader[Unit]
12
implicit val BooleanReader: Reader[Boolean]  
13
implicit val StringReader: Reader[String]
14
implicit val CharReader: Reader[Char]
15
implicit val IntReader: Reader[Int]
16
implicit val LongReader: Reader[Long]
17
implicit val FloatReader: Reader[Float]
18
implicit val DoubleReader: Reader[Double]
19
implicit val ShortReader: Reader[Short] 
20
implicit val ByteReader: Reader[Byte]
21
```
22

23
**Usage Examples:**
24

25
```scala
26
import upickle.default._
27

28
// Automatic conversion from various JSON types
29
val str = read[String]("\"hello\"")           // From string
30
val strFromNum = read[String]("42")           // From number
31
val int = read[Int]("42")                     // From number  
32
val intFromStr = read[Int]("\"42\"")          // From string
33
val bool = read[Boolean]("true")             // From boolean
34
val boolFromStr = read[Boolean]("\"true\"")  // From string
35
```
36

37
### Primitive Type Writers  
38

39
Built-in writers for all Scala primitive types with JSON dictionary key support.
40

41
```scala { .api }
42
implicit val UnitWriter: Writer[Unit]
43
implicit val BooleanWriter: Writer[Boolean]
44
implicit val StringWriter: Writer[String]  
45
implicit val CharWriter: Writer[Char]
46
implicit val IntWriter: Writer[Int]
47
implicit val LongWriter: Writer[Long]
48
implicit val FloatWriter: Writer[Float]
49
implicit val DoubleWriter: Writer[Double]
50
implicit val ShortWriter: Writer[Short]
51
implicit val ByteWriter: Writer[Byte]
52
```
53

54
**Usage Examples:**
55

56
```scala
57
import upickle.default._
58

59
// All primitive writers support JSON dict keys
60
val intMap = Map(1 -> "one", 2 -> "two")
61
val json = write(intMap)
62
// Result: {"1": "one", "2": "two"}
63

64
val stringMap = Map("key" -> "value")  
65
val stringJson = write(stringMap)
66
// Result: {"key": "value"}
67
```
68

69
### Extended Type Readers
70

71
Readers for common extended types like UUID, BigInt, and Symbol.
72

73
```scala { .api }
74
implicit val UUIDReader: Reader[UUID]
75
implicit val BigIntReader: Reader[BigInt]
76
implicit val BigDecimalReader: Reader[BigDecimal]
77
implicit val SymbolReader: Reader[Symbol]
78
```
79

80
**Usage Examples:**
81

82
```scala
83
import upickle.default._
84
import java.util.UUID
85

86
// UUID from string
87
val uuid = read[UUID]("\"550e8400-e29b-41d4-a716-446655440000\"")
88

89
// BigInt from string  
90
val bigInt = read[BigInt]("\"12345678901234567890\"")
91

92
// BigDecimal from string
93
val bigDec = read[BigDecimal]("\"123.456789012345678901234567890\"")
94

95
// Symbol from string
96
val sym = read[Symbol]("\"mySymbol\"")
97
```
98

99
### Extended Type Writers
100

101
Writers for extended types with string-based JSON representation.
102

103
```scala { .api }
104
implicit val UUIDWriter: Writer[UUID]
105
implicit val BigIntWriter: Writer[BigInt] 
106
implicit val BigDecimalWriter: Writer[BigDecimal]
107
implicit val SymbolWriter: Writer[Symbol]
108
```
109

110
### Array Readers
111

112
Readers for arrays with special optimization for byte arrays.
113

114
```scala { .api }
115
/**
116
 * Reader for arrays with ClassTag for type erasure handling
117
 * Special case: byte arrays can be read from binary data
118
 */
119
implicit def ArrayReader[T: Reader: ClassTag]: Reader[Array[T]]
120
```
121

122
**Usage Examples:**
123

124
```scala
125
import upickle.default._
126

127
// Regular arrays
128
val intArray = read[Array[Int]]("[1,2,3,4,5]")
129
val stringArray = read[Array[String]]("""["a","b","c"]""")
130

131
// Byte arrays from JSON array
132
val byteArray = read[Array[Byte]]("[65,66,67]")  // "ABC"
133

134
// Byte arrays from binary data (MessagePack)
135
val binaryData: Array[Byte] = Array(1, 2, 3)
136
val fromBinary = readBinary[Array[Byte]](binaryData)
137
```
138

139
### Array Writers
140

141
Writers for arrays with binary optimization for byte arrays.
142

143
```scala { .api }
144
/**
145
 * Writer for arrays  
146
 * Special case: byte arrays are written as binary data in MessagePack
147
 */
148
implicit def ArrayWriter[T](implicit r: Writer[T]): Writer[Array[T]]
149
```
150

151
**Usage Examples:**
152

153
```scala
154
import upickle.default._
155

156
val intArray = Array(1, 2, 3, 4, 5)
157
val json = write(intArray)
158
// Result: [1,2,3,4,5]
159

160
// Byte arrays optimize to binary in MessagePack
161
val byteArray = Array[Byte](65, 66, 67)
162
val binary = writeBinary(byteArray)  // Efficient binary representation
163
val jsonFromBytes = write(byteArray) // JSON: [65,66,67]
164
```
165

166
### Collection Readers
167

168
Generic readers for all Scala collection types using Factory pattern.
169

170
```scala { .api }
171
/**
172
 * Generic reader for sequence-like collections
173
 */
174
implicit def SeqLikeReader[C[_], T](implicit r: Reader[T], factory: Factory[T, C[T]]): Reader[C[T]]
175

176
/**
177
 * Readers for specific collection types
178
 */
179
implicit def MapReader1[K: Reader, V: Reader]: Reader[collection.Map[K, V]]
180
implicit def MapReader2[K: Reader, V: Reader]: Reader[collection.immutable.Map[K, V]]  
181
implicit def MapReader3[K: Reader, V: Reader]: Reader[collection.mutable.Map[K, V]]
182
implicit def MapReader4[K: Reader, V: Reader]: Reader[collection.mutable.LinkedHashMap[K, V]]
183
implicit def SortedMapReader[K: Reader: Ordering, V: Reader]: Reader[collection.mutable.SortedMap[K, V]]
184
implicit def MapReader6[K: Reader: Ordering, V: Reader]: Reader[collection.immutable.SortedMap[K, V]]
185
```
186

187
**Usage Examples:**
188

189
```scala
190
import upickle.default._
191
import scala.collection.mutable
192

193
// Lists and sequences
194
val list = read[List[Int]]("[1,2,3,4,5]")
195
val vector = read[Vector[String]]("""["a","b","c"]""")
196
val set = read[Set[Int]]("[1,2,3,2,1]")  // Deduplicates to Set(1,2,3)
197

198
// Maps - can be from objects or arrays
199
val map1 = read[Map[String, Int]]("""{"a":1,"b":2}""")
200
val map2 = read[Map[String, Int]]("""[["a",1],["b",2]]""")
201

202
// Mutable collections
203
val mutableMap = read[mutable.Map[String, Int]]("""{"x":10,"y":20}""")
204
val linkedMap = read[mutable.LinkedHashMap[String, Int]]("""{"first":1,"second":2}""")
205
```
206

207
### Collection Writers
208

209
Generic writers for all Scala collection types.
210

211
```scala { .api }
212
/**
213
 * Writer for sequence-like collections  
214
 */
215
implicit def SeqLikeWriter[C[_] <: Iterable[_], T](implicit r: Writer[T]): Writer[C[T]]
216

217
/**
218
 * Writers for map types with key serialization support
219
 */
220
implicit def MapWriter1[K: Writer, V: Writer]: Writer[collection.Map[K, V]]
221
implicit def MapWriter2[K: Writer, V: Writer]: Writer[collection.immutable.Map[K, V]]
222
implicit def MapWriter3[K: Writer, V: Writer]: Writer[collection.mutable.Map[K, V]]
223
```
224

225
**Usage Examples:**
226

227
```scala
228
import upickle.default._
229

230
// Sequences serialize to JSON arrays
231
val list = List(1, 2, 3, 4, 5)
232
val listJson = write(list)  // [1,2,3,4,5]
233

234
// Maps serialize to objects when keys are string-compatible
235
val stringMap = Map("key1" -> "value1", "key2" -> "value2")  
236
val mapJson = write(stringMap)  // {"key1":"value1","key2":"value2"}
237

238
// Maps with non-string keys serialize to arrays
239
val intMap = Map(1 -> "one", 2 -> "two")
240
val intMapJson = write(intMap)  // [[1,"one"],[2,"two"]]
241
```
242

243
### Option Readers and Writers
244

245
Support for Option types with configurable null handling.
246

247
```scala { .api }
248
/**
249
 * Readers for Option types
250
 * Behavior depends on optionsAsNulls configuration
251
 */
252
implicit def OptionReader[T: Reader]: Reader[Option[T]]
253
implicit def SomeReader[T: Reader]: Reader[Some[T]]  
254
implicit def NoneReader: Reader[None.type]
255

256
/**
257
 * Writers for Option types
258
 */
259
implicit def OptionWriter[T: Writer]: Writer[Option[T]]
260
implicit def SomeWriter[T: Writer]: Writer[Some[T]]
261
implicit def NoneWriter: Writer[None.type]
262
```
263

264
**Usage Examples:**
265

266
```scala
267
import upickle.default._
268

269
// Options as arrays (default behavior)
270
val some = read[Option[Int]]("[42]")      // Some(42)  
271
val none = read[Option[Int]]("[]")        // None
272

273
// Options as nulls (when configured)
274
// val someAsNull = read[Option[Int]]("42")    // Some(42)
275
// val noneAsNull = read[Option[Int]]("null")  // None
276

277
// Writing options
278
val someValue: Option[Int] = Some(42)
279
val noneValue: Option[Int] = None
280

281
val someJson = write(someValue)  // [42]
282
val noneJson = write(noneValue)  // []
283
```
284

285
### Either Readers and Writers
286

287
Support for Either types with tuple-based serialization.
288

289
```scala { .api }
290
/**
291
 * Readers for Either types - serialized as [tag, value] tuples
292
 */
293
implicit def EitherReader[T1: Reader, T2: Reader]: SimpleReader[Either[T1, T2]]
294
implicit def RightReader[T1: Reader, T2: Reader]: Reader[Right[T1, T2]]
295
implicit def LeftReader[T1: Reader, T2: Reader]: Reader[Left[T1, T2]]
296

297
/**
298
 * Writers for Either types
299
 */
300
implicit def EitherWriter[T1: Writer, T2: Writer]: Writer[Either[T1, T2]]
301
implicit def RightWriter[T1: Writer, T2: Writer]: Writer[Right[T1, T2]]
302
implicit def LeftWriter[T1: Writer, T2: Writer]: Writer[Left[T1, T2]]
303
```
304

305
**Usage Examples:**
306

307
```scala
308
import upickle.default._
309

310
// Either serialization format: [tag, value]
311
val left: Either[String, Int] = Left("error")
312
val right: Either[String, Int] = Right(42)
313

314
val leftJson = write(left)   // [0, "error"]  
315
val rightJson = write(right) // [1, 42]
316

317
// Reading Either values
318
val parsedLeft = read[Either[String, Int]]("[0, \"error\"]")   // Left("error")
319
val parsedRight = read[Either[String, Int]]("[1, 42]")         // Right(42)
320
```
321

322
### Duration Readers and Writers
323

324
Support for Scala Duration types with string-based serialization.
325

326
```scala { .api }
327
implicit val DurationReader: Reader[Duration]
328
implicit val InfiniteDurationReader: Reader[Duration.Infinite] 
329
implicit val FiniteDurationReader: Reader[FiniteDuration]
330

331
implicit val DurationWriter: Writer[Duration]
332
implicit val InfiniteDurationWriter: Writer[Duration.Infinite]
333
implicit val FiniteDurationWriter: Writer[FiniteDuration]
334
```
335

336
**Usage Examples:**
337

338
```scala
339
import upickle.default._
340
import scala.concurrent.duration._
341

342
// Duration serialization
343
val duration = 5.seconds
344
val infinite = Duration.Inf
345
val minusInf = Duration.MinusInf
346
val undefined = Duration.Undefined
347

348
val durJson = write(duration)   // "5000000000" (nanoseconds) 
349
val infJson = write(infinite)   // "inf"
350
val minusJson = write(minusInf) // "-inf"
351
val undefJson = write(undefined) // "undef"
352

353
// Reading durations
354
val parsedDur = read[Duration]("\"5000000000\"")  // 5.seconds
355
val parsedInf = read[Duration]("\"inf\"")         // Duration.Inf
356
```
357

358
### Java Type Support
359

360
Readers and writers for Java boxed primitive types.
361

362
```scala { .api }
363
implicit val JavaBooleanReader: Reader[java.lang.Boolean]
364
implicit val JavaByteReader: Reader[java.lang.Byte]
365
implicit val JavaCharReader: Reader[java.lang.Character]
366
implicit val JavaShortReader: Reader[java.lang.Short]
367
implicit val JavaIntReader: Reader[java.lang.Integer]
368
implicit val JavaLongReader: Reader[java.lang.Long]
369
implicit val JavaFloatReader: Reader[java.lang.Float]  
370
implicit val JavaDoubleReader: Reader[java.lang.Double]
371

372
implicit val JavaBooleanWriter: Writer[java.lang.Boolean]
373
implicit val JavaByteWriter: Writer[java.lang.Byte]
374
implicit val JavaCharWriter: Writer[java.lang.Character]
375
implicit val JavaShortWriter: Writer[java.lang.Short]
376
implicit val JavaIntWriter: Writer[java.lang.Integer]
377
implicit val JavaLongWriter: Writer[java.lang.Long]
378
implicit val JavaFloatWriter: Writer[java.lang.Float]
379
implicit val JavaDoubleWriter: Writer[java.lang.Double]
380
```
381

382
**Usage Examples:**
383

384
```scala
385
import upickle.default._
386

387
// Java boxed types work seamlessly 
388
val javaInt: java.lang.Integer = 42
389
val javaStr = write(javaInt)  // "42"
390

391
val parsed: java.lang.Integer = read[java.lang.Integer]("42")
392
```
393

394
## Types
395

396
```scala { .api }
397
trait SimpleStringReader[T] extends SimpleReader[T] {
398
  def readString(s: CharSequence): T
399
}
400

401
trait SimpleMapKeyWriter[T] extends Writer[T] {
402
  override def isJsonDictKey: Boolean = true
403
  def writeString(v: T): String
404
}
405

406
trait OptionReader[T] extends Reader[Option[T]]
407
trait OptionWriter[T] extends Writer[Option[T]]
408

409
protected trait NumericReader[T] extends SimpleReader[T]
410
```