1 /*
2 * Copyright 2017-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
3 */
4 @file:Suppress("DEPRECATION_ERROR", "FunctionName")
5
6 package kotlinx.serialization.builtins
7
8 import kotlinx.serialization.*
9 import kotlinx.serialization.internal.*
10 import kotlin.reflect.*
11 import kotlinx.serialization.descriptors.*
12 import kotlin.time.Duration
13 import kotlin.uuid.*
14
15 /**
16 * Returns a nullable serializer for the given serializer of non-null type.
17 */
18 @OptIn(ExperimentalSerializationApi::class)
19 public val <T : Any> KSerializer<T>.nullable: KSerializer<T?>
20 get() {
21 @Suppress("UNCHECKED_CAST")
22 return if (descriptor.isNullable) (this as KSerializer<T?>) else NullableSerializer(this)
23 }
24
25 /**
26 * Returns built-in serializer for Kotlin [Pair].
27 * Resulting serializer represents pair as a structure of two key-value pairs.
28 */
PairSerializernull29 public fun <K, V> PairSerializer(
30 keySerializer: KSerializer<K>,
31 valueSerializer: KSerializer<V>
32 ): KSerializer<Pair<K, V>> = kotlinx.serialization.internal.PairSerializer(keySerializer, valueSerializer)
33
34 /**
35 * Returns built-in serializer for [Map.Entry].
36 * Resulting serializer represents entry as a structure with a single key-value pair.
37 * E.g. `Pair(1, 2)` and `Map.Entry(1, 2)` will be serialized to JSON as
38 * `{"first": 1, "second": 2}` and `{"1": 2}` respectively.
39 */
40 public fun <K, V> MapEntrySerializer(
41 keySerializer: KSerializer<K>,
42 valueSerializer: KSerializer<V>
43 ): KSerializer<Map.Entry<K, V>> = kotlinx.serialization.internal.MapEntrySerializer(keySerializer, valueSerializer)
44
45 /**
46 * Returns built-in serializer for Kotlin [Triple].
47 * Resulting serializer represents triple as a structure of three key-value pairs.
48 */
49 public fun <A, B, C> TripleSerializer(
50 aSerializer: KSerializer<A>,
51 bSerializer: KSerializer<B>,
52 cSerializer: KSerializer<C>
53 ): KSerializer<Triple<A, B, C>> = kotlinx.serialization.internal.TripleSerializer(aSerializer, bSerializer, cSerializer)
54
55 /**
56 * Returns serializer for [Char] with [descriptor][SerialDescriptor] of [PrimitiveKind.CHAR] kind.
57 */
58 public fun Char.Companion.serializer(): KSerializer<Char> = CharSerializer
59
60 /**
61 * Returns serializer for [CharArray] with [descriptor][SerialDescriptor] of [StructureKind.LIST] kind.
62 * Each element of the array is serialized one by one with [Char.Companion.serializer].
63 */
64 @Suppress("UNCHECKED_CAST")
65 public fun CharArraySerializer(): KSerializer<CharArray> = CharArraySerializer
66
67 /**
68 * Returns serializer for [Byte] with [descriptor][SerialDescriptor] of [PrimitiveKind.BYTE] kind.
69 */
70 public fun Byte.Companion.serializer(): KSerializer<Byte> = ByteSerializer
71
72 /**
73 * Returns serializer for [ByteArray] with [descriptor][SerialDescriptor] of [StructureKind.LIST] kind.
74 * Each element of the array is serialized one by one with [Byte.Companion.serializer].
75 */
76 public fun ByteArraySerializer(): KSerializer<ByteArray> = ByteArraySerializer
77
78 /**
79 * Returns serializer for [UByteArray] with [descriptor][SerialDescriptor] of [StructureKind.LIST] kind.
80 * Each element of the array is serialized one by one with [UByte.Companion.serializer].
81 */
82 @ExperimentalSerializationApi
83 @ExperimentalUnsignedTypes
84 public fun UByteArraySerializer(): KSerializer<UByteArray> = UByteArraySerializer
85
86 /**
87 * Returns serializer for [Short] with [descriptor][SerialDescriptor] of [PrimitiveKind.SHORT] kind.
88 */
89 public fun Short.Companion.serializer(): KSerializer<Short> = ShortSerializer
90
91 /**
92 * Returns serializer for [ShortArray] with [descriptor][SerialDescriptor] of [StructureKind.LIST] kind.
93 * Each element of the array is serialized one by one with [Short.Companion.serializer].
94 */
95 public fun ShortArraySerializer(): KSerializer<ShortArray> = ShortArraySerializer
96
97 /**
98 * Returns serializer for [UShortArray] with [descriptor][SerialDescriptor] of [StructureKind.LIST] kind.
99 * Each element of the array is serialized one by one with [UShort.Companion.serializer].
100 */
101 @ExperimentalSerializationApi
102 @ExperimentalUnsignedTypes
103 public fun UShortArraySerializer(): KSerializer<UShortArray> = UShortArraySerializer
104
105 /**
106 * Returns serializer for [Int] with [descriptor][SerialDescriptor] of [PrimitiveKind.INT] kind.
107 */
108 public fun Int.Companion.serializer(): KSerializer<Int> = IntSerializer
109
110 /**
111 * Returns serializer for [IntArray] with [descriptor][SerialDescriptor] of [StructureKind.LIST] kind.
112 * Each element of the array is serialized one by one with [Int.Companion.serializer].
113 */
114 public fun IntArraySerializer(): KSerializer<IntArray> = IntArraySerializer
115
116 /**
117 * Returns serializer for [UIntArray] with [descriptor][SerialDescriptor] of [StructureKind.LIST] kind.
118 * Each element of the array is serialized one by one with [UInt.Companion.serializer].
119 */
120 @ExperimentalSerializationApi
121 @ExperimentalUnsignedTypes
122 public fun UIntArraySerializer(): KSerializer<UIntArray> = UIntArraySerializer
123
124 /**
125 * Returns serializer for [Long] with [descriptor][SerialDescriptor] of [PrimitiveKind.LONG] kind.
126 */
127 public fun Long.Companion.serializer(): KSerializer<Long> = LongSerializer
128
129 /**
130 * Returns serializer for [LongArray] with [descriptor][SerialDescriptor] of [StructureKind.LIST] kind.
131 * Each element of the array is serialized one by one with [Long.Companion.serializer].
132 */
133 public fun LongArraySerializer(): KSerializer<LongArray> = LongArraySerializer
134
135 /**
136 * Returns serializer for [ULongArray] with [descriptor][SerialDescriptor] of [StructureKind.LIST] kind.
137 * Each element of the array is serialized one by one with [ULong.Companion.serializer].
138 */
139 @ExperimentalSerializationApi
140 @ExperimentalUnsignedTypes
141 public fun ULongArraySerializer(): KSerializer<ULongArray> = ULongArraySerializer
142
143 /**
144 * Returns serializer for [Float] with [descriptor][SerialDescriptor] of [PrimitiveKind.FLOAT] kind.
145 */
146 public fun Float.Companion.serializer(): KSerializer<Float> = FloatSerializer
147
148 /**
149 * Returns serializer for [FloatArray] with [descriptor][SerialDescriptor] of [StructureKind.LIST] kind.
150 * Each element of the array is serialized one by one with [Float.Companion.serializer].
151 */
152 public fun FloatArraySerializer(): KSerializer<FloatArray> = FloatArraySerializer
153
154 /**
155 * Returns serializer for [Double] with [descriptor][SerialDescriptor] of [PrimitiveKind.DOUBLE] kind.
156 */
157 public fun Double.Companion.serializer(): KSerializer<Double> = DoubleSerializer
158
159 /**
160 * Returns serializer for [DoubleArray] with [descriptor][SerialDescriptor] of [StructureKind.LIST] kind.
161 * Each element of the array is serialized one by one with [Double.Companion.serializer].
162 */
163 public fun DoubleArraySerializer(): KSerializer<DoubleArray> = DoubleArraySerializer
164
165 /**
166 * Returns serializer for [Boolean] with [descriptor][SerialDescriptor] of [PrimitiveKind.BOOLEAN] kind.
167 */
168 public fun Boolean.Companion.serializer(): KSerializer<Boolean> = BooleanSerializer
169
170 /**
171 * Returns serializer for [BooleanArray] with [descriptor][SerialDescriptor] of [StructureKind.LIST] kind.
172 * Each element of the array is serialized one by one with [Boolean.Companion.serializer].
173 */
174 public fun BooleanArraySerializer(): KSerializer<BooleanArray> = BooleanArraySerializer
175
176 /**
177 * Returns serializer for [Unit] with [descriptor][SerialDescriptor] of [StructureKind.OBJECT] kind.
178 */
179 @Suppress("unused")
180 public fun Unit.serializer(): KSerializer<Unit> = UnitSerializer
181
182 /**
183 * Returns serializer for [String] with [descriptor][SerialDescriptor] of [PrimitiveKind.STRING] kind.
184 */
185 public fun String.Companion.serializer(): KSerializer<String> = StringSerializer
186
187 /**
188 * Returns serializer for reference [Array] of type [E] with [descriptor][SerialDescriptor] of [StructureKind.LIST] kind.
189 * Each element of the array is serialized with the given [elementSerializer].
190 */
191 @Suppress("UNCHECKED_CAST")
192 @ExperimentalSerializationApi
193 public inline fun <reified T : Any, reified E : T?> ArraySerializer(elementSerializer: KSerializer<E>): KSerializer<Array<E>> =
194 ArraySerializer<T, E>(T::class, elementSerializer)
195
196 /**
197 * Returns serializer for reference [Array] of type [E] with [descriptor][SerialDescriptor] of [StructureKind.LIST] kind.
198 * Each element of the array is serialized with the given [elementSerializer].
199 */
200 @ExperimentalSerializationApi
201 public fun <T : Any, E : T?> ArraySerializer(
202 kClass: KClass<T>,
203 elementSerializer: KSerializer<E>
204 ): KSerializer<Array<E>> = ReferenceArraySerializer<T, E>(kClass, elementSerializer)
205
206 /**
207 * Creates a serializer for [`List<T>`][List] for the given serializer of type [T].
208 */
209 public fun <T> ListSerializer(elementSerializer: KSerializer<T>): KSerializer<List<T>> =
210 ArrayListSerializer(elementSerializer)
211
212 /**
213 * Creates a serializer for [`Set<T>`][Set] for the given serializer of type [T].
214 */
215 public fun <T> SetSerializer(elementSerializer: KSerializer<T>): KSerializer<Set<T>> =
216 LinkedHashSetSerializer(elementSerializer)
217
218 /**
219 * Creates a serializer for [`Map<K, V>`][Map] for the given serializers for
220 * its key type [K] and value type [V].
221 */
222 public fun <K, V> MapSerializer(
223 keySerializer: KSerializer<K>,
224 valueSerializer: KSerializer<V>
225 ): KSerializer<Map<K, V>> = LinkedHashMapSerializer(keySerializer, valueSerializer)
226
227 /**
228 * Returns serializer for [UInt].
229 */
230 public fun UInt.Companion.serializer(): KSerializer<UInt> = UIntSerializer
231
232 /**
233 * Returns serializer for [ULong].
234 */
235 public fun ULong.Companion.serializer(): KSerializer<ULong> = ULongSerializer
236
237 /**
238 * Returns serializer for [UByte].
239 */
240 public fun UByte.Companion.serializer(): KSerializer<UByte> = UByteSerializer
241
242 /**
243 * Returns serializer for [UShort].
244 */
245 public fun UShort.Companion.serializer(): KSerializer<UShort> = UShortSerializer
246
247 /**
248 * Returns serializer for [Duration].
249 * It is serialized as a string that represents a duration in the ISO-8601-2 format.
250 *
251 * The result of serialization is similar to calling [Duration.toIsoString], for deserialization is [Duration.parseIsoString].
252 */
253 public fun Duration.Companion.serializer(): KSerializer<Duration> = DurationSerializer
254
255 /**
256 * Returns serializer for [Uuid].
257 * Serializer operates with a standard UUID string representation, also known as "hex-and-dash" format —
258 * [RFC 9562 section 4](https://www.rfc-editor.org/rfc/rfc9562.html#section-4).
259 *
260 * Serialization always produces lowercase string, deserialization is case-insensitive.
261 * More details can be found in the documentation of [Uuid.toString] and [Uuid.parse] functions.
262 *
263 * @see Uuid.toString
264 * @see Uuid.parse
265 */
266 @ExperimentalUuidApi
267 public fun Uuid.Companion.serializer(): KSerializer<Uuid> = UuidSerializer
268
269 /**
270 * Returns serializer for [Nothing].
271 * Throws an exception when trying to encode or decode.
272 *
273 * It is used as a dummy in case it is necessary to pass a type to a parameterized class. At the same time, it is expected that this generic type will not participate in serialization.
274 */
275 @ExperimentalSerializationApi
276 public fun NothingSerializer(): KSerializer<Nothing> = NothingSerializer
277