From 83a7c395edc280503079d77e0e6f70c58161c42f Mon Sep 17 00:00:00 2001
From: alfredo-toledano <alfredo.toledano@allianzdirect.es>
Date: Mon, 26 Aug 2024 00:08:11 +0200
Subject: [PATCH] doc(docs.topics.numbers): add notes and examples

---
 docs/topics/numbers.kt | 15 ++++++++++++
 docs/topics/numbers.md | 53 ++++++++++++------------------------------
 2 files changed, 30 insertions(+), 38 deletions(-)

diff --git a/docs/topics/numbers.kt b/docs/topics/numbers.kt
index a0606b43d36..cc9978b47a0 100644
--- a/docs/topics/numbers.kt
+++ b/docs/topics/numbers.kt
@@ -63,4 +63,19 @@ fun main() {
     val boxedA: Int? = a
     val anotherBoxedA: Int? = a
     println(boxedA === anotherBoxedA) // true
+
+    // 5. Explicit number conversions
+    // 5.1 smaller types != subtypes of bigger types -> NO implicit conversion
+    val intNumber: Int? = 1     // boxed Int (java.lang.Integer) | JVM
+    //val longNumber: Long? = intNumber    // NOT implicit conversion -> boxed Long (java.lang.Long) | JVM
+    val anotherLongNumber = intNumber?.toLong()     // IMPLICIT conversion
+    println("intNumber::class.simpleName ${intNumber!!::class.simpleName}")
+    println("anotherLongNumber::class.simpleName ${anotherLongNumber!!::class.simpleName}")
+    // 5.2 smaller -- can NOT be compared with -- bigger type
+    val longNumber: Long = 1
+    // println(longNumber == intNumber)
+    // println(longNumber === intNumber)
+    // 5.3 arithmetical operations
+    val addition = 1L + 3       // Long + Int => Long
+    println("addition::class.simpleName ${addition::class.simpleName}")
 }
\ No newline at end of file
diff --git a/docs/topics/numbers.md b/docs/topics/numbers.md
index cd02f576755..56b3d9cc2ac 100644
--- a/docs/topics/numbers.md
+++ b/docs/topics/numbers.md
@@ -70,46 +70,23 @@
 
 ## Explicit number conversions
 
-* TODO:
-Due to different representations, smaller types _are not subtypes_ of bigger ones.
-If they were, we would have troubles of the following sort:
-
-```kotlin
-// Hypothetical code, does not actually compile:
-val a: Int? = 1 // A boxed Int (java.lang.Integer)
-val b: Long? = a // Implicit conversion yields a boxed Long (java.lang.Long)
-print(b == a) // Surprise! This prints "false" as Long's equals() checks whether the other is Long as well
-```
-
-So equality would have been lost silently, not to mention identity.
-
-As a consequence, smaller types _are NOT implicitly converted_ to bigger types.
-This means that assigning a value of type `Byte` to an `Int` variable requires an explicit conversion:
-
-```kotlin
-val b: Byte = 1 // OK, literals are checked statically
-// val i: Int = b // ERROR
-val i1: Int = b.toInt()
-```
-
-All number types support conversions to other types:
-
-* `toByte(): Byte`
-* `toShort(): Short`
-* `toInt(): Int`
-* `toLong(): Long`
-* `toFloat(): Float`
-* `toDouble(): Double`
-
-In many cases, there is no need for explicit conversions because the type is inferred from the context,
-and arithmetical operations are overloaded for appropriate conversions, for example:
-
-```kotlin
-val l = 1L + 3 // Long + Int => Long
-```
+* 👁️smaller (about size) types != subtypes of bigger types 👁️
+  * Reason: 🧠have different representations 🧠
+  * -> ⚠️ -- NOT implicitly converted to -- bigger types ⚠️
+* exist ANY number conversions between each other
+  * `toByte(): Byte`
+  * `toShort(): Short`
+  * `toInt(): Int`
+  * `toLong(): Long`
+  * `toFloat(): Float`
+  * `toDouble(): Double`
+* use cases / implicit conversion is needed
+  * smaller types -> bigger types
+* use cases / type -- is inferred from the -- context (==implicit conversion)
+  * arithmetical operations
 
 ## Operations on numbers
-
+* TODO:
 Kotlin supports the standard set of arithmetical operations over numbers: `+`, `-`, `*`, `/`, `%`. They are declared
 as members of appropriate classes: