Skip to content

Commit 6ae839d

Browse files
JesusMcCloudJesusMcCloud
committed
finalize api
1 parent 8d49f2c commit 6ae839d

File tree

12 files changed

+190
-152
lines changed

12 files changed

+190
-152
lines changed

‎benchmark/src/jmh/kotlin/kotlinx/benchmarks/cbor/CborBaseLine.kt‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -52,7 +52,7 @@ open class CborBaseline {
5252
}
5353

5454
val baseBytes = cbor.encodeToByteArray(KTestOuterMessage.serializer(), baseMessage)
55-
val baseStruct = cbor.encodeToCbor(KTestOuterMessage.serializer(), baseMessage)
55+
val baseStruct = cbor.encodeToCborElement(KTestOuterMessage.serializer(), baseMessage)
5656

5757
@Benchmark
5858
fun toBytes() = cbor.encodeToByteArray(KTestOuterMessage.serializer(), baseMessage)
@@ -68,9 +68,9 @@ open class CborBaseline {
6868
fun structFromBytes() = cbor.decodeFromByteArray(CborElement.serializer(), baseBytes)
6969

7070
@Benchmark
71-
fun fromStruct() = cbor.decodeFromCbor(KTestOuterMessage.serializer(), baseStruct)
71+
fun fromStruct() = cbor.decodeFromCborElement(KTestOuterMessage.serializer(), baseStruct)
7272

7373
@Benchmark
74-
fun toStruct() = cbor.encodeToCbor(KTestOuterMessage.serializer(), baseMessage)
74+
fun toStruct() = cbor.encodeToCborElement(KTestOuterMessage.serializer(), baseMessage)
7575

7676
}

‎formats/cbor/commonMain/src/kotlinx/serialization/cbor/Cbor.kt‎

Lines changed: 30 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -89,25 +89,48 @@ public sealed class Cbor(
8989
return reader.decodeSerializableValue(deserializer)
9090
}
9191

92-
public fun <T> decodeFromCbor(deserializer: DeserializationStrategy<T>, element: CborElement): T {
92+
/**
93+
* Deserializes the given [element] into a value of type [T] using the given [deserializer].
94+
*
95+
* @throws [SerializationException] if the given CBOR element is not a valid CBOR input for the type [T]
96+
* @throws [IllegalArgumentException] if the decoded input cannot be represented as a valid instance of type [T]
97+
*/
98+
public fun <T> decodeFromCborElement(deserializer: DeserializationStrategy<T>, element: CborElement): T {
9399
val reader = CborReader(this, StructuredCborParser(element, configuration.verifyObjectTags))
94100
return reader.decodeSerializableValue(deserializer)
95101
}
96102

97-
public fun <T> encodeToCbor(serializer: SerializationStrategy<T>, value: T): CborElement {
103+
/**
104+
* Serializes the given [value] into an equivalent [CborElement] using the given [serializer]
105+
*
106+
* @throws [SerializationException] if the given value cannot be serialized to CBOR
107+
*/
108+
public fun <T> encodeToCborElement(serializer: SerializationStrategy<T>, value: T): CborElement {
98109
val writer = StructuredCborWriter(this)
99110
writer.encodeSerializableValue(serializer, value)
100111
return writer.finalize()
101112
}
102113
}
103-
114+
/**
115+
* Serializes the given [value] into an equivalent [CborElement] using a serializer retrieved
116+
* from reified type parameter.
117+
*
118+
* @throws [SerializationException] if the given value cannot be serialized to CBOR.
119+
*/
104120
@ExperimentalSerializationApi
105-
public inline fun <reified T> Cbor.encodeToCbor(value: T): CborElement =
106-
encodeToCbor(serializersModule.serializer(), value)
121+
public inline fun <reified T> Cbor.encodeToCborElement(value: T): CborElement =
122+
encodeToCborElement(serializersModule.serializer(), value)
107123

124+
/**
125+
* Deserializes the given [element] element into a value of type [T] using a deserializer retrieved
126+
* from reified type parameter.
127+
*
128+
* @throws [SerializationException] if the given JSON element is not a valid CBOR input for the type [T]
129+
* @throws [IllegalArgumentException] if the decoded input cannot be represented as a valid instance of type [T]
130+
*/
108131
@ExperimentalSerializationApi
109-
public inline fun <reified T> Cbor.decodeFromCbor(element: CborElement): T =
110-
decodeFromCbor(serializersModule.serializer(), element)
132+
public inline fun <reified T> Cbor.decodeFromCborElement(element: CborElement): T =
133+
decodeFromCborElement(serializersModule.serializer(), element)
111134

112135
@OptIn(ExperimentalSerializationApi::class)
113136
private class CborImpl(

‎formats/cbor/commonMain/src/kotlinx/serialization/cbor/CborElement.kt‎

Lines changed: 19 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ import kotlinx.serialization.cbor.internal.*
1616
*
1717
* [CborElement.toString] properly prints CBOR tree as a human-readable representation.
1818
* Whole hierarchy is serializable, but only when used with [Cbor] as [CborElement] is purely CBOR-specific structure
19-
* which has a meaningful schemaless semantics only for CBOR.
19+
* which has meaningful schemaless semantics only for CBOR.
2020
*
2121
* The whole hierarchy is [serializable][Serializable] only by [Cbor] format.
2222
*/
@@ -38,7 +38,7 @@ public sealed class CborElement(
3838
*/
3939
@OptIn(ExperimentalUnsignedTypes::class)
4040
public var tags: ULongArray = tags
41-
internal set
41+
internal set //need this to collect
4242

4343
override fun equals(other: Any?): Boolean {
4444
if (this === other) return true
@@ -89,18 +89,35 @@ public sealed class CborPrimitive<T : Any>(
8989
}
9090
}
9191

92+
/**
93+
* Class representing either:
94+
* * signed CBOR integer (major type 1)
95+
* * unsigned CBOR integer (major type 0)
96+
*
97+
* depending on whether a positive or a negative number was passed.
98+
*/
9299
@Serializable(with = CborIntSerializer::class)
93100
public sealed class CborInt<T : Any>(
94101
tags: ULongArray = ulongArrayOf(),
95102
value: T,
96103
) : CborPrimitive<T>(value, tags) {
97104
public companion object {
105+
/**
106+
* Creates:
107+
* * signed CBOR integer (major type 1)
108+
* * unsigned CBOR integer (major type 0)
109+
*
110+
* depending on whether a positive or a negative number was passed.
111+
*/
98112
public operator fun invoke(
99113
value: Long,
100114
vararg tags: ULong
101115
): CborInt<*> =
102116
if (value >= 0) CborPositiveInt(value.toULong(), tags = tags) else CborNegativeInt(value, tags = tags)
103117

118+
/**
119+
* Creates an unsigned CBOR integer (major type 0).
120+
*/
104121
public operator fun invoke(
105122
value: ULong,
106123
vararg tags: ULong

‎formats/cbor/commonTest/src/kotlinx/serialization/cbor/CborArrayTest.kt‎

Lines changed: 10 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,6 @@
11
package kotlinx.serialization.cbor
22

33
import kotlinx.serialization.*
4-
import kotlinx.serialization.cbor.CborIsoTest.DataClass
54
import kotlin.test.*
65

76

@@ -20,8 +19,8 @@ class CborArrayTest {
2019
assertEquals(referenceHexString, cbor.encodeToHexString(ClassAs1Array.serializer(), reference))
2120
assertEquals(reference, cbor.decodeFromHexString(ClassAs1Array.serializer(), referenceHexString))
2221

23-
val struct = cbor.encodeToCbor(ClassAs1Array.serializer(), reference)
24-
assertEquals(reference, cbor.decodeFromCbor(ClassAs1Array.serializer(), struct))
22+
val struct = cbor.encodeToCborElement(ClassAs1Array.serializer(), reference)
23+
assertEquals(reference, cbor.decodeFromCborElement(ClassAs1Array.serializer(), struct))
2524
assertEquals(referenceHexString, cbor.encodeToHexString(CborElement.serializer(), struct))
2625
}
2726

@@ -41,8 +40,8 @@ class CborArrayTest {
4140
assertEquals(referenceHexString, cbor.encodeToHexString(ClassAs2Array.serializer(), reference))
4241
assertEquals(reference, cbor.decodeFromHexString(ClassAs2Array.serializer(), referenceHexString))
4342

44-
val struct = cbor.encodeToCbor(ClassAs2Array.serializer(), reference)
45-
assertEquals(reference, cbor.decodeFromCbor(ClassAs2Array.serializer(), struct))
43+
val struct = cbor.encodeToCborElement(ClassAs2Array.serializer(), reference)
44+
assertEquals(reference, cbor.decodeFromCborElement(ClassAs2Array.serializer(), struct))
4645
assertEquals(referenceHexString, cbor.encodeToHexString(CborElement.serializer(), struct))
4746
}
4847

@@ -64,8 +63,8 @@ class CborArrayTest {
6463
assertEquals(referenceHexString, cbor.encodeToHexString(ClassAs4ArrayNullable.serializer(), reference))
6564
assertEquals(reference, cbor.decodeFromHexString(ClassAs4ArrayNullable.serializer(), referenceHexString))
6665

67-
val struct = cbor.encodeToCbor(ClassAs4ArrayNullable.serializer(), reference)
68-
assertEquals(reference, cbor.decodeFromCbor(ClassAs4ArrayNullable.serializer(), struct))
66+
val struct = cbor.encodeToCborElement(ClassAs4ArrayNullable.serializer(), reference)
67+
assertEquals(reference, cbor.decodeFromCborElement(ClassAs4ArrayNullable.serializer(), struct))
6968
assertEquals(referenceHexString, cbor.encodeToHexString(CborElement.serializer(), struct))
7069
}
7170

@@ -89,8 +88,8 @@ class CborArrayTest {
8988
assertEquals(reference, cbor.decodeFromHexString(ClassWithArray.serializer(), referenceHexString))
9089

9190

92-
val struct = cbor.encodeToCbor(ClassWithArray.serializer(), reference)
93-
assertEquals(reference, cbor.decodeFromCbor(ClassWithArray.serializer(), struct))
91+
val struct = cbor.encodeToCborElement(ClassWithArray.serializer(), reference)
92+
assertEquals(reference, cbor.decodeFromCborElement(ClassWithArray.serializer(), struct))
9493
assertEquals(referenceHexString, cbor.encodeToHexString(CborElement.serializer(), struct))
9594
}
9695

@@ -115,10 +114,10 @@ class CborArrayTest {
115114
assertEquals(referenceHexString, cbor.encodeToHexString(DoubleTaggedClassWithArray.serializer(), reference))
116115
assertEquals(reference, cbor.decodeFromHexString(DoubleTaggedClassWithArray.serializer(), referenceHexString))
117116

118-
val struct = cbor.encodeToCbor(DoubleTaggedClassWithArray.serializer(), reference)
117+
val struct = cbor.encodeToCborElement(DoubleTaggedClassWithArray.serializer(), reference)
119118
val structFromHex = cbor.decodeFromHexString(CborElement.serializer(), referenceHexString)
120119
assertEquals(structFromHex, struct)
121-
assertEquals(reference, cbor.decodeFromCbor(DoubleTaggedClassWithArray.serializer(), struct))
120+
assertEquals(reference, cbor.decodeFromCborElement(DoubleTaggedClassWithArray.serializer(), struct))
122121
assertEquals(referenceHexString, cbor.encodeToHexString(CborElement.serializer(), struct))
123122
}
124123

‎formats/cbor/commonTest/src/kotlinx/serialization/cbor/CborDecoderTest.kt‎

Lines changed: 19 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ class CborDecoderTest {
2222
assertEquals(reference, Cbor.decodeFromHexString(Simple.serializer(), hex))
2323

2424
val struct = Cbor.decodeFromHexString<CborElement>(hex)
25-
assertEquals(reference, Cbor.decodeFromCbor(Simple.serializer(), struct))
25+
assertEquals(reference, Cbor.decodeFromCborElement(Simple.serializer(), struct))
2626

2727
assertEquals(hex, Cbor.encodeToHexString(CborElement.serializer(), struct))
2828
}
@@ -52,8 +52,8 @@ class CborDecoderTest {
5252
)
5353

5454
val struct = Cbor.decodeFromHexString<CborElement>(hex)
55-
assertEquals(Cbor.encodeToCbor(test), struct)
56-
assertEquals(test, Cbor.decodeFromCbor(TypesUmbrella.serializer(), struct))
55+
assertEquals(Cbor.encodeToCborElement(test), struct)
56+
assertEquals(test, Cbor.decodeFromCborElement(TypesUmbrella.serializer(), struct))
5757

5858
assertEquals(hex, Cbor.encodeToHexString(TypesUmbrella.serializer(), test))
5959
assertEquals(hex, Cbor.encodeToHexString(CborElement.serializer(), struct))
@@ -71,8 +71,8 @@ class CborDecoderTest {
7171
)
7272

7373
val structDef = Cbor.decodeFromHexString<CborElement>(hexDef)
74-
assertEquals(Cbor.encodeToCbor(test), structDef)
75-
assertEquals(test, Cbor.decodeFromCbor(TypesUmbrella.serializer(), structDef))
74+
assertEquals(Cbor.encodeToCborElement(test), structDef)
75+
assertEquals(test, Cbor.decodeFromCborElement(TypesUmbrella.serializer(), structDef))
7676

7777
}
7878

@@ -95,7 +95,7 @@ class CborDecoderTest {
9595
)
9696

9797
val struct = Cbor.decodeFromHexString<CborElement>(hex)
98-
assertEquals(expected, Cbor.decodeFromCbor(NullableByteString.serializer(), struct))
98+
assertEquals(expected, Cbor.decodeFromCborElement(NullableByteString.serializer(), struct))
9999

100100
/* A1 # map(1)
101101
* 6A # text(10)
@@ -113,14 +113,14 @@ class CborDecoderTest {
113113
)
114114

115115
val structNull = Cbor.decodeFromHexString<CborElement>(hexNull)
116-
assertEquals(expectedNull, Cbor.decodeFromCbor(NullableByteString.serializer(), structNull))
116+
assertEquals(expectedNull, Cbor.decodeFromCborElement(NullableByteString.serializer(), structNull))
117117
}
118118

119119
@Test
120120
fun testNullables() {
121121
Cbor.decodeFromHexString<NullableByteStringDefaultNull>("a0")
122122
val struct = Cbor.decodeFromHexString<CborElement>("a0")
123-
assertEquals(NullableByteStringDefaultNull(), Cbor.decodeFromCbor(NullableByteStringDefaultNull.serializer(), struct))
123+
assertEquals(NullableByteStringDefaultNull(), Cbor.decodeFromCborElement(NullableByteStringDefaultNull.serializer(), struct))
124124
}
125125

126126
/**
@@ -142,7 +142,7 @@ class CborDecoderTest {
142142

143143
val struct = Cbor.decodeFromHexString<CborElement>(hex)
144144
assertFailsWithMessage<SerializationException>("Field 'a' is required") {
145-
ignoreUnknownKeys.decodeFromCbor(
145+
ignoreUnknownKeys.decodeFromCborElement(
146146
Simple.serializer(),
147147
struct
148148
)
@@ -160,7 +160,7 @@ class CborDecoderTest {
160160

161161
val structDef = Cbor.decodeFromHexString<CborElement>(hexDef)
162162
assertFailsWithMessage<SerializationException>("Field 'a' is required") {
163-
ignoreUnknownKeys.decodeFromCbor(
163+
ignoreUnknownKeys.decodeFromCborElement(
164164
Simple.serializer(),
165165
structDef
166166
)
@@ -269,7 +269,7 @@ class CborDecoderTest {
269269
)
270270
)
271271
val struct = Cbor.decodeFromHexString<CborElement>(hex)
272-
assertEquals(expected, ignoreUnknownKeys.decodeFromCbor(Simple.serializer(), struct))
272+
assertEquals(expected, ignoreUnknownKeys.decodeFromCborElement(Simple.serializer(), struct))
273273

274274
}
275275

@@ -313,7 +313,7 @@ class CborDecoderTest {
313313
)
314314

315315
val struct = Cbor.decodeFromHexString<CborElement>(hex)
316-
assertEquals(expected, ignoreUnknownKeys.decodeFromCbor(Simple.serializer(), struct))
316+
assertEquals(expected, ignoreUnknownKeys.decodeFromCborElement(Simple.serializer(), struct))
317317
}
318318

319319
/**
@@ -410,7 +410,7 @@ class CborDecoderTest {
410410
)
411411
)
412412
val struct = Cbor.decodeFromHexString<CborElement>(hex)
413-
assertEquals(expected, ignoreUnknownKeys.decodeFromCbor(SealedBox.serializer(), struct))
413+
assertEquals(expected, ignoreUnknownKeys.decodeFromCborElement(SealedBox.serializer(), struct))
414414

415415
}
416416

@@ -423,7 +423,7 @@ class CborDecoderTest {
423423
actual = Cbor.decodeFromHexString(hex)
424424
)
425425
val struct = Cbor.decodeFromHexString<CborElement>(hex)
426-
assertEquals(expected, Cbor.decodeFromCbor(TypeWithCustomByteString.serializer(), struct))
426+
assertEquals(expected, Cbor.decodeFromCborElement(TypeWithCustomByteString.serializer(), struct))
427427

428428
}
429429

@@ -436,7 +436,7 @@ class CborDecoderTest {
436436
actual = Cbor.decodeFromHexString(hex)
437437
)
438438
val struct = Cbor.decodeFromHexString<CborElement>(hex)
439-
assertEquals(expected, Cbor.decodeFromCbor(TypeWithNullableCustomByteString.serializer(), struct))
439+
assertEquals(expected, Cbor.decodeFromCborElement(TypeWithNullableCustomByteString.serializer(), struct))
440440

441441
}
442442

@@ -449,7 +449,7 @@ class CborDecoderTest {
449449
actual = Cbor.decodeFromHexString(hex)
450450
)
451451
val struct = Cbor.decodeFromHexString<CborElement>(hex)
452-
assertEquals(expected, Cbor.decodeFromCbor(TypeWithNullableCustomByteString.serializer(), struct))
452+
assertEquals(expected, Cbor.decodeFromCborElement(TypeWithNullableCustomByteString.serializer(), struct))
453453

454454
}
455455

@@ -462,7 +462,7 @@ class CborDecoderTest {
462462
actual = Cbor.decodeFromHexString<ValueClassWithByteString>(hex).x
463463
)
464464
val struct = Cbor.decodeFromHexString<CborElement>(hex)
465-
assertContentEquals(expected, Cbor.decodeFromCbor(ValueClassWithByteString.serializer(), struct).x)
465+
assertContentEquals(expected, Cbor.decodeFromCborElement(ValueClassWithByteString.serializer(), struct).x)
466466

467467
}
468468

@@ -475,7 +475,7 @@ class CborDecoderTest {
475475
actual = Cbor.decodeFromHexString(hex)
476476
)
477477
val struct = Cbor.decodeFromHexString<CborElement>(hex)
478-
assertEquals(expected, Cbor.decodeFromCbor(ValueClassWithCustomByteString.serializer(), struct))
478+
assertEquals(expected, Cbor.decodeFromCborElement(ValueClassWithCustomByteString.serializer(), struct))
479479

480480
}
481481

@@ -492,7 +492,7 @@ class CborDecoderTest {
492492
actual = Cbor.decodeFromHexString<ValueClassWithUnlabeledByteString>(hex).x.x
493493
)
494494
val struct = Cbor.decodeFromHexString<CborElement>(hex)
495-
assertContentEquals(expected, Cbor.decodeFromCbor(ValueClassWithUnlabeledByteString.serializer(), struct).x.x)
495+
assertContentEquals(expected, Cbor.decodeFromCborElement(ValueClassWithUnlabeledByteString.serializer(), struct).x.x)
496496

497497
}
498498

‎formats/cbor/commonTest/src/kotlinx/serialization/cbor/CborDefiniteLengthTest.kt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,7 @@ class CborDefiniteLengthTest {
3131
Cbor { useDefiniteLengthEncoding = true }.run {
3232
encodeToHexString(
3333
CborElement.serializer(),
34-
encodeToCbor(TypesUmbrella.serializer(), test)
34+
encodeToCborElement(TypesUmbrella.serializer(), test)
3535
)
3636
}
3737
)

0 commit comments

Comments
 (0)