Contents

NSAttributedString

A string of text that manages data, layout, and stylistic information for ranges of characters to support rendering.

Declaration

class NSAttributedString

Overview

NSAttributedString is a type you use to manage strings of stylized Unicode text. In addition to text, an attributed string contains key-value pairs known as attributes that specify additional information to apply to ranges of characters within the string. Attributed strings support many different kinds of attributes, including:

  • Rendering attributes that specify font, color, kern, ligature, and other details

  • Attributes for attachments and adaptive image glyphs

  • Semantic attributes such as link URLs or tool-tip information

  • Language attributes to support automatic gender agreement and text layout

  • Accessibility attributes that provide information for assistive technologies

  • Attributes that summarize details of the Markdown import process

  • Custom attributes you define for your app

Use attributed strings anywhere you need styled text, or when you need to associate additional information with your text. Because NSAttributedString is an immutable type, you specify all of the text and attributes for it at creation time and can’t change them later. You can create attributed strings directly from a string of characters and a dictionary of attributes. You can also create attributed strings from the contents of a file, including files that contain RTF, RTFD, HTML, Markdown, or other file formats. If you need to modify the contents of an attributed string later, use the NSMutableAttributedString type instead.

If you create an NSAttributedString without any font information, the string’s default font is Helvetica 12-point, which might differ from the default system font for the platform. To change the font, specify a font attribute at creation time.

Persistence

Be aware of how you persist attributed strings to and from the disk. RTF and RTFD are the preferred format for attributed strings because they offer the best fidelity for reading and writing attribute data. The RTF formats support a large number of standard attributes, and Apple extends the formats to support many Apple-specific attributes. If you define custom attributes for ranges of characters, store them separately alongside the RTF file for your text.

If you work extensively with HTML content, validate the results and performance of import and export operations during testing. WebKit handles the conversion between HTML markup and attributed strings. If an HTML file contains tags or constructs that attributed strings don’t support, the import process ignores them and imports what it can.

When you create an attributed string from Markdown, the system adds presentation intent attributes with information about the original Markdown content. The system doesn’t add style attributes to match the Markdown elements, but the system applies default style information when it renders a string with intent attributes. To change the rendering behavior of your Markdown content, remove the intent attributes and add the style attributes you prefer.

The methods for reading and writing common file formats also support document attributes. Document attributes aren’t part of the attributed string itself, but accompany the text when you save it to a file. When you read a file, the system returns any document attributes that it finds. Similarly, when you write an attributed string to a file, you can specify the attributes to include. For more information about document attributes, see NSAttributedString.DocumentAttributeKey and NSAttributedString.DocumentReadingOptionKey.

System framework interoperability

TextKit and Core Text use attributed strings extensively during the layout and rendering processes. These technologies use the string’s text and rendering-related attributes to calculate the text metrics needed during layout. Similarly, these technologies apply those same attributes during rendering to give the text its styled appearance. The technologies use only attributes that directly affect the appearance of the text, and ignore most other attributes. For some attributes, the text system adds attributes during rendering as needed. For example, the text system provides default style attributes for text with the link attribute.

AppKit and UIKit also support attributed strings in several ways. Some views and controls in these frameworks have APIs that accept attributed strings, and render the string with its style information. The frameworks also add methods to the NSAttributedString class that let you draw a styled string directly in one of your custom views. Because these methods use TextKit to draw the string, they recognize the same rendering-related attributes as that technology.

The NSAttributedString class and its Core Foundation counterpart, CFAttributedString, are toll-free bridged, which means you can use the two types interchangeably in your code without losing any text or attribute information.

Topics

Creating attributed strings

Exporting the string as data

Getting the characters

Getting font attribute information

Getting attributes for a range of text

Getting text content attributes

Getting document-wide attributes

Representing markdown attributes

Comparing strings

Getting the supported text-file formats

Calculating linguistic units

Performing automatic grammar agreement

Calculating ranges for common elements

Drawing the attributed string

Getting metrics for the string

Deprecated

Initializers

See Also

Strings with Metadata