OLD | NEW |
(Empty) | |
| 1 /* |
| 2 ****************************************************************************** |
| 3 * Copyright (C) 2014, International Business Machines |
| 4 * Corporation and others. All Rights Reserved. |
| 5 ****************************************************************************** |
| 6 * simplepatternformatter.h |
| 7 */ |
| 8 |
| 9 #ifndef __SIMPLEPATTERNFORMATTER_H__ |
| 10 #define __SIMPLEPATTERNFORMATTER_H__ |
| 11 |
| 12 #define EXPECTED_PLACEHOLDER_COUNT 3 |
| 13 |
| 14 #include "cmemory.h" |
| 15 #include "unicode/utypes.h" |
| 16 #include "unicode/unistr.h" |
| 17 |
| 18 U_NAMESPACE_BEGIN |
| 19 |
| 20 struct PlaceholderInfo { |
| 21 int32_t id; |
| 22 int32_t offset; |
| 23 }; |
| 24 |
| 25 /** |
| 26 * Compiled version of a pattern string such as "{1} was born in {0}". |
| 27 * <p> |
| 28 * Using SimplePatternFormatter is both faster and safer than adhoc replacement. |
| 29 * They are faster because they are precompiled; they are safer because they |
| 30 * account for curly braces escaped by apostrophe ('). |
| 31 * |
| 32 * Placeholders are of the form \{[0-9]+\}. If a curly brace is preceded |
| 33 * by a single quote, it becomes a curly brace instead of the start of a |
| 34 * placeholder. Two single quotes resolve to one single quote. |
| 35 * <p> |
| 36 * Example: |
| 37 * <pre> |
| 38 * SimplePatternFormatter fmt("{1} '{born} in {0}"); |
| 39 * UnicodeString result; |
| 40 * UErrorCode status = U_ZERO_ERROR; |
| 41 * // Evaluates to: "paul {born} in england" |
| 42 * fmt.format("englad", "paul", result, status); |
| 43 * </pre> |
| 44 */ |
| 45 class U_COMMON_API SimplePatternFormatter : public UMemory { |
| 46 public: |
| 47 /** |
| 48 * Default constructor |
| 49 */ |
| 50 SimplePatternFormatter(); |
| 51 |
| 52 /** |
| 53 * Construct from a pattern. Will never fail if pattern has three or |
| 54 * fewer placeholders in it. |
| 55 */ |
| 56 explicit SimplePatternFormatter(const UnicodeString& pattern); |
| 57 |
| 58 /** |
| 59 * Copy constructor. |
| 60 */ |
| 61 SimplePatternFormatter(const SimplePatternFormatter& other); |
| 62 |
| 63 /** |
| 64 * Assignment operator |
| 65 */ |
| 66 SimplePatternFormatter &operator=(const SimplePatternFormatter& other); |
| 67 |
| 68 /** |
| 69 * Destructor. |
| 70 */ |
| 71 ~SimplePatternFormatter(); |
| 72 |
| 73 /** |
| 74 * Compiles pattern and makes this object represent pattern. |
| 75 * |
| 76 * Returns TRUE on success; FALSE on failure. Will not fail if |
| 77 * there are three or fewer placeholders in pattern. May fail with |
| 78 * U_MEMORY_ALLOCATION_ERROR if there are more than three placeholders. |
| 79 */ |
| 80 UBool compile(const UnicodeString &pattern, UErrorCode &status); |
| 81 |
| 82 /** |
| 83 * Returns (maxPlaceholderId + 1). For example |
| 84 * <code>SimplePatternFormatter("{0} {2}").getPlaceholderCount() |
| 85 * evaluates to 3. |
| 86 * Callers use this function to find out how many values this object |
| 87 * expects when formatting. |
| 88 */ |
| 89 int32_t getPlaceholderCount() const { |
| 90 return placeholderCount; |
| 91 } |
| 92 |
| 93 /** |
| 94 * Returns true if the pattern this object represents starts with |
| 95 * placeholder id; otherwise, returns false. |
| 96 */ |
| 97 UBool startsWithPlaceholder(int32_t id) const; |
| 98 |
| 99 /** |
| 100 * Returns this pattern with none of the placeholders. |
| 101 */ |
| 102 const UnicodeString &getPatternWithNoPlaceholders() const { |
| 103 return noPlaceholders; |
| 104 } |
| 105 |
| 106 /** |
| 107 * Formats given value. |
| 108 */ |
| 109 UnicodeString &format( |
| 110 const UnicodeString &args0, |
| 111 UnicodeString &appendTo, |
| 112 UErrorCode &status) const; |
| 113 |
| 114 /** |
| 115 * Formats given values. |
| 116 */ |
| 117 UnicodeString &format( |
| 118 const UnicodeString &args0, |
| 119 const UnicodeString &args1, |
| 120 UnicodeString &appendTo, |
| 121 UErrorCode &status) const; |
| 122 |
| 123 /** |
| 124 * Formats given values. |
| 125 */ |
| 126 UnicodeString &format( |
| 127 const UnicodeString &args0, |
| 128 const UnicodeString &args1, |
| 129 const UnicodeString &args2, |
| 130 UnicodeString &appendTo, |
| 131 UErrorCode &status) const; |
| 132 |
| 133 /** |
| 134 * Formats given values. |
| 135 * |
| 136 * The caller retains ownership of all pointers. |
| 137 * @param placeholderValues 1st one corresponds to {0}; 2nd to {1}; |
| 138 * 3rd to {2} etc. |
| 139 * @param placeholderValueCount the number of placeholder values |
| 140 * must be at least large enough to provide values for all placeholders |
| 141 * in this object. Otherwise status set to U_ILLEGAL_ARGUMENT_ERROR. |
| 142 * @param appendTo resulting string appended here. Optimization: If |
| 143 * the pattern this object represents starts with a placeholder AND |
| 144 * appendTo references the value of that same placeholder, then that |
| 145 * placeholder value is not copied to appendTo (Its already there). |
| 146 * If the value of the starting placeholder is a very large string, |
| 147 * this optimization can offer huge savings. |
| 148 * @param offsetArray The offset of each placeholder value in appendTo |
| 149 * stored here. The first value gets the offset of the value for {0}; |
| 150 * the 2nd for {1}; the 3rd for {2} etc. -1 means that the corresponding |
| 151 * placeholder does not exist in this object. If caller is not |
| 152 * interested in offsets, it may pass NULL and 0 for the length. |
| 153 * @param offsetArrayLength the size of offsetArray may be less than |
| 154 * placeholderValueCount. |
| 155 * @param status any error stored here. |
| 156 */ |
| 157 UnicodeString &format( |
| 158 const UnicodeString * const *placeholderValues, |
| 159 int32_t placeholderValueCount, |
| 160 UnicodeString &appendTo, |
| 161 int32_t *offsetArray, |
| 162 int32_t offsetArrayLength, |
| 163 UErrorCode &status) const; |
| 164 private: |
| 165 UnicodeString noPlaceholders; |
| 166 MaybeStackArray<PlaceholderInfo, 3> placeholders; |
| 167 int32_t placeholderSize; |
| 168 int32_t placeholderCount; |
| 169 |
| 170 // ensureCapacity ensures that the capacity of the placeholders array |
| 171 // is desiredCapacity. If ensureCapacity must resize the placeholders |
| 172 // array, the first placeholderSize elements stay in the array. Note |
| 173 // that ensureCapcity NEVER changes the value of placeholderSize only |
| 174 // the capacity of the placeholders array. |
| 175 // If there is no memory allocation error when resizing, this |
| 176 // function returns desiredCapacity. If there is a memory allocation |
| 177 // error, this function leaves the placeholders array unchanged and |
| 178 // returns the smaller, old capacity. ensureCapacity resizes only if |
| 179 // the current capacity of placeholders array is less than desiredCapacity. |
| 180 // Otherwise, it leaves the placeholders array unchanged. If caller |
| 181 // specifies an allocation size, then it must be at least as large as |
| 182 // desiredCapacity. In that case, if ensureCapacity resizes, it will |
| 183 // allocate allocationSize spots instead of desiredCapacity spots in |
| 184 // the array. If caller is calling ensureCapacity in a loop while adding |
| 185 // elements, it is recommended that it use an allocationSize of |
| 186 // approximately twice desiredCapacity to avoid memory allocation with |
| 187 // every call to ensureCapacity. |
| 188 int32_t ensureCapacity(int32_t desiredCapacity, int32_t allocationSize=0); |
| 189 |
| 190 // Records the offset of an individual placeholder in the noPlaceholders |
| 191 // string. |
| 192 UBool addPlaceholder(int32_t id, int32_t offset); |
| 193 }; |
| 194 |
| 195 U_NAMESPACE_END |
| 196 |
| 197 #endif |
OLD | NEW |