`HTMLString` is a library written in Swift that enables your app to escape and unescape 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 📚 | [100% documented](https://alexaubry.github.io/HTMLString/) 🤖 | [Compatible with Objective-C](https://github.com/alexaubry/HTMLString/tree/master/README.md#objective%2Dc-api) ## Supported Platforms - iOS 8.0+ - macOS 10.10+ - tvOS 9.0+ - watchOS 2.0+ - Linux ## Installation ### Swift Package Manager Add this line to your `Package.swift` : ~~~swift .Package(url: "https://github.com/alexaubry/HTMLString", majorVersion: 3, minor: 0) ~~~ ### CocoaPods Add this line to your `Podfile`: ~~~ pod 'HTMLString' ~~~ ### Carthage Add this line to your Cartfile: ~~~ github "alexaurby/HTMLString" ~~~ ### Manual Copy the `Sources/HTMLString/` directory into your project. ## Usage `HTMLString` allows you to add and remove HTML entities from a String. ### 🔏 Add HTML Entities (Escape) When a character is not supported into the specified encoding, the library replaces it with a decimal entitiy, such as `&` <=> `&` (compatible with HTML 4+). You can choose between ASCII and Unicode escaping. > 💡 **Pro Tip**: When your content supports UTF-8 or UTF-16, use Unicode escaping as it is faster and yields a less bloated output. #### Docs - [`addingUnicodeEntities`](https://alexaubry.github.io/HTMLString/Extensions/String.html#/s:vE10HTMLStringSS21addingUnicodeEntitiesSS) - [`addingASCIIEntities`](https://alexaubry.github.io/HTMLString/Extensions/String.html#/s:vE10HTMLStringSS19addingASCIIEntitiesSS) #### Example ~~~swift 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.addingUnicodeEntities // "Fish & Chips" ~~~ ### 📝 Remove HTML Entities (Unescape) To remove HTML entities from a String, use the `removingHTMLEntities` property. #### Docs - [`removingHTMLEntities`](https://alexaubry.github.io/HTMLString/Extensions/String.html#/s:vE10HTMLStringSS20removingHTMLEntitiesSS) #### Example ~~~swift 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: - `[aString stringByAddingUnicodeEntities];` : Replaces every character incompatible with HTML Unicode encoding by a decimal HTML entitiy. - `[aString stringByAddingASCIIEntities];` : Replaces every character incompatible with HTML ASCII encoding by a decimal HTML entitiy. - `[aString stringByRemovingHTMLEntities];` : Replaces every HTML entity with the matching Unicode character. ### Escaping Examples ~~~objc @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 ~~~objc @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" ~~~ ## 💯 Acknowledgements  This library was inspired by [**@google**'s Toolbox for Mac](https://github.com/google/google-toolbox-for-mac).