Changeset 51044

Timestamp:

05/28/2021 06:03:06 PM (4 years ago)

Author:

SergeyBiryukov

Message:

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.

Location:

trunk/src/wp-includes

Files:

• class-wp-list-util.php (modified) (1 diff)
• functions.php (modified) (6 diffs)

trunk/src/wp-includes/class-wp-list-util.php

@@ -77 +77 @@
     /**
      * 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

trunk/src/wp-includes/functions.php

@@ -4718 +4718 @@
  * 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.
  */
@@ -4750 +4761 @@
 /**
  * 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
@@ -4769 +4790 @@
 
     $util = new WP_List_Util( $list );
+
     return $util->filter( $args, $operator );
 }
@@ -4782 +4804 @@
  * @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.
@@ -4792 +4814 @@
 function wp_list_pluck( $list, $field, $index_key = null ) {
     $util = new WP_List_Util( $list );
+
     return $util->pluck( $field, $index_key );
 }
@@ -4814 +4837 @@
 
     $util = new WP_List_Util( $list );
+
     return $util->sort( $orderby, $order, $preserve_keys );
 }