Wed, 31 Dec 2014 06:09:35 +0100
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 ... Α Β Γ. |
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 |