Class AlphabeticIndex

Create a new alphabetic index instance. This class handles alphabetic indexes which are collated sequences of buckets into which elements are placed, sorted appropriate to the given language. An example would be an index of person names in a contact list, organized by the first letter of the family name.

Example in English:

Buckets: 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
   Adams
   Albers
   Alvarez
B
   Baker
   Banerjee
   Brunshteyn
...

This class can give you the sorted list of labels to show in the UI. It can also organize a list of string elements into buckets for each label so that you can display the correctly sorted elements. This depends on the Collator class to perform the sorting/collation.

The class also supports having buckets for strings before the first (underflow) and after the last (overflow) bucket.

If you have a lot of characters that are not commonly used in the current locale, you can add more labels for those characters as well. Elements will match those buckets only if they have the same first character as the bucket label.

The options object may contain any (or none) of the following properties:

locale - locale or localeSpec to use to parse the address. If not specified, this function will use the current ilib locale style - the style of collation to use for this index. For some locales, there are different styles of collating strings depending on what kind of strings are being collated or what the preference of the user is. For example, in German, there is a phonebook order and a dictionary ordering that sort the same array of strings slightly differently. The static method Collator#getAvailableStyles will return a list of collation styles that ilib currently knows about for any given locale. If the value of the style option is not recognized for a locale, it will be ignored. Default style is "standard".
overflowLabel - the label to use for the overflow bucket. Default: "#"
underflowLabel - the label to use for the underflow bucket. Default: "*"
onLoad - a callback function to call when the address info for the locale is fully loaded and the index is ready to be used. When the onLoad option is given, the alphabetic index object will attempt to load any missing locale data using the ilib loader callback. When the constructor is done (even if the data is already preassembled), the onLoad function is called with the current instance as a parameter, so this callback can be used with preassembled or dynamic loading or a mix of the two.
sync - tell whether to load any missing locale data synchronously or asynchronously. If this option is given as "false", then the "onLoad" callback must be given, as the instance returned from this constructor will not be usable for a while.
loadParams - an object containing parameters to pass to the loader callback function when locale data is missing. The parameters are not interpretted or modified in any way. They are simply passed along. The object may contain any property/value pairs as long as the calling code is in agreement with the loader callback function as to what those parameters mean.

Defined in: AlphabeticIndex.js.

Class Summary

Constructor Attributes Constructor Name and Description

AlphabeticIndex(options)

Method Summary

Method Attributes Method Name and Description

addElement(element)

Add an element to the index.

addLabels(labels, start)

Add labels to this index for characters that are not commonly used in the current locale.

clear()

Clear all elements from the buckets.

getAllBucketLabels()

Return the all the bucket labels typically used in the locale.

getAllBuckets()

Return a javascript hash containing all elements in the index.

getBucket(element)

Return the label of the bucket for a given element.

getBucketCount()

Return the total number of buckets in this index.

getBucketLabels()

Return the bucket labels for this index in order.

getCollator()

Return the collator used to sort elements in this index.

getElementCount()

Return the total number of elements in the index.

getIndexStyle()

Return default indexing style in the current locale.

getLocale()

Return the locale used with this instance.

getOverflowLabel()

Get the default label used in the for overflow bucket.

getUnderflowLabel()

Get the default label used in underflow, This is the last item in a list.

setOverflowLabel(overflowLabel)

Set the overflow bucket label.

setUnderflowLabel(underflowLabel)

Set the underflow bucket label.

Class Detail

AlphabeticIndex(options)

Parameters:

{Object} options

options to the parser

Method Detail

{string|undefined} addElement(element)

Add an element to the index. The element is added to the appropriate bucket and sorted within that bucket according to the collation for the locale set up within this index.

Parameters:

{string|undefined} element

the element to add

Returns:

{string|undefined} the label of the bucket into which this element was added

addLabels(labels, start)

Add labels to this index for characters that are not commonly used in the current locale. These are added into the list of bucket labels at the given start index. If start is not given, or is not within the range of 0 (the overflow bucket) to N (the underflow bucket), then the default position is at the end of the list right before the underflow bucket.

Parameters:

{Array.} labels

array of labels to add in the order you would like to see them returned

{number=} start

the position in the bucket labels list to add these new labels

clear()

Clear all elements from the buckets. This index can be reused for a new batch of elements by clearing it first.

{Array.} getAllBucketLabels()

Return the all the bucket labels typically used in the locale. This includes all bucket labels, even if those buckets do not contain any elements.

Returns:

{Array.} the array of bucket labels for this index in collation order

{Object} getAllBuckets()

Return a javascript hash containing all elements in the index. The hash has a property for each bucket, and the value of the property is an array of elements. Example: [ { label: "A", elements: [ "A", "Aachen", "Adams", ... ] }, { label: "B", elements: ["B", "Baaa", "Boo"] }, ... { label: "#", elements: ["3par.com", "@handle"] } ] All elements within a bucket are sorted per the collation for the locale of this index.

Returns:

{Object} a hash of all buckets and elements as per the description above.

{string|undefined} getBucket(element)

Return the label of the bucket for a given element. This follows the rules set up when the index was instantiated to find the bucket into which the element would go if it were added to this index. The element is not added to the index, however. (See addElement for that.)

Parameters:

{string|undefined} element

the element to check

Returns:

{string|undefined} the label for the bucket for this element

{number} getBucketCount()

Return the total number of buckets in this index.

Returns:

{number} the number of buckets in this index

{Array.} getBucketLabels()

Return the bucket labels for this index in order. This method only returns the index labels for buckets that actually contain elements. This will include the under- and overflow labels if they are used in this index.

Returns:

{Array.} the array of bucket labels for this index in collation order

{Collator} getCollator()

Return the collator used to sort elements in this index.

Returns:

{Collator} the ilib Collator instance used in this index

{number} getElementCount()

Return the total number of elements in the index. This includes all elements across all buckets.

Returns:

{number} The number of elements in the index

{string} getIndexStyle()

Return default indexing style in the current locale.

Returns:

{string} the default indexing style for this locale.

{Locale} getLocale()

Return the locale used with this instance.

Returns:

{Locale} the Locale instance for this index

{string} getOverflowLabel()

Get the default label used in the for overflow bucket. This is the first item in a list. eg. ... A B C

Returns:

{string} the overflow bucket label

{string} getUnderflowLabel()

Get the default label used in underflow, This is the last item in a list. eg. the last item in: X Y Z #

Returns:

{string} the label used for underflow elements

setOverflowLabel(overflowLabel)

Set the overflow bucket label.

Parameters:

{string} overflowLabel

the label to use for the overflow buckets

setUnderflowLabel(underflowLabel)

Set the underflow bucket label.

Parameters:

{string} underflowLabel

the label to use for the underflow buckets

Method Attributes	Method Name and Description
	addElement(element) Add an element to the index.
	addLabels(labels, start) Add labels to this index for characters that are not commonly used in the current locale.
	clear() Clear all elements from the buckets.
	getAllBucketLabels() Return the all the bucket labels typically used in the locale.
	getAllBuckets() Return a javascript hash containing all elements in the index.
	getBucket(element) Return the label of the bucket for a given element.
	getBucketCount() Return the total number of buckets in this index.
	getBucketLabels() Return the bucket labels for this index in order.
	getCollator() Return the collator used to sort elements in this index.
	getElementCount() Return the total number of elements in the index.
	getIndexStyle() Return default indexing style in the current locale.
	getLocale() Return the locale used with this instance.
	getOverflowLabel() Get the default label used in the for overflow bucket.
	getUnderflowLabel() Get the default label used in underflow, This is the last item in a list.
	setOverflowLabel(overflowLabel) Set the overflow bucket label.
	setUnderflowLabel(underflowLabel) Set the underflow bucket label.

Classes

Class AlphabeticIndex