<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<title>Sort an array by values using a user-defined comparison function</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="function.uksort.html">uksort</a></div>
<div class="next" style="text-align: right; float: right;"><a href="book.classobj.html">Classes/Objects</a></div>
<div class="up"><a href="ref.array.html">Array Functions</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="function.usort" class="refentry">
<div class="refnamediv">
<h1 class="refname">usort</h1>
<p class="verinfo">(PHP 4, PHP 5)</p><p class="refpurpose"><span class="refname">usort</span> — <span class="dc-title">Sort an array by values using a user-defined comparison function</span></p>
</div>
<div class="refsect1 description" id="refsect1-function.usort-description">
<h3 class="title">Description</h3>
<div class="methodsynopsis dc-description">
<span class="type">bool</span> <span class="methodname"><strong>usort</strong></span>
( <span class="methodparam"><span class="type">array</span> <code class="parameter reference">&$array</code></span>
, <span class="methodparam"><span class="type"><a href="language.types.callable.html" class="type callable">callable</a></span> <code class="parameter">$value_compare_func</code></span>
)</div>
<p class="para rdfs-comment">
This function will sort an array by its values using a user-supplied
comparison function. If the array you wish to sort needs to be sorted by
some non-trivial criteria, you should use this function.
</p>
<blockquote class="note"><p><strong class="note">Note</strong>:
<p class="para">
If two members compare as equal, their relative order in the sorted array is undefined.
</p>
</p></blockquote>
<blockquote class="note"><p><strong class="note">Note</strong>: <span class="simpara">This function
assigns new keys to the elements in <em><code class="parameter">array</code></em>.
It will remove any existing keys that may have been assigned, rather
than just reordering the keys.</span></p></blockquote>
</div>
<div class="refsect1 parameters" id="refsect1-function.usort-parameters">
<h3 class="title">Parameters</h3>
<p class="para">
<dl>
<dt>
<span class="term"><em><code class="parameter">array</code></em></span>
<dd>
<p class="para">
The input array.
</p>
</dd>
</dt>
<dt>
<span class="term"><em><code class="parameter">value_compare_func</code></em></span>
<dd>
<p class="para">
The comparison function must return an integer less than, equal to, or greater than zero if the first argument is considered to be respectively less than, equal to, or greater than the second.
</p>
<div class="methodsynopsis dc-description"><span class="type">int</span> <span class="methodname"><span class="replaceable">callback</span></span> ( <span class="methodparam"><span class="type"><a href="language.pseudo-types.html#language.types.mixed" class="type mixed">mixed</a></span> <code class="parameter">$a</code></span>, <span class="methodparam"><span class="type"><a href="language.pseudo-types.html#language.types.mixed" class="type mixed">mixed</a></span> <code class="parameter">$b</code></span> )</div>
<div class="caution"><strong class="caution">Caution</strong>
<p class="para">
Returning <em class="emphasis">non-integer</em> values from the comparison
function, such as <span class="type"><a href="language.types.float.html" class="type float">float</a></span>, will result in an internal cast to
<span class="type"><a href="language.types.integer.html" class="type integer">integer</a></span> of the callback's return value. So values such as
0.99 and 0.1 will both be cast to an integer value of 0, which will
compare such values as equal.
</p>
</div>
</dd>
</dt>
</dl>
</p>
</div>
<div class="refsect1 returnvalues" id="refsect1-function.usort-returnvalues">
<h3 class="title">Return Values</h3>
<p class="para">
Returns <strong><code>TRUE</code></strong> on success or <strong><code>FALSE</code></strong> on failure.
</p>
</div>
<div class="refsect1 changelog" id="refsect1-function.usort-changelog">
<h3 class="title">Changelog</h3>
<p class="para">
<table class="doctable informaltable">
<thead>
<tr>
<th>Version</th>
<th>Description</th>
</tr>
</thead>
<tbody class="tbody">
<tr>
<td>4.1.0</td>
<td>
A new sort algorithm was introduced. The <em><code class="parameter">value_compare_func</code></em>
doesn't keep the original order for elements comparing as equal.
</td>
</tr>
</tbody>
</table>
</p>
</div>
<div class="refsect1 examples" id="refsect1-function.usort-examples">
<h3 class="title">Examples</h3>
<p class="para">
<div class="example" id="function.usort.examples.basic">
<p><strong>Example #1 <span class="function"><strong>usort()</strong></span> example</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /></span><span style="color: #007700">function </span><span style="color: #0000BB">cmp</span><span style="color: #007700">(</span><span style="color: #0000BB">$a</span><span style="color: #007700">, </span><span style="color: #0000BB">$b</span><span style="color: #007700">)<br />{<br /> if (</span><span style="color: #0000BB">$a </span><span style="color: #007700">== </span><span style="color: #0000BB">$b</span><span style="color: #007700">) {<br /> return </span><span style="color: #0000BB">0</span><span style="color: #007700">;<br /> }<br /> return (</span><span style="color: #0000BB">$a </span><span style="color: #007700">< </span><span style="color: #0000BB">$b</span><span style="color: #007700">) ? -</span><span style="color: #0000BB">1 </span><span style="color: #007700">: </span><span style="color: #0000BB">1</span><span style="color: #007700">;<br />}<br /><br /></span><span style="color: #0000BB">$a </span><span style="color: #007700">= array(</span><span style="color: #0000BB">3</span><span style="color: #007700">, </span><span style="color: #0000BB">2</span><span style="color: #007700">, </span><span style="color: #0000BB">5</span><span style="color: #007700">, </span><span style="color: #0000BB">6</span><span style="color: #007700">, </span><span style="color: #0000BB">1</span><span style="color: #007700">);<br /><br /></span><span style="color: #0000BB">usort</span><span style="color: #007700">(</span><span style="color: #0000BB">$a</span><span style="color: #007700">, </span><span style="color: #DD0000">"cmp"</span><span style="color: #007700">);<br /><br />foreach (</span><span style="color: #0000BB">$a </span><span style="color: #007700">as </span><span style="color: #0000BB">$key </span><span style="color: #007700">=> </span><span style="color: #0000BB">$value</span><span style="color: #007700">) {<br /> echo </span><span style="color: #DD0000">"</span><span style="color: #0000BB">$key</span><span style="color: #DD0000">: </span><span style="color: #0000BB">$value</span><span style="color: #DD0000">\n"</span><span style="color: #007700">;<br />}<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
<div class="example-contents"><p>The above example will output:</p></div>
<div class="example-contents screen">
<div class="cdata"><pre>
0: 1
1: 2
2: 3
3: 5
4: 6
</pre></div>
</div>
</div>
</p>
<blockquote class="note"><p><strong class="note">Note</strong>:
<p class="para">
Obviously in this trivial case the <span class="function"><a href="function.sort.html" class="function">sort()</a></span>
function would be more appropriate.
</p>
</p></blockquote>
<p class="para">
<div class="example" id="function.usort.examples.multi">
<p><strong>Example #2
<span class="function"><strong>usort()</strong></span> example using multi-dimensional array
</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /></span><span style="color: #007700">function </span><span style="color: #0000BB">cmp</span><span style="color: #007700">(</span><span style="color: #0000BB">$a</span><span style="color: #007700">, </span><span style="color: #0000BB">$b</span><span style="color: #007700">)<br />{<br /> return </span><span style="color: #0000BB">strcmp</span><span style="color: #007700">(</span><span style="color: #0000BB">$a</span><span style="color: #007700">[</span><span style="color: #DD0000">"fruit"</span><span style="color: #007700">], </span><span style="color: #0000BB">$b</span><span style="color: #007700">[</span><span style="color: #DD0000">"fruit"</span><span style="color: #007700">]);<br />}<br /><br /></span><span style="color: #0000BB">$fruits</span><span style="color: #007700">[</span><span style="color: #0000BB">0</span><span style="color: #007700">][</span><span style="color: #DD0000">"fruit"</span><span style="color: #007700">] = </span><span style="color: #DD0000">"lemons"</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">$fruits</span><span style="color: #007700">[</span><span style="color: #0000BB">1</span><span style="color: #007700">][</span><span style="color: #DD0000">"fruit"</span><span style="color: #007700">] = </span><span style="color: #DD0000">"apples"</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">$fruits</span><span style="color: #007700">[</span><span style="color: #0000BB">2</span><span style="color: #007700">][</span><span style="color: #DD0000">"fruit"</span><span style="color: #007700">] = </span><span style="color: #DD0000">"grapes"</span><span style="color: #007700">;<br /><br /></span><span style="color: #0000BB">usort</span><span style="color: #007700">(</span><span style="color: #0000BB">$fruits</span><span style="color: #007700">, </span><span style="color: #DD0000">"cmp"</span><span style="color: #007700">);<br /><br />while (list(</span><span style="color: #0000BB">$key</span><span style="color: #007700">, </span><span style="color: #0000BB">$value</span><span style="color: #007700">) = </span><span style="color: #0000BB">each</span><span style="color: #007700">(</span><span style="color: #0000BB">$fruits</span><span style="color: #007700">)) {<br /> echo </span><span style="color: #DD0000">"\$fruits[</span><span style="color: #0000BB">$key</span><span style="color: #DD0000">]: " </span><span style="color: #007700">. </span><span style="color: #0000BB">$value</span><span style="color: #007700">[</span><span style="color: #DD0000">"fruit"</span><span style="color: #007700">] . </span><span style="color: #DD0000">"\n"</span><span style="color: #007700">;<br />}<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
<div class="example-contents"><p>
When sorting a multi-dimensional array, <var class="varname"><var class="varname">$a</var></var> and
<var class="varname"><var class="varname">$b</var></var> contain references to the first index of the array.
</p></div>
<div class="example-contents"><p>The above example will output:</p></div>
<div class="example-contents screen">
<div class="cdata"><pre>
$fruits[0]: apples
$fruits[1]: grapes
$fruits[2]: lemons
</pre></div>
</div>
</div>
</p>
<p class="para">
<div class="example" id="function.usort.examples.object">
<p><strong>Example #3
<span class="function"><strong>usort()</strong></span> example using a member function of an object
</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /></span><span style="color: #007700">class </span><span style="color: #0000BB">TestObj </span><span style="color: #007700">{<br /> var </span><span style="color: #0000BB">$name</span><span style="color: #007700">;<br /><br /> function </span><span style="color: #0000BB">TestObj</span><span style="color: #007700">(</span><span style="color: #0000BB">$name</span><span style="color: #007700">)<br /> {<br /> </span><span style="color: #0000BB">$this</span><span style="color: #007700">-></span><span style="color: #0000BB">name </span><span style="color: #007700">= </span><span style="color: #0000BB">$name</span><span style="color: #007700">;<br /> }<br /><br /> </span><span style="color: #FF8000">/* This is the static comparing function: */<br /> </span><span style="color: #007700">static function </span><span style="color: #0000BB">cmp_obj</span><span style="color: #007700">(</span><span style="color: #0000BB">$a</span><span style="color: #007700">, </span><span style="color: #0000BB">$b</span><span style="color: #007700">)<br /> {<br /> </span><span style="color: #0000BB">$al </span><span style="color: #007700">= </span><span style="color: #0000BB">strtolower</span><span style="color: #007700">(</span><span style="color: #0000BB">$a</span><span style="color: #007700">-></span><span style="color: #0000BB">name</span><span style="color: #007700">);<br /> </span><span style="color: #0000BB">$bl </span><span style="color: #007700">= </span><span style="color: #0000BB">strtolower</span><span style="color: #007700">(</span><span style="color: #0000BB">$b</span><span style="color: #007700">-></span><span style="color: #0000BB">name</span><span style="color: #007700">);<br /> if (</span><span style="color: #0000BB">$al </span><span style="color: #007700">== </span><span style="color: #0000BB">$bl</span><span style="color: #007700">) {<br /> return </span><span style="color: #0000BB">0</span><span style="color: #007700">;<br /> }<br /> return (</span><span style="color: #0000BB">$al </span><span style="color: #007700">> </span><span style="color: #0000BB">$bl</span><span style="color: #007700">) ? +</span><span style="color: #0000BB">1 </span><span style="color: #007700">: -</span><span style="color: #0000BB">1</span><span style="color: #007700">;<br /> }<br />}<br /><br /></span><span style="color: #0000BB">$a</span><span style="color: #007700">[] = new </span><span style="color: #0000BB">TestObj</span><span style="color: #007700">(</span><span style="color: #DD0000">"c"</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$a</span><span style="color: #007700">[] = new </span><span style="color: #0000BB">TestObj</span><span style="color: #007700">(</span><span style="color: #DD0000">"b"</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$a</span><span style="color: #007700">[] = new </span><span style="color: #0000BB">TestObj</span><span style="color: #007700">(</span><span style="color: #DD0000">"d"</span><span style="color: #007700">);<br /><br /></span><span style="color: #0000BB">usort</span><span style="color: #007700">(</span><span style="color: #0000BB">$a</span><span style="color: #007700">, array(</span><span style="color: #DD0000">"TestObj"</span><span style="color: #007700">, </span><span style="color: #DD0000">"cmp_obj"</span><span style="color: #007700">));<br /><br />foreach (</span><span style="color: #0000BB">$a </span><span style="color: #007700">as </span><span style="color: #0000BB">$item</span><span style="color: #007700">) {<br /> echo </span><span style="color: #0000BB">$item</span><span style="color: #007700">-></span><span style="color: #0000BB">name </span><span style="color: #007700">. </span><span style="color: #DD0000">"\n"</span><span style="color: #007700">;<br />}<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
<div class="example-contents"><p>The above example will output:</p></div>
<div class="example-contents screen">
<div class="cdata"><pre>
b
c
d
</pre></div>
</div>
</div>
<div class="example" id="function.usort.examples.closure">
<p><strong>Example #4
<span class="function"><strong>usort()</strong></span> example using a <a href="functions.anonymous.html" class="link">closure</a>
to sort a multi-dimensional array
</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br />$array</span><span style="color: #007700">[</span><span style="color: #0000BB">0</span><span style="color: #007700">] = array(</span><span style="color: #DD0000">'key_a' </span><span style="color: #007700">=> </span><span style="color: #DD0000">'z'</span><span style="color: #007700">, </span><span style="color: #DD0000">'key_b' </span><span style="color: #007700">=> </span><span style="color: #DD0000">'c'</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$array</span><span style="color: #007700">[</span><span style="color: #0000BB">1</span><span style="color: #007700">] = array(</span><span style="color: #DD0000">'key_a' </span><span style="color: #007700">=> </span><span style="color: #DD0000">'x'</span><span style="color: #007700">, </span><span style="color: #DD0000">'key_b' </span><span style="color: #007700">=> </span><span style="color: #DD0000">'b'</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$array</span><span style="color: #007700">[</span><span style="color: #0000BB">2</span><span style="color: #007700">] = array(</span><span style="color: #DD0000">'key_a' </span><span style="color: #007700">=> </span><span style="color: #DD0000">'y'</span><span style="color: #007700">, </span><span style="color: #DD0000">'key_b' </span><span style="color: #007700">=> </span><span style="color: #DD0000">'a'</span><span style="color: #007700">);<br /><br />function </span><span style="color: #0000BB">build_sorter</span><span style="color: #007700">(</span><span style="color: #0000BB">$key</span><span style="color: #007700">) {<br /> return function (</span><span style="color: #0000BB">$a</span><span style="color: #007700">, </span><span style="color: #0000BB">$b</span><span style="color: #007700">) use (</span><span style="color: #0000BB">$key</span><span style="color: #007700">) {<br /> return </span><span style="color: #0000BB">strnatcmp</span><span style="color: #007700">(</span><span style="color: #0000BB">$a</span><span style="color: #007700">[</span><span style="color: #0000BB">$key</span><span style="color: #007700">], </span><span style="color: #0000BB">$b</span><span style="color: #007700">[</span><span style="color: #0000BB">$key</span><span style="color: #007700">]);<br /> };<br />}<br /><br /></span><span style="color: #0000BB">usort</span><span style="color: #007700">(</span><span style="color: #0000BB">$array</span><span style="color: #007700">, </span><span style="color: #0000BB">build_sorter</span><span style="color: #007700">(</span><span style="color: #DD0000">'key_b'</span><span style="color: #007700">));<br /><br />foreach (</span><span style="color: #0000BB">$array </span><span style="color: #007700">as </span><span style="color: #0000BB">$item</span><span style="color: #007700">) {<br /> echo </span><span style="color: #0000BB">$item</span><span style="color: #007700">[</span><span style="color: #DD0000">'key_a'</span><span style="color: #007700">] . </span><span style="color: #DD0000">', ' </span><span style="color: #007700">. </span><span style="color: #0000BB">$item</span><span style="color: #007700">[</span><span style="color: #DD0000">'key_b'</span><span style="color: #007700">] . </span><span style="color: #DD0000">"\n"</span><span style="color: #007700">;<br />}<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
<div class="example-contents"><p>The above example will output:</p></div>
<div class="example-contents screen">
<div class="cdata"><pre>
y, a
x, b
z, c
</pre></div>
</div>
</div>
</p>
</div>
<div class="refsect1 seealso" id="refsect1-function.usort-seealso">
<h3 class="title">See Also</h3>
<p class="para">
<ul class="simplelist">
<li class="member"> <span class="function"><a href="function.uasort.html" class="function" rel="rdfs-seeAlso">uasort()</a> - Sort an array with a user-defined comparison function and maintain index association</span></li>
<li class="member">The <a href="array.sorting.html" class="link">comparison of array sorting functions</a></li>
</ul>
</p>
</div>
</div><hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="function.uksort.html">uksort</a></div>
<div class="next" style="text-align: right; float: right;"><a href="book.classobj.html">Classes/Objects</a></div>
<div class="up"><a href="ref.array.html">Array Functions</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
