https://github.com/alexisakers/htmlstring

Escape and unescape HTML entities in Swift
https://github.com/alexisakers/htmlstring

decoder html-entities html-escape string swift

Last synced: about 2 months ago
JSON representation

Escape and unescape HTML entities in Swift

• Host: GitHub
• URL: https://github.com/alexisakers/htmlstring
• Owner: alexisakers
• License: mit
• Created: 2016-09-29T08:31:38.000Z (over 8 years ago)
• Default Branch: main
• Last Pushed: 2022-07-12T23:00:26.000Z (over 2 years ago)
• Last Synced: 2024-12-26T07:06:19.596Z (about 2 months ago)
• Topics: decoder, html-entities, html-escape, string, swift
• Language: Swift
• Homepage:
• Size: 1.12 MB
• Stars: 171
• Watchers: 7
• Forks: 69
• Open Issues: 3
• Metadata Files:
  • Readme: README.md
  • Changelog: CHANGELOG.md
  • License: LICENSE

Awesome Lists containing this project

README

        


    

    

        

    

    

        

    

    

        

    

    

        

    



`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, [email protected]

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