`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](https://alexaubry.github.io/HTMLString/) 🤖 | [Compatible with Objective-C](https://github.com/alexaubry/HTMLString/tree/main/README.md#objective%2Dc-api) ## Supported Platforms This package requires Swift 5 and Xcode 12. - iOS 9.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", from: "6.0.0") ~~~ ### CocoaPods Add this line to your `Podfile`: ~~~ruby pod 'HTMLString', '~> 6.0' ~~~ ### Carthage Add this line to your Cartfile: ~~~ github "alexaubry/HTMLString" ~> 6.0 ~~~ ## Usage `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` function to escape for ASCII-encoded content - Use the `addingUnicodeEntities` function 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. #### 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.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` function. #### 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 interoperability, 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 ~~~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" ~~~ ## Author - Alexis Aubry-Akers, hi@alexisonline.dev - You can find me on Twitter: [@_alexaubry](https://twitter.com/_alexaubry) ## License HTMLString is available under the MIT license. See the [LICENSE](LICENSE) file for more info.