Annotation of embedaddon/php/ext/intl/doc/Tutorial.txt, revision 1.1.1.2
1.1 misho 1: 1. Collator::getAvailableLocales().
2: Return the locales available at the time of the call, including registered locales.
3: If a sever error occurs (such as out of memory condition) this will return null.
4: If there is no locale data, an empty enumeration will be returned.
5: Returned locales list is a strings in format of RFC4646 standart (see http://www.rfc-editor.org/rfc/rfc4646.txt).
6: Examle of locales format: 'en_US', 'ru_UA', 'ua_UA' (see http://demo.icu-project.org/icu-bin/locexp).
7:
8:
9: 2. Collator::getDisplayName( $obj_locale, $disp_locale ).
1.1.1.2 ! misho 10: Get name of the object for the desired Locale, in the desired language. Both arguments
1.1 misho 11: must be from getAvailableLocales method.
12:
13: @param string $obj_locale Locale to get display name for.
14: @param string $disp_locale Specifies the desired locale for output
15:
16: Both parameters are case insensitive.
17: For locale format see RFC4647 standart in ftp://ftp.rfc-editor.org/in-notes/rfc4647.txt
18:
19: 3. Collator::getLocaleByType( $type ).
20: Allow user to select whether she wants information on requested, valid or actual locale.
21: Returned locale tag is a string formatted to a RFC4646 standart and normalize to normal form -
22: value is a string from
23: For example, a collator for "en_US_CALIFORNIA" was requested. In the current state of ICU (2.0),
24: the requested locale is "en_US_CALIFORNIA", the valid locale is "en_US" (most specific locale
25: supported by ICU) and the actual locale is "root" (the collation data comes unmodified from the UCA)
26: The locale is considered supported by ICU if there is a core ICU bundle for that locale (although
27: it may be empty).
28:
29:
30: 4. VariableTop
31: The Variable_Top attribute is only meaningful if the Alternate attribute is not set to NonIgnorable.
32: In such a case, it controls which characters count as ignorable. The string value specifies
33: the "highest" character (in UCA order) weight that is to be considered ignorable.
34: Thus, for example, if a user wanted whitespace to be ignorable, but not any visible characters,
35: then s/he would use the value Variable_Top="\u0020" (space). The string should only be a
36: single character. All characters of the same primary weight are equivalent, so
37: Variable_Top="\u3000" (ideographic space) has the same effect as Variable_Top="\u0020".
38: This setting (alone) has little impact on string comparison performance; setting it lower or higher
39: will make sort keys slightly shorter or longer respectively.
40:
41:
42: 5. Strength
43: The ICU Collation Service supports many levels of comparison (named "Levels", but also
44: known as "Strengths"). Having these categories enables ICU to sort strings precisely
45: according to local conventions. However, by allowing the levels to be selectively
46: employed, searching for a string in text can be performed with various matching
47: conditions.
48: Performance optimizations have been made for ICU collation with the default level
49: settings. Performance specific impacts are discussed in the Performance section below.
50: Following is a list of the names for each level and an example usage:
51:
52: 1. Primary Level: Typically, this is used to denote differences between base characters
53: (for example, "a" < "b"). It is the strongest difference. For example, dictionaries are
54: divided into different sections by base character. This is also called the level1
55: strength.
56:
57: 2. Secondary Level: Accents in the characters are considered secondary differences (for
58: example, "as" < "as" < "at"). Other differences between letters can also be considered
59: secondary differences, depending on the language. A secondary difference is ignored
60: when there is a primary difference anywhere in the strings. This is also called the
61: level2 strength.
62: Note: In some languages (such as Danish), certain accented letters are considered to
63: be separate base characters. In most languages, however, an accented letter only has a
64: secondary difference from the unaccented version of that letter.
65:
66: 3. Tertiary Level: Upper and lower case differences in characters are distinguished at the
67: tertiary level (for example, "ao" < "Ao" < "ao"). In addition, a variant of a letter differs
68: from the base form on the tertiary level (such as "A" and " "). Another ? example is the
69: difference between large and small Kana. A tertiary difference is ignored when there is
70: a primary or secondary difference anywhere in the strings. This is also called the level3
71: strength.
72:
73: 4. Quaternary Level: When punctuation is ignored (see Ignoring Punctuations ) at level
74: 13, an additional level can be used to distinguish words with and without punctuation
75: (for example, "ab" < "a-b" < "aB"). This difference is ignored when there is a primary,
76: secondary or tertiary difference. This is also known as the level4 strength. The
77: quaternary level should only be used if ignoring punctuation is required or when
78: processing Japanese text (see Hiragana processing).
79:
80: 5. Identical Level: When all other levels are equal, the identical level is used as a
81: tiebreaker. The Unicode code point values of the NFD form of each string are
82: compared at this level, just in case there is no difference at levels 14
83: . For example, Hebrew cantillation marks are only distinguished at this level. This level should be
84: used sparingly, as only code point values differences between two strings is an
85: extremely rare occurrence. Using this level substantially decreases the performance for
86: both incremental comparison and sort key generation (as well as increasing the sort
87: key length). It is also known as level 5 strength.
88:
89: For example, people may choose to ignore accents or ignore accents and case when searching
90: for text. Almost all characters are distinguished by the first three levels, and in most
91: locales the default value is thus Tertiary. However, if Alternate is set to be Shifted,
92: then the Quaternary strength can be used to break ties among whitespace, punctuation, and
93: symbols that would otherwise be ignored. If very fine distinctions among characters are required,
94: then the Identical strength can be used (for example, Identical Strength distinguishes
95: between the Mathematical Bold Small A and the Mathematical Italic Small A.). However, using
96: levels higher than Tertiary the Identical strength result in significantly longer sort
97: keys, and slower string comparison performance for equal strings.
98:
99:
100:
101: 6. Collator::__construct( $locale ).
102: The Locale attribute is typically the most important attribute for correct sorting and matching,
103: according to the user expectations in different countries and regions. The default UCA
104: ordering will only sort a few languages such as Dutch and Portuguese correctly ("correctly"
105: meaning according to the normal expectations for users of the languages).
106: Otherwise, you need to supply the locale to UCA in order to properly collate text for a
107: given language. Thus a locale needs to be supplied so as to choose a collator that is correctly
108: tailored for that locale. The choice of a locale will automatically preset the values for
109: all of the attributes to something that is reasonable for that locale. Thus most of the time the
110: other attributes do not need to be explicitly set. In some cases, the choice of locale will make a
111: difference in string comparison performance and/or sort key length.
112: In short attribute names, <language>_<script>_<region>_<keyword>.
113: Not all the elements are required. Valid values for locale elements are general valid values
114: for RFC4646 locale naming, and RFC 4647 lookup algorithm.
115: Example:
116: Locale="sv" (Swedish) "Kypper" < "Kopfe"
117: Locale="de" (German) "Kopfe" < "Kypper"
118:
119:
120: 7. Collator::get/setAttribute.
121: ICU uses UCA as a default starting point for ordering. Not all languages have sorting sequences
122: that correspond with the UCA because UCA cannot simultaneously encompass the specifics of all
123: the languages currently in use. Therefore, ICU provides a data-driven, flexible, and run-time
124: customizable mechanism called "tailoring". Tailoring overrides the default order of code points
125: and the values of the ICU Collation Service attributes.
126: Collator have followed attributes:
127: - FRENCH_COLLATION, possible values are:
128: ON
129: OFF (default)
130: DEFAULT
131:
132: - CASE_FIRST, possible values are:
133: OFF (default)
134: LOWER_FIRST
135: UPPER_FIRST
136: DEFAULT
137:
138: - CASE_LEVEL, possible values are:
139: OFF (default)
140: ON
141: DEFAULT
142:
143: - NORMALIZATION_MODE, possible values are:
144: OFF (default)
145: ON
146: DEFAULT
147:
148: - STRENGTH, possible values are:
149: PRIMARY
150: SECONDARY
151: TERTIARY (default)
152: QUATERNARY
153: IDENTICAL
154: DEFAULT
155:
156: - ALTERNATE_HANDLING, possible values are:
157: NON_IGNORABLE (default)
158: SHIFTED
159: DEFAULT
160:
161: - HIRAGANA_QUATERNARY_MODE, possible values are:
162: ON
163: OFF (default)
164: DEFAULT
165:
166: - NUMERIC_COLLATION, possible values are:
167: ON
168: OFF (default)
169: DEFAULT
170:
171: Description of all of this attributes:
172:
173: FRENCH_COLLATION - Sort strings with different accents from the back of the string. This attribute
174: is automatically set to On for the French locales and a few others. Users normally would
175: not need to explicitly set this attribute. There is a string comparison performance cost when
176: it is set On, but sort key length is unaffected.
177: Example:
178: F=X cote < cote < cote < cote
179: F=O cote < cote < cote < cote
180:
181: CASE_FIRST - The Case_First attribute is used to control whether uppercase letters come before
182: lowercase letters or vice versa, in the absence of other differences in the strings. The possible
183: values are Uppercase_First (U) and Lowercase_First (L), plus the standard Default and Off.
184: There is almost no difference between the Off and Lowercase_First options in terms of results,
185: so typically users will not use Lowercase_First: only Off or Uppercase_First. (People interested
186: in the detailed differences between X and L should consult the Collation Customization).
187: Specifying either L or U won't affect string comparison performance, but will affect the sort key
188: length.
189: Example:
190: C=X or C=L "china" < "China" < "denmark" <
191: "Denmark"
192: C=U "China" < "china" < "Denmark" < "denmark"
193:
194: CASE_LEVEL - The Case_Level attribute is used when ignoring accents but not case. In such a situation,
195: set Strength to be Primary, and Case_Level to be On. In most locales, this setting is Off by default.
196: There is a small string comparison performance and sort key impact if this attribute is set to be On.
197: Example:
198: S=1, E=X role = Role = role
199: S=1, E=O role = role < Role
200:
201: NORMALIZATION_MODE - The Normalization setting determines whether text is thoroughly normalized
202: or not in comparison. Even if the setting is off (which is the default for many locales), text as
203: represented in common usage will compare correctly (for details, see UTN #5). Only if the accent
204: marks are in noncanonical order will there be a problem. If the setting is On, then the best
205: results are guaranteed for all possible text input. There is a medium string comparison performance
206: cost if this attribute is On, depending on the frequency of sequences that require normalization.
207: There is no significant effect on sort key length. If the input text is known to be in NFD or NFKD
208: normalization forms, there is no need to enable this Normalization option.
209:
210: STRENGTH - see Collator::setStrength chapter.
211:
212: ALTERNATE_HANDLING - The Alternate attribute is used to control the handling of the socalled
213: variable characters in the UCA: whitespace, punctuation and symbols. If Alternate is set to
214: NonIgnorable (N), then differences among these characters are of the same importance as
215: differences among letters. If Alternate is set to Shifted (S), then these characters are of only
216: minor importance. The Shifted value is often used in combination with Strength set to Quaternary.
217: In such a case, whitespace, punctuation, and symbols are considered when comparing strings,
218: but only if all other aspects of the strings (base letters, accents, and case) are identical.
219: If Alternate is not set to Shifted, then there is no difference between a Strength of 3 and
220: a Strength of 4. For more information and examples, see
221: Variable_Weighting in the UCA (http://www.unicode.org/reports/tr10/#Variable_Weighting).
222: The reason the Alternate values are not simply On and Off is that additional Alternate values
223: may be added in the future. The UCA option Blanked is expressed with Strength set to 3,
224: and Alternate set to Shifted. The default for most locales is NonIgnorable. If Shifted is selected,
225: it may be slower if there are many strings that are the same except for punctuation;
226: sort key length will not be affected unless the strength level is also increased.
227: Example:
228: S=3, A=N di Silva < Di Silva < diSilva < U.S.A. < USA
229: S=3, A=S di Silva = diSilva < Di Silva < U.S.A. = USA
230: S=4, A=S di Silva < diSilva < Di Silva < U.S.A. < USA
231:
232: HIRAGANA_QUATERNARY_MODE - Compatibility with JIS x 4061 requires the introduction of an additional
233: level to distinguish Hiragana and Katakana characters. If compatibility with that standard is required,
234: then this attribute should be set On, and the strength set to Quaternary. This will affect sort key
235: length and string comparison string comparison performance.
236:
237: NUMERIC_COLLATION - When turned on, this attribute generates a collation key for the
238: numeric value of substrings of digits. This is a way to get '100' to sort AFTER '2'.
239:
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to Tutorial.txt CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / php / ext / intl / doc