1 /*
2 * Copyright (c) 1997, 2018, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
256 // getCollationKey(), but the objects persist anyway to avoid wasting extra
257 // creation time. compare() and getCollationKey() are synchronized to ensure
258 // thread safety with this scheme. The CollationElementIterator is responsible
259 // for generating collation elements from strings and returning one element at
260 // a time (sometimes there's a one-to-many or many-to-one mapping between
261 // characters and collation elements-- this class handles that).
262 // CollationElementIterator depends on RBCollationTables, which contains the
263 // collator's static state. RBCollationTables contains the actual data
264 // tables specifying the collation order of characters for a particular locale
265 // or use. It also contains the base logic that CollationElementIterator
266 // uses to map from characters to collation elements. A single RBCollationTables
267 // object is shared among all RuleBasedCollators for the same locale, and
268 // thus by all the CollationElementIterators they create.
269
270 /**
271 * RuleBasedCollator constructor. This takes the table rules and builds
272 * a collation table out of them. Please see RuleBasedCollator class
273 * description for more details on the collation rule syntax.
274 * @see java.util.Locale
275 * @param rules the collation rules to build the collation table from.
276 * @exception ParseException A format exception
277 * will be thrown if the build process of the rules fails. For
278 * example, build rule "a < ? < d" will cause the constructor to
279 * throw the ParseException because the '?' is not quoted.
280 */
281 public RuleBasedCollator(String rules) throws ParseException {
282 this(rules, Collator.CANONICAL_DECOMPOSITION);
283 }
284
285 /**
286 * RuleBasedCollator constructor. This takes the table rules and builds
287 * a collation table out of them. Please see RuleBasedCollator class
288 * description for more details on the collation rule syntax.
289 * @see java.util.Locale
290 * @param rules the collation rules to build the collation table from.
291 * @param decomp the decomposition strength used to build the
292 * collation table and to perform comparisons.
293 * @exception ParseException A format exception
294 * will be thrown if the build process of the rules fails. For
295 * example, build rule "a < ? < d" will cause the constructor to
296 * throw the ParseException because the '?' is not quoted.
297 */
298 RuleBasedCollator(String rules, int decomp) throws ParseException {
299 setStrength(Collator.TERTIARY);
300 setDecomposition(decomp);
301 tables = new RBCollationTables(rules, decomp);
302 }
303
304 /**
305 * "Copy constructor." Used in clone() for performance.
306 */
307 private RuleBasedCollator(RuleBasedCollator that) {
308 setStrength(that.getStrength());
309 setDecomposition(that.getDecomposition());
310 tables = that.tables;
311 }
312
313 /**
333
334 /**
335 * Returns a CollationElementIterator for the given CharacterIterator.
336 *
337 * @param source the character iterator to be collated
338 * @return a {@code CollationElementIterator} object
339 * @see java.text.CollationElementIterator
340 * @since 1.2
341 */
342 public CollationElementIterator getCollationElementIterator(
343 CharacterIterator source) {
344 return new CollationElementIterator( source, this );
345 }
346
347 /**
348 * Compares the character data stored in two different strings based on the
349 * collation rules. Returns information about whether a string is less
350 * than, greater than or equal to another string in a language.
351 * This can be overridden in a subclass.
352 *
353 * @exception NullPointerException if <code>source</code> or <code>target</code> is null.
354 */
355 public synchronized int compare(String source, String target)
356 {
357 if (source == null || target == null) {
358 throw new NullPointerException();
359 }
360
361 // The basic algorithm here is that we use CollationElementIterators
362 // to step through both the source and target strings. We compare each
363 // collation element in the source string against the corresponding one
364 // in the target, checking for differences.
365 //
366 // If a difference is found, we set <result> to LESS or GREATER to
367 // indicate whether the source string is less or greater than the target.
368 //
369 // However, it's not that simple. If we find a tertiary difference
370 // (e.g. 'A' vs. 'a') near the beginning of a string, it can be
371 // overridden by a primary difference (e.g. "A" vs. "B") later in
372 // the string. For example, "AA" < "aB", even though 'A' > 'a'.
373 //
|
1 /*
2 * Copyright (c) 1997, 2019, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
256 // getCollationKey(), but the objects persist anyway to avoid wasting extra
257 // creation time. compare() and getCollationKey() are synchronized to ensure
258 // thread safety with this scheme. The CollationElementIterator is responsible
259 // for generating collation elements from strings and returning one element at
260 // a time (sometimes there's a one-to-many or many-to-one mapping between
261 // characters and collation elements-- this class handles that).
262 // CollationElementIterator depends on RBCollationTables, which contains the
263 // collator's static state. RBCollationTables contains the actual data
264 // tables specifying the collation order of characters for a particular locale
265 // or use. It also contains the base logic that CollationElementIterator
266 // uses to map from characters to collation elements. A single RBCollationTables
267 // object is shared among all RuleBasedCollators for the same locale, and
268 // thus by all the CollationElementIterators they create.
269
270 /**
271 * RuleBasedCollator constructor. This takes the table rules and builds
272 * a collation table out of them. Please see RuleBasedCollator class
273 * description for more details on the collation rule syntax.
274 * @see java.util.Locale
275 * @param rules the collation rules to build the collation table from.
276 * @throws ParseException A format exception
277 * will be thrown if the build process of the rules fails. For
278 * example, build rule "a < ? < d" will cause the constructor to
279 * throw the ParseException because the '?' is not quoted.
280 */
281 public RuleBasedCollator(String rules) throws ParseException {
282 this(rules, Collator.CANONICAL_DECOMPOSITION);
283 }
284
285 /**
286 * RuleBasedCollator constructor. This takes the table rules and builds
287 * a collation table out of them. Please see RuleBasedCollator class
288 * description for more details on the collation rule syntax.
289 * @see java.util.Locale
290 * @param rules the collation rules to build the collation table from.
291 * @param decomp the decomposition strength used to build the
292 * collation table and to perform comparisons.
293 * @throws ParseException A format exception
294 * will be thrown if the build process of the rules fails. For
295 * example, build rule "a < ? < d" will cause the constructor to
296 * throw the ParseException because the '?' is not quoted.
297 */
298 RuleBasedCollator(String rules, int decomp) throws ParseException {
299 setStrength(Collator.TERTIARY);
300 setDecomposition(decomp);
301 tables = new RBCollationTables(rules, decomp);
302 }
303
304 /**
305 * "Copy constructor." Used in clone() for performance.
306 */
307 private RuleBasedCollator(RuleBasedCollator that) {
308 setStrength(that.getStrength());
309 setDecomposition(that.getDecomposition());
310 tables = that.tables;
311 }
312
313 /**
333
334 /**
335 * Returns a CollationElementIterator for the given CharacterIterator.
336 *
337 * @param source the character iterator to be collated
338 * @return a {@code CollationElementIterator} object
339 * @see java.text.CollationElementIterator
340 * @since 1.2
341 */
342 public CollationElementIterator getCollationElementIterator(
343 CharacterIterator source) {
344 return new CollationElementIterator( source, this );
345 }
346
347 /**
348 * Compares the character data stored in two different strings based on the
349 * collation rules. Returns information about whether a string is less
350 * than, greater than or equal to another string in a language.
351 * This can be overridden in a subclass.
352 *
353 * @throws NullPointerException if <code>source</code> or <code>target</code> is null.
354 */
355 public synchronized int compare(String source, String target)
356 {
357 if (source == null || target == null) {
358 throw new NullPointerException();
359 }
360
361 // The basic algorithm here is that we use CollationElementIterators
362 // to step through both the source and target strings. We compare each
363 // collation element in the source string against the corresponding one
364 // in the target, checking for differences.
365 //
366 // If a difference is found, we set <result> to LESS or GREATER to
367 // indicate whether the source string is less or greater than the target.
368 //
369 // However, it's not that simple. If we find a tertiary difference
370 // (e.g. 'A' vs. 'a') near the beginning of a string, it can be
371 // overridden by a primary difference (e.g. "A" vs. "B") later in
372 // the string. For example, "AA" < "aB", even though 'A' > 'a'.
373 //
|