From c2d67054089f0e0b7e676559f77ab63bb20affa9 Mon Sep 17 00:00:00 2001
From: alfredo-toledano <alfredo.toledano@allianzdirect.es>
Date: Wed, 28 Aug 2024 20:02:14 +0200
Subject: [PATCH] doc(docs.topics.arrays): add notes and examples

---
 docs/topics/arrays.kt | 23 +++++++++++
 docs/topics/arrays.md | 90 +++++++------------------------------------
 2 files changed, 36 insertions(+), 77 deletions(-)

diff --git a/docs/topics/arrays.kt b/docs/topics/arrays.kt
index 74e86596d97..13972460a53 100644
--- a/docs/topics/arrays.kt
+++ b/docs/topics/arrays.kt
@@ -19,4 +19,27 @@ fun main() {
 
     // 3. contentEquals     if you want to compare array's content
     println("array1.contentEquals(array2)   ${array1.contentEquals(array2)}")       // true, because it compares the content
+
+    // 4. ways to create arrays
+    // 4.1 functions
+    // 4.1.1 arrayOf()
+    val simpleArray = arrayOf(1, 2, 3)
+    println(simpleArray.joinToString())
+    // 4.1.2 arrayOfNulls()
+    val nullArray: Array<Int?> = arrayOfNulls(3)        // ALL items are null
+    println(nullArray.joinToString())
+    // 4.1.3 emptyArray()
+    val exampleArray = emptyArray<String>()
+    println(exampleArray.joinToString())        // NOTHING is displayed, because it's empty
+    // 4.2 Array constructor
+    val initArray = Array<Int>(3) { 0 } // Array<Int>(size) { lambdaExpressionWithTIntReturned }
+    println(initArray.joinToString())
+    val asc = Array(5) { i -> (i * i).toString() } // Array(size) { lambdaExpressionWithTypeInferredReturned }
+    asc.forEach { println(it) }
+
+    // 5. ways to specify the type of array
+    // 5.1 | left-hand of the assigment
+    var leftHandSideTypeArray: Array<String> = emptyArray()
+    // 5.2 | right-hand of the assigment
+    var rightHandSideTypeArray = emptyArray<String>()
 }
\ No newline at end of file
diff --git a/docs/topics/arrays.md b/docs/topics/arrays.md
index 2ddb7025c08..60208989a16 100644
--- a/docs/topics/arrays.md
+++ b/docs/topics/arrays.md
@@ -31,86 +31,22 @@
 
 ## Create arrays
 
-* TODO:
-To create arrays in Kotlin, you can use:
-* functions, such as [`arrayOf()`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/array-of.html), [`arrayOfNulls()`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/array-of-nulls.html#kotlin$arrayOfNulls(kotlin.Int)) 
-or [`emptyArray()`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/empty-array.html).
-* the `Array` constructor.
-
-This example uses the [`arrayOf()`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/array-of.html) function 
-and passes item values to it:
-
-```kotlin
-fun main() {
-//sampleStart
-    // Creates an array with values [1, 2, 3]
-    val simpleArray = arrayOf(1, 2, 3)
-    println(simpleArray.joinToString())
-    // 1, 2, 3
-//sampleEnd
-}
-```
-{kotlin-runnable="true" kotlin-min-compiler-version="1.3" id="arrays-simple-array-kotlin"}
-
-This example uses the [`arrayOfNulls()`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/array-of-nulls.html#kotlin$arrayOfNulls(kotlin.Int))
-function to create an array of a given size filled with `null` elements:
-
-```kotlin
-fun main() {
-//sampleStart
-    // Creates an array with values [null, null, null]
-    val nullArray: Array<Int?> = arrayOfNulls(3)
-    println(nullArray.joinToString())
-    // null, null, null
-//sampleEnd
-}
-```
-{kotlin-runnable="true" kotlin-min-compiler-version="1.3" id="arrays-null-array-kotlin"}
-
-This example uses the [`emptyArray()`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/empty-array.html) function to 
-create an empty array :
-
-```kotlin
-    var exampleArray = emptyArray<String>()
-```
-
-> You can specify the type of the empty array on the left-hand or right-hand side of the assignment due to Kotlin's type
-> inference.
->
-> For example:
-> ```Kotlin
-> var exampleArray = emptyArray<String>()
-> 
-> var exampleArray: Array<String> = emptyArray()
->```
->
-{type="note"}
-
-The `Array` constructor takes the array size and a function that returns values for array elements given its index:
-
-```kotlin
-fun main() {
-//sampleStart
-    // Creates an Array<Int> that initializes with zeros [0, 0, 0]
-    val initArray = Array<Int>(3) { 0 }
-    println(initArray.joinToString())
-    // 0, 0, 0
-
-    // Creates an Array<String> with values ["0", "1", "4", "9", "16"]
-    val asc = Array(5) { i -> (i * i).toString() }
-    asc.forEach { print(it) }
-    // 014916
-//sampleEnd
-}
-```
-{kotlin-runnable="true" kotlin-min-compiler-version="1.3" id="arrays-array-constructor-kotlin"}
-
-> Like in most programming languages, indices start from 0 in Kotlin.
->
-{type="note"}
+* ways
+  * functions
+    * [`arrayOf()`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/array-of.html)
+    * [`arrayOfNulls()`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/array-of-nulls.html#kotlin$arrayOfNulls(kotlin.Int))
+    * [`emptyArray()`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/empty-array.html)
+  * `Array` constructor
+    * `Array<T>(size: kotlin.Int, lambdaExpressionWithTReturned)` == `Array<T>(size: kotlin.Int) { lambdaExpressionWithTReturned }`
+      * `lambdaExpressionWithTReturned` runs / array's item & value is the index | array (from 0)
+      * Reason: 🧠 trailing lambda expression 🧠 
+* ways to specify the type of array
+  * | left-hand of the assigment
+  * | right-hand of the assigment
 
 ### Nested arrays
 
+* TODO:
 Arrays can be nested within each other to create multidimensional arrays:
 
 ```kotlin