<?xml version="1.0" encoding="utf-8"?>

<!-- EN-Revision: 5b7646656eb183ea568b8261d6d87a10a1b961c7 Maintainer: PhilDaiguille Status: ready -->

<!-- Reviewed: no -->

<!-- CREDITS: DavidA. -->

<refentry xml:id="function.array-multisort" xmlns="http://docbook.org/ns/docbook">

<refnamediv>

<refname>array_multisort</refname>

<refpurpose>Ordena los arrays multidimensionales</refpurpose>

</refnamediv>

<refsect1 role="description">

&reftitle.description;

<methodsynopsis>

<type>true</type><methodname>array_multisort</methodname>

<methodparam><type>array</type><parameter role="reference">array1</parameter></methodparam>

<methodparam choice="opt"><type>mixed</type><parameter>array1_sort_order</parameter><initializer>SORT_ASC</initializer></methodparam>

<methodparam choice="opt"><type>mixed</type><parameter>array1_sort_flags</parameter><initializer>SORT_REGULAR</initializer></methodparam>

<methodparam rep="repeat"><type>mixed</type><parameter>rest</parameter></methodparam>

</methodsynopsis>

<para>

<function>array_multisort</function> sirve para ordenar simultáneamente

varios arrays, o bien para ordenar un array multidimensional,

siguiendo una u otra de sus dimensiones.

</para>

<para>

Las claves asociativas (<type>string</type>) serán mantenidas, pero

las claves numéricas serán reindexadas.

</para>

&note.sort-unstable;

&note.reset-index;

</refsect1>

<refsect1 role="parameters">

&reftitle.parameters;

<para>

<variablelist>

<varlistentry>

<term><parameter>array1</parameter></term>

<listitem>

<para>

Un <type>array</type> a ordenar.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>array1_sort_order</parameter></term>

<listitem>

<para>

El orden utilizado para ordenar el argumento anterior

<type>array</type>. Puede ser la constante <constant>SORT_ASC</constant>

para ordenar de forma ascendente, o la constante

<constant>SORT_DESC</constant> para ordenar de forma descendente.

</para>

<para>

Este argumento puede ser asociado con el parámetro

<parameter>array1_sort_flags</parameter> o simplemente omitido,

en cuyo caso, la constante <constant>SORT_ASC</constant> será utilizada.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>array1_sort_flags</parameter></term>

<listitem>

<para>

Opciones de ordenación del argumento <type>array</type> anterior:

</para>

<para>

Tipo de opciones de ordenación:

<itemizedlist>

<listitem>

<simpara><constant>SORT_REGULAR</constant> - compara los elementos normalmente (sin cambio de tipo)</simpara>

</listitem>

<listitem>

<simpara><constant>SORT_NUMERIC</constant> - compara los elementos numéricamente</simpara>

</listitem>

<listitem>

<simpara><constant>SORT_STRING</constant> - compara los elementos como strings</simpara>

</listitem>

<listitem>

<simpara>

<constant>SORT_LOCALE_STRING</constant> - compara los elementos como strings,

basándose en la configuración local actual. La función utiliza las locales, y estas pueden ser modificadas

utilizando la función <function>setlocale</function>

</simpara>

</listitem>

<listitem>

<simpara>

<constant>SORT_NATURAL</constant> - compara los elementos como strings, utilizando

el "orden natural", como lo hace la función <function>natsort</function>

</simpara>

</listitem>

<listitem>

<simpara>

<constant>SORT_FLAG_CASE</constant> - puede ser combinado (con el operador OR) con

<constant>SORT_STRING</constant> o

<constant>SORT_NATURAL</constant> para ordenar los strings sin tener en cuenta la casilla

</simpara>

</listitem>

</itemizedlist>

</para>

<para>

Este argumento puede ser asociado con el parámetro <parameter>array1_sort_order</parameter>

o simplemente omitido, en cuyo caso, la constante <constant>SORT_REGULAR</constant> será utilizada.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>rest</parameter></term>

<listitem>

<para>

Más argumentos, opcionalmente seguidos por formas de ordenar y

flags. Solo los elementos equivalentes en los arrays anteriores

son comparados. En otras palabras, el ordenamiento es lexicográfico.

</para>

</listitem>

</varlistentry>

</variablelist>

</para>

</refsect1>

<refsect1 role="returnvalues">

&reftitle.returnvalues;

<para>

&return.true.always;

</para>

</refsect1>

<refsect1 role="changelog">

&reftitle.changelog;

<informaltable>

<tgroup cols="2">

<thead>

<row>

<entry>&Version;</entry>

<entry>&Description;</entry>

</row>

</thead>

<tbody>

<row>

<entry>8.5.0</entry>

<entry>

El tipo de retorno es ahora &true;; anteriormente, era <type>bool</type>.

</entry>

</row>

</tbody>

</tgroup>

</informaltable>

</refsect1>

<refsect1 role="examples">

&reftitle.examples;

<para>

<example>

<title>Ordenar varios arrays</title>

<programlisting role="php">

<![CDATA[

<?php

$ar1 = array(10, 100, 100, 0);

$ar2 = array(1, 3, 2, 4);

array_multisort($ar1, $ar2);

var_dump($ar1);

var_dump($ar2);

?>

]]>

</programlisting>

<para>

En este ejemplo, después del ordenamiento, el primer

array contiene 0, 10, 100, 100. El segundo array

contiene 4, 1, 2, 3. Las entradas del segundo array

correspondientes a los valores duplicados del primer

array (100 y 100), también son ordenadas.

</para>

<screen>

<![CDATA[

array(4) {

[0]=> int(0)

[1]=> int(10)

[2]=> int(100)

[3]=> int(100)

}

array(4) {

[0]=> int(4)

[1]=> int(1)

[2]=> int(2)

[3]=> int(3)

}

]]>

</screen>

</example>

</para>

<para>

<example>

<title>Ordenar un array multidimensional</title>

<programlisting role="php">

<![CDATA[

<?php

$ar = array(

array("10", 11, 100, 100, "a"),

array( 1, 2, "2", 3, 1)

);

array_multisort($ar[0], SORT_ASC, SORT_STRING,

$ar[1], SORT_NUMERIC, SORT_DESC);

var_dump($ar);

?>

]]>

</programlisting>

<para>

En este ejemplo, después del ordenamiento, el primer array contiene

"10", 100, 100, 11, "a" (orden alfabético, orden ascendente); El

segundo array contiene 1, 3, "2", 2, 1 (orden

numérico, orden descendente).

</para>

<screen>

<![CDATA[

array(2) {

[0]=> array(5) {

[0]=> string(2) "10"

[1]=> int(100)

[2]=> int(100)

[3]=> int(11)

[4]=> string(1) "a"

}

[1]=> array(5) {

[0]=> int(1)

[1]=> int(3)

[2]=> string(1) "2"

[3]=> int(2)

[4]=> int(1)

}

}

]]>

</screen>

</example>

</para>

<para>

<example>

<title>Ordenar los resultados de una base de datos</title>

<para>

En este ejemplo, cada elemento del array <varname>data</varname>

representa una fila de la tabla. Este tipo de datos es típico de un

registro de base de datos.

</para>

<para>

Ejemplo de datos:

</para>

<screen>

<![CDATA[

volume | edition

-------+--------

67 | 2

86 | 1

85 | 6

98 | 2

86 | 6

67 | 7

]]>

</screen>

<para>

Los datos están en forma de array, llamado <varname>data</varname>.

Esto es generalmente el resultado, por ejemplo, de la función

<function>mysqli_fetch_assoc</function>.

</para>

<para>

En este ejemplo, vamos a ordenar la columna

<varname>volume</varname> en orden descendente, y

la columna <varname>edition</varname> en orden ascendente.

</para>

<para>

Tenemos un array de filas, pero

<function>array_multisort</function> requiere un array de columnas,

por lo tanto utilizamos el siguiente código para obtener las columnas y

así realizar el ordenamiento.

</para>

<programlisting role="php">

<![CDATA[

<?php

// Los datos son creados recorriendo mysqli_fetch_assoc:

$data[] = array('volume' => 67, 'edition' => 2);

$data[] = array('volume' => 86, 'edition' => 1);

$data[] = array('volume' => 85, 'edition' => 6);

$data[] = array('volume' => 98, 'edition' => 2);

$data[] = array('volume' => 86, 'edition' => 6);

$data[] = array('volume' => 67, 'edition' => 7);

// Obtiene una lista de columnas

foreach ($data as $key => $row) {

$volume[$key] = $row['volume'];

$edition[$key] = $row['edition'];

}

// Puede utilizarse array_column() en lugar del código anterior

$volume = array_column($data, 'volume');

$edition = array_column($data, 'edition');

// Ordena los datos por volume descendente, edition ascendente

// Añade $data como último parámetro, para ordenar por la clave común

array_multisort($volume, SORT_DESC, $edition, SORT_ASC, $data);

// Recorre los datos y muestra los valores ordenados para cada columna

echo 'volume | edition', PHP_EOL;

echo '-------+--------', PHP_EOL;

for ($i = 0; $i < count($data); $i++) {

printf("%6d | %7d\n", $volume[$i], $edition[$i]);

}

?>

]]>

</programlisting>

<para>

El conjunto de registros ahora está ordenado y se ve así:

</para>

<screen>

<![CDATA[

volume | edition

-------+--------

98 | 2

86 | 1

86 | 6

85 | 6

67 | 2

67 | 7

]]>

</screen>

</example>

</para>

<para>

<example>

<title>Ordenamiento no sensible a la casilla</title>

<para>

<constant>SORT_STRING</constant> y

<constant>SORT_REGULAR</constant> son sensibles a la casilla, los strings

que comienzan con una letra mayúscula vendrán antes

que los strings que comienzan con una letra minúscula.

</para>

<para>

Para realizar un ordenamiento no sensible a la casilla, realice el ordenamiento

sobre una copia en minúsculas de las columnas del array original.

</para>

<programlisting role="php">

<![CDATA[

<?php

$array = array('Alpha', 'atomic', 'Beta', 'bank');

$array_lowercase = array_map('strtolower', $array);

array_multisort($array_lowercase, SORT_ASC, SORT_STRING, $array);

print_r($array);

?>

]]>

</programlisting>

&example.outputs;

<screen>

<![CDATA[

Array

(

[0] => Alpha

[1] => atomic

[2] => bank

[3] => Beta

)

]]>

</screen>

</example>

</para>

</refsect1>

<refsect1 role="seealso">

&reftitle.seealso;

<para>

<simplelist>

<member><function>usort</function></member>

<member>&seealso.array.sorting;</member>

</simplelist>

</para>

</refsect1>

</refentry>

<!-- Keep this comment at the end of the file

Local variables:

mode: sgml

sgml-omittag:t

sgml-shorttag:t

sgml-minimize-attributes:nil

sgml-always-quote-attributes:t

sgml-indent-step:1

sgml-indent-data:t

indent-tabs-mode:nil

sgml-parent-document:nil

sgml-default-dtd-file:"~/.phpdoc/manual.ced"

sgml-exposed-tags:nil

sgml-local-catalogs:nil

sgml-local-ecat-files:nil

End:

vim600: syn=xml fen fdm=syntax fdl=2 si

vim: et tw=78 syn=sgml

vi: ts=1 sw=1

-->