EIC code displayed by LXR master/​include/​unicode/​simpleformatter.h	Source navigation Diff markup Identifier search General search
	Version: master test Revert   Change

File indexing completed on 2025-01-18 10:13:08

 // © 2016 and later: Unicode, Inc. and others.
 // License & terms of use: http://www.unicode.org/copyright.html
 /*
 ******************************************************************************
 * Copyright (C) 2014-2016, International Business Machines
 * Corporation and others.  All Rights Reserved.
 ******************************************************************************
 * simpleformatter.h
 */
 
 #ifndef __SIMPLEFORMATTER_H__
 #define __SIMPLEFORMATTER_H__
 
 /**
  * \file
  * \brief C++ API: Simple formatter, minimal subset of MessageFormat.
  */
 
 #include "unicode/utypes.h"
 
 #if U_SHOW_CPLUSPLUS_API
 
 #include "unicode/unistr.h"
 
 U_NAMESPACE_BEGIN
 
 // Forward declaration:
 namespace number {
 namespace impl {
 class SimpleModifier;
 }
 }
 
 /**
  * Formats simple patterns like "{1} was born in {0}".
  * Minimal subset of MessageFormat; fast, simple, minimal dependencies.
  * Supports only numbered arguments with no type nor style parameters,
  * and formats only string values.
  * Quoting via ASCII apostrophe compatible with ICU MessageFormat default behavior.
  *
  * Factory methods set error codes for syntax errors
  * and for too few or too many arguments/placeholders.
  *
  * SimpleFormatter objects are thread-safe except for assignment and applying new patterns.
  *
  * Example:
  * <pre>
  * UErrorCode errorCode = U_ZERO_ERROR;
  * SimpleFormatter fmt("{1} '{born}' in {0}", errorCode);
  * UnicodeString result;
  *
  * // Output: "paul {born} in england"
  * fmt.format("england", "paul", result, errorCode);
  * </pre>
  *
  * This class is not intended for public subclassing.
  *
  * @see MessageFormat
  * @see UMessagePatternApostropheMode
  * @stable ICU 57
  */
 class U_COMMON_API SimpleFormatter final : public UMemory {
 public:
     /**
      * Default constructor.
      * @stable ICU 57
      */
     SimpleFormatter() : compiledPattern((char16_t)0) {}
 
     /**
      * Constructs a formatter from the pattern string.
      *
      * @param pattern The pattern string.
      * @param errorCode ICU error code in/out parameter.
      *                  Must fulfill U_SUCCESS before the function call.
      *                  Set to U_ILLEGAL_ARGUMENT_ERROR for bad argument syntax.
      * @stable ICU 57
      */
     SimpleFormatter(const UnicodeString& pattern, UErrorCode &errorCode) {
         applyPattern(pattern, errorCode);
     }
 
     /**
      * Constructs a formatter from the pattern string.
      * The number of arguments checked against the given limits is the
      * highest argument number plus one, not the number of occurrences of arguments.
      *
      * @param pattern The pattern string.
      * @param min The pattern must have at least this many arguments.
      * @param max The pattern must have at most this many arguments.
      * @param errorCode ICU error code in/out parameter.
      *                  Must fulfill U_SUCCESS before the function call.
      *                  Set to U_ILLEGAL_ARGUMENT_ERROR for bad argument syntax and
      *                  too few or too many arguments.
      * @stable ICU 57
      */
     SimpleFormatter(const UnicodeString& pattern, int32_t min, int32_t max,
                     UErrorCode &errorCode) {
         applyPatternMinMaxArguments(pattern, min, max, errorCode);
     }
 
     /**
      * Copy constructor.
      * @stable ICU 57
      */
     SimpleFormatter(const SimpleFormatter& other)
             : compiledPattern(other.compiledPattern) {}
 
     /**
      * Assignment operator.
      * @stable ICU 57
      */
     SimpleFormatter &operator=(const SimpleFormatter& other);
 
     /**
      * Destructor.
      * @stable ICU 57
      */
     ~SimpleFormatter();
 
     /**
      * Changes this object according to the new pattern.
      *
      * @param pattern The pattern string.
      * @param errorCode ICU error code in/out parameter.
      *                  Must fulfill U_SUCCESS before the function call.
      *                  Set to U_ILLEGAL_ARGUMENT_ERROR for bad argument syntax.
      * @return true if U_SUCCESS(errorCode).
      * @stable ICU 57
      */
     UBool applyPattern(const UnicodeString &pattern, UErrorCode &errorCode) {
         return applyPatternMinMaxArguments(pattern, 0, INT32_MAX, errorCode);
     }
 
     /**
      * Changes this object according to the new pattern.
      * The number of arguments checked against the given limits is the
      * highest argument number plus one, not the number of occurrences of arguments.
      *
      * @param pattern The pattern string.
      * @param min The pattern must have at least this many arguments.
      * @param max The pattern must have at most this many arguments.
      * @param errorCode ICU error code in/out parameter.
      *                  Must fulfill U_SUCCESS before the function call.
      *                  Set to U_ILLEGAL_ARGUMENT_ERROR for bad argument syntax and
      *                  too few or too many arguments.
      * @return true if U_SUCCESS(errorCode).
      * @stable ICU 57
      */
     UBool applyPatternMinMaxArguments(const UnicodeString &pattern,
                                       int32_t min, int32_t max, UErrorCode &errorCode);
 
     /**
      * @return The max argument number + 1.
      * @stable ICU 57
      */
     int32_t getArgumentLimit() const {
         return getArgumentLimit(compiledPattern.getBuffer(), compiledPattern.length());
     }
 
     /**
      * Formats the given value, appending to the appendTo builder.
      * The argument value must not be the same object as appendTo.
      * getArgumentLimit() must be at most 1.
      *
      * @param value0 Value for argument {0}.
      * @param appendTo Gets the formatted pattern and value appended.
      * @param errorCode ICU error code in/out parameter.
      *                  Must fulfill U_SUCCESS before the function call.
      * @return appendTo
      * @stable ICU 57
      */
     UnicodeString &format(
             const UnicodeString &value0,
             UnicodeString &appendTo, UErrorCode &errorCode) const;
 
     /**
      * Formats the given values, appending to the appendTo builder.
      * An argument value must not be the same object as appendTo.
      * getArgumentLimit() must be at most 2.
      *
      * @param value0 Value for argument {0}.
      * @param value1 Value for argument {1}.
      * @param appendTo Gets the formatted pattern and values appended.
      * @param errorCode ICU error code in/out parameter.
      *                  Must fulfill U_SUCCESS before the function call.
      * @return appendTo
      * @stable ICU 57
      */
     UnicodeString &format(
             const UnicodeString &value0,
             const UnicodeString &value1,
             UnicodeString &appendTo, UErrorCode &errorCode) const;
 
     /**
      * Formats the given values, appending to the appendTo builder.
      * An argument value must not be the same object as appendTo.
      * getArgumentLimit() must be at most 3.
      *
      * @param value0 Value for argument {0}.
      * @param value1 Value for argument {1}.
      * @param value2 Value for argument {2}.
      * @param appendTo Gets the formatted pattern and values appended.
      * @param errorCode ICU error code in/out parameter.
      *                  Must fulfill U_SUCCESS before the function call.
      * @return appendTo
      * @stable ICU 57
      */
     UnicodeString &format(
             const UnicodeString &value0,
             const UnicodeString &value1,
             const UnicodeString &value2,
             UnicodeString &appendTo, UErrorCode &errorCode) const;
 
     /**
      * Formats the given values, appending to the appendTo string.
      *
      * @param values The argument values.
      *               An argument value must not be the same object as appendTo.
      *               Can be nullptr if valuesLength==getArgumentLimit()==0.
      * @param valuesLength The length of the values array.
      *                     Must be at least getArgumentLimit().
      * @param appendTo Gets the formatted pattern and values appended.
      * @param offsets offsets[i] receives the offset of where
      *                values[i] replaced pattern argument {i}.
      *                Can be shorter or longer than values. Can be nullptr if offsetsLength==0.
      *                If there is no {i} in the pattern, then offsets[i] is set to -1.
      * @param offsetsLength The length of the offsets array.
      * @param errorCode ICU error code in/out parameter.
      *                  Must fulfill U_SUCCESS before the function call.
      * @return appendTo
      * @stable ICU 57
      */
     UnicodeString &formatAndAppend(
             const UnicodeString *const *values, int32_t valuesLength,
             UnicodeString &appendTo,
             int32_t *offsets, int32_t offsetsLength, UErrorCode &errorCode) const;
 
     /**
      * Formats the given values, replacing the contents of the result string.
      * May optimize by actually appending to the result if it is the same object
      * as the value corresponding to the initial argument in the pattern.
      *
      * @param values The argument values.
      *               An argument value may be the same object as result.
      *               Can be nullptr if valuesLength==getArgumentLimit()==0.
      * @param valuesLength The length of the values array.
      *                     Must be at least getArgumentLimit().
      * @param result Gets its contents replaced by the formatted pattern and values.
      * @param offsets offsets[i] receives the offset of where
      *                values[i] replaced pattern argument {i}.
      *                Can be shorter or longer than values. Can be nullptr if offsetsLength==0.
      *                If there is no {i} in the pattern, then offsets[i] is set to -1.
      * @param offsetsLength The length of the offsets array.
      * @param errorCode ICU error code in/out parameter.
      *                  Must fulfill U_SUCCESS before the function call.
      * @return result
      * @stable ICU 57
      */
     UnicodeString &formatAndReplace(
             const UnicodeString *const *values, int32_t valuesLength,
             UnicodeString &result,
             int32_t *offsets, int32_t offsetsLength, UErrorCode &errorCode) const;
 
     /**
      * Returns the pattern text with none of the arguments.
      * Like formatting with all-empty string values.
      * @stable ICU 57
      */
     UnicodeString getTextWithNoArguments() const {
         return getTextWithNoArguments(
             compiledPattern.getBuffer(),
             compiledPattern.length(),
             nullptr,
             0);
     }
 
 #ifndef U_HIDE_INTERNAL_API
     /**
      * Returns the pattern text with none of the arguments.
      * Like formatting with all-empty string values.
      *
      * TODO(ICU-20406): Replace this with an Iterator interface.
      *
      * @param offsets offsets[i] receives the offset of where {i} was located
      *                before it was replaced by an empty string.
      *                For example, "a{0}b{1}" produces offset 1 for i=0 and 2 for i=1.
      *                Can be nullptr if offsetsLength==0.
      *                If there is no {i} in the pattern, then offsets[i] is set to -1.
      * @param offsetsLength The length of the offsets array.
      *
      * @internal
      */
     UnicodeString getTextWithNoArguments(int32_t *offsets, int32_t offsetsLength) const {
         return getTextWithNoArguments(
             compiledPattern.getBuffer(),
             compiledPattern.length(),
             offsets,
             offsetsLength);
     }
 #endif // U_HIDE_INTERNAL_API
 
 private:
     /**
      * Binary representation of the compiled pattern.
      * Index 0: One more than the highest argument number.
      * Followed by zero or more arguments or literal-text segments.
      *
      * An argument is stored as its number, less than ARG_NUM_LIMIT.
      * A literal-text segment is stored as its length (at least 1) offset by ARG_NUM_LIMIT,
      * followed by that many chars.
      */
     UnicodeString compiledPattern;
 
     static inline int32_t getArgumentLimit(const char16_t *compiledPattern,
                                               int32_t compiledPatternLength) {
         return compiledPatternLength == 0 ? 0 : compiledPattern[0];
     }
 
     static UnicodeString getTextWithNoArguments(
         const char16_t *compiledPattern,
         int32_t compiledPatternLength,
         int32_t *offsets,
         int32_t offsetsLength);
 
     static UnicodeString &format(
             const char16_t *compiledPattern, int32_t compiledPatternLength,
             const UnicodeString *const *values,
             UnicodeString &result, const UnicodeString *resultCopy, UBool forbidResultAsValue,
             int32_t *offsets, int32_t offsetsLength,
             UErrorCode &errorCode);
 
     // Give access to internals to SimpleModifier for number formatting
     friend class number::impl::SimpleModifier;
 };
 
 U_NAMESPACE_END
 
 #endif /* U_SHOW_CPLUSPLUS_API */
 
 #endif  // __SIMPLEFORMATTER_H__

This page was automatically generated by the 2.3.7 LXR engine. The LXR team