From 66852893a2fbd4917d8f3efb88e48a384010cf23 Mon Sep 17 00:00:00 2001 From: Michael Koch Date: Mon, 19 May 2003 09:09:23 +0000 Subject: [PATCH] CollationKey.java: Merged copyright and dat from classpath. 2003-05-19 Michael Koch * java/text/CollationKey.java: Merged copyright and dat from classpath. * java/text/RuleBasedCollator.java: Merged class documentation from classpath. From-SVN: r66955 --- libjava/ChangeLog | 7 ++ libjava/java/text/CollationKey.java | 3 +- libjava/java/text/RuleBasedCollator.java | 87 +++++++++++++++++++++++- 3 files changed, 95 insertions(+), 2 deletions(-) diff --git a/libjava/ChangeLog b/libjava/ChangeLog index d416194f709..a620831f832 100644 --- a/libjava/ChangeLog +++ b/libjava/ChangeLog @@ -1,3 +1,10 @@ +2003-05-19 Michael Koch + + * java/text/CollationKey.java: + Merged copyright and dat from classpath. + * java/text/RuleBasedCollator.java: + Merged class documentation from classpath. + 2003-05-19 Michael Koch * java/nio/CharBuffer.java diff --git a/libjava/java/text/CollationKey.java b/libjava/java/text/CollationKey.java index ff57446d804..9517756cd14 100644 --- a/libjava/java/text/CollationKey.java +++ b/libjava/java/text/CollationKey.java @@ -1,6 +1,6 @@ /* CollationKey.java -- Precomputed collation value + Copyright (C) 1998, 1999, 2000, 2003 Free Software Foundation, Inc. -/* Copyright (C) 1999, 2000 Free Software Foundation This file is part of GNU Classpath. GNU Classpath is free software; you can redistribute it and/or modify @@ -61,6 +61,7 @@ package java.text; * * @author Aaron M. Renn * @author Tom Tromey + * @date March 25, 1999 */ public final class CollationKey implements Comparable { diff --git a/libjava/java/text/RuleBasedCollator.java b/libjava/java/text/RuleBasedCollator.java index 799c3a2088f..2db63881ce2 100644 --- a/libjava/java/text/RuleBasedCollator.java +++ b/libjava/java/text/RuleBasedCollator.java @@ -1,6 +1,6 @@ /* RuleBasedCollator.java -- Concrete Collator Class + Copyright (C) 1998, 1999, 2000, 2001, 2003 Free Software Foundation, Inc. -/* Copyright (C) 1999, 2000, 2001 Free Software Foundation This file is part of GNU Classpath. GNU Classpath is free software; you can redistribute it and/or modify @@ -48,6 +48,91 @@ import java.util.Vector; */ /** + * This class is a concrete subclass of Collator suitable + * for string collation in a wide variety of languages. An instance of + * this class is normally returned by the getInstance method + * of Collator with rules predefined for the requested + * locale. However, an instance of this class can be created manually + * with any desired rules. + *

+ * Rules take the form of a String with the following syntax + *

    + *
  • Modifier: '@' + *
  • Relation: '<' | ';' | ',' | '=' : + *
  • Reset: '&' : + *
+ * The modifier character indicates that accents sort backward as is the + * case with French. The relational operators specify how the text + * argument relates to the previous term. The relation characters have + * the following meanings: + *
    + *
  • '<' - The text argument is greater than the prior term at the primary + * difference level. + *
  • ';' - The text argument is greater than the prior term at the secondary + * difference level. + *
  • ',' - The text argument is greater than the prior term at the tertiary + * difference level. + *
  • '=' - The text argument is equal to the prior term + *
+ *

+ * As for the text argument itself, this is any sequence of Unicode + * characters not in the following ranges: 0x0009-0x000D, 0x0020-0x002F, + * 0x003A-0x0040, 0x005B-0x0060, and 0x007B-0x007E. If these characters are + * desired, they must be enclosed in single quotes. If any whitespace is + * encountered, it is ignored. (For example, "a b" is equal to "ab"). + *

+ * The reset operation inserts the following rule at the point where the + * text argument to it exists in the previously declared rule string. This + * makes it easy to add new rules to an existing string by simply including + * them in a reset sequence at the end. Note that the text argument, or + * at least the first character of it, must be present somewhere in the + * previously declared rules in order to be inserted properly. If this + * is not satisfied, a ParseException will be thrown. + *

+ * This system of configuring RuleBasedCollator is needlessly + * complex and the people at Taligent who developed it (along with the folks + * at Sun who accepted it into the Java standard library) deserve a slow + * and agonizing death. + *

+ * Here are a couple of example of rule strings: + *

+ * "< a < b < c" - This string says that a is greater than b which is + * greater than c, with all differences being primary differences. + *

+ * "< a,A < b,B < c,C" - This string says that 'A' is greater than 'a' with + * a tertiary strength comparison. Both 'b' and 'B' are greater than 'a' and + * 'A' during a primary strength comparison. But 'B' is greater than 'b' + * under a tertiary strength comparison. + *

+ * "< a < c & a < b " - This sequence is identical in function to the + * "< a < b < c" rule string above. The '&' reset symbol indicates that + * the rule "< b" is to be inserted after the text argument "a" in the + * previous rule string segment. + *

+ * "< a < b & y < z" - This is an error. The character 'y' does not appear + * anywhere in the previous rule string segment so the rule following the + * reset rule cannot be inserted. + *

+ * For a description of the various comparison strength types, see the + * documentation for the Collator class. + *

+ * As an additional complication to this already overly complex rule scheme, + * if any characters precede the first rule, these characters are considered + * ignorable. They will be treated as if they did not exist during + * comparisons. For example, "- < a < b ..." would make '-' an ignorable + * character such that the strings "high-tech" and "hightech" would + * be considered identical. + *

+ * A ParseException will be thrown for any of the following + * conditions: + *

    + *
  • Unquoted punctuation characters in a text argument. + *
  • A relational or reset operator not followed by a text argument + *
  • A reset operator where the text argument is not present in + * the previous rule string section. + *
+ * + * @author Aaron M. Renn * @author Tom Tromey * @date March 25, 1999 */