Swiftpack.co - Package - alexaubry/HTMLString

HTMLString Swift 4.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

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

Thanks @google

This library was originally inspired by @google's Toolbox for Mac.

Github

link
Stars: 70
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 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

2.1.2 - Jan 16, 2017

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