Add page for Array.concat

public/css/pages.css

@@ -49,7 +49,7 @@
     background: var(--code-theme-bg-color);
 }
 
-.markdown a {
+.markdown > p > a {
     color: var(--c-link);
     text-decoration: underline;
 }

src/components/docs/CodeMin.astro

@@ -0,0 +1,9 @@
+---
+import { native_highlighter } from "../../lexer/highlighter";
+
+const { thpcode, href } = Astro.props;
+
+const native_html = await native_highlighter(thpcode);
+---
+
+<a href={href} class="inline-block w-full py-2 font-mono whitespace-pre" set:html={native_html} />

src/components/docs/Warning.astro

@@ -0,0 +1,4 @@
+<div class="my-6 px-4 py-2 rounded bg-red-200 dark:bg-red-950">
+    <div class="font-bold pt-2">Warning</div>
+    <slot />
+</div>

src/layouts/ApiLayout.astro

@@ -24,6 +24,7 @@ const { headings } = Astro.props;
             class="py-[3.5rem] lg:pl-12 lg:pr-4 markdown min-w-0 small-container mx-auto"
         >
             <slot />
+            <div class="h-32"></div>
         </main>
 
         <div
@@ -38,6 +39,4 @@ const { headings } = Astro.props;
             </nav>
         </div>
     </div>
-
-    <div class="h-32"></div>
 </BaseLayout>

src/pages/api/std/Array.mdx

@@ -3,6 +3,7 @@ layout: ../../../layouts/ApiLayout.astro
 ---
 import TwoColumn from "../../../components/TwoColumn.astro"
 import Code from "../../../components/Code.astro"
+import CodeMin from "../../../components/docs/CodeMin.astro"
 import Warning from "../../../components/docs/Warning.astro"
 
 # Array
@@ -176,7 +177,7 @@ val colors = [
 If it doesn't, the code formatter will automatically
 insert one for you.
 
-### Assignment
+### Assignment to elements
 
 Use square brackets notation to insert into an array or modify it:
 
@@ -211,7 +212,7 @@ Use a `for` loop to iterate over the elements of an array:
 <Code thpcode={`
 val colors = ["red", "green", "blue"]
 
-for #(_index, c) in colors
+for c in colors
 {
     print("{c} ")
 }
@@ -221,6 +222,36 @@ for #(_index, c) in colors
 red green blue
 ```
 
+A for loop automatically declares new immutable variables. It is a compile
+error to attempt to modify those, as in the following snippet:
+
+<Code thpcode={`
+val colors = ["red", "green", "blue"]
+
+for c in colors
+{
+    c = "orange"    // Compile error: Can't assign to an immutable variable
+    print("{c} ")
+}
+`} />
+
+
+You can also declare an index along with the value:
+
+<Code thpcode={`
+val colors = ["red", "green", "blue"]
+
+for index, color in colors
+{
+    println("item {index}: {c}")
+}
+`} />
+
+```sh
+item 0: red
+item 1: green
+item 2: blue
+```
 
 
 ### Access
@@ -241,6 +272,17 @@ THP arrays don't have destructuring, since the values can all be `null`.
 If you know that the number of elements is fixed and valid, use Tuples instead.
 
 
+### Operators
+
+While PHP allows using certain operators with arrays, THP disallows that.
+Methods that perform comparisons should be used instead.
+
+
+### Assignment
+
+// TODO: Detail that assignment of arrays is copy on write
+
+
 ## Methods
 
 In the parameters, <code class="token keyword">self</code> is the array to operate on.
@@ -254,25 +296,26 @@ In the parameters, <code class="token keyword">self</code> is the array to opera
     <tbody>
         <tr class="dark:odd:bg-zinc-900 odd:bg-stone-200">
             <td class="px-2">
-                <p class="font-mono whitespace-pre">
+                <CodeMin href="./concat" thpcode={`
-                    <span class="token keyword">fun </span>
+                    fun concat[T](
-                    <span class="token function">filter</span>
+                        self,
-                    <span>[</span>
+                        Array[T]... arrays,
-                    <span class="token class">T</span>
+                    ) -> Array[T]
-                    <span>]</span>
+                `} />
-                    <span>(</span>
+            </td>
-                    <br/>
+            <td>
-                    <span class="token keyword">    self</span>
+                Concatenate with other arrays, and return the result
-                    <span>,</span>
+                as a new array.
-                    <br />
+            </td>
-                    <span>    (T) -> Bool callback,</span>
+        </tr>
-                    <br />
+        <tr class="dark:odd:bg-zinc-900 odd:bg-stone-200">
-                    <span>)-> </span>
+            <td class="px-2">
-                    <span class="token class">Array</span>
+                <CodeMin thpcode={`
-                    <span>[</span>
+                fun filter[T](
-                    <span class="token class">T</span>
+                    self,
-                    <span>]</span>
+                    (T) -> (Bool) callback,
-                </p>
+                ) -> Array[T]
+                `} />
             </td>
             <td>
                 Filters elements using a callback function, and returns
@@ -281,17 +324,7 @@ In the parameters, <code class="token keyword">self</code> is the array to opera
         </tr>
         <tr class="dark:odd:bg-zinc-900 odd:bg-stone-200">
             <td class="px-2">
-                <p class="font-mono">
+                <CodeMin thpcode="fun push[T](self, T... elements) -> Int" />
-                    <span class="token keyword">fun </span>
-                    <span class="token function">push</span>
-                    <span>[</span>
-                    <span class="token class">T</span>
-                    <span>]</span>
-                    <span>(</span>
-                    <span class="token keyword">self</span>
-                    <span>, T ...elements) -> </span>
-                    <span class="token class">Int</span>
-                </p>
             </td>
             <td>
                 Appends one or more elements to the end of the array.
@@ -300,17 +333,7 @@ In the parameters, <code class="token keyword">self</code> is the array to opera
         </tr>
         <tr class="dark:odd:bg-zinc-900 odd:bg-stone-200">
             <td class="px-2">
-                <p class="font-mono">
+                <CodeMin thpcode="fun pop[T](self) -> T" />
-                    <span class="token keyword">fun </span>
-                    <span class="token function">pop</span>
-                    <span>[</span>
-                    <span class="token class">T</span>
-                    <span>]</span>
-                    <span>(</span>
-                    <span class="token keyword">self</span>
-                    <span>) -> </span>
-                    <span class="token class">T</span>
-                </p>
             </td>
             <td>
                 Removes the last value of the array, and returns it.

src/pages/api/std/Array/concat.mdx

@@ -0,0 +1,112 @@
+---
+layout: ../../../../layouts/ApiLayout.astro
+---
+import Code from "../../../../components/Code.astro"
+
+# `Array.concat`
+
+Concatenate with other arrays, and return the result as a new array.
+
+## Signature
+
+<Code thpcode={`
+    fun concat[T](
+        self,
+        Array[T]... arrays,
+    ) -> Array[T]
+`} />
+
+## Parameters
+
+- `self`: The callee.
+- `Array[T]... arrays`: Multiple arrays to concatenate the current one to.
+
+## Return value
+
+`Array[T]`: A new array that contains the elements from all arrays.
+
+
+## Description
+
+Concatenates the elements of the callee and the elements of each array in the
+variable `array`. These values are returned in a new array.
+
+If called without any aditional array it returns a new array with the elements
+of `self`.
+
+The returned array is a new one. However, if the elements of the callee and the
+parameters are references, the returned array will contain references that point
+to the same memory. This is important if, for example, the arrays contain other
+arrays or objects.
+
+## Examples
+
+Example concatenating 2 arrays:
+
+<Code thpcode={`
+    val first  = [1, 2, 3]
+    val second = [4, 5, 6]
+
+    val result = first.concat(second)
+    assert_eq(result, [1, 2, 3, 4, 5, 6])
+`} />
+
+Example concatenating 3 arrays:
+
+<Code thpcode={`
+    val first  = ["a", "b"]
+    val second = ["c", "d"]
+    val third  = ["e", "f"]
+
+    val result = first.concat(second, third)
+    assert_eq(result, ["a", "b", "c", "d", "e", "f"])
+`} />
+
+Example concatenating without any other array. In this case
+`first` and `result` are different arrays:
+
+<Code thpcode={`
+    val first  = [1, 2, 3]
+
+    val result = first.concat()
+    assert_eq(result, [1, 2, 3])
+`} />
+
+Example concatenating an empty array with a filled array:
+
+<Code thpcode={`
+    val first  = []
+    val second = [10, 20, 30]
+
+    val result = first.concat(second)
+    assert_eq(result, [10, 20, 30])
+`} />
+
+
+## PHP interop
+
+This method is directly compiled to `array_merge`. Since THP guarantees that
+arrays only have numbers as keys, this will never produce invalid values due
+to merging with an array with string keys.
+
+If the arrays contain invalid keys (negative values, out of bounds) the merge
+is performed based on the insertion order, not the keys order, and the resulting
+array will have correct keys.
+
+```php
+$array_1 = [2 => "a", 0 => "b"];
+$array_2 = [1 => "c"];
+
+var_dump(array_merge($array_1, $array_2));
+```
+
+```out
+array(3) {
+  [0]=> string(1) "a"
+  [1]=> string(1) "b"
+  [2]=> string(1) "c"
+}
+```
+
+
+

src/pages/api/std/Array/filter.md

@@ -1,6 +0,0 @@
----
-layout: ../../../../layouts/ApiLayout.astro
----
-
-# Array.filter
-