Converting Swift String Ranges to NSRange: From Compatibility Issues to Modern Solutions

Background and Core Challenges

In iOS and macOS development, Swift's String type and Objective-C's NSString type have fundamental differences in handling string ranges. Swift's Range<String.Index> is based on Unicode scalars, while NSRange is based on UTF-16 code units. This discrepancy can lead to errors during direct conversion, especially with strings containing surrogate pairs (e.g., emojis).

Solutions for Early Swift Versions

In Swift 3 and earlier, developers needed to manually handle range conversions. A common but flawed approach uses the distance function to calculate start and length:

let start = distance(text.startIndex, substringRange.startIndex)
let length = distance(substringRange.startIndex, substringRange.endIndex)
let range = NSMakeRange(start, length)

However, this method fails with multi-code-unit characters. For example, emojis in a string like "Long paragraph saying!" cause miscalculations, applying attributes to incorrect positions.

Recommended Compatibility Approach

A more reliable method is to convert the Swift string to NSString and use its range APIs directly:

let text = "Long paragraph saying!"
let nsText = text as NSString
let textRange = NSMakeRange(0, nsText.length)
let attributedString = NSMutableAttributedString(string: nsText)

nsText.enumerateSubstrings(in: textRange, options: .byWords, using: {
    (substring, substringRange, _, _) in
    if (substring == "saying") {
        attributedString.addAttribute(.foregroundColor, value: NSColor.red, range: substringRange)
    }
})

This ensures range calculations are based on consistent UTF-16 encoding, avoiding character count errors.

Modern Solutions for Swift 4 and Later

Swift 4 introduced an initializer for NSRange that directly supports conversion from Range<String.Index>:

let text = "Long paragraph saying!"
let attributedString = NSMutableAttributedString(string: text)

text.enumerateSubstrings(in: text.startIndex..<text.endIndex, options: .byWords) {
    (substring, substringRange, _, _) in
    if substring == "saying" {
        attributedString.addAttribute(.foregroundColor, value: NSColor.red,
                                      range: NSRange(substringRange, in: text))
    }
}

The NSRange(substringRange, in: text) initializer automatically handles encoding differences, providing type-safe and efficient range conversion.

Supplementary Methods and Considerations

For simple scenarios, NSString's range(of:) method can be used directly:

let text = "follow the yellow brick road"
let str = NSString(string: text)
let theRange = str.range(of: "yellow")
attributedString.addAttribute(.foregroundColor, value: UIColor.yellow, range: theRange)

But this only works for exact matches and is not suitable for complex text enumeration.

Summary and Best Practices

When converting between Swift string ranges and NSRange, understanding character encoding differences is key. For modern Swift projects (Swift 4+), prioritize the NSRange(_:in:) initializer. For older versions or maximum compatibility, converting to NSString and using its range APIs is the safest choice. Always test with strings containing Unicode special characters to ensure accurate range calculations.