General: Introduce a wp_list_sort() helper function, v2.

In addition to `wp_list_filter()` for filtering a list of objects, and `wp_list_pluck()` for plucking a certain field out of each object in a list, this new function can be used for sorting a list of objects by specific fields. These functions are now all contained within the new `WP_List_Util()` class and `wp_list_sort()` is used in various parts of core for sorting lists.

This was previously committed in [38859] but got reverted in [38862] and [38863]. To fix the previous issues, `wp_list_sort()` supports now an additional argument to preserve array keys via `uasort()`.

Props flixos90, DrewAPicture, jorbin.
Fixes #37128.

git-svn-id: https://develop.svn.wordpress.org/trunk@38928 602fd350-edb4-49c9-b593-d223f7449a82

src/wp-includes/deprecated.php

@@ -3798,3 +3798,83 @@ function wp_kses_js_entities( $string ) {
 
 	return preg_replace( '%&\s*\{[^}]*(\}\s*;?|$)%', '', $string );
 }
+
+/**
+ * Sort categories by ID.
+ *
+ * Used by usort() as a callback, should not be used directly. Can actually be
+ * used to sort any term object.
+ *
+ * @since 2.3.0
+ * @deprecated 4.7.0 Use wp_list_sort()
+ * @access private
+ *
+ * @param object $a
+ * @param object $b
+ * @return int
+ */
+function _usort_terms_by_ID( $a, $b ) {
+	_deprecated_function( __FUNCTION__, '4.7.0', 'wp_list_sort' );
+
+	if ( $a->term_id > $b->term_id )
+		return 1;
+	elseif ( $a->term_id < $b->term_id )
+		return -1;
+	else
+		return 0;
+}
+
+/**
+ * Sort categories by name.
+ *
+ * Used by usort() as a callback, should not be used directly. Can actually be
+ * used to sort any term object.
+ *
+ * @since 2.3.0
+ * @deprecated 4.7.0 Use wp_list_sort()
+ * @access private
+ *
+ * @param object $a
+ * @param object $b
+ * @return int
+ */
+function _usort_terms_by_name( $a, $b ) {
+	_deprecated_function( __FUNCTION__, '4.7.0', 'wp_list_sort' );
+
+	return strcmp( $a->name, $b->name );
+}
+
+/**
+ * Sort menu items by the desired key.
+ *
+ * @since 3.0.0
+ * @deprecated 4.7.0 Use wp_list_sort()
+ * @access private
+ *
+ * @global string $_menu_item_sort_prop
+ *
+ * @param object $a The first object to compare
+ * @param object $b The second object to compare
+ * @return int -1, 0, or 1 if $a is considered to be respectively less than, equal to, or greater than $b.
+ */
+function _sort_nav_menu_items( $a, $b ) {
+	global $_menu_item_sort_prop;
+
+	_deprecated_function( __FUNCTION__, '4.7.0', 'wp_list_sort' );
+
+	if ( empty( $_menu_item_sort_prop ) )
+		return 0;
+
+	if ( ! isset( $a->$_menu_item_sort_prop ) || ! isset( $b->$_menu_item_sort_prop ) )
+		return 0;
+
+	$_a = (int) $a->$_menu_item_sort_prop;
+	$_b = (int) $b->$_menu_item_sort_prop;
+
+	if ( $a->$_menu_item_sort_prop == $b->$_menu_item_sort_prop )
+		return 0;
+	elseif ( $_a == $a->$_menu_item_sort_prop && $_b == $b->$_menu_item_sort_prop )
+		return $_a < $_b ? -1 : 1;
+	else
+		return strcmp( $a->$_menu_item_sort_prop, $b->$_menu_item_sort_prop );
+}