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