<commit_before># Runtime library contents and usage

* [Obtaining serializers](#obtaining-serializers)
  + [Implicit reflection serializers](#implicit-reflection-serializers)
  + [Special serializers](#special-serializers)
* [Serialization formats](#serialization-formats)
  + [JSON](#json)
  + [CBOR](#cbor)
  + [Protobuf](#protobuf)
* [Useful classes](#useful-classes)
  + [Mapper](#mapper)
  + [Dynamic object parser (JS only)](#dynamic-object-parser-js-only)


## Obtaining serializers

Serializers are represented at runtime as `KSerializer<T>`, which in turn, implements interfaces `SerializationStrategy<T>` and `DeserializationStrategy<T>`, where `T` is class you serialize.
You don't need to call them by yourself; you just have to pass them properly to serialization format. You can write them on your own (see [custom serializers](custom_serializers.md)) or let the compiler plugin do the dirty work by marking class `@Serializable`.
To retrieve the generated serializer, plugin emits special function on companion object called `.serializer()`.
If your class has generic type arguments, this function will have arguments for specifying serializers on type parameters, because it's impossible to serialize generic class statically in general case:

```kotlin
@Serializable
data class Data(val a: Int)

@Serializable
data class Box<T>(val boxed: T)

val dataSerial     : KSerializer<Data>      = Data.serializer()
val boxedDataSerial: KSerializer<Box<Data>> = Box.serializer(dataSerial)
```

Built-in types, like Int, and standard collections doesn't have that method. You can use corresponding serializers from `kotlinx.serialization.internal` package:

```kotlin
val i : KSerializer<Int>       = IntSerializer // object
val li: KSerializer<List<Int>> = ArrayListSerializer(IntSerializer) // generic, requires instantiation
```

For convenience, serializers have extension properties:

```kotlin
val li: KSerializer<List<Data>>       = Data.serializer().list
val mp: KSerializer<Map<String, Int>> = (StringSerializer to IntSerializer).map // extension on Pair of serializers
```

All external serializers (defined by user) are instantiated in a user-specific way. To learn how to write them, see [docs](custom_serializers.md).

### Implicit reflection serializers

In following special case:
* Class explicitly marked `@Serializable`
* Class does not have generic type arguments

You can obtain serializer from KClass instance: `val d: KSerializer<MyData> = MyData::class.serializer()`.
This approach is discouraged in general because it is implicit and uses reflection (and therefore not working on Kotlin/Native),
but may be useful shorthand in some cases.

Functions which uses this or similar functionality are annotated
with [experimental](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-experimental/index.html)
annotation `kotlinx.serialization.ImplicitReflectionSerializer`.
Consult [annotation documentation](https://github.com/kotlin/kotlinx.serialization/blob/master/runtime/common/src/main/kotlin/kotlinx/serialization/SerialImplicits.kt#L11)
to learn about restrictions of this approach.
To learn how to use experimental annotations, look at theirs [KEEP](https://github.com/Kotlin/KEEP/blob/master/proposals/experimental.md)
or use [this guide](https://kotlinlang.org/docs/reference/experimental.html#using-experimental-apis).

### Special serializers

There are two special serializers which are turned on using corresponding annotations:
`@Contextual` for `ContextSerializer` and `@Polymorphic` for `PolymorphicSerializer`.

The former allows to switch to the run-time resolving of serializers instead of compile-time.
This can be useful when you want to use some custom external serializer
or to define different serializers for different formats.
The latter allows polymorphic serialization and deserialization using runtime class information
and recorded name of a class. Consult theirs documentation for details.

Both use serial modules system, which is explained [here](custom_serializers.md#registering-and-context).

## Serialization formats

Runtime library provides three ready-to use formats: JSON, CBOR and ProtoBuf.

### JSON

JSON format represented by `Json` class from `kotlinx.serialization.json` package.
It is configurable via `JsonConfiguration` class, which has following parameters:

* encodeDefaults - set this to false to omit writing optional properties if they are equal to theirs default values.
* strictMode - Prohibits unknown keys when parsing JSON. Prohibits NaN and Infinity float values when serializing JSON. Enabled by default.
* unquoted - means that all field names and other objects (where it's possible) would not be wrapped in quotes. Useful for debugging.
* prettyPrint - classic pretty-printed multiline JSON.
* indent - size of indent, applicable if parameter above is true.
* useArrayPolymorphism – switches to writing polymorphic values in `[className, object]` format. Disabled by default.
* classDiscriminator – name of the class descriptor property in polymorphic serialization

It also has two pre-defined sets of parameters: `Default` and `Stable`.
`Default` provides recommended and sane configuration, however, due to a library evolution,
it can be tweaked and changed between library releases.
`Stable` provides backwards-compatible configuration, e.g. `useArrayPolymorphism` is set to `true` in it because early library versions have used this format.<commit_msg>Update runtime_usage.md<commit_after># Runtime library contents and usage

* [Obtaining serializers](#obtaining-serializers)
  + [Implicit reflection serializers](#implicit-reflection-serializers)
  + [Special serializers](#special-serializers)
* [Serialization formats](#serialization-formats)
  + [JSON](#json)
  + [CBOR](#cbor)
  + [Protobuf](#protobuf)
* [Useful classes](#useful-classes)
  + [Mapper](#mapper)
  + [Dynamic object parser (JS only)](#dynamic-object-parser-js-only)


## Obtaining serializers

Serializers are represented at runtime as `KSerializer<T>`, which in turn, implements interfaces `SerializationStrategy<T>` and `DeserializationStrategy<T>`, where `T` is class you serialize.
You don't need to call them by yourself; you just have to pass them properly to serialization format. You can write them on your own (see [custom serializers](custom_serializers.md)) or let the compiler plugin do the dirty work by marking class `@Serializable`.
To retrieve the generated serializer, plugin emits special function on companion object called `.serializer()`.
If your class has generic type arguments, this function will have arguments for specifying serializers on type parameters, because it's impossible to serialize generic class statically in general case:

```kotlin
@Serializable
data class Data(val a: Int)

@Serializable
data class Box<T>(val boxed: T)

val dataSerial     : KSerializer<Data>      = Data.serializer()
val boxedDataSerial: KSerializer<Box<Data>> = Box.serializer(dataSerial)
```

Built-in types, like Int, and standard collections doesn't have that method. You can use corresponding serializers from `kotlinx.serialization.internal` package:

```kotlin
val i : KSerializer<Int>       = IntSerializer // object
val li: KSerializer<List<Int>> = ArrayListSerializer(IntSerializer) // generic, requires instantiation
```

For convenience, serializers have extension properties:

```kotlin
val li: KSerializer<List<Data>>       = Data.serializer().list
val mp: KSerializer<Map<String, Int>> = (StringSerializer to IntSerializer).map // extension on Pair of serializers
```

All external serializers (defined by user) are instantiated in a user-specific way. To learn how to write them, see [docs](custom_serializers.md).

### Implicit reflection serializers

In following special case:
* Class explicitly marked `@Serializable`
* Class does not have generic type arguments

You can obtain serializer from KClass instance: `val d: KSerializer<MyData> = MyData::class.serializer()`.
This approach is discouraged in general because it is implicit and uses reflection (and therefore not working on Kotlin/Native),
but may be useful shorthand in some cases.

Functions which uses this or similar functionality are annotated
with [experimental](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-experimental/index.html)
annotation `kotlinx.serialization.ImplicitReflectionSerializer`.
Consult [annotation documentation](https://github.com/kotlin/kotlinx.serialization/blob/master/runtime/common/src/main/kotlin/kotlinx/serialization/SerialImplicits.kt#L11)
to learn about restrictions of this approach.
To learn how to use experimental annotations, look at theirs [KEEP](https://github.com/Kotlin/KEEP/blob/master/proposals/experimental.md)
or use [this guide](https://kotlinlang.org/docs/reference/experimental.html#using-experimental-apis).

### Special serializers

There are two special serializers which are turned on using corresponding annotations:
`@Contextual` for `ContextSerializer` and `@Polymorphic` for `PolymorphicSerializer`.

The former allows to switch to the run-time resolving of serializers instead of compile-time.
This can be useful when you want to use some custom external serializer
or to define different serializers for different formats.
The latter allows polymorphic serialization and deserialization using runtime class information
and recorded name of a class. Consult theirs documentation for details.

Both use serial modules system, which is explained [here](custom_serializers.md#registering-and-context).

## Serialization formats

Runtime library provides three ready-to use formats: JSON, CBOR and ProtoBuf.

### JSON

JSON format represented by `Json` class from `kotlinx.serialization.json` package.
It is configurable via `JsonConfiguration` class, which has following parameters:

* encodeDefaults - set this to false to omit writing optional properties if they are equal to theirs default values.
* strictMode - Prohibits unknown keys when parsing JSON. Prohibits NaN and Infinity float values when serializing JSON. Enabled by default.
* unquoted - means that all field names and other objects (where it's possible) would not be wrapped in quotes. Useful for debugging.
* prettyPrint - classic pretty-printed multiline JSON.
* indent - size of indent, applicable if parameter above is true.
* useArrayPolymorphism – switches to writing polymorphic values in `[className, object]` format. Disabled by default.
* classDiscriminator – name of the class descriptor property in polymorphic serialization

It also has two pre-defined sets of parameters: `Default` and `Stable`.
`Default` provides recommended and sane configuration, however, due to a library evolution,
it can be tweaked and changed between library releases.
`Stable` provides configuration which is guaranteed to be unchanged between library releases.
{'fraction_non_alphanumeric': 0.08069722401549387, 'fraction_numerical': 0.00036890159549940053, 'mean_word_length': 5.580097087378641, 'pattern_counts': {'":': 0, '<': 33, '<?xml version=': 0, '>': 33, 'https://': 8, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3670827', 'n_tokens_mistral': 2865, 'n_tokens_neox': 2702, 'n_words': 1178}