339 lines
13 KiB
C++
339 lines
13 KiB
C++
// © 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::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__
|