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