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