1 // © 2022 and later: Unicode, Inc. and others. 2 // License & terms of use: http://www.unicode.org/copyright.html 3 4 package com.ibm.icu.text; 5 6 import java.util.Arrays; 7 import java.util.Collections; 8 import java.util.List; 9 10 /** 11 * Represents all the display options that are supported by CLDR such as grammatical case, noun 12 * class, ... etc. It currently supports enums, but may be extended in the future to have other 13 * types of data. It replaces a DisplayContext[] as a method parameter. 14 * <p> 15 * NOTE: This class is Immutable, and uses a Builder interface. 16 * <p>For example: 17 * {@code DisplayOptions x = 18 * DisplayOptions.builder() 19 * .setNounClass(NounClass.DATIVE) 20 * .setPluralCategory(PluralCategory.FEW) 21 * .build(); 22 * } 23 * 24 * @draft ICU 72 25 */ 26 public final class DisplayOptions { 27 private final GrammaticalCase grammaticalCase; 28 private final NounClass nounClass; 29 private final PluralCategory pluralCategory; 30 private final Capitalization capitalization; 31 private final NameStyle nameStyle; 32 private final DisplayLength displayLength; 33 private final SubstituteHandling substituteHandling; 34 DisplayOptions(Builder builder)35 private DisplayOptions(Builder builder) { 36 this.grammaticalCase = builder.grammaticalCase; 37 this.nounClass = builder.nounClass; 38 this.pluralCategory = builder.pluralCategory; 39 this.capitalization = builder.capitalization; 40 this.nameStyle = builder.nameStyle; 41 this.displayLength = builder.displayLength; 42 this.substituteHandling = builder.substituteHandling; 43 } 44 45 /** 46 * Creates a builder with the {@code UNDEFINED} value for all the parameters. 47 * 48 * @return Builder 49 * @draft ICU 72 50 */ builder()51 public static Builder builder() { 52 return new Builder(); 53 } 54 55 /** 56 * Creates a builder with the same parameters from this object. 57 * 58 * @return Builder 59 * @draft ICU 72 60 */ copyToBuilder()61 public Builder copyToBuilder() { 62 return new Builder(this); 63 } 64 65 /** 66 * Gets the grammatical case. 67 * 68 * @return GrammaticalCase 69 * @draft ICU 72 70 */ getGrammaticalCase()71 public GrammaticalCase getGrammaticalCase() { 72 return this.grammaticalCase; 73 } 74 75 /** 76 * Gets the noun class. 77 * 78 * @return NounClass 79 * @draft ICU 72 80 */ getNounClass()81 public NounClass getNounClass() { 82 return this.nounClass; 83 } 84 85 /** 86 * Gets the plural category. 87 * 88 * @return PluralCategory 89 * @draft ICU 72 90 */ getPluralCategory()91 public PluralCategory getPluralCategory() { 92 return this.pluralCategory; 93 } 94 95 /** 96 * Gets the capitalization. 97 * 98 * @return Capitalization 99 * @draft ICU 72 100 */ getCapitalization()101 public Capitalization getCapitalization() { 102 return this.capitalization; 103 } 104 105 /** 106 * Gets the name style. 107 * 108 * @return NameStyle 109 * @draft ICU 72 110 */ getNameStyle()111 public NameStyle getNameStyle() { 112 return this.nameStyle; 113 } 114 115 /** 116 * Gets the display length. 117 * 118 * @return DisplayLength 119 * @draft ICU 72 120 */ getDisplayLength()121 public DisplayLength getDisplayLength() { 122 return this.displayLength; 123 } 124 125 /** 126 * Gets the substitute handling. 127 * 128 * @return SubstituteHandling 129 * @draft ICU 72 130 */ getSubstituteHandling()131 public SubstituteHandling getSubstituteHandling() { 132 return this.substituteHandling; 133 } 134 135 /** 136 * Responsible for building {@code DisplayOptions}. 137 * 138 * @draft ICU 72 139 */ 140 public static class Builder { 141 private GrammaticalCase grammaticalCase; 142 private NounClass nounClass; 143 private PluralCategory pluralCategory; 144 private Capitalization capitalization; 145 private NameStyle nameStyle; 146 private DisplayLength displayLength; 147 private SubstituteHandling substituteHandling; 148 149 /** 150 * Creates a {@code DisplayOptions.Builder} with the default values. 151 * 152 * @draft ICU 72 153 */ Builder()154 private Builder() { 155 this.grammaticalCase = GrammaticalCase.UNDEFINED; 156 this.nounClass = NounClass.UNDEFINED; 157 this.pluralCategory = PluralCategory.UNDEFINED; 158 this.capitalization = Capitalization.UNDEFINED; 159 this.nameStyle = NameStyle.UNDEFINED; 160 this.displayLength = DisplayLength.UNDEFINED; 161 this.substituteHandling = SubstituteHandling.UNDEFINED; 162 } 163 164 /** 165 * Creates a {@code Builder} with all the information from a {@code DisplayOptions}. 166 * 167 * @param displayOptions Options to be copied. 168 * @draft ICU 72 169 */ Builder(DisplayOptions displayOptions)170 private Builder(DisplayOptions displayOptions) { 171 this.grammaticalCase = displayOptions.grammaticalCase; 172 this.nounClass = displayOptions.nounClass; 173 this.pluralCategory = displayOptions.pluralCategory; 174 this.capitalization = displayOptions.capitalization; 175 this.nameStyle = displayOptions.nameStyle; 176 this.displayLength = displayOptions.displayLength; 177 this.substituteHandling = displayOptions.substituteHandling; 178 } 179 180 /** 181 * Sets the grammatical case. 182 * 183 * @param grammaticalCase The grammatical case. 184 * @return Builder 185 * @draft ICU 72 186 */ setGrammaticalCase(GrammaticalCase grammaticalCase)187 public Builder setGrammaticalCase(GrammaticalCase grammaticalCase) { 188 this.grammaticalCase = grammaticalCase; 189 return this; 190 } 191 192 /** 193 * Sets the noun class. 194 * 195 * @param nounClass The noun class. 196 * @return Builder 197 * @draft ICU 72 198 */ setNounClass(NounClass nounClass)199 public Builder setNounClass(NounClass nounClass) { 200 this.nounClass = nounClass; 201 return this; 202 } 203 204 /** 205 * Sets the plural category. 206 * 207 * @param pluralCategory The plural category. 208 * @return Builder 209 * @draft ICU 72 210 */ setPluralCategory(PluralCategory pluralCategory)211 public Builder setPluralCategory(PluralCategory pluralCategory) { 212 this.pluralCategory = pluralCategory; 213 return this; 214 } 215 216 /** 217 * Sets the capitalization. 218 * 219 * @param capitalization The capitalization. 220 * @return Builder 221 * @draft ICU 72 222 */ setCapitalization(Capitalization capitalization)223 public Builder setCapitalization(Capitalization capitalization) { 224 this.capitalization = capitalization; 225 return this; 226 } 227 228 /** 229 * Sets the name style. 230 * 231 * @param nameStyle The name style. 232 * @return Builder 233 * @draft ICU 72 234 */ setNameStyle(NameStyle nameStyle)235 public Builder setNameStyle(NameStyle nameStyle) { 236 this.nameStyle = nameStyle; 237 return this; 238 } 239 240 /** 241 * Sets the display length. 242 * 243 * @param displayLength The display length. 244 * @return Builder 245 * @draft ICU 72 246 */ setDisplayLength(DisplayLength displayLength)247 public Builder setDisplayLength(DisplayLength displayLength) { 248 this.displayLength = displayLength; 249 return this; 250 } 251 252 /** 253 * Sets the substitute handling. 254 * 255 * @param substituteHandling The substitute handling. 256 * @return Builder 257 * @draft ICU 72 258 */ setSubstituteHandling(SubstituteHandling substituteHandling)259 public Builder setSubstituteHandling(SubstituteHandling substituteHandling) { 260 this.substituteHandling = substituteHandling; 261 return this; 262 } 263 264 /** 265 * Builds the display options. 266 * 267 * @return DisplayOptions 268 * @draft ICU 72 269 */ build()270 public DisplayOptions build() { 271 DisplayOptions displayOptions = new DisplayOptions(this); 272 return displayOptions; 273 } 274 } 275 276 /** 277 * Represents all the grammatical noun classes that are supported by CLDR. 278 * 279 * @draft ICU 72 280 */ 281 public enum NounClass { 282 /** 283 * A possible setting for NounClass. The noun class context to be used is unknown (this is the 284 * default value). 285 * 286 * @draft ICU 72 287 */ 288 UNDEFINED("undefined"), 289 /** 290 * @draft ICU 72 291 */ 292 OTHER("other"), 293 /** 294 * @draft ICU 72 295 */ 296 NEUTER("neuter"), 297 /** 298 * @draft ICU 72 299 */ 300 FEMININE("feminine"), 301 /** 302 * @draft ICU 72 303 */ 304 MASCULINE("masculine"), 305 /** 306 * @draft ICU 72 307 */ 308 ANIMATE("animate"), 309 /** 310 * @draft ICU 72 311 */ 312 INANIMATE("inanimate"), 313 /** 314 * @draft ICU 72 315 */ 316 PERSONAL("personal"), 317 /** 318 * @draft ICU 72 319 */ 320 COMMON("common"); 321 322 private final String identifier; 323 NounClass(String identifier)324 private NounClass(String identifier) { 325 this.identifier = identifier; 326 } 327 328 /** 329 * Unmodifiable List of all noun classes constants. List version of {@link #values()}. 330 * 331 * @draft ICU 72 332 */ 333 public static final List<NounClass> VALUES = 334 Collections.unmodifiableList(Arrays.asList(NounClass.values())); 335 336 /** 337 * @return the lowercase CLDR keyword string for the noun class. 338 * @draft ICU 72 339 */ getIdentifier()340 public final String getIdentifier() { 341 return this.identifier; 342 } 343 344 /** 345 * @param identifier in lower case such as "feminine" or "masculine" 346 * @return the plural category corresponding to the identifier, or {@code UNDEFINED} 347 * @draft ICU 72 348 */ fromIdentifier(String identifier)349 public static final NounClass fromIdentifier(String identifier) { 350 if (identifier == null) { 351 return NounClass.UNDEFINED; 352 } 353 354 for (NounClass nounClass : VALUES) { 355 if (identifier.equals(nounClass.getIdentifier())) { 356 return nounClass; 357 } 358 } 359 360 return NounClass.UNDEFINED; 361 } 362 } 363 364 /** 365 * Represents all the name styles. 366 * 367 * @draft ICU 72 368 */ 369 public enum NameStyle { 370 /** 371 * A possible setting for NameStyle. The NameStyle context to be used is unknown (this is the 372 * default value). 373 * 374 * @draft ICU 72 375 */ 376 UNDEFINED, 377 /** 378 * Use standard names when generating a locale name, e.g. en_GB displays as 'English (United 379 * Kingdom)'. 380 * 381 * @draft ICU 72 382 */ 383 STANDARD_NAMES, 384 385 /** 386 * Use dialect names, when generating a locale name, e.g. en_GB displays as 'British English'. 387 * 388 * @draft ICU 72 389 */ 390 DIALECT_NAMES; 391 392 /** 393 * Unmodifiable List of all name styles constants. List version of {@link #values()}. 394 * 395 * @draft ICU 72 396 */ 397 public static final List<NameStyle> VALUES = 398 Collections.unmodifiableList(Arrays.asList(NameStyle.values())); 399 } 400 401 /** 402 * Represents all the substitute handlings. 403 * 404 * @draft ICU 72 405 */ 406 public enum SubstituteHandling { 407 /** 408 * A possible setting for SubstituteHandling. The SubstituteHandling context to be used is 409 * unknown (this is the default value). 410 * 411 * @draft ICU 72 412 */ 413 UNDEFINED, 414 /** 415 * Returns a fallback value (e.g., the input code) when no data is available. This is the 416 * default behaviour. 417 * 418 * @draft ICU 72 419 */ 420 SUBSTITUTE, 421 422 /** 423 * Returns a null value when no data is available. 424 * 425 * @draft ICU 72 426 */ 427 NO_SUBSTITUTE; 428 429 /** 430 * Unmodifiable List of all substitute handlings constants. List version of {@link #values()}. 431 * 432 * @draft ICU 72 433 */ 434 public static final List<SubstituteHandling> VALUES = 435 Collections.unmodifiableList(Arrays.asList(SubstituteHandling.values())); 436 } 437 438 /** 439 * Represents all the display lengths. 440 * 441 * @draft ICU 72 442 */ 443 public enum DisplayLength { 444 /** 445 * A possible setting for DisplayLength. The DisplayLength context to be used is unknown (this 446 * is the default value). 447 * 448 * @draft ICU 72 449 */ 450 UNDEFINED, 451 /** 452 * Uses full names when generating a locale name, e.g. "United States" for US. 453 * 454 * @draft ICU 72 455 */ 456 LENGTH_FULL, 457 458 /** 459 * Use short names when generating a locale name, e.g. "U.S." for US. 460 * 461 * @draft ICU 72 462 */ 463 LENGTH_SHORT; 464 465 /** 466 * Unmodifiable List of all display lengths constants. List version of {@link #values()}. 467 * 468 * @draft ICU 72 469 */ 470 public static final List<DisplayLength> VALUES = 471 Collections.unmodifiableList(Arrays.asList(DisplayLength.values())); 472 } 473 474 /** 475 * Represents all the capitalization options. 476 * 477 * @draft ICU 72 478 */ 479 public enum Capitalization { 480 /** 481 * A possible setting for Capitalization. The capitalization context to be used is unknown (this 482 * is the default value). 483 * 484 * @draft ICU 72 485 */ 486 UNDEFINED, 487 488 /** 489 * The capitalization context if a date, date symbol or display name is to be formatted with 490 * capitalization appropriate for the beginning of a sentence. 491 * 492 * @draft ICU 72 493 */ 494 BEGINNING_OF_SENTENCE, 495 496 /** 497 * The capitalization context if a date, date symbol or display name is to be formatted with 498 * capitalization appropriate for the middle of a sentence. 499 * 500 * @draft ICU 72 501 */ 502 MIDDLE_OF_SENTENCE, 503 504 /** 505 * The capitalization context if a date, date symbol or display name is to be formatted with 506 * capitalization appropriate for stand-alone usage such as an isolated name on a calendar 507 * page. 508 * 509 * @draft ICU 72 510 */ 511 STANDALONE, 512 513 /** 514 * The capitalization context if a date, date symbol or display name is to be formatted with 515 * capitalization appropriate for a user-interface list or menu item. 516 * 517 * @draft ICU 72 518 */ 519 UI_LIST_OR_MENU; 520 521 /** 522 * Unmodifiable List of all the capitalizations constants. List version of {@link #values()}. 523 * 524 * @draft ICU 72 525 */ 526 public static final List<Capitalization> VALUES = 527 Collections.unmodifiableList(Arrays.asList(Capitalization.values())); 528 } 529 530 /** 531 * Standard CLDR plural category constants. See http://www.unicode.org/reports/tr35/tr35-numbers.html#Language_Plural_Rules 532 * 533 * @draft ICU 72 534 */ 535 public enum PluralCategory { 536 /** 537 * A possible setting for PluralCategory. The plural category context to be used is unknown 538 * (this is the default value). 539 * 540 * @draft ICU 72 541 */ 542 UNDEFINED("undefined"), 543 544 /** 545 * @draft ICU 72 546 */ 547 ZERO("zero"), 548 549 /** 550 * @draft ICU 72 551 */ 552 ONE("one"), 553 554 /** 555 * @draft ICU 72 556 */ 557 TWO("two"), 558 559 /** 560 * @draft ICU 72 561 */ 562 FEW("few"), 563 564 /** 565 * @draft ICU 72 566 */ 567 MANY("many"), 568 569 /** 570 * @draft ICU 72 571 */ 572 OTHER("other"); 573 574 private final String identifier; 575 PluralCategory(String identifier)576 private PluralCategory(String identifier) { 577 this.identifier = identifier; 578 } 579 580 /** 581 * Unmodifiable List of all plural categories constants. List version of {@link #values()}. 582 * 583 * @draft ICU 72 584 */ 585 public static final List<PluralCategory> VALUES = 586 Collections.unmodifiableList(Arrays.asList(PluralCategory.values())); 587 588 /** 589 * @return the lowercase CLDR keyword string for the plural category 590 * @draft ICU 72 591 */ getIdentifier()592 public final String getIdentifier() { 593 return this.identifier; 594 } 595 596 /** 597 * @param identifier in lower case such as "few" or "other" 598 * @return the plural category corresponding to the identifier, or {@code UNDEFINED} 599 * @draft ICU 72 600 */ fromIdentifier(String identifier)601 public static final PluralCategory fromIdentifier(String identifier) { 602 if (identifier == null) { 603 return PluralCategory.UNDEFINED; 604 } 605 606 for (PluralCategory pluralCategory : VALUES) { 607 if (identifier.equals(pluralCategory.getIdentifier())) { 608 return pluralCategory; 609 } 610 } 611 612 return PluralCategory.UNDEFINED; 613 } 614 } 615 616 /** 617 * Represents all the grammatical cases that are supported by CLDR. 618 * 619 * @draft ICU 72 620 */ 621 public enum GrammaticalCase { 622 /** 623 * A possible setting for GrammaticalCase. The grammatical case context to be used is unknown 624 * (this is the default value). 625 * 626 * @draft ICU 72 627 */ 628 UNDEFINED("undefined"), 629 630 /** 631 * @draft ICU 72 632 */ 633 ABLATIVE("ablative"), 634 635 /** 636 * @draft ICU 72 637 */ 638 ACCUSATIVE("accusative"), 639 640 /** 641 * @draft ICU 72 642 */ 643 COMITATIVE("comitative"), 644 645 /** 646 * @draft ICU 72 647 */ 648 DATIVE("dative"), 649 650 /** 651 * @draft ICU 72 652 */ 653 ERGATIVE("ergative"), 654 655 /** 656 * @draft ICU 72 657 */ 658 GENITIVE("genitive"), 659 660 /** 661 * @draft ICU 72 662 */ 663 INSTRUMENTAL("instrumental"), 664 665 /** 666 * @draft ICU 72 667 */ 668 LOCATIVE("locative"), 669 670 /** 671 * @draft ICU 72 672 */ 673 LOCATIVE_COPULATIVE("locative_copulative"), 674 675 /** 676 * @draft ICU 72 677 */ 678 NOMINATIVE("nominative"), 679 680 /** 681 * @draft ICU 72 682 */ 683 OBLIQUE("oblique"), 684 685 /** 686 * @draft ICU 72 687 */ 688 PREPOSITIONAL("prepositional"), 689 690 /** 691 * @draft ICU 72 692 */ 693 SOCIATIVE("sociative"), 694 695 /** 696 * @draft ICU 72 697 */ 698 VOCATIVE("vocative"); 699 700 private final String identifier; 701 GrammaticalCase(String identifier)702 private GrammaticalCase(String identifier) { 703 this.identifier = identifier; 704 } 705 706 /** 707 * Unmodifiable List of all grammatical cases constants. List version of {@link #values()}. 708 * 709 * @draft ICU 72 710 */ 711 public static final List<GrammaticalCase> VALUES = 712 Collections.unmodifiableList(Arrays.asList(GrammaticalCase.values())); 713 714 /** 715 * @return the lowercase CLDR keyword string for the grammatical case. 716 * @draft ICU 72 717 */ getIdentifier()718 public final String getIdentifier() { 719 return this.identifier; 720 } 721 722 /** 723 * @param identifier in lower case such as "dative" or "nominative" 724 * @return the plural category corresponding to the identifier, or {@code UNDEFINED} 725 * @draft ICU 72 726 */ fromIdentifier(String identifier)727 public static final GrammaticalCase fromIdentifier(String identifier) { 728 if (identifier == null) { 729 return GrammaticalCase.UNDEFINED; 730 } 731 732 for (GrammaticalCase grammaticalCase : VALUES) { 733 if (identifier.equals(grammaticalCase.getIdentifier())) { 734 return grammaticalCase; 735 } 736 } 737 738 return GrammaticalCase.UNDEFINED; 739 } 740 } 741 } 742