com.ibm.icu.text
Class AlphabeticIndex<V>

java.lang.Object
  com.ibm.icu.text.AlphabeticIndex<V>

All Implemented Interfaces:

Iterable<AlphabeticIndex.Bucket<V>>

public final class AlphabeticIndex<V>
extends Object
implements Iterable<AlphabeticIndex.Bucket<V>>

AlphabeticIndex supports the creation of a UI index appropriate for a given language. It can support either direct use, or use with a client that doesn't support localized collation. The following is an example of what an index might look like in a UI:

  ... A B C D E F G H I J K L M N O P Q R S T U V W X Y Z  ...
  
  A
     Addison
     Albertson
     Azensky
  B
     Baecker
  ...
 

The class can generate a list of labels for use as a UI "index", that is, a list of clickable characters (or character sequences) that allow the user to see a segment (bucket) of a larger "target" list. That is, each label corresponds to a bucket in the target list, where everything in the bucket is greater than or equal to the character (according to the locale's collation). Strings can be added to the index; they will be in sorted order in the right bucket.

The class also supports having buckets for strings before the first (underflow), after the last (overflow), and between scripts (inflow). For example, if the index is constructed with labels for Russian and English, Greek characters would fall into an inflow bucket between the other two scripts.

Note: If you expect to have a lot of ASCII or Latin characters as well as characters from the user's language, then it is a good idea to call addLabels(ULocale.English).

Direct Use

The following shows an example of building an index directly. The "show..." methods below are just to illustrate usage.

 // Create a simple index where the values for the strings are Integers, and add the strings
 
 AlphabeticIndex index = new AlphabeticIndex(desiredLocale).addLabels(additionalLocale);
 int counter = 0;
 for (String item : test) {
     index.addRecord(item, counter++); 
 }
 ...
 // Show index at top. We could skip or gray out empty buckets
 
 for (AlphabeticIndex.Bucket bucket : index) {
     if (showAll || bucket.size() != 0) {
         showLabelAtTop(UI, bucket.getLabel());
     }
 }
  ...
 // Show the buckets with their contents, skipping empty buckets
 
 for (AlphabeticIndex.Bucket bucket : index) {
     if (bucket.size() != 0) {
         showLabelInList(UI, bucket.getLabel());
         for (AlphabeticIndex.Record item : bucket) {
             showIndexedItem(UI, item.getName(), item.getData());
         }
 

The caller can build different UIs using this class. For example, an index character could be omitted or grayed-out if its bucket is empty. Small buckets could also be combined based on size, such as:

 ... A-F G-N O-Z ...
 

Client Support

Callers can also use the AlphabeticIndex to support sorting on a client that doesn't support collation.

• getLabels() can be used to get a list of the labels, such as "...", "A", "B",..., and send that list to the client.
• When the client has a new name, it sends that name to the server. The server needs to call the following methods, and communicate the bucketIndex and collationKey back to the client.

   int bucketIndex = alphabeticIndex.getBucketIndex(name);
   RawCollationKey collationKey = collator.getRawCollationKey(name, null);
   

• The client would put the name (and associated information) into its bucket for bucketIndex. The collationKey is a sequence of bytes that can be compared with a binary compare, and produce the right localized result.

Notes:

• Additional collation parameters can be passed in as part of the locale name. For example, German plus numeric sorting would be "de@kn-true".

  Author:

  markdavis

  Status:

  Draft ICU 4.6.

  Nested Class Summary

  static class	AlphabeticIndex.Bucket<V> A "bucket", containing records sorted under an index string by getIndexBucketCharacters.
  static class	AlphabeticIndex.Record<V> A record to be sorted into buckets with getIndexBucketCharacters.

  Constructor Summary

  AlphabeticIndex(Locale locale)
  Create the index object.

  AlphabeticIndex(ULocale locale)
  Create the index object.

  AlphabeticIndex(ULocale locale, RuleBasedCollator collator, UnicodeSet exemplarChars)
  Deprecated. This API is ICU internal only, for testing purposes and use with CLDR.

  Method Summary

  AlphabeticIndex<V>	addLabels(Locale... additions) Add more index characters (aside from what are in the locale)
  AlphabeticIndex<V>	addLabels(ULocale... additions) Add more index characters (aside from what are in the locale)
  AlphabeticIndex<V>	addLabels(UnicodeSet additions) Add more index characters (aside from what are in the locale)
  AlphabeticIndex<V>	addRecord(CharSequence name, V data) Add a record (name and data) to the index.
  AlphabeticIndex<V>	clearRecords() Clear the index.
  Map<String,Set<String>>	getAlreadyIn() Deprecated. This API is ICU internal only.
  int	getBucketCount() Return the number of buckets in the index.
  int	getBucketIndex(CharSequence name) Get the bucket number for the given name.
  List<String>	getBucketLabels() Get the labels.
  RuleBasedCollator	getCollator() Get a clone of the collator used internally.
  static List<String>	getFirstCharactersInScripts() Deprecated. only for internal testing
  List<String>	getFirstScriptCharacters() Deprecated. This API is ICU internal only.
  String	getInflowLabel() Get the default label used for abbreviated buckets between other labels.
  int	getMaxLabelCount() Get the limit on the number of labels in the index.
  List<String>	getNoDistinctSorting() Deprecated. This API is ICU internal only.
  List<String>	getNotAlphabetic() Deprecated. This API is ICU internal only.
  String	getOverflowComparisonString(String lowerLimit) Deprecated. This API is ICU internal only.
  String	getOverflowLabel() Get the default label used in the IndexCharacters' locale for overflow, eg the first item in: ...
  int	getRecordCount() Return the number of records in the index: that is, the total number of distinct pairs added with addRecord(...), over all the buckets.
  String	getUnderflowLabel() Get the default label used in the IndexCharacters' locale for underflow, eg the last item in: X Y Z ...
  Iterator<AlphabeticIndex.Bucket<V>>	iterator() Return an iterator over the buckets.
  AlphabeticIndex<V>	setInflowLabel(String inflowLabel) Set the inflowLabel label
  AlphabeticIndex<V>	setMaxLabelCount(int maxLabelCount) Set a limit on the number of labels in the index.
  AlphabeticIndex<V>	setOverflowLabel(String overflowLabel) Set the overflow label
  AlphabeticIndex<V>	setUnderflowLabel(String underflowLabel) Set the underflowLabel label

  Methods inherited from class java.lang.Object

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

  Constructor Detail

  AlphabeticIndex

  public AlphabeticIndex(ULocale locale)

  Create the index object.

  Parameters:

  locale - The locale for the index.

  Status:

  Draft ICU 4.6.

  AlphabeticIndex

  public AlphabeticIndex(Locale locale)

  Create the index object.

  Parameters:

  locale - The locale for the index.

  Status:

  Draft ICU 4.6.

  AlphabeticIndex

  public AlphabeticIndex(ULocale locale,
                         RuleBasedCollator collator,
                         UnicodeSet exemplarChars)

  Deprecated. This API is ICU internal only, for testing purposes and use with CLDR.

  Status:

  Internal. This API is ICU internal only.

  Method Detail

  addLabels

  public AlphabeticIndex<V> addLabels(UnicodeSet additions)

  Add more index characters (aside from what are in the locale)

  Parameters:

  additions - additional characters to add to the index, such as A-Z.

  Returns:

  this, for chaining

  Status:

  Draft ICU 4.6.

  addLabels

  public AlphabeticIndex<V> addLabels(ULocale... additions)

  Add more index characters (aside from what are in the locale)

  Parameters:

  additions - additional characters to add to the index, such as those in Swedish.

  Returns:

  this, for chaining

  Status:

  Draft ICU 4.6.

  addLabels

  public AlphabeticIndex<V> addLabels(Locale... additions)

  Add more index characters (aside from what are in the locale)

  Parameters:

  additions - additional characters to add to the index, such as those in Swedish.

  Returns:

  this, for chaining

  Status:

  Draft ICU 4.6.

  setOverflowLabel

  public AlphabeticIndex<V> setOverflowLabel(String overflowLabel)

  Set the overflow label

  Parameters:

  overflowLabel - see class description

  Returns:

  this, for chaining

  Status:

  Draft ICU 4.6.

  getUnderflowLabel

  public String getUnderflowLabel()

  Get the default label used in the IndexCharacters' locale for underflow, eg the last item in: X Y Z ...

  Returns:

  underflow label

  Status:

  Draft ICU 4.6.

  setUnderflowLabel

  public AlphabeticIndex<V> setUnderflowLabel(String underflowLabel)

  Set the underflowLabel label

  Parameters:

  underflowLabel - see class description

  Returns:

  this, for chaining

  Status:

  Draft ICU 4.6.

  getOverflowLabel

  public String getOverflowLabel()

  Get the default label used in the IndexCharacters' locale for overflow, eg the first item in: ... A B C

  Returns:

  overflow label

  Status:

  Draft ICU 4.6.

  setInflowLabel

  public AlphabeticIndex<V> setInflowLabel(String inflowLabel)

  Set the inflowLabel label

  Parameters:

  inflowLabel - see class description

  Returns:

  this, for chaining

  Status:

  Draft ICU 4.6.

  getInflowLabel

  public String getInflowLabel()

  Get the default label used for abbreviated buckets between other labels. For example, consider the labels for Latin and Greek are used: X Y Z ... Α Β Γ.

  Returns:

  inflow label

  Status:

  Draft ICU 4.6.

  getMaxLabelCount

  public int getMaxLabelCount()

  Get the limit on the number of labels in the index. The number of buckets can be slightly larger: see getBucketCount().

  Returns:

  maxLabelCount maximum number of labels.

  Status:

  Draft ICU 4.6.

  setMaxLabelCount

  public AlphabeticIndex<V> setMaxLabelCount(int maxLabelCount)

  Set a limit on the number of labels in the index. The number of buckets can be slightly larger: see getBucketCount().

  Returns:

  maxLabelCount label Set the maximum number of labels. Currently, if the number is exceeded, then every nth item is removed to bring the count down. A more sophisticated mechanism may be available in the future.

  Status:

  Draft ICU 4.6.

  getBucketLabels

  public List<String> getBucketLabels()

  Get the labels.

  Returns:

  A collection listing the labels, after processing.

  Status:

  Draft ICU 4.6.

  getCollator

  public RuleBasedCollator getCollator()

  Get a clone of the collator used internally. Note that for performance reasons, the clone is only done once, and then stored. The next time it is accessed, the same instance is returned.

  Don't use this method across threads if you are changing the settings on the collator, at least not without synchronizing.

  Returns:

  a clone of the collator used internally

  Status:

  Draft ICU 4.6.

  addRecord

  public AlphabeticIndex<V> addRecord(CharSequence name,
                                      V data)

  Add a record (name and data) to the index. The name will be used to sort the items into buckets, and to sort within the bucket. Two records may have the same name. When they do, the sort order is according to the order added: the first added comes first.

  Parameters:

  name - Name, such as a name

  data - Data, such as an address or link

  Returns:

  this, for chaining

  Status:

  Draft ICU 4.6.

  getBucketIndex

  public int getBucketIndex(CharSequence name)

  Get the bucket number for the given name. This routine permits callers to implement their own bucket handling mechanisms, including client-server handling. For example, when a new name is created on the client, it can ask the server for the bucket for that name, and the sortkey (using getCollator). Once the client has that information, it can put the name into the right bucket, and sort it within that bucket, without having access to the index or collator.

  Note that the bucket number (and sort key) are only valid for the settings of the current AlphabeticIndex; if those are changed, then the bucket number and sort key must be regenerated.

  Parameters:

  name - Name, such as a name

  Returns:

  this, for chaining

  Status:

  Draft ICU 4.6.

  clearRecords

  public AlphabeticIndex<V> clearRecords()

  Clear the index.

  Returns:

  this, for chaining

  Status:

  Draft ICU 4.6.

  getBucketCount

  public int getBucketCount()

  Return the number of buckets in the index. This will be the same as the number of labels, plus buckets for the underflow, overflow, and inflow(s).

  Returns:

  number of buckets

  Status:

  Draft ICU 4.6.

  getRecordCount

  public int getRecordCount()

  Return the number of records in the index: that is, the total number of distinct pairs added with addRecord(...), over all the buckets.

  Returns:

  total number of records in buckets

  Status:

  Draft ICU 4.6.

  iterator

  public Iterator<AlphabeticIndex.Bucket<V>> iterator()

  Return an iterator over the buckets.

  Specified by:

  iterator in interface Iterable<AlphabeticIndex.Bucket<V>>

  Returns:

  iterator over buckets.

  Status:

  Draft ICU 4.6.

  getOverflowComparisonString

  public String getOverflowComparisonString(String lowerLimit)

  Deprecated. This API is ICU internal only.

  Get the Unicode character (or tailored string) that defines an overflow bucket; that is anything greater than or equal to that string should go in that bucket, instead of with the last character. Normally that is the first character of the script after lowerLimit. Thus in X Y Z ... Devanagari-ka, the overflow character for Z would be the Greek-alpha.

  Parameters:

  lowerLimit - The character below the overflow (or inflow) bucket

  Returns:

  string that defines top of the overflow buck for lowerLimit, or null if there is none

  Status:

  Internal. This API is ICU internal only.

  getFirstScriptCharacters

  public List<String> getFirstScriptCharacters()

  Deprecated. This API is ICU internal only.

  Return a list of the first character in each script, in collation order. Only exposed for testing.

  Returns:

  list of first characters in each script

  Status:

  Internal. This API is ICU internal only.

  getAlreadyIn

  public Map<String,Set<String>> getAlreadyIn()

  Deprecated. This API is ICU internal only.

  As the index is built, strings may be discarded from the exemplars. This contains some of the discards, and is intended for debugging.

  Status:

  Internal. This API is ICU internal only.

  getNoDistinctSorting

  public List<String> getNoDistinctSorting()

  Deprecated. This API is ICU internal only.

  As the index is built, strings may be discarded from the exemplars. This contains some of the discards, and is intended for debugging.

  Status:

  Internal. This API is ICU internal only.

  getNotAlphabetic

  public List<String> getNotAlphabetic()

  Deprecated. This API is ICU internal only.

  As the index is built, strings may be discarded from the exemplars. This contains some of the discards, and is intended for debugging.

  Status:

  Internal. This API is ICU internal only.

  getFirstCharactersInScripts

  public static List<String> getFirstCharactersInScripts()

  Deprecated. only for internal testing

  Only for testing...

  Status:

  Internal. This API is ICU internal only.