Make WordPress Core

Changeset 51044


Ignore:
Timestamp:
05/28/2021 06:03:06 PM (3 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:
2 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/wp-includes/class-wp-list-util.php

    r48421 r51044  
    7777    /**
    7878     * Filters the list, based on a set of key => value arguments.
     79     *
     80     * Retrieves the objects from the list that match the given arguments.
     81     * Key represents property name, and value represents property value.
     82     *
     83     * If an object has more properties than those specified in arguments,
     84     * that will not disqualify it. When using the 'AND' operator,
     85     * any missing properties will disqualify it.
    7986     *
    8087     * @since 4.7.0
  • trunk/src/wp-includes/functions.php

    r51041 r51044  
    47184718 * Filters a list of objects, based on a set of key => value arguments.
    47194719 *
     4720 * Retrieves the objects from the list that match the given arguments.
     4721 * Key represents property name, and value represents property value.
     4722 *
     4723 * If an object has more properties than those specified in arguments,
     4724 * that will not disqualify it. When using the 'AND' operator,
     4725 * any missing properties will disqualify it.
     4726 *
     4727 * When using the `$field` argument, this function can also retrieve
     4728 * a particular field from all matching objects, whereas wp_list_filter()
     4729 * only does the filtering.
     4730 *
    47204731 * @since 3.0.0
    47214732 * @since 4.7.0 Uses `WP_List_Util` class.
    47224733 *
    4723  * @param array       $list     An array of objects to filter
     4734 * @param array       $list     An array of objects to filter.
    47244735 * @param array       $args     Optional. An array of key => value arguments to match
    47254736 *                              against each object. Default empty array.
    4726  * @param string      $operator Optional. The logical operation to perform. 'or' means
    4727  *                              only one element from the array needs to match; 'and'
    4728  *                              means all elements must match; 'not' means no elements may
    4729  *                              match. Default 'and'.
    4730  * @param bool|string $field    A field from the object to place instead of the entire object.
    4731  *                              Default false.
     4737 * @param string      $operator Optional. The logical operation to perform. 'AND' means
     4738 *                              all elements from the array must match. 'OR' means only
     4739 *                              one element needs to match. 'NOT' means no elements may
     4740 *                              match. Default 'AND'.
     4741 * @param bool|string $field    Optional. A field from the object to place instead
     4742 *                              of the entire object. Default false.
    47324743 * @return array A list of objects or object fields.
    47334744 */
     
    47504761/**
    47514762 * Filters a list of objects, based on a set of key => value arguments.
     4763 *
     4764 * Retrieves the objects from the list that match the given arguments.
     4765 * Key represents property name, and value represents property value.
     4766 *
     4767 * If an object has more properties than those specified in arguments,
     4768 * that will not disqualify it. When using the 'AND' operator,
     4769 * any missing properties will disqualify it.
     4770 *
     4771 * If you want to retrieve a particular field from all matching objects,
     4772 * use wp_filter_object_list() instead.
    47524773 *
    47534774 * @since 3.1.0
     
    47694790
    47704791    $util = new WP_List_Util( $list );
     4792
    47714793    return $util->filter( $args, $operator );
    47724794}
     
    47824804 * @since 4.7.0 Uses `WP_List_Util` class.
    47834805 *
    4784  * @param array      $list      List of objects or arrays
    4785  * @param int|string $field     Field from the object to place instead of the entire object
     4806 * @param array      $list      List of objects or arrays.
     4807 * @param int|string $field     Field from the object to place instead of the entire object.
    47864808 * @param int|string $index_key Optional. Field from the object to use as keys for the new array.
    47874809 *                              Default null.
     
    47924814function wp_list_pluck( $list, $field, $index_key = null ) {
    47934815    $util = new WP_List_Util( $list );
     4816
    47944817    return $util->pluck( $field, $index_key );
    47954818}
     
    48144837
    48154838    $util = new WP_List_Util( $list );
     4839
    48164840    return $util->sort( $orderby, $order, $preserve_keys );
    48174841}
Note: See TracChangeset for help on using the changeset viewer.