Swiftpack.co - Package - alexaubry/HTMLString

HTMLString Swift 5.0 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

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 :

.Package(url: "https://github.com/alexaubry/HTMLString", from: "6.0.0")

CocoaPods

Add this line to your Podfile:

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

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

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

@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-Akers, hi@alexisonline.dev
  • You can find me on Twitter: @_alexaubry

License

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

Github

link
Stars: 114

Dependencies

Releases

🔖 v6.0.1 — 2020-10-01 - 2020-10-01 16:19:07

Changes

  • Add Obj-C tests

Fixes

  • Fix infinite loop when using Obj-C methods

🔖 v6.0.0 — 2020-09-28 - 2020-09-28 14:31:43

Changes

  • Require iOS 9 and Swift 5
  • Removed mutate-in-place methods

Fixes

  • Improve overall performance
  • Fix build warnings with Xcode 12

Migration Guide

  1. Adding Unicode Entities
  • Replace addingUnicodeEntities by addingUnicodeEntities()
  • Replace addUnicodeEntities() by addingUnicodeEntities()
  1. Adding ASCII Entities
  • Replace addingASCIIEntities by addingASCIIEntities()
  • Replace addASCIIEntities() by addingASCIIEntities()
  1. Removing Entities
  • Replace removingHTMLEntities by removingHTMLEntities()
  • Replace removeHTMLEntities by removingHTMLEntities()

- 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.

Improvements

  • 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))

Fixed

  • 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.

Fixed

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

Improvements

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

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

  • Escaping
  • Unescaping