icuSources/common/simplepatternformatter.h

   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 "unicode/utypes.h"
  15 #include "unicode/unistr.h"
  16
  17 U_NAMESPACE_BEGIN
  18
  19 /**
  20  * Compiled version of a pattern string such as "{1} was born in {0}".
  21  * <p>
  22  * Using SimplePatternFormatter is both faster and safer than adhoc replacement.
  23  * They are faster because they are precompiled; they are safer because they
  24  * account for curly braces escaped by apostrophe (').
  25  *
  26  * Placeholders are of the form \{[0-9]+\}. If a curly brace is preceded
  27  * by a single quote, it becomes a curly brace instead of the start of a
  28  * placeholder. Two single quotes resolve to one single quote.
  29  * <p>
  30  * Example:
  31  * <pre>
  32  * SimplePatternFormatter fmt("{1} '{born} in {0}");
  33  * UnicodeString result;
  34  * UErrorCode status = U_ZERO_ERROR;
  35  * // Evaluates to: "paul {born} in england"
  36  * fmt.format("englad", "paul", result, status);
  37  * </pre>
  38  */
  39 class U_COMMON_API SimplePatternFormatter : public UMemory {
  40 public:
  41     /**
  42      * Default constructor
  43      */
  44     SimplePatternFormatter();
  45
  46     /**
  47      * Construct from a pattern. Will never fail if pattern has three or
  48      * fewer placeholders in it.
  49      */
  50     explicit SimplePatternFormatter(const UnicodeString& pattern);
  51
  52     /**
  53      * Copy constructor.
  54      */
  55     SimplePatternFormatter(const SimplePatternFormatter& other);
  56
  57     /**
  58      * Assignment operator
  59      */
  60     SimplePatternFormatter &operator=(const SimplePatternFormatter& other);
  61
  62     /**
  63      * Destructor.
  64      */
  65     ~SimplePatternFormatter();
  66
  67     /**
  68      * Compiles pattern and makes this object represent pattern.
  69      *
  70      * Returns TRUE on success; FALSE on failure. Will not fail if
  71      * there are three or fewer placeholders in pattern. May fail with
  72      * U_MEMORY_ALLOCATION_ERROR if there are more than three placeholders.
  73      */
  74     UBool compile(const UnicodeString &pattern, UErrorCode &status);
  75
  76     /**
  77      * Returns (maxPlaceholderId + 1). For example
  78      * <code>SimplePatternFormatter("{0} {2}").getPlaceholderCount()
  79      * evaluates to 3.
  80      * Callers use this function to find out how many values this object
  81      * expects when formatting.
  82      */
  83     int32_t getPlaceholderCount() const {
  84         return placeholderCount;
  85     }
  86
  87     /**
  88      * Formats given value.
  89      */
  90     UnicodeString &format(
  91             const UnicodeString &args0,
  92             UnicodeString &appendTo,
  93             UErrorCode &status) const;
  94
  95     /**
  96      * Formats given values.
  97      */
  98     UnicodeString &format(
  99             const UnicodeString &args0,
 100             const UnicodeString &args1,
 101             UnicodeString &appendTo,
 102             UErrorCode &status) const;
 103
 104     /**
 105      * Formats given values.
 106      */
 107     UnicodeString &format(
 108             const UnicodeString &args0,
 109             const UnicodeString &args1,
 110             const UnicodeString &args2,
 111             UnicodeString &appendTo,
 112             UErrorCode &status) const;
 113
 114     /**
 115      * Formats given values.
 116      *
 117      * The caller retains ownership of all pointers.
 118      * @param placeholderValues 1st one corresponds to {0}; 2nd to {1};
 119      *  3rd to {2} etc.
 120      * @param placeholderValueCount the number of placeholder values
 121      *  must be at least large enough to provide values for all placeholders
 122      *  in this object. Otherwise status set to U_ILLEGAL_ARGUMENT_ERROR.
 123      * @param appendTo resulting string appended here.
 124      * @param offsetArray The offset of each placeholder value in appendTo
 125      *  stored here. The first value gets the offset of the value for {0};
 126      *  the 2nd for {1}; the 3rd for {2} etc. -1 means that the corresponding
 127      *  placeholder does not exist in this object. If caller is not
 128      *  interested in offsets, it may pass NULL and 0 for the length.
 129      * @param offsetArrayLength the size of offsetArray may be less than
 130      *  placeholderValueCount.
 131      * @param status any error stored here.
 132      */
 133     UnicodeString &format(
 134             const UnicodeString * const *placeholderValues,
 135             int32_t placeholderValueCount,
 136             UnicodeString &appendTo,
 137             int32_t *offsetArray,
 138             int32_t offsetArrayLength,
 139             UErrorCode &status) const;
 140 private:
 141     UnicodeString noPlaceholders;
 142     int32_t placeholderBuffer[EXPECTED_PLACEHOLDER_COUNT * 2];
 143     int32_t *placeholdersByOffset;
 144     int32_t placeholderSize;
 145     int32_t placeholderCapacity;
 146     int32_t placeholderCount;
 147     int32_t ensureCapacity(int32_t size);
 148     UBool addPlaceholder(int32_t id, int32_t offset);
 149 };
 150
 151 U_NAMESPACE_END
 152
 153 #endif