From 6fa04e4bf587b4818bc97c9c1b557ab8a6eabbd2 Mon Sep 17 00:00:00 2001 From: joshuaruesweg Date: Fri, 7 Jun 2024 18:22:21 +0200 Subject: [PATCH 1/9] Add `array_find` documentation --- reference/array/functions/array-find.xml | 144 +++++++++++++++++++++++ reference/array/versions.xml | 1 + 2 files changed, 145 insertions(+) create mode 100644 reference/array/functions/array-find.xml diff --git a/reference/array/functions/array-find.xml b/reference/array/functions/array-find.xml new file mode 100644 index 000000000000..05b7b1d04760 --- /dev/null +++ b/reference/array/functions/array-find.xml @@ -0,0 +1,144 @@ + + + + + array_find + Returns the value of the first element of an &array; for which a callback returns &true;. + + + + &reftitle.description; + + mixedarray_find + arrayarray + callablecallback + + + array_find returns the value of the first element of an + &array; for which the given callback returns &true;. If no matching element + is found the function returns &null;. + + + + + &reftitle.parameters; + + + + array + + + The &array; that should be searched. + + + + + callback + + + The callback function to call to check each element. The first parameter + contains the value, the second parameter contains the corresponding key. + If this function returns &true;, the value is returned from + array_find and the callback will not be called for + further elements. + + + + + + + + + &reftitle.returnvalues; + + The function returns the value of the first element for which the + callback returns &true;. If no matching element is + found the function returns &null;. + + + + + &reftitle.examples; + + + <function>array_find</function> example + + 'dog', + 'b' => 'cat', + 'c' => 'cow', + 'd' => 'duck', + 'e' => 'goose', + 'f' => 'elephant' +]; + +// Find the first animal with a name longer than 4 characters. +var_dump(array_find($array, function (string $value) { + return strlen($value) > 4; +})); + +// Find the first animal whose name begins with f. +var_dump(array_find($array, function (string $value) { + return str_starts_with($value, 'f'); +})); + +// Find the first animal where the array key is the first symbol of the animal. +var_dump(array_find($array, function (string $value, $key) { + return $value[0] === $key; +})); + +// Find the first animal where the array key matching a RegEx. +var_dump(array_find($array, function ($value, $key) { + return preg_match('/^([a-f])$/', $key); +})); +?> +]]> + + + The above example will output: + + + + + + + + + + &reftitle.seealso; + + + array_filter + array_reduce + + + + + + diff --git a/reference/array/versions.xml b/reference/array/versions.xml index ca37edd339cc..f1867c82fe63 100644 --- a/reference/array/versions.xml +++ b/reference/array/versions.xml @@ -18,6 +18,7 @@ + From 97af33944ce3bcdc10f5a9359b2dd8d708d06768 Mon Sep 17 00:00:00 2001 From: joshuaruesweg Date: Thu, 20 Jun 2024 21:17:00 +0200 Subject: [PATCH 2/9] Add `array_find_key` documentation --- reference/array/functions/array-find-key.xml | 144 +++++++++++++++++++ reference/array/functions/array-find.xml | 2 +- reference/array/versions.xml | 1 + 3 files changed, 146 insertions(+), 1 deletion(-) create mode 100644 reference/array/functions/array-find-key.xml diff --git a/reference/array/functions/array-find-key.xml b/reference/array/functions/array-find-key.xml new file mode 100644 index 000000000000..3c06823cc6dd --- /dev/null +++ b/reference/array/functions/array-find-key.xml @@ -0,0 +1,144 @@ + + + + + array_find_key + Returns the key of the first element of an &array; for which a callback returns &true;. + + + + &reftitle.description; + + mixedarray_find_key + arrayarray + callablecallback + + + array_find_key returns the key of the first element of an + &array; for which the given callback returns &true;. If no matching element + is found the function returns &null;. + + + + + &reftitle.parameters; + + + + array + + + The &array; that should be searched. + + + + + callback + + + The callback function to call to check each element. The first parameter + contains the value, the second parameter contains the corresponding key. + If this function returns &true;, the key is returned from + array_find_key and the callback will not be called + for further elements. + + + + + + + + + &reftitle.returnvalues; + + The function returns the key of the first element for which the + callback returns &true;. If no matching element is + found the function returns &null;. + + + + + &reftitle.examples; + + + <function>array_find_key</function> example + + 'dog', + 'b' => 'cat', + 'c' => 'cow', + 'd' => 'duck', + 'e' => 'goose', + 'f' => 'elephant' +]; + +// Find the first animal with a name longer than 4 characters. +var_dump(array_find_key($array, function (string $value) { + return strlen($value) > 4; +})); + +// Find the first animal whose name begins with f. +var_dump(array_find_key($array, function (string $value) { + return str_starts_with($value, 'f'); +})); + +// Find the first animal where the array key is the first symbol of the animal. +var_dump(array_find_key($array, function (string $value, $key) { + return $value[0] === $key; +})); + +// Find the first animal where the array key matching a RegEx. +var_dump(array_find_key($array, function ($value, $key) { + return preg_match('/^([a-f])$/', $key); +})); +?> +]]> + + + The above example will output: + + + + + + + + + + &reftitle.seealso; + + + array_find + array_filter + array_reduce + + + + + diff --git a/reference/array/functions/array-find.xml b/reference/array/functions/array-find.xml index 05b7b1d04760..83c0f02f4f93 100644 --- a/reference/array/functions/array-find.xml +++ b/reference/array/functions/array-find.xml @@ -115,9 +115,9 @@ string(3) "dog" &reftitle.seealso; + array_find_key array_filter array_reduce - diff --git a/reference/array/versions.xml b/reference/array/versions.xml index f1867c82fe63..a1a80fa7667b 100644 --- a/reference/array/versions.xml +++ b/reference/array/versions.xml @@ -19,6 +19,7 @@ + From 6bd2ffe5a12e21896c3cece18927d474ede92a6b Mon Sep 17 00:00:00 2001 From: joshuaruesweg Date: Thu, 20 Jun 2024 21:54:13 +0200 Subject: [PATCH 3/9] Add `array_any` documentation --- reference/array/functions/array-any.xml | 137 +++++++++++++++++++++ reference/array/functions/array-filter.xml | 5 +- reference/array/versions.xml | 1 + 3 files changed, 141 insertions(+), 2 deletions(-) create mode 100644 reference/array/functions/array-any.xml diff --git a/reference/array/functions/array-any.xml b/reference/array/functions/array-any.xml new file mode 100644 index 000000000000..300333a36db7 --- /dev/null +++ b/reference/array/functions/array-any.xml @@ -0,0 +1,137 @@ + + + + + array_any + Returns &true;, if a callback returns &true; for any element in an array. + + + + &reftitle.description; + + mixedarray_any + arrayarray + callablecallback + + + array_any returns &true;, if the given $callback returns + &true; for any element. Otherwise the function returns &false;. + + + + + &reftitle.parameters; + + + + array + + + The &array; that should be searched. + + + + + callback + + + The callback function to call to check each element. The first parameter + contains the value, the second parameter contains the corresponding key. + If this function returns &true;, &true; is returned from + array_any and the callback will not be called for + further elements. + + + + + + + + + &reftitle.returnvalues; + + The function returns &true;, if there is at least one element for which + callback returns &true;. Otherwise the function + returns &false;. + + + + + &reftitle.examples; + + + <function>array_any</function> example + + 'dog', + 'b' => 'cat', + 'c' => 'cow', + 'd' => 'duck', + 'e' => 'goose', + 'f' => 'elephant' +]; + +// Check, if any animal name is longer than 5 letters. +var_dump(array_any($array, function (string $value) { + return strlen($value) > 5; +})); + +// Check, if any animal name is shorter than 3 letters. +var_dump(array_any($array, function (string $value) { + return strlen($value) < 3; +})); + +// Check, if any array key is not a string. +var_dump(array_any($array, function (string $value, $key) { + return !is_string($key); +})); +?> +]]> + + + The above example will output: + + + + + + + + + + &reftitle.seealso; + + + array_filter + array_find + array_find_key + + + + + diff --git a/reference/array/functions/array-filter.xml b/reference/array/functions/array-filter.xml index 0c1190c8ce13..0649f9c35701 100644 --- a/reference/array/functions/array-filter.xml +++ b/reference/array/functions/array-filter.xml @@ -5,7 +5,7 @@ array_filter Filters elements of an array using a callback function - + &reftitle.description; @@ -201,7 +201,7 @@ Array - <function>array_filter</function> with + <title><function>array_filter</function> with <parameter>mode</parameter> array_intersect + array_any array_map array_reduce array_walk diff --git a/reference/array/versions.xml b/reference/array/versions.xml index a1a80fa7667b..6f91781292c7 100644 --- a/reference/array/versions.xml +++ b/reference/array/versions.xml @@ -5,6 +5,7 @@ --> + From 59d808f6bb097c50f7756ad6337e240272e97984 Mon Sep 17 00:00:00 2001 From: joshuaruesweg Date: Thu, 20 Jun 2024 22:05:36 +0200 Subject: [PATCH 4/9] Add `array_all` documentation --- reference/array/functions/array-all.xml | 137 +++++++++++++++++++ reference/array/functions/array-any.xml | 1 + reference/array/functions/array-filter.xml | 2 +- reference/array/functions/array-find-key.xml | 2 + reference/array/functions/array-find.xml | 2 + reference/array/versions.xml | 1 + 6 files changed, 144 insertions(+), 1 deletion(-) create mode 100644 reference/array/functions/array-all.xml diff --git a/reference/array/functions/array-all.xml b/reference/array/functions/array-all.xml new file mode 100644 index 000000000000..78e7e6a950b9 --- /dev/null +++ b/reference/array/functions/array-all.xml @@ -0,0 +1,137 @@ + + + + + array_all + Returns &true;, if a callback returns &true; for all elements in an array. + + + + &reftitle.description; + + mixedarray_all + arrayarray + callablecallback + + + array_all returns &true;, if the given $callback returns + &true; for all elements. Otherwise the function returns &false;. + + + + + &reftitle.parameters; + + + + array + + + The &array; that should be searched. + + + + + callback + + + The callback function to call to check each element. The first parameter + contains the value, the second parameter contains the corresponding key. + If this function returns &false;, &false; is returned from + array_all and the callback will not be called for + further elements. + + + + + + + + + &reftitle.returnvalues; + + The function returns &true;, if callback returns + &true; for all elements. Otherwise the function returns &false;. + + + + + &reftitle.examples; + + + <function>array_all</function> example + + 'dog', + 'b' => 'cat', + 'c' => 'cow', + 'd' => 'duck', + 'e' => 'goose', + 'f' => 'elephant' +]; + +// Check, if all animal names are shorter than 12 letters. +var_dump(array_all($array, function (string $value) { + return strlen($value) < 12; +})); + +// Check, if all animal names are longer than 5 letters. +var_dump(array_all($array, function (string $value) { + return strlen($value) > 5; +})); + +// Check, if all array keys are strings. +var_dump(array_all($array, function (string $value, $key) { + return is_string($key); +})); +?> +]]> + + + The above example will output: + + + + + + + + + + &reftitle.seealso; + + + array_any + array_filter + array_find + array_find_key + + + + + diff --git a/reference/array/functions/array-any.xml b/reference/array/functions/array-any.xml index 300333a36db7..6d0c6f07931c 100644 --- a/reference/array/functions/array-any.xml +++ b/reference/array/functions/array-any.xml @@ -108,6 +108,7 @@ bool(false) &reftitle.seealso; + array_all array_filter array_find array_find_key diff --git a/reference/array/functions/array-filter.xml b/reference/array/functions/array-filter.xml index 0649f9c35701..fabe1b3e1ee3 100644 --- a/reference/array/functions/array-filter.xml +++ b/reference/array/functions/array-filter.xml @@ -253,10 +253,10 @@ array(2) { array_intersect + array_find array_any array_map array_reduce - array_walk diff --git a/reference/array/functions/array-find-key.xml b/reference/array/functions/array-find-key.xml index 3c06823cc6dd..3578c663b3b8 100644 --- a/reference/array/functions/array-find-key.xml +++ b/reference/array/functions/array-find-key.xml @@ -116,6 +116,8 @@ string(1) "a" array_find + array_all + array_any array_filter array_reduce diff --git a/reference/array/functions/array-find.xml b/reference/array/functions/array-find.xml index 83c0f02f4f93..0ce98f1fa52e 100644 --- a/reference/array/functions/array-find.xml +++ b/reference/array/functions/array-find.xml @@ -116,6 +116,8 @@ string(3) "dog" array_find_key + array_all + array_any array_filter array_reduce diff --git a/reference/array/versions.xml b/reference/array/versions.xml index 6f91781292c7..82064ec2e97e 100644 --- a/reference/array/versions.xml +++ b/reference/array/versions.xml @@ -5,6 +5,7 @@ --> + From 80a77528baa5167c988f1c9eb7ff414ccf3a35e2 Mon Sep 17 00:00:00 2001 From: joshuaruesweg Date: Mon, 28 Oct 2024 14:17:29 +0100 Subject: [PATCH 5/9] Resolve annotations --- reference/array/functions/array-all.xml | 13 +++++++++---- reference/array/functions/array-any.xml | 13 +++++++++---- reference/array/functions/array-find-key.xml | 14 ++++++++------ reference/array/functions/array-find.xml | 12 ++++++++---- 4 files changed, 34 insertions(+), 18 deletions(-) diff --git a/reference/array/functions/array-all.xml b/reference/array/functions/array-all.xml index 78e7e6a950b9..b33b5cdcdaca 100644 --- a/reference/array/functions/array-all.xml +++ b/reference/array/functions/array-all.xml @@ -14,8 +14,9 @@ callablecallback - array_all returns &true;, if the given $callback returns - &true; for all elements. Otherwise the function returns &false;. + array_all returns &true;, if the given + callback returns &true; for all elements. Otherwise + the function returns &false;. @@ -35,8 +36,12 @@ callback - The callback function to call to check each element. The first parameter - contains the value, the second parameter contains the corresponding key. + The callback function to call to check each element, which must be + + boolcallback + mixedvalue + mixedkey + If this function returns &false;, &false; is returned from array_all and the callback will not be called for further elements. diff --git a/reference/array/functions/array-any.xml b/reference/array/functions/array-any.xml index 6d0c6f07931c..464e4c1cabf4 100644 --- a/reference/array/functions/array-any.xml +++ b/reference/array/functions/array-any.xml @@ -14,8 +14,9 @@ callablecallback - array_any returns &true;, if the given $callback returns - &true; for any element. Otherwise the function returns &false;. + array_any returns &true;, if the given + callback returns &true; for any element. Otherwise the + function returns &false;. @@ -35,8 +36,12 @@ callback - The callback function to call to check each element. The first parameter - contains the value, the second parameter contains the corresponding key. + The callback function to call to check each element, which must be + + boolcallback + mixedvalue + mixedkey + If this function returns &true;, &true; is returned from array_any and the callback will not be called for further elements. diff --git a/reference/array/functions/array-find-key.xml b/reference/array/functions/array-find-key.xml index 3578c663b3b8..a870767a2967 100644 --- a/reference/array/functions/array-find-key.xml +++ b/reference/array/functions/array-find-key.xml @@ -15,8 +15,8 @@ array_find_key returns the key of the first element of an - &array; for which the given callback returns &true;. If no matching element - is found the function returns &null;. + &array; for which the given callback returns &true;. + If no matching element is found the function returns &null;. @@ -36,8 +36,12 @@ callback - The callback function to call to check each element. The first parameter - contains the value, the second parameter contains the corresponding key. + The callback function to call to check each element, which must be + + boolcallback + mixedvalue + mixedkey + If this function returns &true;, the key is returned from array_find_key and the callback will not be called for further elements. @@ -60,7 +64,6 @@ &reftitle.examples; - <function>array_find_key</function> example - diff --git a/reference/array/functions/array-find.xml b/reference/array/functions/array-find.xml index 0ce98f1fa52e..d28b866c18c6 100644 --- a/reference/array/functions/array-find.xml +++ b/reference/array/functions/array-find.xml @@ -15,8 +15,8 @@ array_find returns the value of the first element of an - &array; for which the given callback returns &true;. If no matching element - is found the function returns &null;. + &array; for which the given callback returns &true;. + If no matching element is found the function returns &null;. @@ -36,8 +36,12 @@ callback - The callback function to call to check each element. The first parameter - contains the value, the second parameter contains the corresponding key. + The callback function to call to check each element, which must be + + boolcallback + mixedvalue + mixedkey + If this function returns &true;, the value is returned from array_find and the callback will not be called for further elements. From 186ccfaa2b6f5afe528b84dcb3127b0f1e8c3593 Mon Sep 17 00:00:00 2001 From: joshuaruesweg Date: Mon, 28 Oct 2024 14:30:06 +0100 Subject: [PATCH 6/9] Remove `para` tag within examples --- reference/array/functions/array-all.xml | 22 +++++++++----------- reference/array/functions/array-any.xml | 22 +++++++++----------- reference/array/functions/array-find-key.xml | 20 +++++++++--------- reference/array/functions/array-find.xml | 22 +++++++++----------- 4 files changed, 40 insertions(+), 46 deletions(-) diff --git a/reference/array/functions/array-all.xml b/reference/array/functions/array-all.xml index b33b5cdcdaca..54afef3751a7 100644 --- a/reference/array/functions/array-all.xml +++ b/reference/array/functions/array-all.xml @@ -62,10 +62,9 @@ &reftitle.examples; - - - <function>array_all</function> example - + + <function>array_all</function> example + ]]> - - - The above example will output: - - + + + The above example will output: + + - - - + + diff --git a/reference/array/functions/array-any.xml b/reference/array/functions/array-any.xml index 464e4c1cabf4..f9fc1b20c220 100644 --- a/reference/array/functions/array-any.xml +++ b/reference/array/functions/array-any.xml @@ -63,10 +63,9 @@ &reftitle.examples; - - - <function>array_any</function> example - + + <function>array_any</function> example + ]]> - - - The above example will output: - - + + + The above example will output: + + - - - + + diff --git a/reference/array/functions/array-find-key.xml b/reference/array/functions/array-find-key.xml index a870767a2967..e29b1e7991a6 100644 --- a/reference/array/functions/array-find-key.xml +++ b/reference/array/functions/array-find-key.xml @@ -63,9 +63,9 @@ &reftitle.examples; - - <function>array_find_key</function> example - + + <function>array_find_key</function> example + ]]> - - - The above example will output: - - + + + The above example will output: + + - - + + diff --git a/reference/array/functions/array-find.xml b/reference/array/functions/array-find.xml index d28b866c18c6..6022926d70dd 100644 --- a/reference/array/functions/array-find.xml +++ b/reference/array/functions/array-find.xml @@ -63,10 +63,9 @@ &reftitle.examples; - - - <function>array_find</function> example - + + <function>array_find</function> example + ]]> - - - The above example will output: - - + + + The above example will output: + + - - - + + From 27a1cbaee10d93114790f0787417ca69a4957ddf Mon Sep 17 00:00:00 2001 From: joshuaruesweg Date: Sun, 3 Nov 2024 15:34:02 +0100 Subject: [PATCH 7/9] Add suggested changes --- reference/array/functions/array-all.xml | 78 +++++++++--------- reference/array/functions/array-any.xml | 78 +++++++++--------- reference/array/functions/array-find-key.xml | 84 +++++++++----------- reference/array/functions/array-find.xml | 80 +++++++++---------- 4 files changed, 148 insertions(+), 172 deletions(-) diff --git a/reference/array/functions/array-all.xml b/reference/array/functions/array-all.xml index 54afef3751a7..3e4f861c54c5 100644 --- a/reference/array/functions/array-all.xml +++ b/reference/array/functions/array-all.xml @@ -3,7 +3,7 @@ array_all - Returns &true;, if a callback returns &true; for all elements in an array. + Checks if all &array; elements satisfy a callback function @@ -22,42 +22,40 @@ &reftitle.parameters; - - - - array - - - The &array; that should be searched. - - - - - callback - - - The callback function to call to check each element, which must be - - boolcallback - mixedvalue - mixedkey - - If this function returns &false;, &false; is returned from - array_all and the callback will not be called for - further elements. - - - - - + + + array + + + The &array; that should be searched. + + + + + callback + + + The callback function to call to check each element, which must be + + boolcallback + mixedvalue + mixedkey + + If this function returns &false;, &false; is returned from + array_all and the callback will not be called for + further elements. + + + + &reftitle.returnvalues; - + The function returns &true;, if callback returns &true; for all elements. Otherwise the function returns &false;. - + @@ -93,9 +91,7 @@ var_dump(array_all($array, function (string $value, $key) { ?> ]]> - - The above example will output: - + &example.outputs; &reftitle.seealso; - - - array_any - array_filter - array_find - array_find_key - - + + array_any + array_filter + array_find + array_find_key +