1 // Copyright (C) 2016 and later: Unicode, Inc. and others. 2 // License & terms of use: http://www.unicode.org/copyright.html 3 /* 4 ****************************************************************************** 5 * Copyright (C) 1996-2012, International Business Machines * 6 * Corporation and others. All Rights Reserved. * 7 ****************************************************************************** 8 */ 9 10 /** 11 * \file 12 * \brief Originally, added as C++ API for Collation data used to compute minLengthInChars 13 * \internal 14 */ 15 16 /* 17 * Note: This module was incldued in ICU 4.0.1 as @internal technology preview for supporting 18 * Boyer-Moore string search API. For now, only SSearchTest depends on this module. I temporaly 19 * moved the module from i18n directory to intltest, because we have no plan to publish this 20 * as public API. (2012-12-18 yoshito) 21 */ 22 23 #ifndef COLL_DATA_H 24 #define COLL_DATA_H 25 26 #include "unicode/utypes.h" 27 28 #if !UCONFIG_NO_COLLATION 29 30 #include "unicode/ucol.h" 31 #include "unicode/unistr.h" 32 33 /** 34 * The size of the internal CE buffer in a <code>CEList</code> object 35 */ 36 #define CELIST_BUFFER_SIZE 4 37 38 /** 39 * \def INSTRUMENT_CELIST 40 * Define this to enable the <code>CEList</code> objects to collect 41 * statistics. 42 */ 43 44 /** 45 * The size of the initial list in a <code>StringList</code> object. 46 */ 47 #define STRING_LIST_BUFFER_SIZE 16 48 49 U_NAMESPACE_USE 50 51 /** 52 * This object holds a list of CEs generated from a particular 53 * <code>UnicodeString</code> 54 * 55 */ 56 class CEList 57 { 58 public: 59 /** 60 * Construct a <code>CEList</code> object. 61 * 62 * @param coll - the Collator used to collect the CEs. 63 * @param string - the string for which to collect the CEs. 64 * @param status - will be set if any errors occur. 65 * 66 * Note: if on return, status is set to an error code, 67 * the only safe thing to do with this object is to call 68 * the destructor. 69 */ 70 CEList(UCollator *coll, const UnicodeString &string, UErrorCode &status); 71 72 /** 73 * The destructor. 74 */ 75 ~CEList(); 76 77 /** 78 * Return the number of CEs in the list. 79 * 80 * @return the number of CEs in the list. 81 */ 82 int32_t size() const; 83 84 /** 85 * Get a particular CE from the list. 86 * 87 * @param index - the index of the CE to return 88 * 89 * @return the CE, or <code>0</code> if <code>index</code> is out of range 90 */ 91 uint32_t get(int32_t index) const; 92 93 /** 94 * Check if the CEs in another <code>CEList</code> match the 95 * suffix of this list starting at a give offset. 96 * 97 * @param offset - the offset of the suffix 98 * @param other - the other <code>CEList</code> 99 * 100 * @return <code>TRUE</code> if the CEs match, <code>FALSE</code> otherwise. 101 */ 102 UBool matchesAt(int32_t offset, const CEList *other) const; 103 104 /** 105 * The index operator. 106 * 107 * @param index - the index 108 * 109 * @return a reference to the given CE in the list 110 */ 111 uint32_t &operator[](int32_t index) const; 112 113 private: 114 void add(uint32_t ce, UErrorCode &status); 115 116 uint32_t ceBuffer[CELIST_BUFFER_SIZE]; 117 uint32_t *ces; 118 int32_t listMax; 119 int32_t listSize; 120 }; 121 122 /** 123 * StringList 124 * 125 * This object holds a list of <code>UnicodeString</code> objects. 126 */ 127 class StringList 128 { 129 public: 130 /** 131 * Construct an empty <code>StringList</code> 132 * 133 * @param status - will be set if any errors occur. 134 * 135 * Note: if on return, status is set to an error code, 136 * the only safe thing to do with this object is to call 137 * the destructor. 138 */ 139 StringList(UErrorCode &status); 140 141 /** 142 * The destructor. 143 */ 144 ~StringList(); 145 146 /** 147 * Add a string to the list. 148 * 149 * @param string - the string to add 150 * @param status - will be set if any errors occur. 151 */ 152 void add(const UnicodeString *string, UErrorCode &status); 153 154 /** 155 * Add an array of Unicode code points to the list. 156 * 157 * @param chars - the address of the array of code points 158 * @param count - the number of code points in the array 159 * @param status - will be set if any errors occur. 160 */ 161 void add(const UChar *chars, int32_t count, UErrorCode &status); 162 163 /** 164 * Get a particular string from the list. 165 * 166 * @param index - the index of the string 167 * 168 * @return a pointer to the <code>UnicodeString</code> or <code>NULL</code> 169 * if <code>index</code> is out of bounds. 170 */ 171 const UnicodeString *get(int32_t index) const; 172 173 /** 174 * Get the number of stings in the list. 175 * 176 * @return the number of strings in the list. 177 */ 178 int32_t size() const; 179 180 private: 181 UnicodeString *strings; 182 int32_t listMax; 183 int32_t listSize; 184 }; 185 186 187 /* 188 * Forward references to internal classes. 189 */ 190 class StringToCEsMap; 191 class CEToStringsMap; 192 193 /** 194 * CollData 195 * 196 * This class holds the Collator-specific data needed to 197 * compute the length of the shortest string that can 198 * generate a partcular list of CEs. 199 * 200 * <code>CollData</code> objects are quite expensive to compute. Because 201 * of this, they are cached. When you call <code>CollData::open</code> it 202 * returns a reference counted cached object. When you call <code>CollData::close</code> 203 * the reference count on the object is decremented but the object is not deleted. 204 * 205 * If you do not need to reuse any unreferenced objects in the cache, you can call 206 * <code>CollData::flushCollDataCache</code>. If you no longer need any <code>CollData</code> 207 * objects, you can call <code>CollData::freeCollDataCache</code> 208 */ 209 class CollData 210 { 211 public: 212 /** 213 * Construct a <code>CollData</code> object. 214 * 215 * @param collator - the collator 216 * @param status - will be set if any errors occur. 217 */ 218 CollData(UCollator *collator, UErrorCode &status); 219 220 /** 221 * The destructor. 222 */ 223 ~CollData(); 224 225 /** 226 * Get the <code>UCollator</code> object used to create this object. 227 * The object returned may not be the exact object that was used to 228 * create this object, but it will have the same behavior. 229 */ 230 UCollator *getCollator() const; 231 232 /** 233 * Get a list of all the strings which generate a list 234 * of CEs starting with a given CE. 235 * 236 * @param ce - the CE 237 * 238 * return a <code>StringList</code> object containing all 239 * the stirngs, or <code>NULL</code> if there are 240 * no such strings. 241 */ 242 const StringList *getStringList(int32_t ce) const; 243 244 /** 245 * Get a list of the CEs generated by a partcular stirng. 246 * 247 * @param string - the string 248 * 249 * @return a <code>CEList</code> object containt the CEs. You 250 * must call <code>freeCEList</code> when you are finished 251 * using the <code>CEList</code>/ 252 */ 253 const CEList *getCEList(const UnicodeString *string) const; 254 255 /** 256 * Release a <code>CEList</code> returned by <code>getCEList</code>. 257 * 258 * @param list - the <code>CEList</code> to free. 259 */ 260 void freeCEList(const CEList *list); 261 262 /** 263 * Return the length of the shortest string that will generate 264 * the given list of CEs. 265 * 266 * @param ces - the CEs 267 * @param offset - the offset of the first CE in the list to use. 268 * 269 * @return the length of the shortest string. 270 */ 271 int32_t minLengthInChars(const CEList *ces, int32_t offset) const; 272 273 274 /** 275 * Return the length of the shortest string that will generate 276 * the given list of CEs. 277 * 278 * Note: the algorithm used to do this computation is recursive. To 279 * limit the amount of recursion, a "history" list is used to record 280 * the best answer starting at a particular offset in the list of CEs. 281 * If the same offset is visited again during the recursion, the answer 282 * in the history list is used. 283 * 284 * @param ces - the CEs 285 * @param offset - the offset of the first CE in the list to use. 286 * @param history - the history list. Must be at least as long as 287 * the number of cEs in the <code>CEList</code> 288 * 289 * @return the length of the shortest string. 290 */ 291 int32_t minLengthInChars(const CEList *ces, int32_t offset, int32_t *history) const; 292 293 private: 294 UCollator *coll; 295 CEToStringsMap *ceToCharsStartingWith; 296 297 uint32_t minHan; 298 uint32_t maxHan; 299 300 uint32_t jamoLimits[4]; 301 }; 302 303 #endif // #if !UCONFIG_NO_COLLATION 304 #endif // #ifndef COLL_DATA_H 305