From bfeb065c686a73dd8f48b06be59cac76ca3cb06f Mon Sep 17 00:00:00 2001 From: Araozu Date: Fri, 12 Jul 2024 19:15:07 -0500 Subject: [PATCH] Add page for Array.concat --- public/css/pages.css | 2 +- src/components/docs/CodeMin.astro | 9 +++ src/components/docs/Warning.astro | 4 ++ src/layouts/ApiLayout.astro | 3 +- src/pages/api/std/Array.mdx | 109 +++++++++++++++++----------- src/pages/api/std/Array/concat.mdx | 112 +++++++++++++++++++++++++++++ src/pages/api/std/Array/filter.md | 6 -- 7 files changed, 193 insertions(+), 52 deletions(-) create mode 100644 src/components/docs/CodeMin.astro create mode 100644 src/components/docs/Warning.astro create mode 100644 src/pages/api/std/Array/concat.mdx delete mode 100644 src/pages/api/std/Array/filter.md diff --git a/public/css/pages.css b/public/css/pages.css index 2ef51dd..ad99572 100644 --- a/public/css/pages.css +++ b/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; } diff --git a/src/components/docs/CodeMin.astro b/src/components/docs/CodeMin.astro new file mode 100644 index 0000000..85b1777 --- /dev/null +++ b/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); +--- + + diff --git a/src/components/docs/Warning.astro b/src/components/docs/Warning.astro new file mode 100644 index 0000000..0b41d45 --- /dev/null +++ b/src/components/docs/Warning.astro @@ -0,0 +1,4 @@ +
+
Warning
+ +
\ No newline at end of file diff --git a/src/layouts/ApiLayout.astro b/src/layouts/ApiLayout.astro index bd1346f..74ca91d 100644 --- a/src/layouts/ApiLayout.astro +++ b/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" > +
- -
diff --git a/src/pages/api/std/Array.mdx b/src/pages/api/std/Array.mdx index abd6637..93ed6c0 100644 --- a/src/pages/api/std/Array.mdx +++ b/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: + + +You can also declare an index along with the value: + + + +```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, self is the array to operate on. @@ -254,25 +296,26 @@ In the parameters, self is the array to opera -

- fun - filter - [ - T - ] - ( -
- self - , -
- (T) -> Bool callback, -
- )-> - Array - [ - T - ] -

+ Array[T] + `} /> + + + Concatenate with other arrays, and return the result + as a new array. + + + + + (Bool) callback, + ) -> Array[T] + `} /> Filters elements using a callback function, and returns @@ -281,17 +324,7 @@ In the parameters, self is the array to opera -

- fun - push - [ - T - ] - ( - self - , T ...elements) -> - Int -

+ Appends one or more elements to the end of the array. @@ -300,17 +333,7 @@ In the parameters, self is the array to opera -

- fun - pop - [ - T - ] - ( - self - ) -> - T -

+ Removes the last value of the array, and returns it. diff --git a/src/pages/api/std/Array/concat.mdx b/src/pages/api/std/Array/concat.mdx new file mode 100644 index 0000000..1bf760d --- /dev/null +++ b/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 + + 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: + + + +Example concatenating 3 arrays: + + + +Example concatenating without any other array. In this case +`first` and `result` are different arrays: + + + +Example concatenating an empty array with a filled array: + + + + +## 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" +} +``` + + + diff --git a/src/pages/api/std/Array/filter.md b/src/pages/api/std/Array/filter.md deleted file mode 100644 index 052af3d..0000000 --- a/src/pages/api/std/Array/filter.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -layout: ../../../../layouts/ApiLayout.astro ---- - -# Array.filter -