mirror of
https://github.com/php/php-src.git
synced 2024-10-19 15:34:25 +00:00
240 lines
13 KiB
Plaintext
Executable File
240 lines
13 KiB
Plaintext
Executable File
1. Collator::getAvailableLocales().
|
|
Return the locales available at the time of the call, including registered locales.
|
|
If a sever error occurs (such as out of memory condition) this will return null.
|
|
If there is no locale data, an empty enumeration will be returned.
|
|
Returned locales list is a strings in format of RFC4646 standart (see http://www.rfc-editor.org/rfc/rfc4646.txt).
|
|
Examle of locales format: 'en_US', 'ru_UA', 'ua_UA' (see http://demo.icu-project.org/icu-bin/locexp).
|
|
|
|
|
|
2. Collator::getDisplayName( $obj_locale, $disp_locale ).
|
|
Get name of the object for the desired Locale, in the desired langauge. Both arguments
|
|
must be from getAvailableLocales method.
|
|
|
|
@param string $obj_locale Locale to get display name for.
|
|
@param string $disp_locale Specifies the desired locale for output
|
|
|
|
Both parameters are case insensitive.
|
|
For locale format see RFC4647 standart in ftp://ftp.rfc-editor.org/in-notes/rfc4647.txt
|
|
|
|
3. Collator::getLocaleByType( $type ).
|
|
Allow user to select whether she wants information on requested, valid or actual locale.
|
|
Returned locale tag is a string formatted to a RFC4646 standart and normalize to normal form -
|
|
value is a string from
|
|
For example, a collator for "en_US_CALIFORNIA" was requested. In the current state of ICU (2.0),
|
|
the requested locale is "en_US_CALIFORNIA", the valid locale is "en_US" (most specific locale
|
|
supported by ICU) and the actual locale is "root" (the collation data comes unmodified from the UCA)
|
|
The locale is considered supported by ICU if there is a core ICU bundle for that locale (although
|
|
it may be empty).
|
|
|
|
|
|
4. VariableTop
|
|
The Variable_Top attribute is only meaningful if the Alternate attribute is not set to NonIgnorable.
|
|
In such a case, it controls which characters count as ignorable. The string value specifies
|
|
the "highest" character (in UCA order) weight that is to be considered ignorable.
|
|
Thus, for example, if a user wanted whitespace to be ignorable, but not any visible characters,
|
|
then s/he would use the value Variable_Top="\u0020" (space). The string should only be a
|
|
single character. All characters of the same primary weight are equivalent, so
|
|
Variable_Top="\u3000" (ideographic space) has the same effect as Variable_Top="\u0020".
|
|
This setting (alone) has little impact on string comparison performance; setting it lower or higher
|
|
will make sort keys slightly shorter or longer respectively.
|
|
|
|
|
|
5. Strength
|
|
The ICU Collation Service supports many levels of comparison (named "Levels", but also
|
|
known as "Strengths"). Having these categories enables ICU to sort strings precisely
|
|
according to local conventions. However, by allowing the levels to be selectively
|
|
employed, searching for a string in text can be performed with various matching
|
|
conditions.
|
|
Performance optimizations have been made for ICU collation with the default level
|
|
settings. Performance specific impacts are discussed in the Performance section below.
|
|
Following is a list of the names for each level and an example usage:
|
|
|
|
1. Primary Level: Typically, this is used to denote differences between base characters
|
|
(for example, "a" < "b"). It is the strongest difference. For example, dictionaries are
|
|
divided into different sections by base character. This is also called the level1
|
|
strength.
|
|
|
|
2. Secondary Level: Accents in the characters are considered secondary differences (for
|
|
example, "as" < "as" < "at"). Other differences between letters can also be considered
|
|
secondary differences, depending on the language. A secondary difference is ignored
|
|
when there is a primary difference anywhere in the strings. This is also called the
|
|
level2 strength.
|
|
Note: In some languages (such as Danish), certain accented letters are considered to
|
|
be separate base characters. In most languages, however, an accented letter only has a
|
|
secondary difference from the unaccented version of that letter.
|
|
|
|
3. Tertiary Level: Upper and lower case differences in characters are distinguished at the
|
|
tertiary level (for example, "ao" < "Ao" < "ao"). In addition, a variant of a letter differs
|
|
from the base form on the tertiary level (such as "A" and " "). Another ? example is the
|
|
difference between large and small Kana. A tertiary difference is ignored when there is
|
|
a primary or secondary difference anywhere in the strings. This is also called the level3
|
|
strength.
|
|
|
|
4. Quaternary Level: When punctuation is ignored (see Ignoring Punctuations ) at level
|
|
13, an additional level can be used to distinguish words with and without punctuation
|
|
(for example, "ab" < "a-b" < "aB"). This difference is ignored when there is a primary,
|
|
secondary or tertiary difference. This is also known as the level4 strength. The
|
|
quaternary level should only be used if ignoring punctuation is required or when
|
|
processing Japanese text (see Hiragana processing).
|
|
|
|
5. Identical Level: When all other levels are equal, the identical level is used as a
|
|
tiebreaker. The Unicode code point values of the NFD form of each string are
|
|
compared at this level, just in case there is no difference at levels 14
|
|
. For example, Hebrew cantillation marks are only distinguished at this level. This level should be
|
|
used sparingly, as only code point values differences between two strings is an
|
|
extremely rare occurrence. Using this level substantially decreases the performance for
|
|
both incremental comparison and sort key generation (as well as increasing the sort
|
|
key length). It is also known as level 5 strength.
|
|
|
|
For example, people may choose to ignore accents or ignore accents and case when searching
|
|
for text. Almost all characters are distinguished by the first three levels, and in most
|
|
locales the default value is thus Tertiary. However, if Alternate is set to be Shifted,
|
|
then the Quaternary strength can be used to break ties among whitespace, punctuation, and
|
|
symbols that would otherwise be ignored. If very fine distinctions among characters are required,
|
|
then the Identical strength can be used (for example, Identical Strength distinguishes
|
|
between the Mathematical Bold Small A and the Mathematical Italic Small A.). However, using
|
|
levels higher than Tertiary the Identical strength result in significantly longer sort
|
|
keys, and slower string comparison performance for equal strings.
|
|
|
|
|
|
|
|
6. Collator::__construct( $locale ).
|
|
The Locale attribute is typically the most important attribute for correct sorting and matching,
|
|
according to the user expectations in different countries and regions. The default UCA
|
|
ordering will only sort a few languages such as Dutch and Portuguese correctly ("correctly"
|
|
meaning according to the normal expectations for users of the languages).
|
|
Otherwise, you need to supply the locale to UCA in order to properly collate text for a
|
|
given language. Thus a locale needs to be supplied so as to choose a collator that is correctly
|
|
tailored for that locale. The choice of a locale will automatically preset the values for
|
|
all of the attributes to something that is reasonable for that locale. Thus most of the time the
|
|
other attributes do not need to be explicitly set. In some cases, the choice of locale will make a
|
|
difference in string comparison performance and/or sort key length.
|
|
In short attribute names, <language>_<script>_<region>_<keyword>.
|
|
Not all the elements are required. Valid values for locale elements are general valid values
|
|
for RFC4646 locale naming, and RFC 4647 lookup algorithm.
|
|
Example:
|
|
Locale="sv" (Swedish) "Kypper" < "Kopfe"
|
|
Locale="de" (German) "Kopfe" < "Kypper"
|
|
|
|
|
|
7. Collator::get/setAttribute.
|
|
ICU uses UCA as a default starting point for ordering. Not all languages have sorting sequences
|
|
that correspond with the UCA because UCA cannot simultaneously encompass the specifics of all
|
|
the languages currently in use. Therefore, ICU provides a data-driven, flexible, and run-time
|
|
customizable mechanism called "tailoring". Tailoring overrides the default order of code points
|
|
and the values of the ICU Collation Service attributes.
|
|
Collator have followed attributes:
|
|
- FRENCH_COLLATION, possible values are:
|
|
ON
|
|
OFF (default)
|
|
DEFAULT
|
|
|
|
- CASE_FIRST, possible values are:
|
|
OFF (default)
|
|
LOWER_FIRST
|
|
UPPER_FIRST
|
|
DEFAULT
|
|
|
|
- CASE_LEVEL, possible values are:
|
|
OFF (default)
|
|
ON
|
|
DEFAULT
|
|
|
|
- NORMALIZATION_MODE, possible values are:
|
|
OFF (default)
|
|
ON
|
|
DEFAULT
|
|
|
|
- STRENGTH, possible values are:
|
|
PRIMARY
|
|
SECONDARY
|
|
TERTIARY (default)
|
|
QUATERNARY
|
|
IDENTICAL
|
|
DEFAULT
|
|
|
|
- ALTERNATE_HANDLING, possible values are:
|
|
NON_IGNORABLE (default)
|
|
SHIFTED
|
|
DEFAULT
|
|
|
|
- HIRAGANA_QUATERNARY_MODE, possible values are:
|
|
ON
|
|
OFF (default)
|
|
DEFAULT
|
|
|
|
- NUMERIC_COLLATION, possible values are:
|
|
ON
|
|
OFF (default)
|
|
DEFAULT
|
|
|
|
Description of all of this attributes:
|
|
|
|
FRENCH_COLLATION - Sort strings with different accents from the back of the string. This attribute
|
|
is automatically set to On for the French locales and a few others. Users normally would
|
|
not need to explicitly set this attribute. There is a string comparison performance cost when
|
|
it is set On, but sort key length is unaffected.
|
|
Example:
|
|
F=X cote < cote < cote < cote
|
|
F=O cote < cote < cote < cote
|
|
|
|
CASE_FIRST - The Case_First attribute is used to control whether uppercase letters come before
|
|
lowercase letters or vice versa, in the absence of other differences in the strings. The possible
|
|
values are Uppercase_First (U) and Lowercase_First (L), plus the standard Default and Off.
|
|
There is almost no difference between the Off and Lowercase_First options in terms of results,
|
|
so typically users will not use Lowercase_First: only Off or Uppercase_First. (People interested
|
|
in the detailed differences between X and L should consult the Collation Customization).
|
|
Specifying either L or U won't affect string comparison performance, but will affect the sort key
|
|
length.
|
|
Example:
|
|
C=X or C=L "china" < "China" < "denmark" <
|
|
"Denmark"
|
|
C=U "China" < "china" < "Denmark" < "denmark"
|
|
|
|
CASE_LEVEL - The Case_Level attribute is used when ignoring accents but not case. In such a situation,
|
|
set Strength to be Primary, and Case_Level to be On. In most locales, this setting is Off by default.
|
|
There is a small string comparison performance and sort key impact if this attribute is set to be On.
|
|
Example:
|
|
S=1, E=X role = Role = role
|
|
S=1, E=O role = role < Role
|
|
|
|
NORMALIZATION_MODE - The Normalization setting determines whether text is thoroughly normalized
|
|
or not in comparison. Even if the setting is off (which is the default for many locales), text as
|
|
represented in common usage will compare correctly (for details, see UTN #5). Only if the accent
|
|
marks are in noncanonical order will there be a problem. If the setting is On, then the best
|
|
results are guaranteed for all possible text input. There is a medium string comparison performance
|
|
cost if this attribute is On, depending on the frequency of sequences that require normalization.
|
|
There is no significant effect on sort key length. If the input text is known to be in NFD or NFKD
|
|
normalization forms, there is no need to enable this Normalization option.
|
|
|
|
STRENGTH - see Collator::setStrength chapter.
|
|
|
|
ALTERNATE_HANDLING - The Alternate attribute is used to control the handling of the socalled
|
|
variable characters in the UCA: whitespace, punctuation and symbols. If Alternate is set to
|
|
NonIgnorable (N), then differences among these characters are of the same importance as
|
|
differences among letters. If Alternate is set to Shifted (S), then these characters are of only
|
|
minor importance. The Shifted value is often used in combination with Strength set to Quaternary.
|
|
In such a case, whitespace, punctuation, and symbols are considered when comparing strings,
|
|
but only if all other aspects of the strings (base letters, accents, and case) are identical.
|
|
If Alternate is not set to Shifted, then there is no difference between a Strength of 3 and
|
|
a Strength of 4. For more information and examples, see
|
|
Variable_Weighting in the UCA (http://www.unicode.org/reports/tr10/#Variable_Weighting).
|
|
The reason the Alternate values are not simply On and Off is that additional Alternate values
|
|
may be added in the future. The UCA option Blanked is expressed with Strength set to 3,
|
|
and Alternate set to Shifted. The default for most locales is NonIgnorable. If Shifted is selected,
|
|
it may be slower if there are many strings that are the same except for punctuation;
|
|
sort key length will not be affected unless the strength level is also increased.
|
|
Example:
|
|
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
|
|
|
|
HIRAGANA_QUATERNARY_MODE - Compatibility with JIS x 4061 requires the introduction of an additional
|
|
level to distinguish Hiragana and Katakana characters. If compatibility with that standard is required,
|
|
then this attribute should be set On, and the strength set to Quaternary. This will affect sort key
|
|
length and string comparison string comparison performance.
|
|
|
|
NUMERIC_COLLATION - When turned on, this attribute generates a collation key for the
|
|
numeric value of substrings of digits. This is a way to get '100' to sort AFTER '2'.
|
|
|