ICU 64.2  64.2
Public Member Functions | Friends
icu::SimpleFormatter Class Referencefinal

Formats simple patterns like "{1} was born in {0}". More...

#include <simpleformatter.h>

Inheritance diagram for icu::SimpleFormatter:
icu::UMemory

Public Member Functions

 SimpleFormatter ()
 Default constructor. More...
 
 SimpleFormatter (const UnicodeString &pattern, UErrorCode &errorCode)
 Constructs a formatter from the pattern string. More...
 
 SimpleFormatter (const UnicodeString &pattern, int32_t min, int32_t max, UErrorCode &errorCode)
 Constructs a formatter from the pattern string. More...
 
 SimpleFormatter (const SimpleFormatter &other)
 Copy constructor. More...
 
SimpleFormatteroperator= (const SimpleFormatter &other)
 Assignment operator. More...
 
 ~SimpleFormatter ()
 Destructor. More...
 
UBool applyPattern (const UnicodeString &pattern, UErrorCode &errorCode)
 Changes this object according to the new pattern. More...
 
UBool applyPatternMinMaxArguments (const UnicodeString &pattern, int32_t min, int32_t max, UErrorCode &errorCode)
 Changes this object according to the new pattern. More...
 
int32_t getArgumentLimit () const
 
UnicodeStringformat (const UnicodeString &value0, UnicodeString &appendTo, UErrorCode &errorCode) const
 Formats the given value, appending to the appendTo builder. More...
 
UnicodeStringformat (const UnicodeString &value0, const UnicodeString &value1, UnicodeString &appendTo, UErrorCode &errorCode) const
 Formats the given values, appending to the appendTo builder. More...
 
UnicodeStringformat (const UnicodeString &value0, const UnicodeString &value1, const UnicodeString &value2, UnicodeString &appendTo, UErrorCode &errorCode) const
 Formats the given values, appending to the appendTo builder. More...
 
UnicodeStringformatAndAppend (const UnicodeString *const *values, int32_t valuesLength, UnicodeString &appendTo, int32_t *offsets, int32_t offsetsLength, UErrorCode &errorCode) const
 Formats the given values, appending to the appendTo string. More...
 
UnicodeStringformatAndReplace (const UnicodeString *const *values, int32_t valuesLength, UnicodeString &result, int32_t *offsets, int32_t offsetsLength, UErrorCode &errorCode) const
 Formats the given values, replacing the contents of the result string. More...
 
UnicodeString getTextWithNoArguments () const
 Returns the pattern text with none of the arguments. More...
 
UnicodeString getTextWithNoArguments (int32_t *offsets, int32_t offsetsLength) const
 Returns the pattern text with none of the arguments. More...
 

Friends

class number::impl::SimpleModifier
 

Detailed Description

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:

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);

This class is not intended for public subclassing.

See also
MessageFormat
UMessagePatternApostropheMode
Stable:
ICU 57

Definition at line 59 of file simpleformatter.h.

Constructor & Destructor Documentation

◆ SimpleFormatter() [1/4]

icu::SimpleFormatter::SimpleFormatter ( )
inline

Default constructor.

Stable:
ICU 57

Definition at line 65 of file simpleformatter.h.

◆ SimpleFormatter() [2/4]

icu::SimpleFormatter::SimpleFormatter ( const UnicodeString pattern,
UErrorCode errorCode 
)
inline

Constructs a formatter from the pattern string.

Parameters
patternThe pattern string.
errorCodeICU 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

Definition at line 76 of file simpleformatter.h.

◆ SimpleFormatter() [3/4]

icu::SimpleFormatter::SimpleFormatter ( const UnicodeString pattern,
int32_t  min,
int32_t  max,
UErrorCode errorCode 
)
inline

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.

Parameters
patternThe pattern string.
minThe pattern must have at least this many arguments.
maxThe pattern must have at most this many arguments.
errorCodeICU 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

Definition at line 94 of file simpleformatter.h.

◆ SimpleFormatter() [4/4]

icu::SimpleFormatter::SimpleFormatter ( const SimpleFormatter other)
inline

Copy constructor.

Stable:
ICU 57

Definition at line 103 of file simpleformatter.h.

◆ ~SimpleFormatter()

icu::SimpleFormatter::~SimpleFormatter ( )

Destructor.

Stable:
ICU 57

Member Function Documentation

◆ applyPattern()

UBool icu::SimpleFormatter::applyPattern ( const UnicodeString pattern,
UErrorCode errorCode 
)
inline

Changes this object according to the new pattern.

Parameters
patternThe pattern string.
errorCodeICU error code in/out parameter. Must fulfill U_SUCCESS before the function call. Set to U_ILLEGAL_ARGUMENT_ERROR for bad argument syntax.
Returns
TRUE if U_SUCCESS(errorCode).
Stable:
ICU 57

Definition at line 128 of file simpleformatter.h.

References INT32_MAX.

◆ applyPatternMinMaxArguments()

UBool icu::SimpleFormatter::applyPatternMinMaxArguments ( const UnicodeString pattern,
int32_t  min,
int32_t  max,
UErrorCode 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.

Parameters
patternThe pattern string.
minThe pattern must have at least this many arguments.
maxThe pattern must have at most this many arguments.
errorCodeICU 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.
Returns
TRUE if U_SUCCESS(errorCode).
Stable:
ICU 57

◆ format() [1/3]

UnicodeString& icu::SimpleFormatter::format ( const UnicodeString value0,
UnicodeString appendTo,
UErrorCode errorCode 
) const

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.

Parameters
value0Value for argument {0}.
appendToGets the formatted pattern and value appended.
errorCodeICU error code in/out parameter. Must fulfill U_SUCCESS before the function call.
Returns
appendTo
Stable:
ICU 57

◆ format() [2/3]

UnicodeString& icu::SimpleFormatter::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 2.

Parameters
value0Value for argument {0}.
value1Value for argument {1}.
appendToGets the formatted pattern and values appended.
errorCodeICU error code in/out parameter. Must fulfill U_SUCCESS before the function call.
Returns
appendTo
Stable:
ICU 57

◆ format() [3/3]

UnicodeString& icu::SimpleFormatter::format ( const UnicodeString value0,
const UnicodeString value1,
const UnicodeString value2,
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.

Parameters
value0Value for argument {0}.
value1Value for argument {1}.
value2Value for argument {2}.
appendToGets the formatted pattern and values appended.
errorCodeICU error code in/out parameter. Must fulfill U_SUCCESS before the function call.
Returns
appendTo
Stable:
ICU 57

◆ formatAndAppend()

UnicodeString& icu::SimpleFormatter::formatAndAppend ( const UnicodeString *const *  values,
int32_t  valuesLength,
UnicodeString appendTo,
int32_t *  offsets,
int32_t  offsetsLength,
UErrorCode errorCode 
) const

Formats the given values, appending to the appendTo string.

Parameters
valuesThe argument values. An argument value must not be the same object as appendTo. Can be NULL if valuesLength==getArgumentLimit()==0.
valuesLengthThe length of the values array. Must be at least getArgumentLimit().
appendToGets the formatted pattern and values appended.
offsetsoffsets[i] receives the offset of where values[i] replaced pattern argument {i}. Can be shorter or longer than values. Can be NULL if offsetsLength==0. If there is no {i} in the pattern, then offsets[i] is set to -1.
offsetsLengthThe length of the offsets array.
errorCodeICU error code in/out parameter. Must fulfill U_SUCCESS before the function call.
Returns
appendTo
Stable:
ICU 57

◆ formatAndReplace()

UnicodeString& icu::SimpleFormatter::formatAndReplace ( const UnicodeString *const *  values,
int32_t  valuesLength,
UnicodeString result,
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.

Parameters
valuesThe argument values. An argument value may be the same object as result. Can be NULL if valuesLength==getArgumentLimit()==0.
valuesLengthThe length of the values array. Must be at least getArgumentLimit().
resultGets its contents replaced by the formatted pattern and values.
offsetsoffsets[i] receives the offset of where values[i] replaced pattern argument {i}. Can be shorter or longer than values. Can be NULL if offsetsLength==0. If there is no {i} in the pattern, then offsets[i] is set to -1.
offsetsLengthThe length of the offsets array.
errorCodeICU error code in/out parameter. Must fulfill U_SUCCESS before the function call.
Returns
result
Stable:
ICU 57

◆ getArgumentLimit()

int32_t icu::SimpleFormatter::getArgumentLimit ( ) const
inline
Returns
The max argument number + 1.
Stable:
ICU 57

Definition at line 154 of file simpleformatter.h.

◆ getTextWithNoArguments() [1/2]

UnicodeString icu::SimpleFormatter::getTextWithNoArguments ( ) const
inline

Returns the pattern text with none of the arguments.

Like formatting with all-empty string values.

Stable:
ICU 57

Definition at line 267 of file simpleformatter.h.

◆ getTextWithNoArguments() [2/2]

UnicodeString icu::SimpleFormatter::getTextWithNoArguments ( int32_t *  offsets,
int32_t  offsetsLength 
) const
inline

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.

Parameters
offsetsoffsets[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.
offsetsLengthThe length of the offsets array.
Internal:
Do not use. This API is for internal use only.

Definition at line 291 of file simpleformatter.h.

References U_NAMESPACE_END.

◆ operator=()

SimpleFormatter& icu::SimpleFormatter::operator= ( const SimpleFormatter other)

Assignment operator.

Stable:
ICU 57

The documentation for this class was generated from the following file: