base/i18n/message_formatter.h

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