Mercurial > repos > rliterman > csp2

annotate CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/include/unicode/selfmt.h @ 69:33d812a61356

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
planemo upload commit 2e9511a184a1ca667c7be0c6321a36dc4e3d116d
author jpayne
date Tue, 18 Mar 2025 17:55:14 -0400
parents
children
rev   line source
jpayne@69 1 // © 2016 and later: Unicode, Inc. and others.
jpayne@69 2 // License & terms of use: http://www.unicode.org/copyright.html
jpayne@69 3 /********************************************************************
jpayne@69 4 * COPYRIGHT:
jpayne@69 5 * Copyright (c) 1997-2011, International Business Machines Corporation and
jpayne@69 6 * others. All Rights Reserved.
jpayne@69 7 * Copyright (C) 2010 , Yahoo! Inc.
jpayne@69 8 ********************************************************************
jpayne@69 9 *
jpayne@69 10 * File SELFMT.H
jpayne@69 11 *
jpayne@69 12 * Modification History:
jpayne@69 13 *
jpayne@69 14 * Date Name Description
jpayne@69 15 * 11/11/09 kirtig Finished first cut of implementation.
jpayne@69 16 ********************************************************************/
jpayne@69 17
jpayne@69 18 #ifndef SELFMT
jpayne@69 19 #define SELFMT
jpayne@69 20
jpayne@69 21 #include "unicode/utypes.h"
jpayne@69 22
jpayne@69 23 #if U_SHOW_CPLUSPLUS_API
jpayne@69 24
jpayne@69 25 #include "unicode/messagepattern.h"
jpayne@69 26 #include "unicode/numfmt.h"
jpayne@69 27
jpayne@69 28 /**
jpayne@69 29 * \file
jpayne@69 30 * \brief C++ API: SelectFormat object
jpayne@69 31 */
jpayne@69 32
jpayne@69 33 #if !UCONFIG_NO_FORMATTING
jpayne@69 34
jpayne@69 35 U_NAMESPACE_BEGIN
jpayne@69 36
jpayne@69 37 class MessageFormat;
jpayne@69 38
jpayne@69 39 /**
jpayne@69 40 * <p><code>SelectFormat</code> supports the creation of internationalized
jpayne@69 41 * messages by selecting phrases based on keywords. The pattern specifies
jpayne@69 42 * how to map keywords to phrases and provides a default phrase. The
jpayne@69 43 * object provided to the format method is a string that's matched
jpayne@69 44 * against the keywords. If there is a match, the corresponding phrase
jpayne@69 45 * is selected; otherwise, the default phrase is used.</p>
jpayne@69 46 *
jpayne@69 47 * <h4>Using <code>SelectFormat</code> for Gender Agreement</h4>
jpayne@69 48 *
jpayne@69 49 * <p>Note: Typically, select formatting is done via <code>MessageFormat</code>
jpayne@69 50 * with a <code>select</code> argument type,
jpayne@69 51 * rather than using a stand-alone <code>SelectFormat</code>.</p>
jpayne@69 52 *
jpayne@69 53 * <p>The main use case for the select format is gender based inflection.
jpayne@69 54 * When names or nouns are inserted into sentences, their gender can affect pronouns,
jpayne@69 55 * verb forms, articles, and adjectives. Special care needs to be
jpayne@69 56 * taken for the case where the gender cannot be determined.
jpayne@69 57 * The impact varies between languages:</p>
jpayne@69 58 * \htmlonly
jpayne@69 59 * <ul>
jpayne@69 60 * <li>English has three genders, and unknown gender is handled as a special
jpayne@69 61 * case. Names use the gender of the named person (if known), nouns referring
jpayne@69 62 * to people use natural gender, and inanimate objects are usually neutral.
jpayne@69 63 * The gender only affects pronouns: "he", "she", "it", "they".
jpayne@69 64 *
jpayne@69 65 * <li>German differs from English in that the gender of nouns is rather
jpayne@69 66 * arbitrary, even for nouns referring to people ("M&#x00E4;dchen", girl, is neutral).
jpayne@69 67 * The gender affects pronouns ("er", "sie", "es"), articles ("der", "die",
jpayne@69 68 * "das"), and adjective forms ("guter Mann", "gute Frau", "gutes M&#x00E4;dchen").
jpayne@69 69 *
jpayne@69 70 * <li>French has only two genders; as in German the gender of nouns
jpayne@69 71 * is rather arbitrary - for sun and moon, the genders
jpayne@69 72 * are the opposite of those in German. The gender affects
jpayne@69 73 * pronouns ("il", "elle"), articles ("le", "la"),
jpayne@69 74 * adjective forms ("bon", "bonne"), and sometimes
jpayne@69 75 * verb forms ("all&#x00E9;", "all&#x00E9;e").
jpayne@69 76 *
jpayne@69 77 * <li>Polish distinguishes five genders (or noun classes),
jpayne@69 78 * human masculine, animate non-human masculine, inanimate masculine,
jpayne@69 79 * feminine, and neuter.
jpayne@69 80 * </ul>
jpayne@69 81 * \endhtmlonly
jpayne@69 82 * <p>Some other languages have noun classes that are not related to gender,
jpayne@69 83 * but similar in grammatical use.
jpayne@69 84 * Some African languages have around 20 noun classes.</p>
jpayne@69 85 *
jpayne@69 86 * <p><b>Note:</b>For the gender of a <i>person</i> in a given sentence,
jpayne@69 87 * we usually need to distinguish only between female, male and other/unknown.</p>
jpayne@69 88 *
jpayne@69 89 * <p>To enable localizers to create sentence patterns that take their
jpayne@69 90 * language's gender dependencies into consideration, software has to provide
jpayne@69 91 * information about the gender associated with a noun or name to
jpayne@69 92 * <code>MessageFormat</code>.
jpayne@69 93 * Two main cases can be distinguished:</p>
jpayne@69 94 *
jpayne@69 95 * <ul>
jpayne@69 96 * <li>For people, natural gender information should be maintained for each person.
jpayne@69 97 * Keywords like "male", "female", "mixed" (for groups of people)
jpayne@69 98 * and "unknown" could be used.
jpayne@69 99 *
jpayne@69 100 * <li>For nouns, grammatical gender information should be maintained for
jpayne@69 101 * each noun and per language, e.g., in resource bundles.
jpayne@69 102 * The keywords "masculine", "feminine", and "neuter" are commonly used,
jpayne@69 103 * but some languages may require other keywords.
jpayne@69 104 * </ul>
jpayne@69 105 *
jpayne@69 106 * <p>The resulting keyword is provided to <code>MessageFormat</code> as a
jpayne@69 107 * parameter separate from the name or noun it's associated with. For example,
jpayne@69 108 * to generate a message such as "Jean went to Paris", three separate arguments
jpayne@69 109 * would be provided: The name of the person as argument 0, the gender of
jpayne@69 110 * the person as argument 1, and the name of the city as argument 2.
jpayne@69 111 * The sentence pattern for English, where the gender of the person has
jpayne@69 112 * no impact on this simple sentence, would not refer to argument 1 at all:</p>
jpayne@69 113 *
jpayne@69 114 * <pre>{0} went to {2}.</pre>
jpayne@69 115 *
jpayne@69 116 * <p><b>Note:</b> The entire sentence should be included (and partially repeated)
jpayne@69 117 * inside each phrase. Otherwise translators would have to be trained on how to
jpayne@69 118 * move bits of the sentence in and out of the select argument of a message.
jpayne@69 119 * (The examples below do not follow this recommendation!)</p>
jpayne@69 120 *
jpayne@69 121 * <p>The sentence pattern for French, where the gender of the person affects
jpayne@69 122 * the form of the participle, uses a select format based on argument 1:</p>
jpayne@69 123 *
jpayne@69 124 * \htmlonly<pre>{0} est {1, select, female {all&#x00E9;e} other {all&#x00E9;}} &#x00E0; {2}.</pre>\endhtmlonly
jpayne@69 125 *
jpayne@69 126 * <p>Patterns can be nested, so that it's possible to handle interactions of
jpayne@69 127 * number and gender where necessary. For example, if the above sentence should
jpayne@69 128 * allow for the names of several people to be inserted, the following sentence
jpayne@69 129 * pattern can be used (with argument 0 the list of people's names,
jpayne@69 130 * argument 1 the number of people, argument 2 their combined gender, and
jpayne@69 131 * argument 3 the city name):</p>
jpayne@69 132 *
jpayne@69 133 * \htmlonly
jpayne@69 134 * <pre>{0} {1, plural,
jpayne@69 135 * one {est {2, select, female {all&#x00E9;e} other {all&#x00E9;}}}
jpayne@69 136 * other {sont {2, select, female {all&#x00E9;es} other {all&#x00E9;s}}}
jpayne@69 137 * }&#x00E0; {3}.</pre>
jpayne@69 138 * \endhtmlonly
jpayne@69 139 *
jpayne@69 140 * <h4>Patterns and Their Interpretation</h4>
jpayne@69 141 *
jpayne@69 142 * <p>The <code>SelectFormat</code> pattern string defines the phrase output
jpayne@69 143 * for each user-defined keyword.
jpayne@69 144 * The pattern is a sequence of (keyword, message) pairs.
jpayne@69 145 * A keyword is a "pattern identifier": [^[[:Pattern_Syntax:][:Pattern_White_Space:]]]+</p>
jpayne@69 146 *
jpayne@69 147 * <p>Each message is a MessageFormat pattern string enclosed in {curly braces}.</p>
jpayne@69 148 *
jpayne@69 149 * <p>You always have to define a phrase for the default keyword
jpayne@69 150 * <code>other</code>; this phrase is returned when the keyword
jpayne@69 151 * provided to
jpayne@69 152 * the <code>format</code> method matches no other keyword.
jpayne@69 153 * If a pattern does not provide a phrase for <code>other</code>, the method
jpayne@69 154 * it's provided to returns the error <code>U_DEFAULT_KEYWORD_MISSING</code>.
jpayne@69 155 * <br>
jpayne@69 156 * Pattern_White_Space between keywords and messages is ignored.
jpayne@69 157 * Pattern_White_Space within a message is preserved and output.</p>
jpayne@69 158 *
jpayne@69 159 * <p><pre>Example:
jpayne@69 160 * \htmlonly
jpayne@69 161 *
jpayne@69 162 * UErrorCode status = U_ZERO_ERROR;
jpayne@69 163 * MessageFormat *msgFmt = new MessageFormat(UnicodeString("{0} est {1, select, female {all&#x00E9;e} other {all&#x00E9;}} &#x00E0; Paris."), Locale("fr"), status);
jpayne@69 164 * if (U_FAILURE(status)) {
jpayne@69 165 * return;
jpayne@69 166 * }
jpayne@69 167 * FieldPosition ignore(FieldPosition::DONT_CARE);
jpayne@69 168 * UnicodeString result;
jpayne@69 169 *
jpayne@69 170 * char* str1= "Kirti,female";
jpayne@69 171 * Formattable args1[] = {"Kirti","female"};
jpayne@69 172 * msgFmt->format(args1, 2, result, ignore, status);
jpayne@69 173 * cout << "Input is " << str1 << " and result is: " << result << endl;
jpayne@69 174 * delete msgFmt;
jpayne@69 175 *
jpayne@69 176 * \endhtmlonly
jpayne@69 177 * </pre>
jpayne@69 178 * </p>
jpayne@69 179 *
jpayne@69 180 * Produces the output:<br>
jpayne@69 181 * \htmlonly
jpayne@69 182 * <code>Kirti est all&#x00E9;e &#x00E0; Paris.</code>
jpayne@69 183 * \endhtmlonly
jpayne@69 184 *
jpayne@69 185 * @stable ICU 4.4
jpayne@69 186 */
jpayne@69 187
jpayne@69 188 class U_I18N_API SelectFormat : public Format {
jpayne@69 189 public:
jpayne@69 190
jpayne@69 191 /**
jpayne@69 192 * Creates a new <code>SelectFormat</code> for a given pattern string.
jpayne@69 193 * @param pattern the pattern for this <code>SelectFormat</code>.
jpayne@69 194 * errors are returned to status if the pattern is invalid.
jpayne@69 195 * @param status output param set to success/failure code on exit, which
jpayne@69 196 * must not indicate a failure before the function call.
jpayne@69 197 * @stable ICU 4.4
jpayne@69 198 */
jpayne@69 199 SelectFormat(const UnicodeString& pattern, UErrorCode& status);
jpayne@69 200
jpayne@69 201 /**
jpayne@69 202 * copy constructor.
jpayne@69 203 * @stable ICU 4.4
jpayne@69 204 */
jpayne@69 205 SelectFormat(const SelectFormat& other);
jpayne@69 206
jpayne@69 207 /**
jpayne@69 208 * Destructor.
jpayne@69 209 * @stable ICU 4.4
jpayne@69 210 */
jpayne@69 211 virtual ~SelectFormat();
jpayne@69 212
jpayne@69 213 /**
jpayne@69 214 * Sets the pattern used by this select format.
jpayne@69 215 * for the keyword rules.
jpayne@69 216 * Patterns and their interpretation are specified in the class description.
jpayne@69 217 *
jpayne@69 218 * @param pattern the pattern for this select format
jpayne@69 219 * errors are returned to status if the pattern is invalid.
jpayne@69 220 * @param status output param set to success/failure code on exit, which
jpayne@69 221 * must not indicate a failure before the function call.
jpayne@69 222 * @stable ICU 4.4
jpayne@69 223 */
jpayne@69 224 void applyPattern(const UnicodeString& pattern, UErrorCode& status);
jpayne@69 225
jpayne@69 226
jpayne@69 227 using Format::format;
jpayne@69 228
jpayne@69 229 /**
jpayne@69 230 * Selects the phrase for the given keyword
jpayne@69 231 *
jpayne@69 232 * @param keyword The keyword that is used to select an alternative.
jpayne@69 233 * @param appendTo output parameter to receive result.
jpayne@69 234 * result is appended to existing contents.
jpayne@69 235 * @param pos On input: an alignment field, if desired.
jpayne@69 236 * On output: the offsets of the alignment field.
jpayne@69 237 * @param status output param set to success/failure code on exit, which
jpayne@69 238 * must not indicate a failure before the function call.
jpayne@69 239 * @return Reference to 'appendTo' parameter.
jpayne@69 240 * @stable ICU 4.4
jpayne@69 241 */
jpayne@69 242 UnicodeString& format(const UnicodeString& keyword,
jpayne@69 243 UnicodeString& appendTo,
jpayne@69 244 FieldPosition& pos,
jpayne@69 245 UErrorCode& status) const;
jpayne@69 246
jpayne@69 247 /**
jpayne@69 248 * Assignment operator
jpayne@69 249 *
jpayne@69 250 * @param other the SelectFormat object to copy from.
jpayne@69 251 * @stable ICU 4.4
jpayne@69 252 */
jpayne@69 253 SelectFormat& operator=(const SelectFormat& other);
jpayne@69 254
jpayne@69 255 /**
jpayne@69 256 * Return true if another object is semantically equal to this one.
jpayne@69 257 *
jpayne@69 258 * @param other the SelectFormat object to be compared with.
jpayne@69 259 * @return true if other is semantically equal to this.
jpayne@69 260 * @stable ICU 4.4
jpayne@69 261 */
jpayne@69 262 virtual UBool operator==(const Format& other) const;
jpayne@69 263
jpayne@69 264 /**
jpayne@69 265 * Return true if another object is semantically unequal to this one.
jpayne@69 266 *
jpayne@69 267 * @param other the SelectFormat object to be compared with.
jpayne@69 268 * @return true if other is semantically unequal to this.
jpayne@69 269 * @stable ICU 4.4
jpayne@69 270 */
jpayne@69 271 virtual UBool operator!=(const Format& other) const;
jpayne@69 272
jpayne@69 273 /**
jpayne@69 274 * Clones this Format object polymorphically. The caller owns the
jpayne@69 275 * result and should delete it when done.
jpayne@69 276 * @stable ICU 4.4
jpayne@69 277 */
jpayne@69 278 virtual SelectFormat* clone() const;
jpayne@69 279
jpayne@69 280 /**
jpayne@69 281 * Format an object to produce a string.
jpayne@69 282 * This method handles keyword strings.
jpayne@69 283 * If the Formattable object is not a <code>UnicodeString</code>,
jpayne@69 284 * then it returns a failing UErrorCode.
jpayne@69 285 *
jpayne@69 286 * @param obj A keyword string that is used to select an alternative.
jpayne@69 287 * @param appendTo output parameter to receive result.
jpayne@69 288 * Result is appended to existing contents.
jpayne@69 289 * @param pos On input: an alignment field, if desired.
jpayne@69 290 * On output: the offsets of the alignment field.
jpayne@69 291 * @param status output param filled with success/failure status.
jpayne@69 292 * @return Reference to 'appendTo' parameter.
jpayne@69 293 * @stable ICU 4.4
jpayne@69 294 */
jpayne@69 295 UnicodeString& format(const Formattable& obj,
jpayne@69 296 UnicodeString& appendTo,
jpayne@69 297 FieldPosition& pos,
jpayne@69 298 UErrorCode& status) const;
jpayne@69 299
jpayne@69 300 /**
jpayne@69 301 * Returns the pattern from applyPattern() or constructor.
jpayne@69 302 *
jpayne@69 303 * @param appendTo output parameter to receive result.
jpayne@69 304 * Result is appended to existing contents.
jpayne@69 305 * @return the UnicodeString with inserted pattern.
jpayne@69 306 * @stable ICU 4.4
jpayne@69 307 */
jpayne@69 308 UnicodeString& toPattern(UnicodeString& appendTo);
jpayne@69 309
jpayne@69 310 /**
jpayne@69 311 * This method is not yet supported by <code>SelectFormat</code>.
jpayne@69 312 * <P>
jpayne@69 313 * Before calling, set parse_pos.index to the offset you want to start
jpayne@69 314 * parsing at in the source. After calling, parse_pos.index is the end of
jpayne@69 315 * the text you parsed. If error occurs, index is unchanged.
jpayne@69 316 * <P>
jpayne@69 317 * When parsing, leading whitespace is discarded (with a successful parse),
jpayne@69 318 * while trailing whitespace is left as is.
jpayne@69 319 * <P>
jpayne@69 320 * See Format::parseObject() for more.
jpayne@69 321 *
jpayne@69 322 * @param source The string to be parsed into an object.
jpayne@69 323 * @param result Formattable to be set to the parse result.
jpayne@69 324 * If parse fails, return contents are undefined.
jpayne@69 325 * @param parse_pos The position to start parsing at. Upon return
jpayne@69 326 * this param is set to the position after the
jpayne@69 327 * last character successfully parsed. If the
jpayne@69 328 * source is not parsed successfully, this param
jpayne@69 329 * will remain unchanged.
jpayne@69 330 * @stable ICU 4.4
jpayne@69 331 */
jpayne@69 332 virtual void parseObject(const UnicodeString& source,
jpayne@69 333 Formattable& result,
jpayne@69 334 ParsePosition& parse_pos) const;
jpayne@69 335
jpayne@69 336 /**
jpayne@69 337 * ICU "poor man's RTTI", returns a UClassID for this class.
jpayne@69 338 * @stable ICU 4.4
jpayne@69 339 */
jpayne@69 340 static UClassID U_EXPORT2 getStaticClassID(void);
jpayne@69 341
jpayne@69 342 /**
jpayne@69 343 * ICU "poor man's RTTI", returns a UClassID for the actual class.
jpayne@69 344 * @stable ICU 4.4
jpayne@69 345 */
jpayne@69 346 virtual UClassID getDynamicClassID() const;
jpayne@69 347
jpayne@69 348 private:
jpayne@69 349 friend class MessageFormat;
jpayne@69 350
jpayne@69 351 SelectFormat(); // default constructor not implemented.
jpayne@69 352
jpayne@69 353 /**
jpayne@69 354 * Finds the SelectFormat sub-message for the given keyword, or the "other" sub-message.
jpayne@69 355 * @param pattern A MessagePattern.
jpayne@69 356 * @param partIndex the index of the first SelectFormat argument style part.
jpayne@69 357 * @param keyword a keyword to be matched to one of the SelectFormat argument's keywords.
jpayne@69 358 * @param ec Error code.
jpayne@69 359 * @return the sub-message start part index.
jpayne@69 360 */
jpayne@69 361 static int32_t findSubMessage(const MessagePattern& pattern, int32_t partIndex,
jpayne@69 362 const UnicodeString& keyword, UErrorCode& ec);
jpayne@69 363
jpayne@69 364 MessagePattern msgPattern;
jpayne@69 365 };
jpayne@69 366
jpayne@69 367 U_NAMESPACE_END
jpayne@69 368
jpayne@69 369 #endif /* #if !UCONFIG_NO_FORMATTING */
jpayne@69 370
jpayne@69 371 #endif /* U_SHOW_CPLUSPLUS_API */
jpayne@69 372
jpayne@69 373 #endif // _SELFMT
jpayne@69 374 //eof