Swiftpack.co - Package - alexaubry/HTMLString

HTMLString Swift 5.0 Build Status CocoaPods Carthage compatible Contact : @_alexaubry

HTMLString is a library written in Swift that allows your program to add and remove HTML entities in Strings.

| | Main features | ----------|---------------- 🔏 | Adds entities for ASCII and UTF-8/UTF-16 encodings 📝 | Removes more than 2100 named entities (like &) 🔢 | Supports removing decimal and hexadecimal entities 🐣 | Designed to support Swift Extended Grapheme Clusters (→ 100% emoji-proof) ✅ | Fully unit tested ⚡ | Fast 📚 | Documented 🤖 | Compatible with Objective-C

Supported Platforms

  • iOS 8.0+
  • macOS 10.10+
  • tvOS 9.0+
  • watchOS 2.0+
  • Linux


Swift Package Manager

Add this line to your Package.swift :

.Package(url: "https://github.com/alexaubry/HTMLString", majorVersion: 5, minor: 0)


Add this line to your Podfile:

pod 'HTMLString', '~> 5.0'


Add this line to your Cartfile:

github "alexaubry/HTMLString" ~> 5.0


HTMLString allows you to add and remove HTML entities from a String.

🔏 Adding HTML Entities (Escape)

When a character is not supported into the specified encoding, the library will replace it with a decimal entity (supported by all browsers supporting HTML 4 and later).

For instance, the & character will be replaced by &.

You can choose between ASCII and Unicode escaping:

  • Use the addingASCIIEntities property to escape for ASCII-encoded content
  • Use the addingUnicodeEntities property to escape for Unicode-compatible content

💡 Pro Tip: When your content supports UTF-8 or UTF-16, use Unicode escaping as it is faster and produces a less bloated output.


import HTMLString

let emoji = "My favorite emoji is 🙃"
let escapedEmoji = emoji.addingASCIIEntities // "My favorite emoji is 🙃"
let noNeedToEscapeThatEmoji = emoji.addingUnicodeEntities // "My favorite emoji is 🙃"

let snack = "Fish & Chips"
let escapedSnack = snack.addingASCIIEntities // "Fish & Chips"
let weAlsoNeedToEscapeThisSnack = snack.addingUnicodeEntities // "Fish & Chips"

📝 Removing HTML Entities (Unescape)

To remove all the HTML entities from a String, use the removingHTMLEntities property.


import HTMLString

let escapedEmoji = "My favorite emoji is 🙃"
let emoji = escapedEmoji.removingHTMLEntities // "My favorite emoji is 🙃"

let escapedSnack = "Fish & Chips"
let snack = escapedSnack.removingHTMLEntities // "Fish & Chips"

Objective-C API

With Obj-C Mix and Match, you can import and use the HTMLString module from in Objective-C code.

The library introduces a set of Objective-C specific APIs as categories on the NSString type:

  • -[NSString stringByAddingUnicodeEntities]; : Replaces every character incompatible with HTML Unicode encoding by a decimal HTML entitiy.
  • -[NSString stringByAddingASCIIEntities]; : Replaces every character incompatible with HTML ASCII encoding by a decimal HTML entitiy.
  • -[NSString stringByRemovingHTMLEntities]; : Replaces every HTML entity with the matching Unicode character.

Escaping Examples

@import HTMLString;

NSString *emoji = @"My favorite emoji is 🙃";
NSString *escapedEmoji = [emoji stringByAddingASCIIEntities]; // "My favorite emoji is 🙃"

NSString *snack = @"Fish & Chips";
NSString *escapedSnack = [snack stringByAddingUnicodeEntities]; // "Fish & Chips"

Unescaping Examples

@import HTMLString;

NSString *escapedEmoji = @"My favorite emoji is 🙃";
NSString *emoji = [escapedEmoji stringByRemovingHTMLEntities]; // "My favorite emoji is 🙃"

NSString *escapedSnack = @"Fish & Chips";
NSString *snack = [escapedSnack stringByRemovingHTMLEntities]; // "Fish & Chips"


  • Alexis Aubry, me@alexaubry.fr
  • You can find me on Twitter: @_alexaubry


HTMLString is available under the MIT license. See the LICENSE file for more info.


Stars: 108



- 2018-06-05 14:43:14

🔖 v4.0.2 - 2018-05-08 07:24:33

Update for Xcode 9.3 and Swift 4.1

  • Update project for Swift 4.1
  • Improve tests and documentation

🔖 v4.0.0 - 2017-09-20 10:36:09

Update for Xcode 9 and Swift 4

  • Update project for Swift 4
  • Improve tests and documentation
  • Run CI tests on mutliple platforms
  • Update metadata

🔖 v3.0.0 - 2017-02-14 09:45:11

HTMLString 3.0.0 makes everything Swiftier.

⚠️️ Source-breaking changes

The old API has been deprecated in favor of a new one that aligns to Foundation's API to add/remove percent encoding.

Swift API

  • escapingForUnicodeHTML has been renamed to addingUnicodeEntities
  • escapingForASCIIHTML has been renamed to addingASCIIEntities
  • unescapingFromHTML has been renamed to removingHTMLEntities

NSString Swift API

  • stringByEscapingForUnicodeHTML() has been renamed to addingUnicodeEntities()
  • stringByEscapingForASCIIHTML() has been renamed to addingASCIIEntities()
  • stringByUnescapingFromHTML() has been renamed to removingHTMLEntities()

NSString Objective-C API

  • stringByEscapingForUnicodeHTML has been renamed to stringByAddingUnicodeEntities
  • stringByEscapingForASCIIHTML has been renamed to stringByAddingASCIIEntities
  • stringByUnescapingFromHTML has been renamed to stringByRemovingHTMLEntities

Xcode fix-its should be able to help you migrate to the latest syntax.

✅ Fixed/Improved

  • The Xcode project has now 1 target/platform
  • Fixed an error with build settings that caused the library to be unusable with Carthage
  • Better Objective-C annotation
  • More expressive and instructive README and docs

🔖 v2.1.2 - 2017-01-16 16:23:31

This release extends the library's compatibility to Objective-C projects using Mix and Match interoperability.

🔖 v2.1.1 - 2017-01-05 20:48:23

This minor release focuses on code, security and performance improvements.

New APIs

  • You can now perform custom escaping by escaping Unicode scalars individually.


  • Further improved the escaping algorithm, which is now up to 6 times faster.
  • Changed the escaping strategy: special characters are now escaped with decimal sequences. This allows for better compatibility with browsers (HTML 4.0 compatible) and better speed
  • Changed the Unicode escaping strategy: only escape characters that could cause an XSS injection
  • Added an asymptotic complexity approximation calculator (every algorithm is now O(N))


  • Removed .DS_Store

🔖 v2.1.0 - 2017-01-04 12:02:45

Meet HTMLString v2.1.0 and its huge performance improvements!

Escaping is now up to 6.5 times faster and unescaping up to 98 times faster. Check out the new benchmark reports for more details.

Internal Changes

  • Change the escaping algorithm (reduce instead of map)
  • Reduced the size of the escaping mappings

And also

⚠️ Source breaking changes

  • The Character extensions have been removed.

🔖 v2.0.1 - 2016-12-06 12:52:29

This release focuses on improving the library's performance : escaping is 99.37% (!) faster and unescaping is 10,38% faster in average (🎉)

And also:

  • Changed the escaping/unescaping tables model
  • Better tests and coverage

🔖 v2.0.0 - 2016-12-03 17:09:01

  • Transitioned to a Character-based API: this adds full support for extended grapheme clusters.
  • Reduced build times: now builds in ~5seconds (vs ~15 in v1)
  • Rewrote tests: improved code coverage
  • Several bug fixes and code improvements
  • Added independent documentation

🔖 v1.0.2 - 2016-10-29 12:18:50

HTMLString 1.0.2 is a minor update. It contains bug fixes and improvements.


  • unescapingFromHTML : An API difference between Darwin and Open-Source Foundation in Scanner caused compilation to fail on Linux.


  • Tests on Linux and macOS
  • Minor changes in README and Podspec

🔖 v1.0.1 - 2016-10-01 10:04:30

  • Escaping
  • Unescaping