Introduction

Replacing characters in a Swift String can mean a few different things: replacing all occurrences of a substring, replacing one specific character at a known position, or doing pattern-based replacement with a regular expression. Swift supports all of these, but strings are Unicode-correct collections, so the API is more careful than simple integer indexing in some other languages.

Replace All Matching Text

The most common tool is replacingOccurrences(of:with:).

1let original = "2026-03-11"
2let updated = original.replacingOccurrences(of: "-", with: "/")
3
4print(updated) // 2026/03/11

This returns a new string. It does not mutate the original value.

That makes it ideal for replacing all matching characters or substrings in one call.

Replace One Character at a Specific Position

If you need to change only one known character, use string indices and replaceSubrange.

1var text = "color"
2if let index = text.firstIndex(of: "o") {
3    text.replaceSubrange(index...index, with: "a")
4}
5
6print(text) // calor

Swift does not let you write text[1] = "a" because String uses variable-width Unicode encoding. Using proper string indices keeps the operation safe.

Use Regular Expressions for Pattern-Based Replacement

For more complex patterns, Foundation regular expressions are useful.

1import Foundation
2
3let input = "Order-123 and Order-456"
4let output = input.replacingOccurrences(
5    of: #"Order-\d+"#,
6    with: "Order-XXX",
7    options: .regularExpression
8)
9
10print(output) // Order-XXX and Order-XXX

This is a good fit when the replacement target is defined by a pattern rather than a literal character.

Be Clear About Mutation Versus Return Value

A common Swift mistake is forgetting that many string replacement APIs return a new string.

1var name = "Mina"
2name.replacingOccurrences(of: "i", with: "e")
3
4print(name) // still "Mina"

You must assign the result:

name = name.replacingOccurrences(of: "i", with: "e")
print(name) // Mena

If you want to mutate a String in place, use var plus range-based replacement methods.

Replace Characters with Manual Logic

If the rule depends on each character, build a new string manually.

1let input = "555-123-4567"
2let sanitized = String(input.map { $0 == "-" ? " " : $0 })
3
4print(sanitized) // 555 123 4567

This is useful when the transformation is more custom than a simple literal replacement.

Unicode and Indexing Matter

Swift strings are Unicode-aware, which is the right behavior, but it means you should avoid treating them like arrays of bytes or fixed-width characters.

For example:

• 'String.Index is safer than integer offsets'
• one user-visible character may not equal one byte
• replacing by position should use indices derived from the string itself

That matters especially when strings may contain emoji, accented characters, or combined glyphs.

Common Pitfalls

The most common issue is forgetting to store the result of replacingOccurrences. The original string stays unchanged unless you assign the new value.

Another problem is trying to index strings with integers as if they were simple arrays. Swift intentionally avoids that because Unicode-safe indexing is more complex.

Developers also sometimes reach for regular expressions when a literal replacement is enough. replacingOccurrences(of:with:) is simpler and clearer when the target text is fixed.

Finally, be careful when replacing a single character by position. Always derive the index from the actual string rather than assuming a certain offset maps cleanly to a visible character.

Summary

• Use replacingOccurrences(of:with:) for simple global replacement.
• Use replaceSubrange with a valid String.Index for one targeted replacement.
• Use regular expressions when the replacement target is pattern-based.
• Remember that many Swift string replacement methods return a new string.
• Treat Swift strings as Unicode-aware values, not as integer-indexed byte arrays.