Home | History | Annotate | Download | only in common 
      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
    154