icuSources/common/unicode/simpleformatter.h

   1 // © 2016 and later: Unicode, Inc. and others.
   2 // License & terms of use: http://www.unicode.org/copyright.html
   3 /*
   4 ******************************************************************************
   5 * Copyright (C) 2014-2016, International Business Machines
   6 * Corporation and others.  All Rights Reserved.
   7 ******************************************************************************
   8 * simpleformatter.h
   9 */
  10
  11 #ifndef __SIMPLEFORMATTER_H__
  12 #define __SIMPLEFORMATTER_H__
  13
  14 /**
  15  * \file
  16  * \brief C++ API: Simple formatter, minimal subset of MessageFormat.
  17  */
  18
  19 #include "unicode/utypes.h"
  20 #include "unicode/unistr.h"
  21
  22 #if U_SHOW_CPLUSPLUS_API
  23 U_NAMESPACE_BEGIN
  24
  25 // Forward declaration:
  26 namespace number {
  27 namespace impl {
  28 class SimpleModifier;
  29 }
  30 }
  31
  32 /**
  33  * Formats simple patterns like "{1} was born in {0}".
  34  * Minimal subset of MessageFormat; fast, simple, minimal dependencies.
  35  * Supports only numbered arguments with no type nor style parameters,
  36  * and formats only string values.
  37  * Quoting via ASCII apostrophe compatible with ICU MessageFormat default behavior.
  38  *
  39  * Factory methods set error codes for syntax errors
  40  * and for too few or too many arguments/placeholders.
  41  *
  42  * SimpleFormatter objects are thread-safe except for assignment and applying new patterns.
  43  *
  44  * Example:
  45  * <pre>
  46  * UErrorCode errorCode = U_ZERO_ERROR;
  47  * SimpleFormatter fmt("{1} '{born}' in {0}", errorCode);
  48  * UnicodeString result;
  49  *
  50  * // Output: "paul {born} in england"
  51  * fmt.format("england", "paul", result, errorCode);
  52  * </pre>
  53  *
  54  * This class is not intended for public subclassing.
  55  *
  56  * @see MessageFormat
  57  * @see UMessagePatternApostropheMode
  58  * @stable ICU 57
  59  */
  60 class U_COMMON_API SimpleFormatter U_FINAL : public UMemory {
  61 public:
  62     /**
  63      * Default constructor.
  64      * @stable ICU 57
  65      */
  66     SimpleFormatter() : compiledPattern((char16_t)0) {}
  67
  68     /**
  69      * Constructs a formatter from the pattern string.
  70      *
  71      * @param pattern The pattern string.
  72      * @param errorCode ICU error code in/out parameter.
  73      *                  Must fulfill U_SUCCESS before the function call.
  74      *                  Set to U_ILLEGAL_ARGUMENT_ERROR for bad argument syntax.
  75      * @stable ICU 57
  76      */
  77     SimpleFormatter(const UnicodeString& pattern, UErrorCode &errorCode) {
  78         applyPattern(pattern, errorCode);
  79     }
  80
  81     /**
  82      * Constructs a formatter from the pattern string.
  83      * The number of arguments checked against the given limits is the
  84      * highest argument number plus one, not the number of occurrences of arguments.
  85      *
  86      * @param pattern The pattern string.
  87      * @param min The pattern must have at least this many arguments.
  88      * @param max The pattern must have at most this many arguments.
  89      * @param errorCode ICU error code in/out parameter.
  90      *                  Must fulfill U_SUCCESS before the function call.
  91      *                  Set to U_ILLEGAL_ARGUMENT_ERROR for bad argument syntax and
  92      *                  too few or too many arguments.
  93      * @stable ICU 57
  94      */
  95     SimpleFormatter(const UnicodeString& pattern, int32_t min, int32_t max,
  96                     UErrorCode &errorCode) {
  97         applyPatternMinMaxArguments(pattern, min, max, errorCode);
  98     }
  99
 100     /**
 101      * Copy constructor.
 102      * @stable ICU 57
 103      */
 104     SimpleFormatter(const SimpleFormatter& other)
 105             : compiledPattern(other.compiledPattern) {}
 106
 107     /**
 108      * Assignment operator.
 109      * @stable ICU 57
 110      */
 111     SimpleFormatter &operator=(const SimpleFormatter& other);
 112
 113     /**
 114      * Destructor.
 115      * @stable ICU 57
 116      */
 117     ~SimpleFormatter();
 118
 119     /**
 120      * Changes this object according to the new pattern.
 121      *
 122      * @param pattern The pattern string.
 123      * @param errorCode ICU error code in/out parameter.
 124      *                  Must fulfill U_SUCCESS before the function call.
 125      *                  Set to U_ILLEGAL_ARGUMENT_ERROR for bad argument syntax.
 126      * @return TRUE if U_SUCCESS(errorCode).
 127      * @stable ICU 57
 128      */
 129     UBool applyPattern(const UnicodeString &pattern, UErrorCode &errorCode) {
 130         return applyPatternMinMaxArguments(pattern, 0, INT32_MAX, errorCode);
 131     }
 132
 133     /**
 134      * Changes this object according to the new pattern.
 135      * The number of arguments checked against the given limits is the
 136      * highest argument number plus one, not the number of occurrences of arguments.
 137      *
 138      * @param pattern The pattern string.
 139      * @param min The pattern must have at least this many arguments.
 140      * @param max The pattern must have at most this many arguments.
 141      * @param errorCode ICU error code in/out parameter.
 142      *                  Must fulfill U_SUCCESS before the function call.
 143      *                  Set to U_ILLEGAL_ARGUMENT_ERROR for bad argument syntax and
 144      *                  too few or too many arguments.
 145      * @return TRUE if U_SUCCESS(errorCode).
 146      * @stable ICU 57
 147      */
 148     UBool applyPatternMinMaxArguments(const UnicodeString &pattern,
 149                                       int32_t min, int32_t max, UErrorCode &errorCode);
 150
 151     /**
 152      * @return The max argument number + 1.
 153      * @stable ICU 57
 154      */
 155     int32_t getArgumentLimit() const {
 156         return getArgumentLimit(compiledPattern.getBuffer(), compiledPattern.length());
 157     }
 158
 159     /**
 160      * Formats the given value, appending to the appendTo builder.
 161      * The argument value must not be the same object as appendTo.
 162      * getArgumentLimit() must be at most 1.
 163      *
 164      * @param value0 Value for argument {0}.
 165      * @param appendTo Gets the formatted pattern and value appended.
 166      * @param errorCode ICU error code in/out parameter.
 167      *                  Must fulfill U_SUCCESS before the function call.
 168      * @return appendTo
 169      * @stable ICU 57
 170      */
 171     UnicodeString &format(
 172             const UnicodeString &value0,
 173             UnicodeString &appendTo, UErrorCode &errorCode) const;
 174
 175     /**
 176      * Formats the given values, appending to the appendTo builder.
 177      * An argument value must not be the same object as appendTo.
 178      * getArgumentLimit() must be at most 2.
 179      *
 180      * @param value0 Value for argument {0}.
 181      * @param value1 Value for argument {1}.
 182      * @param appendTo Gets the formatted pattern and values appended.
 183      * @param errorCode ICU error code in/out parameter.
 184      *                  Must fulfill U_SUCCESS before the function call.
 185      * @return appendTo
 186      * @stable ICU 57
 187      */
 188     UnicodeString &format(
 189             const UnicodeString &value0,
 190             const UnicodeString &value1,
 191             UnicodeString &appendTo, UErrorCode &errorCode) const;
 192
 193     /**
 194      * Formats the given values, appending to the appendTo builder.
 195      * An argument value must not be the same object as appendTo.
 196      * getArgumentLimit() must be at most 3.
 197      *
 198      * @param value0 Value for argument {0}.
 199      * @param value1 Value for argument {1}.
 200      * @param value2 Value for argument {2}.
 201      * @param appendTo Gets the formatted pattern and values appended.
 202      * @param errorCode ICU error code in/out parameter.
 203      *                  Must fulfill U_SUCCESS before the function call.
 204      * @return appendTo
 205      * @stable ICU 57
 206      */
 207     UnicodeString &format(
 208             const UnicodeString &value0,
 209             const UnicodeString &value1,
 210             const UnicodeString &value2,
 211             UnicodeString &appendTo, UErrorCode &errorCode) const;
 212
 213     /**
 214      * Formats the given values, appending to the appendTo string.
 215      *
 216      * @param values The argument values.
 217      *               An argument value must not be the same object as appendTo.
 218      *               Can be NULL if valuesLength==getArgumentLimit()==0.
 219      * @param valuesLength The length of the values array.
 220      *                     Must be at least getArgumentLimit().
 221      * @param appendTo Gets the formatted pattern and values appended.
 222      * @param offsets offsets[i] receives the offset of where
 223      *                values[i] replaced pattern argument {i}.
 224      *                Can be shorter or longer than values. Can be NULL if offsetsLength==0.
 225      *                If there is no {i} in the pattern, then offsets[i] is set to -1.
 226      * @param offsetsLength The length of the offsets array.
 227      * @param errorCode ICU error code in/out parameter.
 228      *                  Must fulfill U_SUCCESS before the function call.
 229      * @return appendTo
 230      * @stable ICU 57
 231      */
 232     UnicodeString &formatAndAppend(
 233             const UnicodeString *const *values, int32_t valuesLength,
 234             UnicodeString &appendTo,
 235             int32_t *offsets, int32_t offsetsLength, UErrorCode &errorCode) const;
 236
 237     /**
 238      * Formats the given values, replacing the contents of the result string.
 239      * May optimize by actually appending to the result if it is the same object
 240      * as the value corresponding to the initial argument in the pattern.
 241      *
 242      * @param values The argument values.
 243      *               An argument value may be the same object as result.
 244      *               Can be NULL if valuesLength==getArgumentLimit()==0.
 245      * @param valuesLength The length of the values array.
 246      *                     Must be at least getArgumentLimit().
 247      * @param result Gets its contents replaced by the formatted pattern and values.
 248      * @param offsets offsets[i] receives the offset of where
 249      *                values[i] replaced pattern argument {i}.
 250      *                Can be shorter or longer than values. Can be NULL if offsetsLength==0.
 251      *                If there is no {i} in the pattern, then offsets[i] is set to -1.
 252      * @param offsetsLength The length of the offsets array.
 253      * @param errorCode ICU error code in/out parameter.
 254      *                  Must fulfill U_SUCCESS before the function call.
 255      * @return result
 256      * @stable ICU 57
 257      */
 258     UnicodeString &formatAndReplace(
 259             const UnicodeString *const *values, int32_t valuesLength,
 260             UnicodeString &result,
 261             int32_t *offsets, int32_t offsetsLength, UErrorCode &errorCode) const;
 262
 263     /**
 264      * Returns the pattern text with none of the arguments.
 265      * Like formatting with all-empty string values.
 266      * @stable ICU 57
 267      */
 268     UnicodeString getTextWithNoArguments() const {
 269         return getTextWithNoArguments(compiledPattern.getBuffer(), compiledPattern.length());
 270     }
 271
 272 private:
 273     /**
 274      * Binary representation of the compiled pattern.
 275      * Index 0: One more than the highest argument number.
 276      * Followed by zero or more arguments or literal-text segments.
 277      *
 278      * An argument is stored as its number, less than ARG_NUM_LIMIT.
 279      * A literal-text segment is stored as its length (at least 1) offset by ARG_NUM_LIMIT,
 280      * followed by that many chars.
 281      */
 282     UnicodeString compiledPattern;
 283
 284     static inline int32_t getArgumentLimit(const char16_t *compiledPattern,
 285                                               int32_t compiledPatternLength) {
 286         return compiledPatternLength == 0 ? 0 : compiledPattern[0];
 287     }
 288
 289     static UnicodeString getTextWithNoArguments(const char16_t *compiledPattern, int32_t compiledPatternLength);
 290
 291     static UnicodeString &format(
 292             const char16_t *compiledPattern, int32_t compiledPatternLength,
 293             const UnicodeString *const *values,
 294             UnicodeString &result, const UnicodeString *resultCopy, UBool forbidResultAsValue,
 295             int32_t *offsets, int32_t offsetsLength,
 296             UErrorCode &errorCode);
 297
 298     // Give access to internals to SimpleModifier for number formatting
 299     friend class number::impl::SimpleModifier;
 300 };
 301
 302 U_NAMESPACE_END
 303 #endif // U_SHOW_CPLUSPLUS_API
 304
 305 #endif  // __SIMPLEFORMATTER_H__