xref: /PHP-7.1/ext/intl/doc/collator_api.php (revision 7f6387b5)
1<?php
2#############################################################################
3# Object-oriented API
4#############################################################################
5
6/**
7 * Collator class.
8 *
9 * This is a wrapper around ICU Collator C API (declared in ucol.h).
10 *
11 * Example:
12 * <code>
13 *
14 * </code>
15 *
16 * @see http://www.icu-project.org/apiref/icu4c/ucol_8h.html
17 * @see http://www.icu-project.org/apiref/icu4c/classCollator.html
18 *
19 */
20class Collator {
21#############################################################################
22# Common constants.
23#############################################################################
24
25/**
26 * Locale-related constants.
27 *
28 * These will be moved out of Collator when Locale class is created.
29 */
30	const ULOC_ACTUAL_LOCALE    = 0;
31	const ULOC_VALID_LOCALE     = 1;
32	const ULOC_REQUESTED_LOCALE = 2;
33
34	/*
35	 * WARNING:
36	 * The values described here are NOT the actual values in PHP code.
37	 * They are references to the ICU C definitions, so the line
38	 *    const DEFAULT_STRENGTH = 'UCOL_DEFAULT_STRENGTH';
39	 * actually means that Collator::DEFAULT_STRENGTH is the same as
40	 * UCOL_DEFAULT_STRENGTH constant in the ICU library.
41	 */
42	/**
43     * Valid attribute values.
44     *
45     * @see Collator::setAttribute()
46     * @see collator_set_attribute()
47     */
48    const DEFAULT_VALUE    = 'UCOL_DEFAULT';
49    const PRIMARY          = 'UCOL_PRIMARY';
50    const SECONDARY        = 'UCOL_SECONDARY';
51    const TERTIARY         = 'UCOL_TERTIARY';
52    const DEFAULT_STRENGTH = 'UCOL_DEFAULT_STRENGTH';
53    const QUATERNARY       = 'UCOL_QUATERNARY';
54    const IDENTICAL        = 'UCOL_IDENTICAL';
55    const OFF              = 'UCOL_OFF';
56    const ON               = 'UCOL_ON';
57    const SHIFTED          = 'UCOL_SHIFTED';
58    const NON_IGNORABLE    = 'UCOL_NON_IGNORABLE';
59    const LOWER_FIRST      = 'UCOL_LOWER_FIRST';
60    const UPPER_FIRST      = 'UCOL_UPPER_FIRST';
61
62    /**
63     * Valid attribute names.
64     *
65     * @see Collator::setAttribute()
66     * @see collator_set_attribute()
67     */
68    const FRENCH_COLLATION         = 'UCOL_FRENCH_COLLATION';
69    const ALTERNATE_HANDLING       = 'UCOL_ALTERNATE_HANDLING';
70    const CASE_FIRST               = 'UCOL_CASE_FIRST';
71    const CASE_LEVEL               = 'UCOL_CASE_LEVEL';
72    const NORMALIZATION_MODE       = 'UCOL_NORMALIZATION_MODE';
73    const STRENGTH                 = 'UCOL_STRENGTH';
74    const HIRAGANA_QUATERNARY_MODE = 'UCOL_HIRAGANA_QUATERNARY_MODE';
75    const NUMERIC_COLLATION        = 'UCOL_NUMERIC_COLLATION';
76
77    /**
78     * Create a collator
79     *
80     * @param string $locale The locale whose collation rules
81     *                       should be used. Special values for
82     *                       locales can be passed in - if null is
83     *                       passed for the locale, the default
84     *                       locale collation rules will be used. If
85     *                       empty string ("") or "root" are passed,
86     *                       UCA rules will be used.
87     *
88     * @return Collator     New instance of Collator object.
89     */
90    public function __construct( $locale ) {}
91
92    /**
93     * Create a collator
94     *
95     * Creates a new instance of Collator.
96     *
97     * This method is useful when you prefer just to get null on error,
98     * as if you called collator_create().
99     *
100     * @return Collator      Newly created Collator instance,
101     *                       or null on error.
102     *
103     * @see __construct()
104     * @see collator_create()
105     */
106    public static function create( $locale ) {}
107
108    /**
109     * Get collator's last error code.
110     *
111     * @return  int  Error code returned by the last
112     *               Collator method call.
113     */
114    public function getErrorCode() {}
115
116    /**
117     * Return error text for the last ICU operation.
118     *
119     * @return string Description of an error occurred in the last
120     *                Collator method call.
121     */
122    public function getErrorMessage() {}
123
124    /**
125     * Compare two strings using PHP strcmp() semantics.
126     *
127     * Wrapper around ICU ucol_strcoll().
128     *
129     * @param string $str1  First string to compare.
130     * @param string $str2  Second string to compare.
131     *
132     * @return int   1   if $str1 is  greater than  $str2;
133     *               0   if $str1 is  equal to      $str2;
134     *               -1  if $str1 is  less than     $str2.
135     *               On error false is returned.
136     */
137    public function compare( $str1, $str2 ) {}
138
139    /**
140     * Equivalent to standard PHP sort() using Collator.
141     *
142     * @param array $arr         Array of strings to sort
143     * @param int   $sort_flags  Optional sorting type, one of the following:
144     *                           - SORT_REGULAR - compare items normally (don't change types)
145     *                           - SORT_NUMERIC - compare items numerically
146     *                           - SORT_STRING - compare items as strings
147     *                           Default sorting type is SORT_REGULAR.
148     *
149     * @return bool true on success or false on failure.
150     */
151    public function sort( $arr, $sort_flags ) {}
152
153    /**
154     * Sort array maintaining index association.
155     *
156     * Equivalent to standard PHP asort() using Collator.
157     *
158     * @param array $arr         Array of strings to sort
159     * @param int   $sort_flags  Optional sorting type
160     *
161     * @return bool true on success or false on failure.
162     *
163     * @see Collator::sort()
164     */
165    public function asort( $arr, $sort_flags ) {}
166
167    /**
168     * Equivalent to standard PHP sort() using Collator.
169     *
170     * Similar to Collator::sort().
171     * Uses ICU ucol_getSortKey() to gain more speed on large arrays.
172     *
173     * @param array $arr  Array of strings to sort
174     *
175     * @return bool       true on success or false on failure.
176     */
177    public function sortWithSortKeys( $arr ) {}
178
179    /**
180     * @todo  Do we want to support other standard PHP sort functions:  ksort, rsort, asort?
181     */
182
183    /**
184     * Get collation attribute value.
185     *
186     * Wrapper around ICU ucol_getAttribute().
187     *
188     * @param  int      $attr Attribute to get value for.
189     *
190     * @return int      Attribute value, or false on error.
191     */
192    public function getAttribute( $attr ) {}
193
194    /**
195     * Set collation attribute.
196     *
197     * Wrapper around ICU ucol_setAttribute().
198     *
199     * @param int       $attr Attribute.
200     * @param int       $val  Attribute value.
201     *
202     * @return bool     true on success, false otherwise.
203     */
204    public function setAttribute( $attr, $val ) {}
205
206    /**
207     * Get current collation strength.
208     *
209     * Wrapper around ICU ucol_getStrength().
210     *
211     * @return int     Current collation strength, or false on error.
212     */
213    public function getStrength() {}
214
215    /**
216     * Set collation strength.
217     *
218     * Wrapper around ICU ucol_setStrength().
219     *
220     * @param int      $strength Strength to set.
221     *
222     * @return bool    true on success, false otherwise.
223     */
224    public function setStrength( $strength ) {}
225
226    /**
227     * Get the locale name of the collator.
228     *
229     * Wrapper around ICU ucol_getLocaleByType().
230     *
231     * @param int      $type You can choose between requested, valid
232     *                       and actual locale
233     *                       (ULOC_REQUESTED_LOCALE,
234     *                       ULOC_VALID_LOCALE, ULOC_ACTUAL_LOCALE,
235     *                       respectively).
236     *
237     * @return string        Real locale name from which the
238     *                       collation data comes. If the collator
239     *                       was instantiated from rules or an error occurred,
240     *                       returns false.
241     */
242    public function getLocale( $type ) {}
243}
244
245#############################################################################
246# Procedural API
247#############################################################################
248
249/**
250 * Create collator.
251 *
252 * @param string     $locale  The locale containing the required
253 *                            collation rules. Special values for
254 *                            locales can be passed in - if null is
255 *                            passed for the locale, the default
256 *                            locale collation rules will be used. If
257 *                            empty string ("") or "root" are passed,
258 *                            UCA rules will be used.
259 *
260 * @return Collator  New instance of Collator object, or null on error.
261 */
262function collator_create( $locale ) {}
263
264/**
265 * Compare two strings.
266 *
267 * The strings will be compared using the options already
268 * specified.
269 *
270 * @param Collator $coll Collator object.
271 * @param string   $str1 The first string to compare.
272 * @param string   $str2 The second string to compare.
273 *
274 * @return int     1   if $str1 is  greater than  $str2;
275 *                 0   if $str1 is  equal to      $str2;
276 *                 -1  if $str1 is  less than     $str2.
277 *                 On error false is returned.
278 *
279 */
280function collator_compare( $coll, $str1, $str2 ) {}
281
282/**
283 * Sort array using specified collator.
284 *
285 * @param  Collator $coll        Collator object.
286 * @param  array    $arr         Array of strings to sort.
287 * @param  int      $sort_flags  Optional sorting type, one of the following:
288 *                               - SORT_REGULAR - compare items normally (don't change types)
289 *                               - SORT_NUMERIC - compare items numerically
290 *                               - SORT_STRING - compare items as strings
291 *                               Default sorting type is SORT_REGULAR.
292 *
293 * @return bool     true on success or false on failure.
294 */
295function collator_sort( $coll, $arr, $sort_flags ) {}
296
297/**
298 * Sort array maintaining index association.
299 *
300 * @param Collator $coll        Collator object.
301 * @param array    $arr         Array of strings to sort.
302 * @param int      $sort_flags  Optional sorting type.
303 *
304 * @return bool    true on success or false on failure.
305 *
306 * @see collator_sort()
307 */
308function collator_asort( $coll, $arr, $sort_flags ) {}
309
310/**
311 * Sort array using specified collator.
312 *
313 * Similar to collator_sort().
314 * Uses ICU ucol_getSortKey() to gain more speed on large arrays.
315 *
316 * @param  Collator $coll  Collator object.
317 * @param  array    $arr   Array of strings to sort
318 *
319 * @return bool     true on success or false on failure.
320 */
321function collator_sort_with_sort_keys( $coll, $arr ) {}
322
323/**
324 * Get the locale name of the collator.
325 *
326 * @param Collator $coll Collator object.
327 * @param int      $type You can choose between valid and
328 *                       actual locale
329 *                       (ULOC_VALID_LOCALE, ULOC_ACTUAL_LOCALE
330 *                       respectively).
331 *
332 * @return string  Real locale name from which the
333 *                 collation data comes. If the collator
334 *                 was instantiated from rules or an error occurred,
335 *                 returns false.
336 */
337function collator_get_locale( $coll, $type ) {}
338
339/**
340 * Get collation attribute value.
341 *
342 * @param  Collator $coll Collator object.
343 * @param  int      $attr Attribute to get value for.
344 *
345 * @return int      Attribute value, or false on error.
346 */
347function collator_get_attribute( $coll, $attr ) {}
348
349/**
350 * Get current collation strength.
351 *
352 * @param Collator $coll Collator object.
353 *
354 * @return int     Current collation strength, or false on error.
355 */
356function collator_get_strength( $coll ) {}
357
358/**
359 * Set collation strength.
360 *
361 * @param Collator $coll      Collator object.
362 * @param int      $strength  Strength to set.
363 *
364 * @return bool    true on success, false otherwise.
365 */
366function collator_set_strength( $coll, $strength ) {}
367
368/**
369 * Set collation attribute.
370 *
371 * @param Collator  $coll  Collator object.
372 * @param int       $attr  Attribute.
373 * @param int       $val   Attribute value.
374 *
375 * @return bool     true on success, false otherwise.
376 */
377function collator_set_attribute( $coll, $attr, $val ) {}
378
379/**
380 * Get collator's last error code.
381 *
382 * @param Collator $coll    Collator object.
383 *
384 * @return int     Error code returned by the last
385 *                 Collator API function call.
386 */
387function collator_get_error_code( $coll ) {}
388
389/**
390 * Get text for collator's last error code.
391 *
392 * @param Collator $coll    Collator object.
393 *
394 * @return string  Description of an error occurred in the last
395 *                 Collator API function call.
396 */
397function collator_get_error_message( $coll ) {}
398