1 // © 2022 and later: Unicode, Inc. and others. 2 // License & terms of use: http://www.unicode.org/copyright.html 3 package com.ibm.icu.text; 4 5 import java.util.HashSet; 6 import java.util.Locale; 7 import java.util.Set; 8 9 import com.ibm.icu.impl.personname.PersonNameFormatterImpl; 10 11 /** 12 * A class for formatting names of people. Takes raw name data for a person and renders it into a string according to 13 * the caller's specifications, taking into account how people's names are rendered in the caller's locale. 14 * 15 * The Length, Usage, and Formality options can be used to get a wide variety of results. In English, they would 16 * produce results along these lines: 17 * <table border="1"> 18 * <tr> 19 * <th rowspan="2"> 20 * </th> 21 * <th colspan="2"> 22 * REFERRING 23 * </th> 24 * <th colspan="2"> 25 * ADDRESSING 26 * </th> 27 * <th colspan="2"> 28 * MONOGRAM 29 * </th> 30 * </tr> 31 * <tr> 32 * <th>FORMAL</th> 33 * <th>INFORMAL</th> 34 * <th>FORMAL</th> 35 * <th>INFORMAL</th> 36 * <th>FORMAL</th> 37 * <th>INFORMAL</th> 38 * </tr> 39 * <tr> 40 * <th>LONG</th> 41 * <td>James Earl Carter Jr.</td> 42 * <td>Jimmy Carter</td> 43 * <td>Mr. Carter</td> 44 * <td>Jimmy</td> 45 * <td>JEC</td> 46 * <td>JC</td> 47 * </tr> 48 * <tr> 49 * <th>MEDIUM</th> 50 * <td>James E. Carter Jr.</td> 51 * <td>Jimmy Carter</td> 52 * <td>Mr. Carter</td> 53 * <td>Jimmy</td> 54 * <td>C</td> 55 * <td>J</td> 56 * </tr> 57 * <tr> 58 * <th>SHORT</th> 59 * <td>J. E. Carter</td> 60 * <td>Jimmy Carter</td> 61 * <td>Mr. Carter</td> 62 * <td>Jimmy</td> 63 * <td>C</td> 64 * <td>J</td> 65 * </tr> 66 * </table> 67 * 68 * @internal ICU 72 technology preview 69 * @deprecated This API is for technology preview only. 70 */ 71 @Deprecated 72 public class PersonNameFormatter { 73 //============================================================================== 74 // Parameters that control formatting behavior 75 76 /** 77 * Specifies the desired length of the formatted name. 78 * @internal ICU 72 technology preview 79 * @deprecated This API is for technology preview only. 80 */ 81 @Deprecated 82 public enum Length { 83 /** 84 * The longest name length. Generally uses most of the fields in the name object. 85 * @internal ICU 72 technology preview 86 * @deprecated This API is for technology preview only. 87 */ 88 @Deprecated 89 LONG, 90 91 /** 92 * The most typical name length. Generally includes the given name and surname, but generally 93 * not most of the other fields. 94 * @internal ICU 72 technology preview 95 * @deprecated This API is for technology preview only. 96 */ 97 @Deprecated 98 MEDIUM, 99 100 /** 101 * A shortened name. Skips most fields and may abbreviate some name fields to just their initials. 102 * When Formality is INFORMAL, may only include one field. 103 * @internal ICU 72 technology preview 104 * @deprecated This API is for technology preview only. 105 */ 106 @Deprecated 107 SHORT 108 } 109 110 /** 111 * Specifies the intended usage of the formatted name. 112 * @internal ICU 72 technology preview 113 * @deprecated This API is for technology preview only. 114 */ 115 @Deprecated 116 public enum Usage { 117 /** 118 * Used for when the name is going to be used to address the user directly: "Turn left here, John." 119 * @internal ICU 72 technology preview 120 * @deprecated This API is for technology preview only. 121 */ 122 @Deprecated 123 ADDRESSING, 124 125 /** 126 * Used in general cases, when the name is used to refer to somebody else. 127 * @internal ICU 72 technology preview 128 * @deprecated This API is for technology preview only. 129 */ 130 @Deprecated 131 REFERRING, 132 133 /** 134 * Used to generate monograms, short 1 to 3-character versions of the name suitable for use in things 135 * like chat avatars. In English, this is usually the person's initials, but this isn't true in all 136 * languages. When the caller specifies Usage.MONOGRAM, the Length parameter can be used to get different 137 * lengths of monograms: Length.SHORT is generally a single letter; Length.LONG may be as many as three or four. 138 * @internal ICU 72 technology preview 139 * @deprecated This API is for technology preview only. 140 */ 141 @Deprecated 142 MONOGRAM 143 } 144 145 /** 146 * Specifies the intended formality of the formatted name. 147 * @internal ICU 72 technology preview 148 * @deprecated This API is for technology preview only. 149 */ 150 @Deprecated 151 public enum Formality { 152 /** 153 * The more formal version of the name. 154 * @internal ICU 72 technology preview 155 * @deprecated This API is for technology preview only. 156 */ 157 @Deprecated 158 FORMAL, 159 160 /** 161 * The more informal version of the name. In English, this might omit fields or use the "informal" variant 162 * of the given name. 163 * @internal ICU 72 technology preview 164 * @deprecated This API is for technology preview only. 165 */ 166 @Deprecated 167 INFORMAL 168 } 169 170 /** 171 * Additional options to customize the behavior of the formatter. 172 * @internal ICU 72 technology preview 173 * @deprecated This API is for technology preview only. 174 */ 175 @Deprecated 176 public enum Options { 177 /** 178 * Causes the formatter to generate results suitable for inclusion in a sorted list. For GN-first languages, 179 * this generally means moving the surname to the beginning of the string, with a comma between it and 180 * the rest of the name: e.g., "Carter, James E. Jr.". 181 * @internal ICU 72 technology preview 182 * @deprecated This API is for technology preview only. 183 */ 184 @Deprecated 185 SORTING, 186 187 /** 188 * Requests that the surname in the formatted result be rendered in ALL CAPS. This is often done with 189 * Japanese names to highlight which name is the surname. 190 * @internal ICU 72 technology preview 191 * @deprecated This API is for technology preview only. 192 */ 193 @Deprecated 194 SURNAME_ALLCAPS 195 } 196 197 private final PersonNameFormatterImpl impl; 198 199 //============================================================================== 200 // Builder for PersonNameFormatter 201 202 /** 203 * A utility class that can be used to construct a PersonNameFormatter. 204 * Use PersonNameFormatter.builder() to get a new instance. 205 * @internal ICU 72 technology preview 206 * @deprecated This API is for technology preview only. 207 */ 208 @Deprecated 209 public static class Builder { 210 /** 211 * Sets the locale for the formatter to be constructed. 212 * @param locale The new formatter locale. May not be null. 213 * @return This builder. 214 * @internal ICU 72 technology preview 215 * @deprecated This API is for technology preview only. 216 */ 217 @Deprecated setLocale(Locale locale)218 public Builder setLocale(Locale locale) { 219 if (locale != null) { 220 this.locale = locale; 221 } 222 return this; 223 } 224 225 /** 226 * Sets the name length for the formatter to be constructed. 227 * @param length The new name length. 228 * @return This builder. 229 * @internal ICU 72 technology preview 230 * @deprecated This API is for technology preview only. 231 */ 232 @Deprecated setLength(Length length)233 public Builder setLength(Length length) { 234 this.length = length; 235 return this; 236 } 237 238 /** 239 * Sets the name usage for the formatter to be constructed. 240 * @param usage The new name length. 241 * @return This builder. 242 * @internal ICU 72 technology preview 243 * @deprecated This API is for technology preview only. 244 */ 245 @Deprecated setUsage(Usage usage)246 public Builder setUsage(Usage usage) { 247 this.usage = usage; 248 return this; 249 } 250 251 /** 252 * Sets the name formality for the formatter to be constructed. 253 * @param formality The new name length. 254 * @return This builder. 255 * @internal ICU 72 technology preview 256 * @deprecated This API is for technology preview only. 257 */ 258 @Deprecated setFormality(Formality formality)259 public Builder setFormality(Formality formality) { 260 this.formality = formality; 261 return this; 262 } 263 264 /** 265 * Sets the options set for the formatter to be constructed. The Set passed in 266 * here replaces the entire options set the builder already has (if one has 267 * already been set); this method doesn't modify the builder's options set. 268 * @param options The new options set. 269 * @return This builder. 270 * @internal ICU 72 technology preview 271 * @deprecated This API is for technology preview only. 272 */ 273 @Deprecated setOptions(Set<Options> options)274 public Builder setOptions(Set<Options> options) { 275 this.options = options; 276 return this; 277 } 278 279 /** 280 * Returns a new PersonNameFormatter with the values that were passed to this builder. 281 * This method doesn't freeze or delete the builder; you can call build() more than once 282 * (presumably after calling the other methods to change the parameter) to create more 283 * than one PersonNameFormatter; you don't need a new Builder for each PersonNameFormatter. 284 * @return A new PersonNameFormatter. 285 * @internal ICU 72 technology preview 286 * @deprecated This API is for technology preview only. 287 */ 288 @Deprecated build()289 public PersonNameFormatter build() { 290 return new PersonNameFormatter(locale, length, usage, formality, options); 291 } 292 Builder()293 private Builder() { 294 } 295 296 private Locale locale = Locale.getDefault(); 297 private Length length = Length.MEDIUM; 298 private Usage usage = Usage.REFERRING; 299 private Formality formality = Formality.FORMAL; 300 private Set<Options> options = new HashSet<>(); 301 } 302 303 //============================================================================== 304 // Public API on PersonNameFormatter 305 306 /** 307 * Returns a Builder object that can be used to construct a new PersonNameFormatter. 308 * @return A new Builder. 309 * @internal ICU 72 technology preview 310 * @deprecated This API is for technology preview only. 311 */ 312 @Deprecated builder()313 public static Builder builder() { 314 return new Builder(); 315 } 316 317 /** 318 * Returns a Builder object whose fields match those used to construct this formatter, 319 * allowing a new formatter to be created based on this one. 320 * @return A new Builder that can be used to create a new formatter based on this formatter. 321 * @internal ICU 72 technology preview 322 * @deprecated This API is for technology preview only. 323 */ 324 @Deprecated toBuilder()325 public Builder toBuilder() { 326 Builder builder = builder(); 327 builder.setLocale(impl.getLocale()); 328 builder.setLength(impl.getLength()); 329 builder.setUsage(impl.getUsage()); 330 builder.setFormality(impl.getFormality()); 331 builder.setOptions(impl.getOptions()); 332 return builder; 333 } 334 335 /** 336 * Formats a name. 337 * @param name A PersonName object that supplies individual field values (optionally, with modifiers applied) 338 * to the formatter for formatting. 339 * @return The name, formatted according to the locale and other parameters passed to the formatter's constructor. 340 * @internal ICU 72 technology preview 341 * @deprecated This API is for technology preview only. 342 */ 343 @Deprecated formatToString(PersonName name)344 public String formatToString(PersonName name) { 345 // TODO: Add a format() method that returns a FormattedPersonName object that descends from FormattedValue. 346 return impl.formatToString(name); 347 } 348 349 //============================================================================== 350 // Internal implementation PersonNameFormatter(Locale locale, Length length, Usage usage, Formality formality, Set<Options> options)351 private PersonNameFormatter(Locale locale, Length length, Usage usage, Formality formality, Set<Options> options) { 352 this.impl = new PersonNameFormatterImpl(locale, length, usage, formality, options); 353 } 354 355 /** 356 * @internal For unit testing only! 357 * @deprecated This API is for unit testing only. 358 */ 359 @Deprecated PersonNameFormatter(Locale locale, String[] patterns)360 public PersonNameFormatter(Locale locale, String[] patterns) { 361 this.impl = new PersonNameFormatterImpl(locale, patterns); 362 } 363 } 364