source/i18n/unicode/alphaindex.h

   1 // Copyright (C) 2016 and later: Unicode, Inc. and others.
   2 // License & terms of use: http://www.unicode.org/copyright.html
   3 /*
   4 *******************************************************************************
   5 *
   6 *   Copyright (C) 2011-2014 International Business Machines
   7 *   Corporation and others.  All Rights Reserved.
   8 *
   9 *******************************************************************************
  10 */
  11
  12 #ifndef INDEXCHARS_H
  13 #define INDEXCHARS_H
  14
  15 #include "unicode/utypes.h"
  16 #include "unicode/uobject.h"
  17 #include "unicode/locid.h"
  18
  19 #if !UCONFIG_NO_COLLATION
  20
  21 /**
  22  * \file
  23  * \brief C++ API: Index Characters
  24  */
  25
  26 U_CDECL_BEGIN
  27
  28 /**
  29  * Constants for Alphabetic Index Label Types.
  30  * The form of these enum constants anticipates having a plain C API
  31  * for Alphabetic Indexes that will also use them.
  32  * @stable ICU 4.8
  33  */
  34 typedef enum UAlphabeticIndexLabelType {
  35     /**
  36      *  Normal Label, typically the starting letter of the names
  37      *  in the bucket with this label.
  38      * @stable ICU 4.8
  39      */
  40     U_ALPHAINDEX_NORMAL    = 0,
  41
  42     /**
  43      * Undeflow Label.  The bucket with this label contains names
  44      * in scripts that sort before any of the bucket labels in this index.
  45      * @stable ICU 4.8
  46      */
  47     U_ALPHAINDEX_UNDERFLOW = 1,
  48
  49     /**
  50      * Inflow Label.  The bucket with this label contains names
  51      * in scripts that sort between two of the bucket labels in this index.
  52      * Inflow labels are created when an index contains normal labels for
  53      * multiple scripts, and skips other scripts that sort between some of the
  54      * included scripts.
  55      * @stable ICU 4.8
  56      */
  57     U_ALPHAINDEX_INFLOW    = 2,
  58
  59     /**
  60      * Overflow Label. Te bucket with this label contains names in scripts
  61      * that sort after all of the bucket labels in this index.
  62      * @stable ICU 4.8
  63      */
  64     U_ALPHAINDEX_OVERFLOW  = 3
  65 } UAlphabeticIndexLabelType;
  66
  67
  68 struct UHashtable;
  69 U_CDECL_END
  70
  71 U_NAMESPACE_BEGIN
  72
  73 // Forward Declarations
  74
  75 class BucketList;
  76 class Collator;
  77 class RuleBasedCollator;
  78 class StringEnumeration;
  79 class UnicodeSet;
  80 class UVector;
  81
  82 /**
  83  * AlphabeticIndex supports the creation of a UI index appropriate for a given language.
  84  * It can support either direct use, or use with a client that doesn't support localized collation.
  85  * The following is an example of what an index might look like in a UI:
  86  *
  87  * <pre>
  88  *  <b>... 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  ...</b>
  89  *
  90  *  <b>A</b>
  91  *     Addison
  92  *     Albertson
  93  *     Azensky
  94  *  <b>B</b>
  95  *     Baker
  96  *  ...
  97  * </pre>
  98  *
  99  * The class can generate a list of labels for use as a UI "index", that is, a list of
 100  * clickable characters (or character sequences) that allow the user to see a segment
 101  * (bucket) of a larger "target" list. That is, each label corresponds to a bucket in
 102  * the target list, where everything in the bucket is greater than or equal to the character
 103  * (according to the locale's collation). Strings can be added to the index;
 104  * they will be in sorted order in the right bucket.
 105  * <p>
 106  * The class also supports having buckets for strings before the first (underflow),
 107  * after the last (overflow), and between scripts (inflow). For example, if the index
 108  * is constructed with labels for Russian and English, Greek characters would fall
 109  * into an inflow bucket between the other two scripts.
 110  * <p>
 111  * The AlphabeticIndex class is not intended for public subclassing.
 112  *
 113  * <p><em>Note:</em> If you expect to have a lot of ASCII or Latin characters
 114  * as well as characters from the user's language,
 115  * then it is a good idea to call addLabels(Locale::getEnglish(), status).</p>
 116  *
 117  * <h2>Direct Use</h2>
 118  * <p>The following shows an example of building an index directly.
 119  *  The "show..." methods below are just to illustrate usage.
 120  *
 121  * <pre>
 122  * // Create a simple index.  "Item" is assumed to be an application
 123  * // defined type that the application's UI and other processing knows about,
 124  * //  and that has a name.
 125  *
 126  * UErrorCode status = U_ZERO_ERROR;
 127  * AlphabeticIndex index = new AlphabeticIndex(desiredLocale, status);
 128  * index->addLabels(additionalLocale, status);
 129  * for (Item *item in some source of Items ) {
 130  *     index->addRecord(item->name(), item, status);
 131  * }
 132  * ...
 133  * // Show index at top. We could skip or gray out empty buckets
 134  *
 135  * while (index->nextBucket(status)) {
 136  *     if (showAll || index->getBucketRecordCount() != 0) {
 137  *         showLabelAtTop(UI, index->getBucketLabel());
 138  *     }
 139  * }
 140  *  ...
 141  * // Show the buckets with their contents, skipping empty buckets
 142  *
 143  * index->resetBucketIterator(status);
 144  * while (index->nextBucket(status)) {
 145  *    if (index->getBucketRecordCount() != 0) {
 146  *        showLabelInList(UI, index->getBucketLabel());
 147  *        while (index->nextRecord(status)) {
 148  *            showIndexedItem(UI, static_cast<Item *>(index->getRecordData()))
 149  * </pre>
 150  *
 151  * The caller can build different UIs using this class.
 152  * For example, an index character could be omitted or grayed-out
 153  * if its bucket is empty. Small buckets could also be combined based on size, such as:
 154  *
 155  * <pre>
 156  * <b>... A-F G-N O-Z ...</b>
 157  * </pre>
 158  *
 159  * <h2>Client Support</h2>
 160  * <p>Callers can also use the AlphabeticIndex::ImmutableIndex, or the AlphabeticIndex itself,
 161  * to support sorting on a client that doesn't support AlphabeticIndex functionality.
 162  *
 163  * <p>The ImmutableIndex is both immutable and thread-safe.
 164  * The corresponding AlphabeticIndex methods are not thread-safe because
 165  * they "lazily" build the index buckets.
 166  * <ul>
 167  * <li>ImmutableIndex.getBucket(index) provides random access to all
 168  *     buckets and their labels and label types.
 169  * <li>The AlphabeticIndex bucket iterator or ImmutableIndex.getBucket(0..getBucketCount-1)
 170  *     can be used to get a list of the labels,
 171  *     such as "...", "A", "B",..., and send that list to the client.
 172  * <li>When the client has a new name, it sends that name to the server.
 173  * The server needs to call the following methods,
 174  * and communicate the bucketIndex and collationKey back to the client.
 175  *
 176  * <pre>
 177  * int32_t bucketIndex = index.getBucketIndex(name, status);
 178  * const UnicodeString &label = immutableIndex.getBucket(bucketIndex)->getLabel();  // optional
 179  * int32_t skLength = collator.getSortKey(name, sk, skCapacity);
 180  * </pre>
 181  *
 182  * <li>The client would put the name (and associated information) into its bucket for bucketIndex. The sort key sk is a
 183  * sequence of bytes that can be compared with a binary compare, and produce the right localized result.</li>
 184  * </ul>
 185  *
 186  * @stable ICU 4.8
 187  */
 188 class U_I18N_API AlphabeticIndex: public UObject {
 189 public:
 190      /**
 191       * An index "bucket" with a label string and type.
 192       * It is referenced by getBucketIndex(),
 193       * and returned by ImmutableIndex.getBucket().
 194       *
 195       * The Bucket class is not intended for public subclassing.
 196       * @stable ICU 51
 197       */
 198      class U_I18N_API Bucket : public UObject {
 199      public:
 200         /**
 201          * Destructor.
 202          * @stable ICU 51
 203          */
 204         virtual ~Bucket();
 205
 206         /**
 207          * Returns the label string.
 208          *
 209          * @return the label string for the bucket
 210          * @stable ICU 51
 211          */
 212         const UnicodeString &getLabel() const { return label_; }
 213         /**
 214          * Returns whether this bucket is a normal, underflow, overflow, or inflow bucket.
 215          *
 216          * @return the bucket label type
 217          * @stable ICU 51
 218          */
 219         UAlphabeticIndexLabelType getLabelType() const { return labelType_; }
 220
 221      private:
 222         friend class AlphabeticIndex;
 223         friend class BucketList;
 224
 225         UnicodeString label_;
 226         UnicodeString lowerBoundary_;
 227         UAlphabeticIndexLabelType labelType_;
 228         Bucket *displayBucket_;
 229         int32_t displayIndex_;
 230         UVector *records_;  // Records are owned by the inputList_ vector.
 231
 232         Bucket(const UnicodeString &label,   // Parameter strings are copied.
 233                const UnicodeString &lowerBoundary,
 234                UAlphabeticIndexLabelType type);
 235      };
 236
 237     /**
 238      * Immutable, thread-safe version of AlphabeticIndex.
 239      * This class provides thread-safe methods for bucketing,
 240      * and random access to buckets and their properties,
 241      * but does not offer adding records to the index.
 242      *
 243      * The ImmutableIndex class is not intended for public subclassing.
 244      *
 245      * @stable ICU 51
 246      */
 247     class U_I18N_API ImmutableIndex : public UObject {
 248     public:
 249         /**
 250          * Destructor.
 251          * @stable ICU 51
 252          */
 253         virtual ~ImmutableIndex();
 254
 255         /**
 256          * Returns the number of index buckets and labels, including underflow/inflow/overflow.
 257          *
 258          * @return the number of index buckets
 259          * @stable ICU 51
 260          */
 261         int32_t getBucketCount() const;
 262
 263         /**
 264          * Finds the index bucket for the given name and returns the number of that bucket.
 265          * Use getBucket() to get the bucket's properties.
 266          *
 267          * @param name the string to be sorted into an index bucket
 268          * @return the bucket number for the name
 269          * @stable ICU 51
 270          */
 271         int32_t getBucketIndex(const UnicodeString &name, UErrorCode &errorCode) const;
 272
 273         /**
 274          * Returns the index-th bucket. Returns NULL if the index is out of range.
 275          *
 276          * @param index bucket number
 277          * @return the index-th bucket
 278          * @stable ICU 51
 279          */
 280         const Bucket *getBucket(int32_t index) const;
 281
 282     private:
 283         friend class AlphabeticIndex;
 284
 285         ImmutableIndex(BucketList *bucketList, Collator *collatorPrimaryOnly)
 286                 : buckets_(bucketList), collatorPrimaryOnly_(collatorPrimaryOnly) {}
 287
 288         BucketList *buckets_;
 289         Collator *collatorPrimaryOnly_;
 290     };
 291
 292     /**
 293      * Construct an AlphabeticIndex object for the specified locale.  If the locale's
 294      * data does not include index characters, a set of them will be
 295      * synthesized based on the locale's exemplar characters.  The locale
 296      * determines the sorting order for both the index characters and the
 297      * user item names appearing under each Index character.
 298      *
 299      * @param locale the desired locale.
 300      * @param status Error code, will be set with the reason if the construction
 301      *               of the AlphabeticIndex object fails.
 302      * @stable ICU 4.8
 303      */
 304      AlphabeticIndex(const Locale &locale, UErrorCode &status);
 305
 306    /**
 307      * Construct an AlphabeticIndex that uses a specific collator.
 308      *
 309      * The index will be created with no labels; the addLabels() function must be called
 310      * after creation to add the desired labels to the index.
 311      *
 312      * The index adopts the collator, and is responsible for deleting it.
 313      * The caller should make no further use of the collator after creating the index.
 314      *
 315      * @param collator The collator to use to order the contents of this index.
 316      * @param status Error code, will be set with the reason if the
 317      *               operation fails.
 318      * @stable ICU 51
 319      */
 320     AlphabeticIndex(RuleBasedCollator *collator, UErrorCode &status);
 321
 322     /**
 323      * Add Labels to this Index.  The labels are additions to those
 324      * that are already in the index; they do not replace the existing
 325      * ones.
 326      * @param additions The additional characters to add to the index, such as A-Z.
 327      * @param status Error code, will be set with the reason if the
 328      *               operation fails.
 329      * @return this, for chaining
 330      * @stable ICU 4.8
 331      */
 332     virtual AlphabeticIndex &addLabels(const UnicodeSet &additions, UErrorCode &status);
 333
 334     /**
 335      * Add the index characters from a Locale to the index.  The labels
 336      * are added to those that are already in the index; they do not replace the
 337      * existing index characters.  The collation order for this index is not
 338      * changed; it remains that of the locale that was originally specified
 339      * when creating this Index.
 340      *
 341      * @param locale The locale whose index characters are to be added.
 342      * @param status Error code, will be set with the reason if the
 343      *               operation fails.
 344      * @return this, for chaining
 345      * @stable ICU 4.8
 346      */
 347     virtual AlphabeticIndex &addLabels(const Locale &locale, UErrorCode &status);
 348
 349      /**
 350       * Destructor
 351       * @stable ICU 4.8
 352       */
 353     virtual ~AlphabeticIndex();
 354
 355     /**
 356      * Builds an immutable, thread-safe version of this instance, without data records.
 357      *
 358      * @return an immutable index instance
 359      * @stable ICU 51
 360      */
 361     ImmutableIndex *buildImmutableIndex(UErrorCode &errorCode);
 362
 363     /**
 364      * Get the Collator that establishes the ordering of the items in this index.
 365      * Ownership of the collator remains with the AlphabeticIndex instance.
 366      *
 367      * The returned collator is a reference to the internal collator used by this
 368      * index.  It may be safely used to compare the names of items or to get
 369      * sort keys for names.  However if any settings need to be changed,
 370      * or other non-const methods called, a cloned copy must be made first.
 371      *
 372      * @return The collator
 373      * @stable ICU 4.8
 374      */
 375     virtual const RuleBasedCollator &getCollator() const;
 376
 377
 378    /**
 379      * Get the default label used for abbreviated buckets <i>between</i> other index characters.
 380      * For example, consider the labels when Latin and Greek are used:
 381      *     X Y Z ... &#x0391; &#x0392; &#x0393;.
 382      *
 383      * @return inflow label
 384      * @stable ICU 4.8
 385      */
 386     virtual const UnicodeString &getInflowLabel() const;
 387
 388    /**
 389      * Set the default label used for abbreviated buckets <i>between</i> other index characters.
 390      * An inflow label will be automatically inserted if two otherwise-adjacent label characters
 391      * are from different scripts, e.g. Latin and Cyrillic, and a third script, e.g. Greek,
 392      * sorts between the two.  The default inflow character is an ellipsis (...)
 393      *
 394      * @param inflowLabel the new Inflow label.
 395      * @param status Error code, will be set with the reason if the operation fails.
 396      * @return this
 397      * @stable ICU 4.8
 398      */
 399     virtual AlphabeticIndex &setInflowLabel(const UnicodeString &inflowLabel, UErrorCode &status);
 400
 401
 402    /**
 403      * Get the special label used for items that sort after the last normal label,
 404      * and that would not otherwise have an appropriate label.
 405      *
 406      * @return the overflow label
 407      * @stable ICU 4.8
 408      */
 409     virtual const UnicodeString &getOverflowLabel() const;
 410
 411
 412    /**
 413      * Set the label used for items that sort after the last normal label,
 414      * and that would not otherwise have an appropriate label.
 415      *
 416      * @param overflowLabel the new overflow label.
 417      * @param status Error code, will be set with the reason if the operation fails.
 418      * @return this
 419      * @stable ICU 4.8
 420      */
 421     virtual AlphabeticIndex &setOverflowLabel(const UnicodeString &overflowLabel, UErrorCode &status);
 422
 423    /**
 424      * Get the special label used for items that sort before the first normal label,
 425      * and that would not otherwise have an appropriate label.
 426      *
 427      * @return underflow label
 428      * @stable ICU 4.8
 429      */
 430     virtual const UnicodeString &getUnderflowLabel() const;
 431
 432    /**
 433      * Set the label used for items that sort before the first normal label,
 434      * and that would not otherwise have an appropriate label.
 435      *
 436      * @param underflowLabel the new underflow label.
 437      * @param status Error code, will be set with the reason if the operation fails.
 438      * @return this
 439      * @stable ICU 4.8
 440      */
 441     virtual AlphabeticIndex &setUnderflowLabel(const UnicodeString &underflowLabel, UErrorCode &status);
 442
 443
 444     /**
 445      * Get the limit on the number of labels permitted in the index.
 446      * The number does not include over, under and inflow labels.
 447      *
 448      * @return maxLabelCount maximum number of labels.
 449      * @stable ICU 4.8
 450      */
 451     virtual int32_t getMaxLabelCount() const;
 452
 453     /**
 454      * Set a limit on the number of labels permitted in the index.
 455      * The number does not include over, under and inflow labels.
 456      * Currently, if the number is exceeded, then every
 457      * nth item is removed to bring the count down.
 458      * A more sophisticated mechanism may be available in the future.
 459      *
 460      * @param maxLabelCount the maximum number of labels.
 461      * @param status error code
 462      * @return This, for chaining
 463      * @stable ICU 4.8
 464      */
 465     virtual AlphabeticIndex &setMaxLabelCount(int32_t maxLabelCount, UErrorCode &status);
 466
 467
 468     /**
 469      * Add a record to the index.  Each record will be associated with an index Bucket
 470      *  based on the record's name.  The list of records for each bucket will be sorted
 471      *  based on the collation ordering of the names in the index's locale.
 472      *  Records with duplicate names are permitted; they will be kept in the order
 473      *  that they were added.
 474      *
 475      * @param name The display name for the Record.  The Record will be placed in
 476      *             a bucket based on this name.
 477      * @param data An optional pointer to user data associated with this
 478      *             item.  When iterating the contents of a bucket, both the
 479      *             data pointer the name will be available for each Record.
 480      * @param status  Error code, will be set with the reason if the operation fails.
 481      * @return        This, for chaining.
 482      * @stable ICU 4.8
 483      */
 484     virtual AlphabeticIndex &addRecord(const UnicodeString &name, const void *data, UErrorCode &status);
 485
 486     /**
 487      * Remove all Records from the Index.  The set of Buckets, which define the headings under
 488      * which records are classified, is not altered.
 489      *
 490      * @param status  Error code, will be set with the reason if the operation fails.
 491      * @return        This, for chaining.
 492      * @stable ICU 4.8
 493      */
 494     virtual AlphabeticIndex &clearRecords(UErrorCode &status);
 495
 496
 497     /**  Get the number of labels in this index.
 498      *      Note: may trigger lazy index construction.
 499      *
 500      * @param status  Error code, will be set with the reason if the operation fails.
 501      * @return        The number of labels in this index, including any under, over or
 502      *                in-flow labels.
 503      * @stable ICU 4.8
 504      */
 505     virtual int32_t  getBucketCount(UErrorCode &status);
 506
 507
 508     /**  Get the total number of Records in this index, that is, the number
 509      *   of <name, data> pairs added.
 510      *
 511      * @param status  Error code, will be set with the reason if the operation fails.
 512      * @return        The number of records in this index, that is, the total number
 513      *                of (name, data) items added with addRecord().
 514      * @stable ICU 4.8
 515      */
 516     virtual int32_t  getRecordCount(UErrorCode &status);
 517
 518
 519
 520     /**
 521      *   Given the name of a record, return the zero-based index of the Bucket
 522      *   in which the item should appear.  The name need not be in the index.
 523      *   A Record will not be added to the index by this function.
 524      *   Bucket numbers are zero-based, in Bucket iteration order.
 525      *
 526      * @param itemName  The name whose bucket position in the index is to be determined.
 527      * @param status  Error code, will be set with the reason if the operation fails.
 528      * @return The bucket number for this name.
 529      * @stable ICU 4.8
 530      *
 531      */
 532     virtual int32_t  getBucketIndex(const UnicodeString &itemName, UErrorCode &status);
 533
 534
 535     /**
 536      *   Get the zero based index of the current Bucket from an iteration
 537      *   over the Buckets of this index.  Return -1 if no iteration is in process.
 538      *   @return  the index of the current Bucket
 539      *   @stable ICU 4.8
 540      */
 541     virtual int32_t  getBucketIndex() const;
 542
 543
 544     /**
 545      *   Advance the iteration over the Buckets of this index.  Return FALSE if
 546      *   there are no more Buckets.
 547      *
 548      *   @param status  Error code, will be set with the reason if the operation fails.
 549      *   U_ENUM_OUT_OF_SYNC_ERROR will be reported if the index is modified while
 550      *   an enumeration of its contents are in process.
 551      *
 552      *   @return TRUE if success, FALSE if at end of iteration
 553      *   @stable ICU 4.8
 554      */
 555     virtual UBool nextBucket(UErrorCode &status);
 556
 557     /**
 558      *   Return the name of the Label of the current bucket from an iteration over the buckets.
 559      *   If the iteration is before the first Bucket (nextBucket() has not been called),
 560      *   or after the last, return an empty string.
 561      *
 562      *   @return the bucket label.
 563      *   @stable ICU 4.8
 564      */
 565     virtual const UnicodeString &getBucketLabel() const;
 566
 567     /**
 568      *  Return the type of the label for the current Bucket (selected by the
 569      *  iteration over Buckets.)
 570      *
 571      * @return the label type.
 572      * @stable ICU 4.8
 573      */
 574     virtual UAlphabeticIndexLabelType getBucketLabelType() const;
 575
 576     /**
 577       * Get the number of <name, data> Records in the current Bucket.
 578       * If the current bucket iteration position is before the first label or after the
 579       * last, return 0.
 580       *
 581       *  @return the number of Records.
 582       *  @stable ICU 4.8
 583       */
 584     virtual int32_t getBucketRecordCount() const;
 585
 586
 587     /**
 588      *  Reset the Bucket iteration for this index.  The next call to nextBucket()
 589      *  will restart the iteration at the first label.
 590      *
 591      * @param status  Error code, will be set with the reason if the operation fails.
 592      * @return        this, for chaining.
 593      * @stable ICU 4.8
 594      */
 595     virtual AlphabeticIndex &resetBucketIterator(UErrorCode &status);
 596
 597     /**
 598      * Advance to the next record in the current Bucket.
 599      * When nextBucket() is called, Record iteration is reset to just before the
 600      * first Record in the new Bucket.
 601      *
 602      *   @param status  Error code, will be set with the reason if the operation fails.
 603      *   U_ENUM_OUT_OF_SYNC_ERROR will be reported if the index is modified while
 604      *   an enumeration of its contents are in process.
 605      *   @return TRUE if successful, FALSE when the iteration advances past the last item.
 606      *   @stable ICU 4.8
 607      */
 608     virtual UBool nextRecord(UErrorCode &status);
 609
 610     /**
 611      * Get the name of the current Record.
 612      * Return an empty string if the Record iteration position is before first
 613      * or after the last.
 614      *
 615      *  @return The name of the current index item.
 616      *  @stable ICU 4.8
 617      */
 618     virtual const UnicodeString &getRecordName() const;
 619
 620
 621     /**
 622      * Return the data pointer of the Record currently being iterated over.
 623      * Return NULL if the current iteration position before the first item in this Bucket,
 624      * or after the last.
 625      *
 626      *  @return The current Record's data pointer.
 627      *  @stable ICU 4.8
 628      */
 629     virtual const void *getRecordData() const;
 630
 631
 632     /**
 633      * Reset the Record iterator position to before the first Record in the current Bucket.
 634      *
 635      *  @return This, for chaining.
 636      *  @stable ICU 4.8
 637      */
 638     virtual AlphabeticIndex &resetRecordIterator();
 639
 640 private:
 641      /**
 642       * No Copy constructor.
 643       * @internal
 644       */
 645      AlphabeticIndex(const AlphabeticIndex &other);
 646
 647      /**
 648       *   No assignment.
 649       */
 650      AlphabeticIndex &operator =(const AlphabeticIndex & /*other*/) { return *this;};
 651
 652     /**
 653      * No Equality operators.
 654      * @internal
 655      */
 656      virtual UBool operator==(const AlphabeticIndex& other) const;
 657
 658     /**
 659      * Inequality operator.
 660      * @internal
 661      */
 662      virtual UBool operator!=(const AlphabeticIndex& other) const;
 663
 664      // Common initialization, for use from all constructors.
 665      void init(const Locale *locale, UErrorCode &status);
 666
 667     /**
 668      * This method is called to get the index exemplars. Normally these come from the locale directly,
 669      * but if they aren't available, we have to synthesize them.
 670      */
 671     void addIndexExemplars(const Locale &locale, UErrorCode &status);
 672     /**
 673      * Add Chinese index characters from the tailoring.
 674      */
 675     UBool addChineseIndexCharacters(UErrorCode &errorCode);
 676
 677     UVector *firstStringsInScript(UErrorCode &status);
 678
 679     static UnicodeString separated(const UnicodeString &item);
 680
 681     /**
 682      * Determine the best labels to use.
 683      * This is based on the exemplars, but we also process to make sure that they are unique,
 684      * and sort differently, and that the overall list is small enough.
 685      */
 686     void initLabels(UVector &indexCharacters, UErrorCode &errorCode) const;
 687     BucketList *createBucketList(UErrorCode &errorCode) const;
 688     void initBuckets(UErrorCode &errorCode);
 689     void clearBuckets();
 690     void internalResetBucketIterator();
 691
 692 public:
 693
 694     //  The Record is declared public only to allow access from
 695     //  implementation code written in plain C.
 696     //  It is not intended for public use.
 697
 698 #ifndef U_HIDE_INTERNAL_API
 699     /**
 700      * A (name, data) pair, to be sorted by name into one of the index buckets.
 701      * The user data is not used by the index implementation.
 702      * @internal
 703      */
 704     struct Record: public UMemory {
 705         const UnicodeString  name_;
 706         const void           *data_;
 707         Record(const UnicodeString &name, const void *data);
 708         ~Record();
 709     };
 710 #endif  /* U_HIDE_INTERNAL_API */
 711
 712 private:
 713
 714     /**
 715      * Holds all user records before they are distributed into buckets.
 716      * Type of contents is (Record *)
 717      * @internal
 718      */
 719     UVector  *inputList_;
 720
 721     int32_t  labelsIterIndex_;        // Index of next item to return.
 722     int32_t  itemsIterIndex_;
 723     Bucket   *currentBucket_;         // While an iteration of the index in underway,
 724                                       //   point to the bucket for the current label.
 725                                       // NULL when no iteration underway.
 726
 727     int32_t    maxLabelCount_;        // Limit on # of labels permitted in the index.
 728
 729     UnicodeSet *initialLabels_;       // Initial (unprocessed) set of Labels.  Union
 730                                       //   of those explicitly set by the user plus
 731                                       //   those from locales.  Raw values, before
 732                                       //   crunching into bucket labels.
 733
 734     UVector *firstCharsInScripts_;    // The first character from each script,
 735                                       //   in collation order.
 736
 737     RuleBasedCollator *collator_;
 738     RuleBasedCollator *collatorPrimaryOnly_;
 739
 740     // Lazy evaluated: null means that we have not built yet.
 741     BucketList *buckets_;
 742
 743     UnicodeString  inflowLabel_;
 744     UnicodeString  overflowLabel_;
 745     UnicodeString  underflowLabel_;
 746     UnicodeString  overflowComparisonString_;
 747
 748     UnicodeString emptyString_;
 749 };
 750
 751 U_NAMESPACE_END
 752
 753 #endif  // !UCONFIG_NO_COLLATION
 754 #endif