From 972d2bc1174d8810a661c7c37739a512dbdd22eb Mon Sep 17 00:00:00 2001 From: Sergey Biryukov Date: Fri, 28 May 2021 18:04:57 +0000 Subject: [PATCH] Docs: Improve documentation for `wp_list_filter()` and `wp_filter_object_list()`. This should make the purpose and behavior of these functions more obvious without reading the code. Props ribaricplusplus. Fixes #52808. Built from https://develop.svn.wordpress.org/trunk@51044 git-svn-id: http://core.svn.wordpress.org/trunk@50653 1a063a9b-81f0-0310-95a4-ce76da25c4cd --- wp-includes/class-wp-list-util.php | 7 +++++ wp-includes/functions.php | 42 +++++++++++++++++++++++------- wp-includes/version.php | 2 +- 3 files changed, 41 insertions(+), 10 deletions(-) diff --git a/wp-includes/class-wp-list-util.php b/wp-includes/class-wp-list-util.php index 0eef72c4a1..dfd44172b4 100644 --- a/wp-includes/class-wp-list-util.php +++ b/wp-includes/class-wp-list-util.php @@ -77,6 +77,13 @@ class WP_List_Util { /** * Filters the list, based on a set of key => value arguments. * + * Retrieves the objects from the list that match the given arguments. + * Key represents property name, and value represents property value. + * + * If an object has more properties than those specified in arguments, + * that will not disqualify it. When using the 'AND' operator, + * any missing properties will disqualify it. + * * @since 4.7.0 * * @param array $args Optional. An array of key => value arguments to match diff --git a/wp-includes/functions.php b/wp-includes/functions.php index 363316216d..043491e310 100644 --- a/wp-includes/functions.php +++ b/wp-includes/functions.php @@ -4717,18 +4717,29 @@ function wp_is_numeric_array( $data ) { /** * Filters a list of objects, based on a set of key => value arguments. * + * Retrieves the objects from the list that match the given arguments. + * Key represents property name, and value represents property value. + * + * If an object has more properties than those specified in arguments, + * that will not disqualify it. When using the 'AND' operator, + * any missing properties will disqualify it. + * + * When using the `$field` argument, this function can also retrieve + * a particular field from all matching objects, whereas wp_list_filter() + * only does the filtering. + * * @since 3.0.0 * @since 4.7.0 Uses `WP_List_Util` class. * - * @param array $list An array of objects to filter + * @param array $list An array of objects to filter. * @param array $args Optional. An array of key => value arguments to match * against each object. Default empty array. - * @param string $operator Optional. The logical operation to perform. 'or' means - * only one element from the array needs to match; 'and' - * means all elements must match; 'not' means no elements may - * match. Default 'and'. - * @param bool|string $field A field from the object to place instead of the entire object. - * Default false. + * @param string $operator Optional. The logical operation to perform. 'AND' means + * all elements from the array must match. 'OR' means only + * one element needs to match. 'NOT' means no elements may + * match. Default 'AND'. + * @param bool|string $field Optional. A field from the object to place instead + * of the entire object. Default false. * @return array A list of objects or object fields. */ function wp_filter_object_list( $list, $args = array(), $operator = 'and', $field = false ) { @@ -4750,6 +4761,16 @@ function wp_filter_object_list( $list, $args = array(), $operator = 'and', $fiel /** * Filters a list of objects, based on a set of key => value arguments. * + * Retrieves the objects from the list that match the given arguments. + * Key represents property name, and value represents property value. + * + * If an object has more properties than those specified in arguments, + * that will not disqualify it. When using the 'AND' operator, + * any missing properties will disqualify it. + * + * If you want to retrieve a particular field from all matching objects, + * use wp_filter_object_list() instead. + * * @since 3.1.0 * @since 4.7.0 Uses `WP_List_Util` class. * @@ -4768,6 +4789,7 @@ function wp_list_filter( $list, $args = array(), $operator = 'AND' ) { } $util = new WP_List_Util( $list ); + return $util->filter( $args, $operator ); } @@ -4781,8 +4803,8 @@ function wp_list_filter( $list, $args = array(), $operator = 'AND' ) { * @since 4.0.0 $index_key parameter added. * @since 4.7.0 Uses `WP_List_Util` class. * - * @param array $list List of objects or arrays - * @param int|string $field Field from the object to place instead of the entire object + * @param array $list List of objects or arrays. + * @param int|string $field Field from the object to place instead of the entire object. * @param int|string $index_key Optional. Field from the object to use as keys for the new array. * Default null. * @return array Array of found values. If `$index_key` is set, an array of found values with keys @@ -4791,6 +4813,7 @@ function wp_list_filter( $list, $args = array(), $operator = 'AND' ) { */ function wp_list_pluck( $list, $field, $index_key = null ) { $util = new WP_List_Util( $list ); + return $util->pluck( $field, $index_key ); } @@ -4813,6 +4836,7 @@ function wp_list_sort( $list, $orderby = array(), $order = 'ASC', $preserve_keys } $util = new WP_List_Util( $list ); + return $util->sort( $orderby, $order, $preserve_keys ); } diff --git a/wp-includes/version.php b/wp-includes/version.php index 04077ddff1..084d94b648 100644 --- a/wp-includes/version.php +++ b/wp-includes/version.php @@ -13,7 +13,7 @@ * * @global string $wp_version */ -$wp_version = '5.8-alpha-51043'; +$wp_version = '5.8-alpha-51044'; /** * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.