base/i18n/message_formatter.h

   1 // Copyright 2015 The Chromium Authors
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef BASE_I18N_MESSAGE_FORMATTER_H_
   6 #define BASE_I18N_MESSAGE_FORMATTER_H_
   7
   8 #include <stdint.h>
   9
  10 #include <memory>
  11 #include <string>
  12
  13 #include "base/i18n/base_i18n_export.h"
  14 #include "base/strings/string_piece.h"
  15 #include "third_party/icu/source/common/unicode/uversion.h"
  16
  17 U_NAMESPACE_BEGIN
  18 class Formattable;
  19 U_NAMESPACE_END
  20
  21 namespace base {
  22
  23 class Time;
  24
  25 namespace i18n {
  26
  27 class MessageFormatter;
  28
  29 namespace internal {
  30
  31 class BASE_I18N_EXPORT MessageArg {
  32  public:
  33   MessageArg(const char* s);
  34   MessageArg(StringPiece s);
  35   MessageArg(const std::string& s);
  36   MessageArg(const std::u16string& s);
  37   MessageArg(int i);
  38   MessageArg(int64_t i);
  39   MessageArg(double d);
  40   MessageArg(const Time& t);
  41
  42   MessageArg(const MessageArg&) = delete;
  43   MessageArg& operator=(const MessageArg&) = delete;
  44
  45   ~MessageArg();
  46
  47  private:
  48   friend class base::i18n::MessageFormatter;
  49   MessageArg();
  50   // Tests if this argument has a value, and if so increments *count.
  51   bool has_value(int* count) const;
  52   std::unique_ptr<icu::Formattable> formattable;
  53 };
  54
  55 }  // namespace internal
  56
  57 // Message Formatter with the ICU message format syntax support.
  58 // It can format strings (UTF-8 and UTF-16), numbers and base::Time with
  59 // plural, gender and other 'selectors' support. This is handy if you
  60 // have multiple parameters of differnt types and some of them require
  61 // plural or gender/selector support.
  62 //
  63 // To use this API for locale-sensitive formatting, retrieve a 'message
  64 // template' in the ICU message format from a message bundle (e.g. with
  65 // l10n_util::GetStringUTF16()) and pass it to FormatWith{Named,Numbered}Args.
  66 //
  67 // MessageFormat specs:
  68 //   http://icu-project.org/apiref/icu4j/com/ibm/icu/text/MessageFormat.html
  69 //   http://icu-project.org/apiref/icu4c/classicu_1_1DecimalFormat.html#details
  70 // Examples:
  71 //   http://userguide.icu-project.org/formatparse/messages
  72 //   message_formatter_unittest.cc
  73 //   go/plurals inside Google.
  74 //   TODO(jshin): Document this API in md format docs.
  75 // Caveat:
  76 //   When plural/select/gender is used along with other format specifiers such
  77 //   as date or number, plural/select/gender should be at the top level. It's
  78 //   not an ICU restriction but a constraint imposed by Google's translation
  79 //   infrastructure. Message A does not work. It must be revised to Message B.
  80 //
  81 //     A.
  82 //       Rated <ph name="RATING">{0, number,0.0}<ex>3.2</ex></ph>
  83 //       by {1, plural, =1{a user} other{# users}}
  84 //
  85 //     B.
  86 //       {1, plural,
  87 //         =1{Rated <ph name="RATING">{0, number,0.0}<ex>3.2</ex></ph>
  88 //             by a user.}
  89 //         other{Rated <ph name="RATING">{0, number,0.0}<ex>3.2</ex></ph>
  90 //               by # users.}}
  91
  92 class BASE_I18N_EXPORT MessageFormatter {
  93  public:
  94   MessageFormatter() = delete;
  95   MessageFormatter(const MessageFormatter&) = delete;
  96   MessageFormatter& operator=(const MessageFormatter&) = delete;
  97
  98   static std::u16string FormatWithNamedArgs(
  99       StringPiece16 msg,
 100       StringPiece name0 = StringPiece(),
 101       const internal::MessageArg& arg0 = internal::MessageArg(),
 102       StringPiece name1 = StringPiece(),
 103       const internal::MessageArg& arg1 = internal::MessageArg(),
 104       StringPiece name2 = StringPiece(),
 105       const internal::MessageArg& arg2 = internal::MessageArg(),
 106       StringPiece name3 = StringPiece(),
 107       const internal::MessageArg& arg3 = internal::MessageArg(),
 108       StringPiece name4 = StringPiece(),
 109       const internal::MessageArg& arg4 = internal::MessageArg(),
 110       StringPiece name5 = StringPiece(),
 111       const internal::MessageArg& arg5 = internal::MessageArg(),
 112       StringPiece name6 = StringPiece(),
 113       const internal::MessageArg& arg6 = internal::MessageArg());
 114
 115   static std::u16string FormatWithNumberedArgs(
 116       StringPiece16 msg,
 117       const internal::MessageArg& arg0 = internal::MessageArg(),
 118       const internal::MessageArg& arg1 = internal::MessageArg(),
 119       const internal::MessageArg& arg2 = internal::MessageArg(),
 120       const internal::MessageArg& arg3 = internal::MessageArg(),
 121       const internal::MessageArg& arg4 = internal::MessageArg(),
 122       const internal::MessageArg& arg5 = internal::MessageArg(),
 123       const internal::MessageArg& arg6 = internal::MessageArg());
 124 };
 125
 126 }  // namespace i18n
 127 }  // namespace base
 128
 129 #endif  // BASE_I18N_MESSAGE_FORMATTER_H_