Hyphenator

public final class Hyphenator

An object that hyphenates text using the Knuth-Liang algorithm.

The Knuth-Liang hyphenation algorithm identifies likely points at which a word can be hyphenated, or split across two lines of text. By default, the hyphenate(text:) method inserts U+00AD (soft hyphen) at the calculated break points. This character is invisible unless the word occurs at the end of a line, and breaking would improve text flow. Then it is rendered as a normal hyphen.

The example below shows how to hyphenate a string, specifying the hyphen character as the separator:

Example

let hyphenator = Hyphenator()
hyphenator.separator = "-"

let text = "This algorithm identifies likely hyphenation points."
print(hyphenator.hyphenate(text: text)
// This al-go-rithm iden-ti-fies like-ly hy-phen-ation points.

The algorithm is designed to prioritize the prevention of incorrect hyphenations over finding every correct hyphenation—missing a single hyphenation rarely effects text flow meaningfully, but bad hyphenation can be rather noticable. Nevertheless, the algorithm may occasionally produce unexpected results for brand names or other unusual words. In this case, you may manually specify a desired hyphenation using exceptions.

Example

let hyphenator = Hyphenator()
hyphenator.separator = "-"

print(hyphenator.hyphenate(text: "Microsoft sesquipedalian"))
// Mi-crosoft sesquipedalian

hyphenator.addCustomExceptions(["Micro-soft", "ses-qui-pe-da-li-an"])

print(hyphenator.hyphenate(text: "Microsoft sesquipedalian"))
// Micro-soft ses-qui-pe-da-li-an

The library includes American English patterns by default. Patterns for many other languages are available online with varying licenses; see Hyphenation package README for more details.

Note

The Hyphenator class is thread-safe, and can be used to hyphenate on multiple threads simultaneously (although the performance benefits over using two instances are negligible).

Important

You should not apply the hyphenate(text:) method directly to strings containing HTML or code, as the code elements may be erroneously hyphenated. A safer approach is to use another tool capable of identifying HTML or code elements and applying hyphenation only to plain text content. See HyphenationPublishPlugin for an example hyphenating HTML using SwiftSoup.

Properties

  • The minimum character count for a word to be hyphenated.

    Declaration

    Swift

    public var minLength: UInt { get set }

  • The minimum number of characters between the beginning of the word and a hyphenation point.

    Declaration

    Swift

    public var minLeading: UInt { get set }

  • The minimum number of characters between the end of the word and a hyphenation point.

    Declaration

    Swift

    public var minTrailing: UInt { get set }

  • The character to insert at each hyphenation point.

    Declaration

    Swift

    public var separator: Character { get set }

Initializers

  • Creates a Hyphenator instance using the default English patterns and exceptions.

    Declaration

    Swift

    public init()

  • Creates a Hyphenator instance using the patterns and exceptions contained in strings.

    The patterns and exceptions can be separated by newlines and/or whitespace.

    See PatternParsingError documentation for correct pattern syntax.

    Throws

    An error of type PatternParsingError.

    Declaration

    Swift

    public init(patterns: String, exceptions: String? = nil) throws

    Parameters

    patterns

    A string containing patterns.
    exceptions

    A string containing exceptions.

  • Creates a Hyphenator instance using the patterns and exceptions contained in files.

    The patterns and exceptions can be separated by newlines and/or whitespace.

    See PatternParsingError documentation for correct pattern syntax.

    Throws

    An error of type PatternParsingError, or any error thrown by String(contentsOf:encoding:).

    Declaration

    Swift

    public init(patternFile: URL, exceptionFile: URL? = nil) throws

    Parameters

    patternFile

    A URL referreing to a file containing patterns.
    exceptionFile

    A URL referreing to a file containing exceptions.

Copying

  • Returns a new Hyphenator instance, copied from an existing instance.

    Declaration

    Swift

    public func copy() -> Self

Methods

  • Returns a new String formed by finding hyphenation points in the input text and inserting the separator character at those points.

    Complexity

    Hyphenation is an O(n) operation.

    Declaration

    Swift

    public func hyphenate<T>(text: T) -> String where T : StringProtocol

    Parameters

    text

    A String or Substring containing text to be hyphenated.

  • Returns a new String formed by removing the separator character from the input text.

    Important

    Hyphenating a string is not guarenteed to be a reversible operation—if the original string contained separator characters, they will also be removed by this function.

    Declaration

    Swift

    public func unhyphenate<T>(text: T) -> String where T : StringProtocol

  • Clears the Hyphenator‘s internal cache.

    It is typically unnecessary to clear the cache, unless one wants to keep a configured Hyphenator instance and ensure it does not take any more memory than necessary.

    Declaration

    Swift

    public func clearCache()

Exceptions

  • Adds custom exceptions to the Hyphenator.

    Declaration

    Swift

    public func addCustomExceptions<T>(_ exceptions: T) where T : Collection, T.Element == String

    Parameters

    exceptions

    A collection of words to be treated as exceptions, with hyphens (“-”) inserted at the desired hyphenation points.

  • Removes custom exceptions from the Hyphenator.

    Declaration

    Swift

    public func removeCustomExceptions<T>(_ exceptions: T) where T : Collection, T.Element == String

    Parameters

    exceptions

    A collection of words that should not have custom hyphenation exceptions.

  • Removes all custom exceptions that have been added to the Hyphenator using addCustomExceptions(_:).

    Declaration

    Swift

    public func removeAllCustomExceptions()