hphp/runtime/ext/icu/ext_icu_collator.php

   1 <?hh // partial
   2
   3 /**
   4  * Provides string comparison capability with support for appropriate
   5  * locale-sensitive sort orderings.
   6  */
   7 <<__NativeData("Collator")>>
   8 class Collator {
   9   /**
  10    * Construct a new Collator instance
  11    */
  12   <<__Native>>
  13   public function __construct(string $locale): void;
  14
  15   /**
  16    * Sort array maintaining index association
  17    *
  18    * @param array $arr - Array of strings to sort.
  19    * @param int $sort_flag - Optional sorting type, one of the following:
  20    *      Collator::SORT_REGULAR - compare items normally (don't change
  21    *   types)     Collator::SORT_NUMERIC - compare items numerically
  22    *   Collator::SORT_STRING - compare items as strings      Default
  23    *   $sort_flag value is Collator::SORT_REGULAR. It is also used if an
  24    *   invalid $sort_flag value has been specified.
  25    *
  26    * @return bool -
  27    */
  28   <<__Native>>
  29   public function asort(inout mixed $arr,
  30                         int $sort_flag = Collator::SORT_REGULAR): bool;
  31
  32   /**
  33    * Compare two Unicode strings
  34    *
  35    * @param string $str1 - The first string to compare.
  36    * @param string $str2 - The second string to compare.
  37    *
  38    * @return int - Return comparison result:     1 if str1 is greater
  39    *   than str2 ;     0 if str1 is equal to str2;     -1 if str1 is less
  40    *   than str2 .    On error boolean FALSE is returned.
  41    */
  42   <<__Native>>
  43   public function compare(mixed $str1,
  44                           mixed $str2): mixed;
  45
  46   /**
  47    * Create a collator
  48    *
  49    * @param string $locale - The locale containing the required collation
  50    *   rules. Special values for locales can be passed in - if null is
  51    *   passed for the locale, the default locale collation rules will be
  52    *   used. If empty string ("") or "root" are passed, UCA rules will be
  53    *   used.
  54    *
  55    * @return Collator - Return new instance of Collator object, or NULL
  56    *   on error.
  57    */
  58   public static function create(string $locale): Collator {
  59     return new Collator($locale);
  60   }
  61
  62   /**
  63    * Get collation attribute value
  64    *
  65    * @param int $attr - Attribute to get value for.
  66    *
  67    * @return int - Attribute value, or boolean FALSE on error.
  68    */
  69   <<__Native>>
  70   public function getAttribute(int $attr): int;
  71
  72   /**
  73    * Get collator's last error code
  74    *
  75    * @return int - Error code returned by the last Collator API function
  76    *   call.
  77    */
  78   <<__Native>>
  79   public function getErrorCode(): int;
  80
  81   /**
  82    * Get text for collator's last error code
  83    *
  84    * @return string - Description of an error occurred in the last
  85    *   Collator API function call.
  86    */
  87   <<__Native>>
  88   public function getErrorMessage(): string;
  89
  90   /**
  91    * Get the locale name of the collator
  92    *
  93    * @param int $type - You can choose between valid and actual locale (
  94    *   Locale::VALID_LOCALE and Locale::ACTUAL_LOCALE, respectively).
  95    *
  96    * @return string - Real locale name from which the collation data
  97    *   comes. If the collator was instantiated from rules or an error
  98    *   occurred, returns boolean FALSE.
  99    */
 100   <<__Native>>
 101   public function getLocale(int $type): string;
 102
 103   /**
 104    * Get sorting key for a string
 105    *
 106    * @param string $str - The string to produce the key from.
 107    *
 108    * @return string - Returns the collation key for the string. Collation
 109    *   keys can be compared directly instead of strings.
 110    */
 111   <<__Native>>
 112   public function getSortKey(string $str): mixed;
 113
 114   /**
 115    * Get current collation strength
 116    *
 117    * @return int - Returns current collation strength, or boolean FALSE
 118    *   on error.
 119    */
 120   <<__Native>>
 121   public function getStrength(): int;
 122
 123   /**
 124    * Set collation attribute
 125    *
 126    * @param int $attr - Attribute.
 127    * @param int $val - Attribute value.
 128    *
 129    * @return bool -
 130    */
 131   <<__Native>>
 132   public function setAttribute(int $attr,
 133                                int $val): bool;
 134
 135   /**
 136    * Set collation strength
 137    *
 138    * @param int $strength - Strength to set.  Possible values are:
 139    *   Collator::PRIMARY     Collator::SECONDARY     Collator::TERTIARY
 140    *   Collator::QUATERNARY     Collator::IDENTICAL
 141    *   Collator::DEFAULT_STRENGTH
 142    *
 143    * @return bool -
 144    */
 145   <<__Native>>
 146   public function setStrength(int $strength): bool;
 147
 148   /**
 149    * Sort array using specified collator and sort keys
 150    *
 151    * @param array $arr - Array of strings to sort
 152    *
 153    * @return bool -
 154    */
 155   <<__Native>>
 156   public function sortWithSortKeys(inout mixed $arr): bool;
 157
 158   /**
 159    * Sort array using specified collator
 160    *
 161    * @param array $arr - Array of strings to sort.
 162    * @param int $sort_flag - Optional sorting type, one of the following:
 163    *        Collator::SORT_REGULAR - compare items normally (don't change
 164    *   types)     Collator::SORT_NUMERIC - compare items numerically
 165    *   Collator::SORT_STRING - compare items as strings    Default sorting
 166    *   type is Collator::SORT_REGULAR. It is also used if an invalid
 167    *   sort_flag value has been specified.
 168    *
 169    * @return bool -
 170    */
 171   <<__Native>>
 172   public function sort(inout mixed $arr,
 173                        int $sort_flag = Collator::SORT_REGULAR): bool;
 174 }
 175
 176 /**
 177  * Sort array maintaining index association
 178  *
 179  * @param collator $coll - Collator object.
 180  * @param array $arr - Array of strings to sort.
 181  * @param int $sort_flag - Optional sorting type, one of the following:
 182  *    Collator::SORT_REGULAR - compare items normally (don't change types)
 183  *      Collator::SORT_NUMERIC - compare items numerically
 184  *   Collator::SORT_STRING - compare items as strings      Default
 185  *   $sort_flag value is Collator::SORT_REGULAR. It is also used if an
 186  *   invalid $sort_flag value has been specified.
 187  *
 188  * @return bool -
 189  */
 190 function collator_asort(collator $coll,
 191                         inout mixed $arr,
 192                         int $sort_flag = Collator::SORT_REGULAR): bool {
 193   return $coll->asort(inout $arr, $sort_flag);
 194 }
 195
 196 /**
 197  * Compare two Unicode strings
 198  *
 199  * @param collator $coll - Collator object.
 200  * @param string $str1 - The first string to compare.
 201  * @param string $str2 - The second string to compare.
 202  *
 203  * @return int - Return comparison result:     1 if str1 is greater than
 204  *   str2 ;     0 if str1 is equal to str2;     -1 if str1 is less than
 205  *   str2 .    On error boolean FALSE is returned.
 206  */
 207 function collator_compare(collator $coll,
 208                           mixed $str1,
 209                           mixed $str2): int {
 210   return $coll->compare($str1, $str2);
 211 }
 212
 213 /**
 214  * Create a collator
 215  *
 216  * @param string $locale - The locale containing the required collation
 217  *   rules. Special values for locales can be passed in - if null is passed
 218  *   for the locale, the default locale collation rules will be used. If
 219  *   empty string ("") or "root" are passed, UCA rules will be used.
 220  *
 221  * @return Collator - Return new instance of Collator object, or NULL on
 222  *   error.
 223  */
 224 function collator_create(string $locale): Collator {
 225   return Collator::create($locale);
 226 }
 227
 228 /**
 229  * Get collation attribute value
 230  *
 231  * @param collator $coll - Collator object.
 232  * @param int $attr - Attribute to get value for.
 233  *
 234  * @return int - Attribute value, or boolean FALSE on error.
 235  */
 236 function collator_get_attribute(collator $coll,
 237                                 int $attr): int {
 238   return $coll->getAttribute($attr);
 239 }
 240
 241 /**
 242  * Get collator's last error code
 243  *
 244  * @param collator $coll - Collator object.
 245  *
 246  * @return int - Error code returned by the last Collator API function
 247  *   call.
 248  */
 249 function collator_get_error_code(collator $coll): int {
 250   return $coll->getErrorCode();
 251 }
 252
 253 /**
 254  * Get text for collator's last error code
 255  *
 256  * @param collator $coll - Collator object.
 257  *
 258  * @return string - Description of an error occurred in the last Collator
 259  *   API function call.
 260  */
 261 function collator_get_error_message(collator $coll): string {
 262   return $coll->getErrorMessage();
 263 }
 264
 265 /**
 266  * Get the locale name of the collator
 267  *
 268  * @param collator $coll - Collator object.
 269  * @param int $type - You can choose between valid and actual locale (
 270  *   Locale::VALID_LOCALE and Locale::ACTUAL_LOCALE, respectively).
 271  *
 272  * @return string - Real locale name from which the collation data comes.
 273  *   If the collator was instantiated from rules or an error occurred,
 274  *   returns boolean FALSE.
 275  */
 276 function collator_get_locale(collator $coll,
 277                              int $type): string {
 278   return $coll->getLocale($type);
 279 }
 280
 281 /**
 282  * Get sorting key for a string
 283  *
 284  * @param collator $coll - Collator object.
 285  * @param string $str - The string to produce the key from.
 286  *
 287  * @return string - Returns the collation key for the string. Collation
 288  *   keys can be compared directly instead of strings.
 289  */
 290 function collator_get_sort_key(collator $coll,
 291                                string $str): string {
 292   return $coll->getSortKey($str);
 293 }
 294
 295 /**
 296  * Get current collation strength
 297  *
 298  * @param collator $coll - Collator object.
 299  *
 300  * @return int - Returns current collation strength, or boolean FALSE on
 301  *   error.
 302  */
 303 function collator_get_strength(collator $coll): int {
 304   return $coll->getStrength();
 305 }
 306
 307 /**
 308  * Set collation attribute
 309  *
 310  * @param collator $coll - Collator object.
 311  * @param int $attr - Attribute.
 312  * @param int $val - Attribute value.
 313  *
 314  * @return bool -
 315  */
 316 function collator_set_attribute(collator $coll,
 317                                 int $attr,
 318                                 int $val): bool {
 319   return $coll->setAttribute($attr, $val);
 320 }
 321
 322 /**
 323  * Set collation strength
 324  *
 325  * @param collator $coll - Collator object.
 326  * @param int $strength - Strength to set.  Possible values are:
 327  *   Collator::PRIMARY     Collator::SECONDARY     Collator::TERTIARY
 328  *   Collator::QUATERNARY     Collator::IDENTICAL
 329  *   Collator::DEFAULT_STRENGTH
 330  *
 331  * @return bool -
 332  */
 333 function collator_set_strength(collator $coll,
 334                                int $strength): bool {
 335   return $coll->setStrength($strength);
 336 }
 337
 338 /**
 339  * Sort array using specified collator and sort keys
 340  *
 341  * @param collator $coll - Collator object.
 342  * @param array $arr - Array of strings to sort
 343  *
 344  * @return bool -
 345  */
 346 function collator_sort_with_sort_keys(collator $coll,
 347                                       inout mixed $arr): bool {
 348   return $coll->sortWithSortKeys(inout $arr);
 349 }
 350
 351 /**
 352  * Sort array using specified collator
 353  *
 354  * @param collator $coll - Collator object.
 355  * @param array $arr - Array of strings to sort.
 356  * @param int $sort_flag - Optional sorting type, one of the following:
 357  *      Collator::SORT_REGULAR - compare items normally (don't change
 358  *   types)     Collator::SORT_NUMERIC - compare items numerically
 359  *   Collator::SORT_STRING - compare items as strings    Default sorting
 360  *   type is Collator::SORT_REGULAR. It is also used if an invalid
 361  *   sort_flag value has been specified.
 362  *
 363  * @return bool -
 364  */
 365 function collator_sort(collator $coll,
 366                        inout mixed $arr,
 367                        int $sort_flag = Collator::SORT_REGULAR): bool {
 368   return $coll->sort(inout $arr, $sort_flag);
 369 }