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
Installation
HTMLString version vs Swift version
Below is a table that shows which version of HTMLString you should use for your Swift version.
| Swift version | HTMLString Version | |---------------|--------------------| | 4.X | >= 4.0.0 | | 3.X | >= 3.0.0 |
Swift Package Manager
Add this line to your Package.swift
:
.Package(url: "https://github.com/alexaubry/HTMLString", majorVersion: 4, minor: 0)
CocoaPods
Add this line to your Podfile
:
pod 'HTMLString', '~> 4.0'
Carthage
Add this line to your Cartfile:
github "alexaubry/HTMLString" ~> 4.0
Manual
Copy the Sources/HTMLString/
directory into your project.
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
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.
Example
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.
Example
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"
Author
- Alexis Aubry, me@alexaubry.fr
- You can find me on Twitter: @_alexaubry
License
HTMLString is available under the MIT license. See the LICENSE file for more info.
💯 Acknowledgements
This library was originally inspired by @google's Toolbox for Mac.
Github
link |
Stars: 80 |
Help us keep the lights on
Dependencies
Releases
4.1.0-beta.1 - Jun 5, 2018
4.0.2 - May 8, 2018
Update for Xcode 9.3 and Swift 4.1
- Update project for Swift 4.1
- Improve tests and documentation
4.0.0 - Sep 20, 2017
Update for Xcode 9 and Swift 4
- Update project for Swift 4
- Improve tests and documentation
- Run CI tests on mutliple platforms
- Update metadata
3.0.0 - Feb 14, 2017
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 toaddingUnicodeEntities
escapingForASCIIHTML
has been renamed toaddingASCIIEntities
unescapingFromHTML
has been renamed toremovingHTMLEntities
NSString Swift API
stringByEscapingForUnicodeHTML()
has been renamed toaddingUnicodeEntities()
stringByEscapingForASCIIHTML()
has been renamed toaddingASCIIEntities()
stringByUnescapingFromHTML()
has been renamed toremovingHTMLEntities()
NSString Objective-C API
stringByEscapingForUnicodeHTML
has been renamed tostringByAddingUnicodeEntities
stringByEscapingForASCIIHTML
has been renamed tostringByAddingASCIIEntities
stringByUnescapingFromHTML
has been renamed tostringByRemovingHTMLEntities
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
2.1.2 - Jan 16, 2017
This release extends the library's compatibility to Objective-C projects using Mix and Match interoperability.