AlphabeticIndex

class AlphabeticIndex<V : Any!> : MutableIterable<AlphabeticIndex.Bucket<V>!>
kotlin.Any
   ↳ android.icu.text.AlphabeticIndex

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<Integer> index = new AlphabeticIndex<Integer>(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<Integer> bucket : index) { if (showAll || bucket.size() != 0) { showLabelAtTop(UI, bucket.getLabel()); } } ... // Show the buckets with their contents, skipping empty buckets for (AlphabeticIndex.Bucket<Integer> bucket : index) { if (bucket.size() != 0) { showLabelInList(UI, bucket.getLabel()); for (AlphabeticIndex.Record<Integer> 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.ImmutableIndex, or the AlphabeticIndex itself, to support sorting on a client that doesn't support AlphabeticIndex functionality.

The ImmutableIndex is both immutable and thread-safe. The corresponding AlphabeticIndex methods are not thread-safe because they "lazily" build the index buckets.

  • ImmutableIndex.getBucket(index) provides random access to all buckets and their labels and label types.
  • AlphabeticIndex.getBucketLabels() or the bucket iterator on either class 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 = index.getBucketIndex(name); String label = immutableIndex.getBucket(bucketIndex).getLabel(); // optional 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.

Requires API level 24 (Android 7.0, Nougat)

Summary

Nested classes

An index "bucket" with a label string and type.

Immutable, thread-safe version of AlphabeticIndex.

A (name, data) pair, to be sorted by name into one of the index buckets.

Public constructors
<init>(locale: ULocale!)

Create the index object.

<init>(locale: Locale!)

Create the index object.

Create an AlphabeticIndex that uses a specific collator.

Public methods
Int

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

RuleBasedCollator!

Get a clone of the collator used internally.

AlphabeticIndex<V>!
setMaxLabelCount(maxLabelCount: Int)

Set a limit on the number of labels in the index.

AlphabeticIndex.ImmutableIndex<V>!

Builds an immutable, thread-safe version of this instance, without data records.

MutableIterator<AlphabeticIndex.Bucket<V>!>

Return an iterator over the buckets.

AlphabeticIndex<V>!
setUnderflowLabel(underflowLabel: String!)

Set the underflowLabel label
Requires API level 24 (Android 7.0, Nougat)

AlphabeticIndex<V>!
setInflowLabel(inflowLabel: String!)

Set the inflowLabel label
Requires API level 24 (Android 7.0, Nougat)

Int

Get the bucket number for the given name.

Int

Return the number of buckets in the index.

String!

Get the default label used for abbreviated buckets between other labels.

AlphabeticIndex<V>!
addRecord(name: CharSequence!, data: V)

Add a record (name and data) to the index.

Int

Get the limit on the number of labels in the index.

String!

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

String!

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

AlphabeticIndex<V>!

Clear the index.

AlphabeticIndex<V>!
addLabels(additions: UnicodeSet!)

Add more index characters (aside from what are in the locale)
Requires API level 24 (Android 7.0, Nougat)

AlphabeticIndex<V>!
addLabels(vararg additions: ULocale!)

Add more index characters (aside from what are in the locale)
Requires API level 24 (Android 7.0, Nougat)

AlphabeticIndex<V>!
addLabels(vararg additions: Locale!)

Add more index characters (aside from what are in the locale)
Requires API level 24 (Android 7.0, Nougat)

MutableList<String!>!

Get the labels.

AlphabeticIndex<V>!
setOverflowLabel(overflowLabel: String!)

Set the overflow label
Requires API level 24 (Android 7.0, Nougat)

Public constructors

<init>

AlphabeticIndex(locale: ULocale!)

Create the index object.

Parameters
locale ULocale!: The locale for the index.

<init>

AlphabeticIndex(locale: Locale!)

Create the index object.

Parameters
locale Locale!: The locale for the index.

<init>

AlphabeticIndex(collator: RuleBasedCollator!)

Create an AlphabeticIndex that uses a specific collator.

The index will be created with no labels; the addLabels() function must be called after creation to add the desired labels to the index.

The index will work directly with the supplied collator. If the caller will need to continue working with the collator it should be cloned first, so that the collator provided to the AlphabeticIndex remains unchanged after creation of the index.

Parameters
collator RuleBasedCollator!: The collator to use to order the contents of this index.

Public methods

getRecordCount

added in API level 24
fun getRecordCount(): Int

Return the number of records in the index: that is, the total number of distinct <name,data> pairs added with addRecord(...), over all the buckets.
Requires API level 24 (Android 7.0, Nougat)

Return
Int: total number of records in buckets

getCollator

added in API level 24
fun getCollator(): RuleBasedCollator!

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.
Requires API level 24 (Android 7.0, Nougat)

Return
RuleBasedCollator!: a clone of the collator used internally

setMaxLabelCount

added in API level 24
fun setMaxLabelCount(maxLabelCount: Int): AlphabeticIndex<V>!

Set a limit on the number of labels in the index. The number of buckets can be slightly larger: see getBucketCount().
Requires API level 24 (Android 7.0, Nougat)

Parameters
maxLabelCount Int: 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.
Return
AlphabeticIndex<V>!: this, for chaining

buildImmutableIndex

added in API level 24
fun buildImmutableIndex(): AlphabeticIndex.ImmutableIndex<V>!

Builds an immutable, thread-safe version of this instance, without data records.
Requires API level 24 (Android 7.0, Nougat)

Return
AlphabeticIndex.ImmutableIndex<V>!: an immutable index instance

iterator

added in API level 24
fun iterator(): MutableIterator<AlphabeticIndex.Bucket<V>!>

Return an iterator over the buckets.
Requires API level 24 (Android 7.0, Nougat)

Return
MutableIterator<AlphabeticIndex.Bucket<V>!>: iterator over buckets.

setUnderflowLabel

added in API level 24
fun setUnderflowLabel(underflowLabel: String!): AlphabeticIndex<V>!

Set the underflowLabel label
Requires API level 24 (Android 7.0, Nougat)

Parameters
underflowLabel String!: see class description
Return
AlphabeticIndex<V>!: this, for chaining

setInflowLabel

added in API level 24
fun setInflowLabel(inflowLabel: String!): AlphabeticIndex<V>!

Set the inflowLabel label
Requires API level 24 (Android 7.0, Nougat)

Parameters
inflowLabel String!: see class description
Return
AlphabeticIndex<V>!: this, for chaining

getBucketIndex

added in API level 24
fun getBucketIndex(name: CharSequence!): Int

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.
Requires API level 24 (Android 7.0, Nougat)

Parameters
name CharSequence!: Name, such as a name
Return
Int: the bucket index for the name

getBucketCount

added in API level 24
fun getBucketCount(): Int

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).
Requires API level 24 (Android 7.0, Nougat)

Return
Int: number of buckets

getInflowLabel

added in API level 24
fun getInflowLabel(): String!

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 ... Α Β Γ.
Requires API level 24 (Android 7.0, Nougat)

Return
String!: inflow label

addRecord

added in API level 24
fun addRecord(name: CharSequence!, data: V): AlphabeticIndex<V>!

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.
Requires API level 24 (Android 7.0, Nougat)

Parameters
name CharSequence!: Name, such as a name
data CharSequence!: Data, such as an address or link
Return
AlphabeticIndex<V>!: this, for chaining

getMaxLabelCount

added in API level 24
fun getMaxLabelCount(): Int

Get the limit on the number of labels in the index. The number of buckets can be slightly larger: see getBucketCount().
Requires API level 24 (Android 7.0, Nougat)

Return
Int: maxLabelCount maximum number of labels.

getUnderflowLabel

added in API level 24
fun getUnderflowLabel(): String!

Get the default label used in the IndexCharacters' locale for underflow, eg the last item in: X Y Z ...
Requires API level 24 (Android 7.0, Nougat)

Return
String!: underflow label

getOverflowLabel

added in API level 24
fun getOverflowLabel(): String!

Get the default label used in the IndexCharacters' locale for overflow, eg the first item in: ... A B C
Requires API level 24 (Android 7.0, Nougat)

Return
String!: overflow label

clearRecords

added in API level 24
fun clearRecords(): AlphabeticIndex<V>!

Clear the index.
Requires API level 24 (Android 7.0, Nougat)

Return
AlphabeticIndex<V>!: this, for chaining

addLabels

added in API level 24
fun addLabels(additions: UnicodeSet!): AlphabeticIndex<V>!

Add more index characters (aside from what are in the locale)
Requires API level 24 (Android 7.0, Nougat)

Parameters
additions UnicodeSet!: additional characters to add to the index, such as A-Z.
Return
AlphabeticIndex<V>!: this, for chaining

addLabels

added in API level 24
fun addLabels(vararg additions: ULocale!): AlphabeticIndex<V>!

Add more index characters (aside from what are in the locale)
Requires API level 24 (Android 7.0, Nougat)

Parameters
additions ULocale!: additional characters to add to the index, such as those in Swedish.
Return
AlphabeticIndex<V>!: this, for chaining

addLabels

added in API level 24
fun addLabels(vararg additions: Locale!): AlphabeticIndex<V>!

Add more index characters (aside from what are in the locale)
Requires API level 24 (Android 7.0, Nougat)

Parameters
additions Locale!: additional characters to add to the index, such as those in Swedish.
Return
AlphabeticIndex<V>!: this, for chaining

getBucketLabels

added in API level 24
fun getBucketLabels(): MutableList<String!>!

Get the labels.
Requires API level 24 (Android 7.0, Nougat)

Return
MutableList<String!>!: The list of bucket labels, after processing.

setOverflowLabel

added in API level 24
fun setOverflowLabel(overflowLabel: String!): AlphabeticIndex<V>!

Set the overflow label
Requires API level 24 (Android 7.0, Nougat)

Parameters
overflowLabel String!: see class description
Return
AlphabeticIndex<V>!: this, for chaining