# La clase Collator

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

## Introducción

Proporciona la capacidad de comparar strings, con soporte para una ordenación apropiada, según la región.

## Sinopsis de la Clase

class Collator {
/* Métodos */
public __construct(string `$locale`)
public asort(array `&$arr`, int `$sort_flag` = ?): bool
collator_asort(Collator `$coll`, array `&$arr`, int `$sort_flag` = ?): bool
public compare(string `$str1`, string `$str2`): int
collator_compare(Collator `$coll`, string `$str1`, string `$str2`): int
public static create(string `$locale`): Collator
collator_create(string `$locale`): Collator
public getAttribute(int `$attr`): int
collator_get_attribute(Collator `$coll`, int `$attr`): int
public getErrorCode(): int|false
public getErrorMessage(): string|false
public getLocale(int `$type`): string
collator_get_locale(Collator `$coll`, int `$type`): string
public getSortKey(string `$str`): string
collator_get_sort_key(Collator `$coll`, string `$str`): string
public getStrength(): int
collator_get_strength(Collator `$coll`): int
public setAttribute(int `$attr`, int `$val`): bool
collator_set_attribute(Collator `$coll`, int `$attr`, int `$val`): bool
public setStrength(int `$strength`): bool
collator_set_strength(Collator `$coll`, int `$strength`): bool
public sortWithSortKeys(array `&$array`): bool
public sort(array `&$array`, int `$flags` = Collator::SORT_REGULAR): bool
}

## Constantes predefinidas

`Collator::FRENCH_COLLATION` (integer)

  Ordenar cadenas con diferentes acentos. Este atributo es establecido automáticamente a On para los identificadores regionales franceses y unos pocos más. Los usuarios normalmente no necesitarán establecer explicitamente este atributo. Existe un coste de rendimiento en la comparación de cadenas cuando se establece a On, excepto para la longitud de la clave de ordenación, que no se ve afectada. Los valores posibles son:

  - `Collator::ON`
  - `Collator::OFF` (predeterminado)
  - `Collator::DEFAULT_VALUE`

  Ejemplo #1 Reglas de FRENCH_COLLATION

  - F=OFF cote < coté < côte < côté
  - F=ON cote < côte < coté < côté
`Collator::ALTERNATE_HANDLING` (integer)

  El atributo Alternate se usa para controlar el manejo de los también llamados caracters variables en el UCA: los espacios en blanco, de puntuación y símbolos. Si Alternate se establece a NonIgnorable (N), las diferencias entre estos caracteres son de la misma importancia que las diferencias entre letras. Si Alternate se establece a Shifted (S), estos caracteres son de menor importancia. El valor Shifted a menudo se usa en combinación con Strength establecido a Quaternary. En tal caso, los espacios en blanco, de puntuación y símbolos se consideran cuando se comparan las cadenas, pero sólo si todos los demás aspectos de las cadenas (letras base, acentos y si son mayúsculas/minúsculas) son idénticos. Si Alternate no se establece a Shifted, no existe ninguna diferencia entre un Strength de 3 y un Strength de 4. Para más información y algunos ejemplos véase Variable_Weighting en el » UCA. La razoón de que los valores de Alternate no sean simplemente On y Off es que se pueden añadir valores adicionales a Alternate en el futuro. La opción del UCA, Blanked, se expresa con Strength establecido a 3, y Alternate establecido a Shifted. Lo predeterminado para la mayoría de las configuraciones regionales es NonIgnorable. Si se selecciona Shifted, puede ser más lento si existen muchas cadenas que son la misma excepto por la puntuación; la longitud de la clave de ordenación no se verá afectada a menos que el nivel de fuerza (Strength) también sea aumentado.

  Los valores posibles son:

  - `Collator::NON_IGNORABLE` (predeterminado)
  - `Collator::SHIFTED`
  - `Collator::DEFAULT_VALUE`

  Ejemplo #2 Reglas de ALTERNATE_HANDLING

  - S=3, A=N di Silva < Di Silva < diSilva < U.S.A. < USA
  - S=3, A=S di Silva = diSilva < Di Silva < U.S.A. = USA
  - S=4, A=S di Silva < diSilva < Di Silva < U.S.A. < USA
`Collator::CASE_FIRST` (integer)

  El atributo Case_First se usa para controlar si las letras mayúsculas van antes que las minúsculas o viceversa, en ausencia de otras diferencias en las cadenas. Los valores posibles son Uppercase_First (U) y Lowercase_First (L), más el estándar Default y Off. No existe casi ninguna diferencia entre las opciones Off y Lowercase_First en términos de resultados, por lo que normalmente los usuarios no usarán Lowercase_First: solamente Off o Uppercase_First. (Los interesados en los detalles de las diferencias entre X y L deberían consultar la `Personalización del Cotejo`). Especificar L o U no afectará al rendimiento de la comparación de cadenas, pero afectará a la longitud de la clave de ordenación.

  Los valores posibles son:

  - `Collator::OFF` (predeterminado)
  - `Collator::LOWER_FIRST`
  - `Collator::UPPER_FIRST`
  - `Collator:DEFAULT`

  Ejemplo #3 Reglas de CASE_FIRST

  - C=X or C=L "china" < "China" < "denmark" < "Denmark"
  - C=U "China" < "china" < "Denmark" < "denmark"
`Collator::CASE_LEVEL` (integer)

  El atributo Case_Level se usa para cuando en el texto se quieren ignorar los acentos pero no si son mayúsculas/minúsculas. En tal situación, se establece Strength a Primary, y Case_Level a On. En la mayoría de las configuraciones regionales, este ajuste está establecido a Off por omision. Existe un pequeño impacto en el rendimiento de comparación de cadenas y en la ordenación por clave si este atributo se establece a On.

  Los valores posibles son:

  - `Collator::OFF` (predeterminado)
  - `Collator::ON`
  - `Collator::DEFAULT_VALUE`

  Ejemplo #4 Reglas de CASE_LEVEL

  - S=1, E=X role = Role = rôle
  - S=1, E=O role = rôle < Role
`Collator::NORMALIZATION_MODE` (integer)

  El ajuste Normalization determina si el texto se normaliza por completo o no en la comparación. Incluso si el ajuste está desactivado (lo predeterminado en muchas configuraciones regionales), el texto representado en su uso común se comparará correctamente (para más detalles, véase UTN #5). Solamente si los acentos están en orden no canónico existirá un problema. Si el ajuste se establece a On, se garantizan los mejores resultados para todas las posibles entradas de texto. Existe un coste medio de rendimiento en la comparación de cadenas si este atributo se establece a On, dependiendo de la frecuencia de secuencias que requiera la normalización. No hay un efecto significativo en la longitud de la clave de ordenación. Si el texto de entrada se sabe que está en la forma de normalización NFD o NFKD, no hay necesidad de habilitar esta opción Normalization.

  Los valores posibles son:

  - `Collator::OFF` (predeterminado)
  - `Collator::ON`
  - `Collator::DEFAULT_VALUE`
`Collator::STRENGTH` (integer)

  El Servicio de Cotejo de ICU soporta muchos niveles de comparación (llamados "Levels", pero también conocidos como "Strengths"). Tener estas categorías habilita a ICU para ordenar cadenas de manera precisa según las convenciones regionales. Sin embargo, al permitir que los niveles sean empleados selectivamente, la búsqueda de una cadena en un texto se podrá realizar con varias condiciones de coincidencia. Para una información más detallada, véase el capítlo collator_set_strength().

  Los valores posibles son:

  - `Collator::PRIMARY`
  - `Collator::SECONDARY`
  - `Collator::TERTIARY` (predeterminado)
  - `Collator::QUATERNARY`
  - `Collator::IDENTICAL`
  - `Collator::DEFAULT_VALUE`
`Collator::HIRAGANA_QUATERNARY_MODE` (integer)

  La compatibilidad con JIS x 4061 requiere la introducción de un nivel adinional para poder distinguir entre caracteres Hiragana y Katakana. Si se necesita compatibilidad con el estándar, este atributo debería establecerse a On y la fuerza (strength) a Quaternary. Esto afectará a la longitud de la clave de ordenación y al rendimiento en la comparación de cadenas.

  Los valores posibles son:

  - `Collator::OFF` (predeterminado)
  - `Collator::ON`
  - `Collator::DEFAULT_VALUE`
`Collator::NUMERIC_COLLATION` (integer)

  Cuando se activa, este atributo genera una clave de cotejo para el valor numérico de subcadenas de dígitos. Es una manera de obtener '100' DESPUÉS de '2' en una ordenación

  Los valores posibles son:

  - `Collator::OFF` (predeterminado)
  - `Collator::ON`
  - `Collator::DEFAULT_VALUE`
`Collator::DEFAULT_VALUE` (integer)
`Collator::PRIMARY` (integer)
`Collator::SECONDARY` (integer)
`Collator::TERTIARY` (integer)
`Collator::DEFAULT_STRENGTH` (integer)
`Collator::QUATERNARY` (integer)
`Collator::IDENTICAL` (integer)
`Collator::OFF` (integer)
`Collator::ON` (integer)
`Collator::SHIFTED` (integer)
`Collator::NON_IGNORABLE` (integer)
`Collator::LOWER_FIRST` (integer)
`Collator::UPPER_FIRST` (integer)

## Tabla de contenidos

- Collator::asort — Ordenar un array manteniendo la relación de índices
- Collator::compare — Comparar dos cadenas Unicode
- Collator::__construct — Crear un objeto Collator
- Collator::create — Crear un cotejador
- Collator::getAttribute — Obtener el valor de un atributo de cotejo
- Collator::getErrorCode — Obtener el último código de error del cotejeador
- Collator::getErrorMessage — Obtener el texto del último código de error del cotejador
- Collator::getLocale — Obtener el nombre de la configuración regional del cotejador
- Collator::getSortKey — Obtener la clave de ordenación de una cadena
- Collator::getStrength — Obtener la fuerza de cotejo actual
- Collator::setAttribute — Establecer el atributo de cotejo
- Collator::setStrength — Establecer la fuerza (strength) de un cotejo
- Collator::sortWithSortKeys — Ordenar un array usando el cotejador y las claves de ordenación especificados
- Collator::sort — Ordenar un array usando cotejador especificado