* Using SimplePatternFormatter is both faster and safer than adhoc replacement. * They are faster because they are precompiled; they are safer because they * account for curly braces escaped by apostrophe ('). * * Placeholders are of the form \{[0-9]+\}. If a curly brace is preceded * by a single quote, it becomes a curly brace instead of the start of a * placeholder. Two single quotes resolve to one single quote. *
* Example: *
* SimplePatternFormatter fmt("{1} '{born} in {0}");
* UnicodeString result;
* UErrorCode status = U_ZERO_ERROR;
* // Evaluates to: "paul {born} in england"
* fmt.format("englad", "paul", result, status);
*
*/
class U_COMMON_API SimplePatternFormatter : public UMemory {
public:
/**
* Default constructor
*/
SimplePatternFormatter();
/**
* Construct from a pattern. Will never fail if pattern has three or
* fewer placeholders in it.
*/
explicit SimplePatternFormatter(const UnicodeString& pattern);
/**
* Copy constructor.
*/
SimplePatternFormatter(const SimplePatternFormatter& other);
/**
* Assignment operator
*/
SimplePatternFormatter &operator=(const SimplePatternFormatter& other);
/**
* Destructor.
*/
~SimplePatternFormatter();
/**
* Compiles pattern and makes this object represent pattern.
*
* Returns TRUE on success; FALSE on failure. Will not fail if
* there are three or fewer placeholders in pattern. May fail with
* U_MEMORY_ALLOCATION_ERROR if there are more than three placeholders.
*/
UBool compile(const UnicodeString &pattern, UErrorCode &status);
/**
* Returns (maxPlaceholderId + 1). For example
* SimplePatternFormatter("{0} {2}").getPlaceholderCount()
* evaluates to 3.
* Callers use this function to find out how many values this object
* expects when formatting.
*/
int32_t getPlaceholderCount() const {
return placeholderCount;
}
/**
* Returns true if the pattern this object represents starts with
* placeholder id; otherwise, returns false.
*/
UBool startsWithPlaceholder(int32_t id) const;
/**
* Returns this pattern with none of the placeholders.
*/
const UnicodeString &getPatternWithNoPlaceholders() const {
return noPlaceholders;
}
/**
* Formats given value.
*/
UnicodeString &format(
const UnicodeString &args0,
UnicodeString &appendTo,
UErrorCode &status) const;
/**
* Formats given values.
*/
UnicodeString &format(
const UnicodeString &args0,
const UnicodeString &args1,
UnicodeString &appendTo,
UErrorCode &status) const;
/**
* Formats given values.
*/
UnicodeString &format(
const UnicodeString &args0,
const UnicodeString &args1,
const UnicodeString &args2,
UnicodeString &appendTo,
UErrorCode &status) const;
/**
* Formats given values.
*
* The caller retains ownership of all pointers.
* @param placeholderValues 1st one corresponds to {0}; 2nd to {1};
* 3rd to {2} etc.
* @param placeholderValueCount the number of placeholder values
* must be at least large enough to provide values for all placeholders
* in this object. Otherwise status set to U_ILLEGAL_ARGUMENT_ERROR.
* @param appendTo resulting string appended here. Optimization: If
* the pattern this object represents starts with a placeholder AND
* appendTo references the value of that same placeholder, then that
* placeholder value is not copied to appendTo (Its already there).
* If the value of the starting placeholder is a very large string,
* this optimization can offer huge savings.
* @param offsetArray The offset of each placeholder value in appendTo
* stored here. The first value gets the offset of the value for {0};
* the 2nd for {1}; the 3rd for {2} etc. -1 means that the corresponding
* placeholder does not exist in this object. If caller is not
* interested in offsets, it may pass NULL and 0 for the length.
* @param offsetArrayLength the size of offsetArray may be less than
* placeholderValueCount.
* @param status any error stored here.
*/
UnicodeString &format(
const UnicodeString * const *placeholderValues,
int32_t placeholderValueCount,
UnicodeString &appendTo,
int32_t *offsetArray,
int32_t offsetArrayLength,
UErrorCode &status) const;
private:
UnicodeString noPlaceholders;
MaybeStackArray placeholders;
int32_t placeholderSize;
int32_t placeholderCount;
// ensureCapacity ensures that the capacity of the placeholders array
// is desiredCapacity. If ensureCapacity must resize the placeholders
// array, the first placeholderSize elements stay in the array. Note
// that ensureCapcity NEVER changes the value of placeholderSize only
// the capacity of the placeholders array.
// If there is no memory allocation error when resizing, this
// function returns desiredCapacity. If there is a memory allocation
// error, this function leaves the placeholders array unchanged and
// returns the smaller, old capacity. ensureCapacity resizes only if
// the current capacity of placeholders array is less than desiredCapacity.
// Otherwise, it leaves the placeholders array unchanged. If caller
// specifies an allocation size, then it must be at least as large as
// desiredCapacity. In that case, if ensureCapacity resizes, it will
// allocate allocationSize spots instead of desiredCapacity spots in
// the array. If caller is calling ensureCapacity in a loop while adding
// elements, it is recommended that it use an allocationSize of
// approximately twice desiredCapacity to avoid memory allocation with
// every call to ensureCapacity.
int32_t ensureCapacity(int32_t desiredCapacity, int32_t allocationSize=0);
// Records the offset of an individual placeholder in the noPlaceholders
// string.
UBool addPlaceholder(int32_t id, int32_t offset);
};
U_NAMESPACE_END
#endif