Module java.base
Package java.text

Class CollationElementIterator

java.lang.Object
java.text.CollationElementIterator
public final class CollationElementIterator extends Object
CollationElementIterator类用作遍历国际字符串中每个字符的迭代器。使用该迭代器返回定位字符的排序优先级。字符的排序优先级，我们称之为键，定义了字符在给定排序对象中的排序方式。

例如，考虑以下西班牙语示例：

 "ca" → 第一个键是键('c')，第二个键是键('a')。
 "cha" → 第一个键是键('ch')，第二个键是键('a')。
而在德语中， 
 "äb" → 第一个键是键('a')，第二个键是键('e')，第三个键是键('b')。
字符的键是由主排序（short）、次要排序（byte）和第三排序（byte）组成的整数。Java严格定义了其原始数据类型的大小和有符号性。因此，静态函数primaryOrder、secondaryOrder和tertiaryOrder分别返回int、short和short，以确保键值的正确性。

迭代器用法示例：

String testString = "This is a test";
Collator col = Collator.getInstance();
if (col instanceof RuleBasedCollator ruleBasedCollator) {
    CollationElementIterator collationElementIterator = ruleBasedCollator.getCollationElementIterator(testString);
    int primaryOrder = CollationElementIterator.primaryOrder(collationElementIterator.next());
        ⋮
}

CollationElementIterator.next返回下一个字符的排序顺序。排序顺序包括主排序、次要排序和第三排序。排序顺序的数据类型为int。排序顺序的前16位是其主排序；接下来的8位是次要排序，最后的8位是第三排序。

注意： CollationElementIterator是RuleBasedCollator实现的一部分。它只能与RuleBasedCollator实例一起使用。

自：
1.1
参见：

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    NULLORDER
    表示光标到达字符串末尾的空值。

  • Method Summary

    Modifier and Type
    Method
    Description
    int
    getMaxExpansion(int order)
    返回以指定比较顺序结尾的任何扩展序列的最大长度。
    int
    getOffset()
    返回原始文本中与下一个排序元素对应的字符偏移量。
    int
    next()
    获取字符串中的下一个排序元素。
    int
    previous()
    获取字符串中的上一个排序元素。
    static final int
    primaryOrder(int order)
    返回排序元素的主要组件。
    void
    reset()
    将光标重置到字符串开头。
    static final short
    secondaryOrder(int order)
    返回排序元素的次要组件。
    void
    setOffset(int newOffset)
    将迭代器设置为指向与指定字符对应的排序元素（参数是原始字符串中的字符偏移量，而不是其对应的排序元素序列的偏移量）。
    void
    setText(String source)
    设置要迭代的新字符串。
    void
    setText(CharacterIterator source)
    设置要迭代的新字符串。
    static final short
    tertiaryOrder(int order)
    返回排序元素的第三组件。

    Methods declared in class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • NULLORDER

      public static final int NULLORDER
      表示光标到达字符串末尾的空值。
      参见：

  • Method Details

    • reset

      public void reset()
      将光标重置到字符串开头。下一次调用next()将返回字符串中的第一个排序元素。

    • next

      public int next()
      获取字符串中的下一个排序元素。

      此迭代器遍历从字符串构建的排序元素序列。因为字符到排序元素之间不一定是一对一的映射，这并不意味着“返回字符串中下一个字符的排序元素[或排序优先级]”。

      此函数返回迭代器当前指向的排序元素，然后更新内部指针以指向下一个元素。previous()首先更新指针，然后返回元素。这意味着在迭代时改变方向（即调用next()然后调用previous()，或调用previous()然后调用next()）时，将会两次返回相同的元素。

      返回：
      下一个排序元素

    • previous

      public int previous()
      获取字符串中的上一个排序元素。

      此迭代器遍历从字符串构建的排序元素序列。因为字符到排序元素之间不一定是一对一的映射，这并不意味着“返回字符串中上一个字符的排序元素[或排序优先级]”。

      此函数更新迭代器的内部指针，指向当前指向的排序元素之前的排序元素，然后返回该元素，而next()返回当前元素然后更新指针。这意味着在迭代时改变方向（即调用next()然后调用previous()，或调用previous()然后调用next()）时，将会两次返回相同的元素。

      返回：
      上一个排序元素
      自：
      1.2

    • primaryOrder

      public static final int primaryOrder(int order)
      返回排序元素的主要组件。
      参数：
      order - 排序元素
      返回：
      元素的主要组件

    • secondaryOrder

      public static final short secondaryOrder(int order)
      返回排序元素的次要组件。
      参数：
      order - 排序元素
      返回：
      元素的次要组件

    • tertiaryOrder

      public static final short tertiaryOrder(int order)
      返回排序元素的第三组件。
      参数：
      order - 排序元素
      返回：
      元素的第三组件

    • setOffset

      public void setOffset(int newOffset)
      将迭代器设置为指向与指定字符对应的排序元素（参数是原始字符串中的字符偏移量，而不是其对应的排序元素序列的偏移量）。下一次调用next()返回的值将是文本中指定位置对应的排序元素。如果该位置位于收缩字符序列的中间，则下一次调用next()的结果是该序列的排序元素。这意味着getOffset()不能保证返回与传递给前一个setOffset()调用的值相同的值。
      参数：
      newOffset - 新的字符偏移量到原始文本中
      自：
      1.2

    • getOffset

      public int getOffset()
      返回原始文本中与下一个排序元素对应的字符偏移量。（也就是说，getOffset()返回与下一次调用next()将返回的排序元素对应的文本中的位置。）此值始终是对应于排序元素的第一个字符的索引（当两个或更多字符都对应于相同的排序元素时，这称为收缩字符序列）。这意味着如果您立即执行setOffset(x)然后执行getOffset()，getOffset()不一定会返回x。
      返回：
      下一次调用next()将返回的排序元素对应的原始文本中的字符偏移量。
      自：
      1.2

    • getMaxExpansion

      public int getMaxExpansion(int order)
      返回以指定比较顺序结尾的任何扩展序列的最大长度。
      参数：
      order - 由previous或next返回的排序顺序
      返回：
      以指定顺序结尾的任何扩展序列的最大长度。
      自：
      1.2

    • setText

      public void setText(String source)
      设置要迭代的新字符串。
      参数：
      source - 新的源文本
      自：
      1.2

    • setText

      public void setText(CharacterIterator source)
      设置要迭代的新字符串。
      参数：
      source - 新的源文本。
      自：
      1.2