intl/icu/source/i18n/unicode/alphaindex.h

Wed, 31 Dec 2014 06:09:35 +0100

author
Michael Schloh von Bennewitz <michael@schloh.com>
date
Wed, 31 Dec 2014 06:09:35 +0100
changeset 0
6474c204b198
permissions
-rw-r--r--

Cloned upstream origin tor-browser at tor-browser-31.3.0esr-4.5-1-build1
revision ID fc1c9ff7c1b2defdbc039f12214767608f46423f for hacking purpose.

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

mercurial