263 lines
10 KiB
Java
263 lines
10 KiB
Java
/* GENERATED SOURCE. DO NOT MODIFY. */
|
|
// © 2022 and later: Unicode, Inc. and others.
|
|
// License & terms of use: http://www.unicode.org/copyright.html
|
|
package android.icu.text;
|
|
|
|
import java.util.Locale;
|
|
import java.util.Set;
|
|
|
|
/**
|
|
* An object used to provide name data to the PersonNameFormatter for formatting.
|
|
* Clients can implement this interface to talk directly to some other subsystem
|
|
* that actually contains the name data (instead of having to copy it into a separate
|
|
* object just for formatting) or to override the default modifier behavior described
|
|
* above. A concrete SimplePersonName object that does store the field values directly
|
|
* is provided.
|
|
*
|
|
* @see SimplePersonName
|
|
* @hide Only a subset of ICU is exposed in Android
|
|
*/
|
|
public interface PersonName {
|
|
//==============================================================================
|
|
// Identifiers used to request field values from the PersonName object
|
|
|
|
/**
|
|
* Identifiers for the name fields supported by the PersonName object.
|
|
*/
|
|
enum NameField {
|
|
/**
|
|
* Contains titles such as "Mr.", "Dr." (in English these typically
|
|
* precede the name)
|
|
*/
|
|
TITLE("title"),
|
|
|
|
/**
|
|
* The given name. May contain more than one token.
|
|
*/
|
|
GIVEN("given"),
|
|
|
|
/**
|
|
* Additional given names. (In English, this is usually the "middle name" and
|
|
* may contain more than one word.)
|
|
*/
|
|
GIVEN2("given2"),
|
|
|
|
/**
|
|
* The surname. In Spanish, this is the patronymic surname.
|
|
*/
|
|
SURNAME("surname"),
|
|
|
|
/**
|
|
* Additional surnames. This is only used in a few languages, such as Spanish,
|
|
* where it is the matronymic surname. (In most languages, multiple surnames all
|
|
* just go in the SURNAME field.)
|
|
*/
|
|
SURNAME2("surname2"),
|
|
|
|
/**
|
|
* Generational qualifiers that in English generally follow the actual name,
|
|
* such as "Jr." or "III".
|
|
*/
|
|
GENERATION("generation"),
|
|
|
|
/**
|
|
* Professional qualifiers that in English generally follow the actual name,
|
|
* such as "M.D." or "J.D.".
|
|
*/
|
|
CREDENTIALS("credentials");
|
|
|
|
private final String name;
|
|
|
|
private NameField(String name) {
|
|
this.name = name;
|
|
}
|
|
|
|
/**
|
|
* Returns the NameField's display name.
|
|
*/
|
|
@Override
|
|
public String toString() {
|
|
return name;
|
|
}
|
|
|
|
/**
|
|
* Returns the appropriate NameField for its display name.
|
|
* @deprecated This API is for ICU internal use only.
|
|
* @hide draft / provisional / internal are hidden on Android
|
|
*/
|
|
@Deprecated
|
|
public static NameField forString(String name) {
|
|
for (NameField field : values()) {
|
|
if (field.name.equals(name)) {
|
|
return field;
|
|
}
|
|
}
|
|
throw new IllegalArgumentException("Invalid field name " + name);
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Identifiers for the name field modifiers supported by the PersonName and PersonNameFormatter objects.
|
|
*/
|
|
enum FieldModifier {
|
|
/**
|
|
* Requests an "informal" variant of the field, generally a nickname of some type:
|
|
* if "given" is "James", "given-informal" might be "Jimmy". Only applied to the "given"
|
|
* field. If the PersonName object doesn't apply this modifier, PersonNameFormatter just
|
|
* uses the unmodified version of "given".
|
|
*/
|
|
INFORMAL("informal"),
|
|
|
|
/**
|
|
* If the field contains a main word with one or more separate prefixes, such as
|
|
* "van den Hul", this requests just the prefixes ("van den"). Only applied to the "surname"
|
|
* field. If the PersonName object doesn't apply this modifier, PersonNameFormatter
|
|
* assumes there are no prefixes.
|
|
*/
|
|
PREFIX("prefix"),
|
|
|
|
/**
|
|
* If the field contains a main word with one or more separate prefixes, such as
|
|
* "van den Hul", this requests just the main word ("Hul"). Only applied to the "surname"
|
|
* field. If the implementing class doesn't apply this modifier, PersonNameFormatter
|
|
* assumes the entire "surname" field is the "core".
|
|
*/
|
|
CORE("core"),
|
|
|
|
/**
|
|
* Requests an initial for the specified field. PersonNameFormatter will do
|
|
* this algorithmically, but a PersonName object can apply this modifier itself if it wants
|
|
* different initial-generation logic (or stores the initial separately).
|
|
*/
|
|
INITIAL("initial"),
|
|
|
|
/**
|
|
* Requests an initial for the specified field, suitable for use in a monogram
|
|
* (this usually differs from "initial" in that "initial" often adds a period and "monogram"
|
|
* never does). PersonNameFormatter will do this algorithmically, but a PersonName object can
|
|
* apply this modifier itself if it wants different monogram-generation logic.
|
|
*/
|
|
MONOGRAM("monogram"),
|
|
|
|
/**
|
|
* Requests the field value converted to ALL CAPS. PersonName objects
|
|
* generally won't need to handle this modifier themselves.
|
|
*/
|
|
ALL_CAPS("allCaps"),
|
|
|
|
/**
|
|
* When used in conjunction with "initial", preserves the punctuation between the initials
|
|
* as it existed in the original name field (e.g., "Jean-Claude" initializes into "J-C"
|
|
* instead of "J.C.") Has no effect if "initial" isn't also present in the list of modifiers.
|
|
* @deprecated This API is ICU internal only.
|
|
* @hide draft / provisional / internal are hidden on Android
|
|
*/
|
|
@Deprecated
|
|
RETAIN("retain"),
|
|
|
|
/**
|
|
* Requests the field value with the first grapheme of each word converted to titlecase.
|
|
* A PersonName object might handle this modifier itself to capitalize words more
|
|
* selectively.
|
|
*/
|
|
INITIAL_CAP("initialCap"),
|
|
|
|
/**
|
|
* Requests the genitive form of the field's contents, if possible. The default implementation
|
|
* does nothing, but subclasses of PersonName can override getFieldValue() to produce the genitive
|
|
* form (or just add an "xxx-genitive" entry to a SimplePersonName).
|
|
* @hide draft / provisional / internal are hidden on Android
|
|
*/
|
|
GENITIVE("genitive"),
|
|
|
|
/**
|
|
* Requests the vocative form of the field's contents, if possible. The default implementation
|
|
* does nothing, but subclasses of PersonName can override getFieldValue() to produce the vocative
|
|
* form (or just add an "xxx-vocative" entry to a SimplePersonName).
|
|
* @hide draft / provisional / internal are hidden on Android
|
|
*/
|
|
VOCATIVE("vocative");
|
|
|
|
private final String name;
|
|
|
|
private FieldModifier(String name) {
|
|
this.name = name;
|
|
}
|
|
|
|
/**
|
|
* Returns the FieldModifier's display name.
|
|
*/
|
|
@Override
|
|
public String toString() {
|
|
return name;
|
|
}
|
|
|
|
/**
|
|
* Returns the appropriate fieldModifier for its display name.
|
|
*/
|
|
public static FieldModifier forString(String name) {
|
|
for (FieldModifier modifier : values()) {
|
|
if (modifier.name.equals(name)) {
|
|
return modifier;
|
|
}
|
|
}
|
|
throw new IllegalArgumentException("Invalid modifier name " + name);
|
|
}
|
|
}
|
|
|
|
/**
|
|
* An enum to specify the preferred field order for the name.
|
|
*/
|
|
enum PreferredOrder {
|
|
/**
|
|
* Indicates the name has no preferred field order, and that the formatter should deduce the
|
|
* proper field order based on the locales of the name and the formatter.
|
|
*/
|
|
DEFAULT,
|
|
|
|
/**
|
|
* Indicates that the name should be formatted in given-first order, even when the formatter
|
|
* would normally guess that it should be formatted in surname-first order.
|
|
*/
|
|
GIVEN_FIRST,
|
|
|
|
/**
|
|
* Indicates that the name should be formatted in surname-first order, even when the formatter
|
|
* would normally guess that it should be formatted in given-first order.
|
|
*/
|
|
SURNAME_FIRST
|
|
}
|
|
|
|
//==============================================================================
|
|
// Public API on PersonName
|
|
/**
|
|
* Returns the locale of the name-- that is, the language or country of origin for the person being named.
|
|
* An implementing class is allowed to return null here to indicate the name's locale is unknown.
|
|
*
|
|
* @return The name's locale, or null if it's not known.
|
|
*/
|
|
public Locale getNameLocale();
|
|
|
|
/**
|
|
* Returns the preferred field order for the name. PersonName objects should generally return DEFAULT,
|
|
* allowing the PersonNameFormatter to deduce the peoper field order based on the locales of the name
|
|
* and the formatter. But this can be used to force a particular field order, generally in cases
|
|
* where the deduction logic in PersonNameFormatter would guess wrong.
|
|
* @return The name's preferred field order.
|
|
*/
|
|
public PreferredOrder getPreferredOrder();
|
|
|
|
/**
|
|
* Returns one field of the name, possibly in a modified form.
|
|
*
|
|
* @param identifier The identifier of the requested field.
|
|
* @param modifiers An <b>IN/OUT</b> parameter that specifies modifiers to apply to the basic field value.
|
|
* An implementing class can choose to handle or ignore any modifiers; it should modify
|
|
* the passed-in Set so that on exit, it contains only the requested modifiers that it
|
|
* DIDN'T handle. This parameter may not be null, and must either be mutable or empty.
|
|
* @return The value of the requested field, optionally modified by some or all of the requested modifiers, or
|
|
* null if the requested field isn't present in the name.
|
|
*/
|
|
public String getFieldValue(NameField identifier, Set<FieldModifier> modifiers);
|
|
}
|