Installation • Usage • Donation • Issues • Contributing • License
The goal of this library is to provide handy features that didn't make it to the Swift standard library (yet) due to many different reasons. Those could be that the Swift community wants to keep the standard library clean and manageable or simply hasn't finished discussion on a specific feature yet.
If you like this, please also checkout HandyUIKit for handy UI features that we feel should have been part of the UIKit frameworks in the first place.
If you are upgrading from a previous major version of HandySwift (e.g. 1.x to 2.x) then checkout the releases section on GitHub and look out for the release notes of the last major releas(es) (e.g. 2.0.0) for an overview of the changes made. It'll save you time as hints are on how best to migrate are included there.
Currently the recommended way of installing this library is via Swift Package Manager. Carthage & Cocoapods are supported, too.
You can of course also just include this framework manually into your project by downloading it or by using git submodules.
Please have a look at the UsageExamples.playground for a complete list of features provided.
Open the Playground from within the .xcworkspace in order for it to work.
- Globals
- Extensions
- New types
Some global helpers.
Runs a given closure after a delay given in seconds. Dispatch queue can be set optionally, defaults to Main thread.
delay(by: .milliseconds(1_500)) { // Runs in Main thread by default
date = NSDate() // Delayed by 1.5 seconds: 2016-06-07 05:38:05 +0000
}
delay(by: .seconds(5), dispatchLevel: .userInteractive) {
date = NSDate() // Delayed by 5 seconds: 2016-06-07 05:38:08 +0000
}Initialize random Int value below given positive value.
Int(randomBelow: 50)! // => 26
Int(randomBelow: 1_000_000)! // => 208041Repeat some code block a given number of times.
3.times { print("Hello World!") }
// => prints "Hello World!" 3 timesMakes array by adding closure's return value n times.
let intArray = 5.timesMake { Int(randomBelow: 1_000)! }
// => [481, 16, 680, 87, 912]Apply a limiting range as the bounds of a Comparable.
Supports ClosedRange (a ... b), PartialRangeFrom (a...) and PartialRangeThrough (...b) as the limits.
let myNum = 3
myNum.clamped(to: 0 ... 6) // => 3
myNum.clamped(to: 0 ... 2) // => 2
myNum.clamped(to: 4 ... 6) // => 4
myNum.clamped(to: 5...) // => 4
myNum.clamped(to: ...2) // => 2
let myString = "d"
myString.clamped(to: "a" ... "g") // => "d"
myString.clamped(to: "a" ... "c") // => "c"
myString.clamped(to: "e" ... "g") // => "e"
myString.clamped(to: "f"...) // => "f"
myString.clamped(to: ..."c") // => "c"In-place mutating variant of clamped(to:)
var myNum = 3
myNum.clamp(to: 0...2)
myNum // => 2Rounds the value to an integral value using the specified fraction digits and rounding rule.
var price: Double = 2.875
price.round(fractionDigits: 2) // => 2.88
// OR with explicit rule:
price.round(fractionDigits: 2, rule: .down) // 2.87Returns this value rounded to an integral value using the specified fraction digits and rounding rule.
let price: Double = 2.875
price.rounded(fractionDigits: 2) // => 2.88
// OR with explicit rule:
price.rounded(fractionDigits: 2, rule: .down) // => 2.87Returns string with whitespace characters stripped from start and end.
" \n\t BB-8 likes Rey \t\n ".stripped()
// => "BB-8 likes Rey"Checks if String contains any characters other than whitespace characters.
" \t ".isBlank
// => trueGet random numeric/alphabetic/alphanumeric String of given length.
String(randomWithLength: 4, allowedCharactersType: .numeric) // => "8503"
String(randomWithLength: 6, allowedCharactersType: .alphabetic) // => "ysTUzU"
String(randomWithLength: 8, allowedCharactersType: .alphaNumeric) // => "2TgM5sUG"
String(randomWithLength: 10, allowedCharactersType: .allCharactersIn("?!🐲🍏✈️🎎🍜"))
// => "!🍏🐲✈️🎎🐲🍜??🍜"Get the full Range on a String object.
let unicodeString = "Hello composed unicode symbols! 👨👩👧👦👨👨👦👦👩👩👧👧"
unicodeString[unicodeString.fullRange] // => same stringEncrypts this plain text String with the given key using AES.GCM and returns a base64 encoded representation of the encrypted data.
@available(macOS 10.15, iOS 13, watchOS 6, tvOS 13, *)
let key = SymmetricKey(size: .bits256)
let plainText = "Harry Potter is a 🧙"
let encryptedString = try plainText.encrypted(key: key) // => "nz9LDkTNUEFj16Hrqvs4oCYeuIgV+nSP4OSqahkbtH62eJHHW664wC8NeFAMBPq7ZsY="Decrypts this base64 encoded representation of encrypted data with the given key using AES.GCM and returns the decrypted plain text String.
@available(macOS 10.15, iOS 13, watchOS 6, tvOS 13, *)
encryptedString.decrypt(key: key) // => "Harry Potter is a 🧙"Converting from NSRange to Range<String.Index> became simple in Swift 4:
let string = "Hello World!"
let nsRange = NSRange(location: 0, length: 10)
let swiftRange = Range(nsRange, in: string)The opposite is now also possible with this extension:
let string = "Hello World!"
let swiftRange: Range<String.Index> = string.fullRange
let nsRange = NSRange(swiftRange, in: string)Returns a random element within the array or nil if array empty.
[1, 2, 3, 4, 5].sample // => 4
([] as [Int]).sample // => nilReturns an array with size random elements or nil if array empty.
[1, 2, 3, 4, 5].sample(size: 3) // => [2, 1, 4]
[1, 2, 3, 4, 5].sample(size: 8) // => [1, 4, 2, 4, 3, 4, 1, 5]
([] as [Int]).sample(size: 3) // => nilCombines each element with each element of a given other array.
[1, 2, 3].combinations(with: ["A", "B"])
// => [(1, "A"), (1, "B"), (2, "A"), (2, "B"), (3, "A"), (3, "B")]Initializes a new Dictionary and fills it with keys and values arrays or returns nil if count of arrays differ.
let structure = ["firstName", "lastName"]
let dataEntries = [["Harry", "Potter"], ["Hermione", "Granger"], ["Ron", "Weasley"]]
Dictionary(keys: structure, values: dataEntries[0]) // => ["firstName": "Harry", "lastName": "Potter"]
dataEntries.map { Dictionary(keys: structure, values: $0) }
// => [["firstName": "Harry", "lastName": "Potter"], ["firstName": "Hermione", "lastName": "Grange"], ...]
Dictionary(keys: [1,2,3], values: [1,2,3,4,5]) // => nilMerges a given Dictionary into an existing Dictionary overriding existing values for matching keys.
var dict = ["A": "A value", "B": "Old B value"]
dict.merge(["B": "New B value", "C": "C value"])
dict // => ["A": "A value", "B": "New B value", "C": "C value"]Create new merged Dictionary with the given Dictionary merged into a Dictionary overriding existing values for matching keys.
let immutableDict = ["A": "A value", "B": "Old B value"]
immutableDict.merged(with: ["B": "New B value", "C": "C value"])
// => ["A": "A value", "B": "New B value", "C": "C value"]Returns a TimeInterval object from a DispatchTimeInterval.
DispatchTimeInterval.milliseconds(500).timeInterval // => 0.5Returns a TimeInterval object with a given value in a the specified unit.
TimeInterval.days(1.5) // => 129600
TimeInterval.hours(1.5) // => 5400
TimeInterval.minutes(1.5) // => 90
TimeInterval.seconds(1.5) // => 1.5
TimeInterval.milliseconds(1.5) // => 0.0015
TimeInterval.microseconds(1.5) // => 1.5e-06
TimeInterval.nanoseconds(1.5) // => 1.5e-09Returns a double value with the time interval converted to the specified unit.
let timeInterval: TimeInterval = 60 * 60 * 6
timeInterval.days // => 0.25
timeInterval.hours // => 6
timeInterval.minutes // => 360
timeInterval.seconds // => 21600
timeInterval.milliseconds // => 21600000
timeInterval.microseconds // => 21600000000
timeInterval.nanoseconds // => 21600000000000The main purpose of this wrapper is to provide speed improvements for specific actions on sorted arrays.
let unsortedArray = [5, 2, 1, 3, 0, 4]
let sortedArray = SortedArray(unsortedArray)
sortedArray.array // => [0, 1, 2, 3, 4, 5]Finds the lowest index matching the given predicate using binary search for an improved performance (O(log n)).
SortedArray([5, 2, 1, 3, 0, 4]).index { $0 > 1 }
// => 2SortedArray([5, 2, 1, 3, 0, 4]).prefix(upTo: 2)
// => [0, 1]SortedArray([5, 2, 1, 3, 0, 4]).suffix(from: 2)
// => [2, 3, 4, 5]Initialize with values and closure.
struct WordFrequency {
let word: String; let frequency: Int
init(word: String, frequency: Int) { self.word = word; self.frequency = frequency }
}
let wordFrequencies = [
WordFrequency(word: "Harry", frequency: 10),
WordFrequency(word: "Hermione", frequency: 4),
WordFrequency(word: "Ronald", frequency: 1)
]
let frequencyTable = FrequencyTable(values: wordFrequencies) { $0.frequency }
// => HandySwift.FrequencyTable<WordFrequency>Returns a random element with frequency-based probability within the array or nil if array empty.
frequencyTable.sample
let randomWord = frequencyTable.sample.map { $0.word }
// => "Harry"Returns an array with size frequency-based random elements or nil if array empty.
frequencyTable.sample(size: 6)
let randomWords = frequencyTable.sample(size: 6)!.map { $0.word }
// => ["Harry", "Ronald", "Harry", "Harry", "Hermione", "Hermione"]Regex is a swifty regex engine built on top of the NSRegularExpression API.
Initialize with pattern and, optionally, options.
let regex = try Regex("(Phil|John), [\\d]{4}")
let options: Regex.Options = [.ignoreCase, .anchorsMatchLines, .dotMatchesLineSeparators, .ignoreMetacharacters]
let regexWithOptions = try Regex("(Phil|John), [\\d]{4}", options: options)Checks whether regex matches string
regex.matches("Phil, 1991") // => trueReturns all matches
regex.matches(in: "Phil, 1991 and John, 1985")
// => [Match<"Phil, 1991">, Match<"John, 1985">]Returns first match if any
regex.firstMatch(in: "Phil, 1991 and John, 1985")
// => Match<"Phil, 1991">Replaces all matches in a string with a template string, up to the a maximum of matches (count).
regex.replacingMatches(in: "Phil, 1991 and John, 1985", with: "$1 was born in $2", count: 2)
// => "Phil was born in 1991 and John was born in 1985"Returns the captured string
match.string // => "Phil, 1991"Returns the range of the captured string within the base string
match.range // => RangeReturns the capture groups of a match
match.captures // => ["Phil", "1991"]Replaces the matched string with a template string
match.string(applyingTemplate: "$1 was born in $2")
// => "Phil was born in 1991"Weak is a wrapper to store weak references to a Wrapped instance.
Initialize with an object reference.
let text: NSString = "Hello World!"
var weak = Weak(text)Access the inner wrapped reference with the value property.
print(weak.value!)Create a Weak wrapper by assigning nil to the value.
var weakWrappedValue: Weak<AnyObject> = nilUnowned is a wrapper to store unowned references to a Wrapped instance.
Initialize with an object reference.
var unowned = Unowned(text)Access the inner wrapped reference with the value property.
print(unowned.value)Returns an element with the specified index or nil if the element does not exist .
let testArray = [0, 1, 2, 3, 20]
testArray[try: 4] // => Optional(20)
testArray[try: 20] // => nilReturns the sum of all elements. The return type is determined by the numeric elements, e.g. Int for [Int].
NOTE: Only available for Numeric types.
[0, 1, 2, 3, 4].sum() // => 10
[0.5, 1.5, 2.5].sum() // => 4.5Returns the average of all elements as a Double value.
NOTE: Only available for Int and Double collections.
[10, 20, 30, 40].average() // => 25.0
[10.75, 20.75, 30.25, 40.25].average() // => 25.5Simple protocol to make constructing and modifying objects with multiple properties more pleasant (functional, chainable, point-free). Supported by all NSObject subclasses by default.
struct Foo: Withable {
var bar: Int
var isEasy: Bool = false
}
let defaultFoo = Foo(bar: 5)
let customFoo = Foo(bar: 5).with { $0.isEasy = true }
foo.isEasy // => false
foo2.isEasy // => trueHandySwift was brought to you by Cihat Gündüz in his free time. If you want to thank me and support the development of this project, please make a small donation on PayPal. In case you also like my other open source contributions and articles, please consider motivating me by becoming a sponsor on GitHub or a patron on Patreon.
Thank you very much for any donation, it really helps out a lot! 💯
Contributions are welcome. Feel free to open an issue on GitHub with your ideas or implement an idea yourself and post a pull request. If you want to contribute code, please try to follow the same syntax and semantic in your commit messages (see rationale here). Also, please make sure to add an entry to the CHANGELOG.md file which explains your change.
This library is released under the MIT License. See LICENSE for details.