PersonNameComponentsFormatter

Declaration

class PersonNameComponentsFormatter

Overview

Each locale has its own set of rules and conventions for how personal names are structured and represented. These rules vary widely across different locales in a several ways, including the sort and display order of given and family names, the use of salutations and honorifics, and other concerns related to the grammar, spelling, punctuation, and formatting. About the only thing that is consistent across all locales is that personal names are significant and meaningful. For this reason, names deserve careful and respectful treatment—perhaps more than any other kind of information your app interacts with.

Formatters can be configured to represent names in a variety of styles, which are described in detail below.

• Default (PersonNameComponentsFormatter.Style.default)

• Short (PersonNameComponentsFormatter.Style.short)

• Long (PersonNameComponentsFormatter.Style.long)

• Abbreviated (PersonNameComponentsFormatter.Style.abbreviated)

When determining how to represent a name in a particular style, a formatter takes a number of factors into consideration, in order of priority:

1. Script derived behaviors Scripts may specify a strict sort or display order of given and family names, and the availability of styles.

2. User specified preferences Users can enable and configure the display of short names, as well as whether or not to display nicknames when available. Users can also override the default sort and display order of given and family names for their current locale.

3. Locale derived defaults Locales specify a default sort and display order for given and family names.

4. Developer specified configuration The style property value set for the NSPersonNameComponentsFormatter object.

When the behavior specified in one factor conflicts with any other factors, the behavior specified by the factor with the most precedence is used. For example, the U.S. English (en-US) locale specifies that names be displayed in “given name followed by the family name” (for example,“John Appleseed”). This behavior would be overridden if the user changed their system preferences to have names displayed as family name followed by given name (for example, “Appleseed, John”), because user-specified preferences take precedence over locale-derived defaults. Furthermore, if the name to be formatted were Japanese (for example, given name: “泰夫”, family name: “木田”), the behavior derived for the name’s script (CJK, for Chinese, Japanese, and Korean languages) would take precedence over any locale-derived defaults or user-specified preferences to have the name displayed as family name followed by given name (for example, “木田 泰夫”).

These considerations extend to the availability of certain formatter styles as well. Because developer-specified configurations have the lowest precedence in determining behavior, the value set for the formatter’s style property can be invalidated if it’s not supported for the locale, user preferences, or script. If the specified style is not available, the next longest valid style is used. For example, a name in Arabic script (for example, “أحمد الراجحي”) does not support the Abbreviated style, so the Short style is used instead. A name that contains more than one script (for example, given name: “John”, family name: “王”) is detected to have “Unknown” script, which has its own set of behaviors and characteristics.

Styles

NSPersonNameComponentsFormatter can be configured to format names in the following styles:

PersonNameComponentsFormatter.Style.default

The minimally necessary features for differentiation in a casual setting. Equivalent to PersonNameComponentsFormatter.Style.medium.

PersonNameComponentsFormatter.Style.short

Relies on user preferences and language defaults to display shortened form appropriate for display in space-constrained settings.

PersonNameComponentsFormatter.Style.long

The fully qualified name complete with all known components.

PersonNameComponentsFormatter.Style.abbreviated

The maximally abbreviated form of a name.

Default

The Default, or Medium, style presents names in a way that is suitable for most contexts. It uses the given and family names, as well as a nickname, if provided and enabled by the user in System Preferences.

Short

The Short style offers an alternative display method for names whose default representation may exceed a certain length constraint. It is only available if the user has enabled “Short Names” in System Preferences, and only for names with a script that supports Short style. Otherwise, a formatter configured to display with Short style is displayed with Medium style instead.

If a user has enabled the use of short names, the user can choose from one of four variations:

• Given Name - Family Initial

• Family Name - Given Initial

• Given Name Only

• Family Name Only

Short style is not available for names in CJK script and is restricted to Given Name Only or Family Name Only for names in Arabic or Devanagari script. If the specified Short style is unavailable, the Medium style is used instead.

Long

The Long style provides the most explicit representation of names. It uses all available name components, with the exception of nickname.

Abbreviated

The Abbreviated style offers the most compact representation of names, similar to a monogram.

Abbreviated style is supported for names in several scripts, with the following general characteristics:

• For names in Cyrillic, Greek, or Latin script, the first characters of givenName, middleName, and familyName may be used.

• For names in Chinese or Japanese script, familyName may be used. If familyName is too long, or if the family name is nil, the Short or Medium style may be used instead.

• For names in Korean script, givenName may be used. If givenName is too long, the first character of givenName may be used. If givenName is nil, the familyName may be used instead.

• For names in Bengali, Devanagari, Gujarati, Gurmukhi, Kannada, Malayalam, Oriya, Sinhala, Tamil, Telugu, Tibetan, or Thai script, the first character of givenName may be used. If givenName is nil, the first character of familyName may be used instead.

• For names that contain more than one script, the abbreviated style may use the familyName, givenName, or the first characters of givenName and/or familyName.

If the Abbreviated style is unavailable, the Short style is used instead—unless that too is unsupported, in which case the Medium style is used instead.

Topics

Configuring Formatter Behavior

• style
• isPhonetic

Converting Between Person Name Components and Strings

• localizedString(from:style:options:)
• string(from:)
• annotatedString(from:)
• personNameComponents(from:)
• getObjectValue(_:for:errorDescription:)

Constants

• PersonNameComponentsFormatter.Style
• PersonNameComponentsFormatter.Options
• Attributed String Key
• Attributed String Components
• Component Delimiter

Instance Properties

• locale

Relationships

Inherits From

• Formatter

Conforms To

• CVarArg
• CustomDebugStringConvertible
• CustomStringConvertible
• Equatable
• Hashable
• NSCoding
• NSCopying
• NSObjectProtocol
• Sendable
• SendableMetatype

See Also

Names

• PersonNameComponents