woshilaozhang / swiftyattributes

A Swifty API for attributed strings

SwiftyAttributes

A Swifty API for attributed strings.

---

The original way to create an attributed string in Swift:

let attributes: [String: Any] = [
    NSForegroundColorAttributeName: UIColor.blue, 
    NSUnderlineStyleAttributeName:  NSNumber(value: NSUnderlineStyle.styleSingle.rawValue)
]
let fancyString = NSAttributedString(string: "Hello World!", attributes: attributes) 

With SwiftyAttributes, you can write the same thing like this:

let fancyString = "Hello World!".withTextColor(.blue).withUnderlineStyle(.styleSingle)

Alternatively, SwiftyAttributes provides an Attribute enum:

let fancyString = "Hello World!".withAttributes([
    .backgroundColor(.magenta),
    .strokeColor(.orange),
    .strokeWidth(1),
    .baselineOffset(5.2)
])

You can also easily combine attributed strings using a plus sign:

let fancyString = "Hello".withFont(.systemFont(ofSize: 12)) + " World!".withFont(.systemFont(ofSize: 18))

SwiftyAttributes has support for every attribute available in Cocoa and Cocoa Touch.

Requirements

• iOS 8.0+, macOS 10.11+, watchOS 2.0+, tvOS 9.0+

Installation

With CocoaPods

For Swift 3:

pod 'SwiftyAttributes'

For Swift 2.3:

pod 'SwiftyAttributes', '1.1'

If using Xcode 8, you may need to add this to end of your Podfile:

post_install do |installer|
    installer.pods_project.targets.each do |target| 
        target.build_configurations.each do |config| 
            config.build_settings["SWIFT_VERSION"] = "2.3"
        end
    end
end

With Carthage

For Swift 3:

github "eddiekaiger/SwiftyAttributes"

For Swift 2.3:

github "eddiekaiger/SwiftyAttributes" == 1.1.1

Usage

Initializing attributed strings in SwiftyAttributes can be done several ways:

• Using the with[Attribute] extensions:

  "Hello World".withUnderlineColor(.red).withUnderlineStyle(.styleDouble)

• Using the Attribute enum extensions:

  "Hello World".withAttributes([.underlineColor(.red), .underlineStyle(.styleDouble)])

• Using the Attribute enum in an initializer:

  NSAttributedString(string: "Hello World", attributes: [.kern(5), .backgroundColor(.gray)])

You can retrieve the attribute at a specific location using an attribute name from the Attribute.Name enum:

let attr: Attribute? = myAttributedString.attribute(.shadow, at: 5)

Several API methods are provided to use these new enums as well as Swift's Range type instead of NSRange. Some of the method signatures include:

extension NSMutableAttributedString {
    func addAttributes(_ attributes: [Attribute], range: Range<Int>)
    func addAttributes(_ attributes: [Attribute], range: NSRange)
    func setAttributes(_ attributes: [Attribute], range: Range<Int>)
    func setAttributes(_ attributes: [Attribute], range: NSRange)
    func replaceCharacters(in range: Range<Int>, with str: String)
    func replaceCharacters(in range: Range<Int>, with attrString: NSAttributedString)
    func deleteCharacters(in range: Range<Int>)
    func removeAttribute(_ name: Attribute.Name, range: Range<Int>)
}

extension NSAttributedString {
    convenience init(string str: String, attributes: [Attribute])
    func withAttributes(_ attributes: [Attribute]) -> NSMutableAttributedString
    func withAttribute(_ attribute: Attribute) -> NSMutableAttributedString
    func attributedSubstring(from range: Range<Int>) -> NSAttributedString
    func attribute(_ attrName: Attribute.Name, at location: Int, effectiveRange range: NSRangePointer? = nil) -> Attribute?
    func attributes(in range: Range<Int>, options: NSAttributedString.EnumerationOptions = []) -> [([Attribute], Range<Int>)]
    func enumerateAttributes(in enumerationRange: Range<Int>, options: NSAttributedString.EnumerationOptions = [], using block: (_ attrs: [Attribute], _ range: Range<Int>, _ stop: UnsafeMutablePointer<ObjCBool>) -> Void)
    func enumerateAttribute(_ attrName: Attribute.Name, in enumerationRange: Range<Int>, options: NSAttributedString.EnumerationOptions = [], using block: (_ value: Any?, _ range: Range<Int>, _ stop: UnsafeMutablePointer<ObjCBool>) -> Void)
}

extension String {
    var attributedString: NSMutableAttributedString
    func withAttributes(_ attributes: [Attribute]) -> NSMutableAttributedString
    func withAttribute(_ attribute: Attribute) -> NSMutableAttributedString
}

// ... and more!

Support

For questions, support, and suggestions, please open up an issue.

License

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