Clarify writeFloat/readFloat behavior on Kotlin/JS

Addresses concerns described in #322
Kotlin · May 10, 2024 · f3556b6 · f3556b6
1 parent 601e5f1
commit f3556b6
Show file tree

Hide file tree

Showing 2 changed files with 16 additions and 0 deletions.
diff --git a/core/common/src/Sinks.kt b/core/common/src/Sinks.kt
@@ -285,6 +285,10 @@ public fun Sink.writeULongLe(long: ULong) {
  *
  * Should be used with care when working with special values (like `NaN`) as bit patterns obtained for [Float.NaN] may vary depending on a platform.
  *
+ * Note that in Kotlin/JS a value obtained by writing an original [Float] value to a [Sink] using
+ * [Sink.writeFloat] and then reading it back using [Source.readFloat] may not be equal to the original value.
+ * Please refer to [Float.toBits] documentation for details.
+ *
  * @param float the floating point number to be written.
  *
  * @throws IllegalStateException when the sink is closed.
@@ -321,6 +325,10 @@ public fun Sink.writeDouble(double: Double) {
  *
  * Should be used with care when working with special values (like `NaN`) as bit patterns obtained for [Float.NaN] may vary depending on a platform.
  *
+ * Note that in Kotlin/JS a value obtained by writing an original [Float] value to a [Sink] using
+ * [Sink.writeFloatLe] and then reading it back using [Source.readFloatLe] may not be equal to the original value.
+ * Please refer to [Float.toBits] documentation for details.
+ *
  * @param float the floating point number to be written.
  *
  * @throws IllegalStateException when the sink is closed.

diff --git a/core/common/src/Sources.kt b/core/common/src/Sources.kt
@@ -361,6 +361,10 @@ public fun Source.readULongLe(): ULong = readLongLe().toULong()
  *
  * The [Float.Companion.fromBits] function is used for decoding bytes into [Float].
  *
+ * Note that in Kotlin/JS a value obtained by writing an original [Float] value to a [Sink] using
+ * [Sink.writeFloat] and then reading it back using [Source.readFloat] may not be equal to the original value.
+ * Please refer to [Float.Companion.fromBits] documentation for details.
+ *
  * @throws EOFException when there are not enough data to read an unsigned int value.
  * @throws IllegalStateException when the source is closed.
  *
@@ -387,6 +391,10 @@ public fun Source.readDouble(): Double = Double.fromBits(readLong())
  *
  * The [Float.Companion.fromBits] function is used for decoding bytes into [Float].
  *
+ * Note that in Kotlin/JS a value obtained by writing an original [Float] value to a [Sink] using
+ * [Sink.writeFloatLe] and then reading it back using [Source.readFloatLe] may not be equal to the original value.
+ * Please refer to [Float.Companion.fromBits] documentation for details.
+ *
  * @throws EOFException when there are not enough data to read an unsigned int value.
  * @throws IllegalStateException when the source is closed.
  *