Latest 1.1.0
Homepage https://github.com/fiveagency/ios-five-utils
License MIT
Platforms ios 8.0, osx 10.10
Authors

CI Status
Version
License
Platform
Swift Package Manager compatible

About

This bundle contains Swift utility functions we tend to re-use on many of our projects (us being Five Agency’s iOS Team). We expect there’ll be many more added, but in the mean time, you’re free to use/re-use/upgrade all of the existing code here. Everything and anything regarding helper functions, random generators, math, and other nice to have snippets.

Requirements

  • Xcode 8.0+
  • Swift 3.0

  • iOS 8.0+
  • OSX 10.10+

Installation

There are no additional dependencies.

Currently supported installation options:

Using CocoaPods

To install it, simply add the following line to your Podfile:

# Podfile
use_frameworks!

target 'YOUR_TARGET_NAME' do
    pod 'FiveUtils'
end

Replace YOUR_TARGET_NAME and then, in the Podfile directory, type:

$ pod install

Swift Package Manager

Create a Package.swift file.

import PackageDescription

let package = Package(
    name: "FiveUtilsTestProject",
    targets: [],
    dependencies: [
        .Package(url: "https://github.com/fiveagency/ios-five-utils", majorVersion: 1)
    ]
)

Manually using git submodules

  • Add FiveUtils as a submodule
$ git submodule add https://github.com/fiveagency/ios-five-utils.git
  • Drag FiveUtils.xcodeproj into Project Navigator.

  • Go to Project > Targets > Build Phases > Link Binary With Libraries, click + and select FiveUtils.framework target.

Examples

To run the example project do the following.

  • Clone the repo by typing:

    $ git clone https://github.com/fiveagency/ios-five-utils.git YOUR_DESTINATION_FOLDER
  • Open FiveUtils.xcworkspace, choose Example scheme and hit run. This method will build everything and run the sample app.

Usage

Math module

/**
 Clamps value between lower and upper bound.
 */

public static func clamp<T: Comparable>(_ value: T, between lower: T, and upper: T) -> T

Example usage:

print(clamp(32, lower: 1, upper: 3))
print(clamp(14, lower: 10, upper: 20))
print(clamp(1, lower: 5, upper: 7))

results in

> 3
> 14
> 5
/**
 Interpolates linearly between initial and target value.
 */

public static func lerp<T: Lerpable>(from first: T, to second: T, t: CGFloat) -> T

Note: Currently supported lerpable types are CGFloat, Double, Float and Int.

Example usage:

print(lerp(from: 4, to: 8, t: 0.5))
print(lerp(from: 1.0, to: 5.0, t: 1.0))

results in

> 6
> 5.0
/**
 Enables us to compare floating point numbers within a given precision frame.
 */

protocol FloatingPointComparable: FloatingPoint {

    func isEqualEnough(to other: Self, withPrecision precision: Double) -> Bool
    func typeBasedPrecision(fromPrecision precision: Double) -> Self
}

Example usage:

print(Float(15).isEqualEnough(to: 15.002, withPrecision: 0.001))
print(Float(15.0025).isEqualEnough(to: 15.002, withPrecisionScale: 0.001))
print(Float(15).isEqualEnough(to: 15.002))

results in

> false
> true
> false

Note: One could use a shortened version of this function without the precision scale parameter. The default one is 0.001.
Note: Currently supported lerpable types are CGFloat, Double and Float.

Random module

/**
 Returns a random CGFloat value specified in the [from, to) set. If no values get specified,
 the default set is [0.0, 1.0). The method allows for set bounds to be inverted meaning
 upper set bound may be set to smaller number than lower bound.
 */

public static func random(_ from: CGFloat = 0, to: CGFloat = 1.0) -> CGFloat

Example usage:

print(random())
print(random(3.0, to: 4.5))
print(random(2.0, to: 0.0))

can result in

> ~0.76
> ~3.78
> ~1.15

Similarly, there are other random generators in this module:

public static func from(_ range: Range<Int>) -> Int

public static func from(_ from: Int, to: Int) -> Int

public static func alphanumericCharacter() -> Character

public static func alphanumericString(withLength length: Int) -> String

TimeInterval module

/**
 Creates an FiveTimeInterval object by summing up amounts of different time units.
 */

public init(weeks: Int = 0, days: Int = 0, hours: Int = 0, minutes: Int = 0, seconds: Double = 0)

Example usage:

let timeInterval = TimeInterval(weeks: 0, days: 0, hours: 0, minutes: 2)
print(timeInterval.totalSeconds)
print(timeInterval.totalMinutes)

results in

> 120
> 2

Array+Five module

/*
 Allows for returning of 'nil' values in case a specified index is out of bounds.
 */

public subscript(safe index: Int) -> Element?

Example usage:

let dummyArray = [1, 2, 3, 4, 5]
print(dummyArray[safe: 1])
print(dummyArray[safe: 13])

results in

> 2
> nil
/**
 Returns a random element.
 */    

public func randomElement() -> Element

Example usage:

let dummyArray = [1, 2, 3, 4, 5]
print(dummyArray.randomElement())

can result in

> 4

The following two are related to archiving an array via NSKeyedArchiver/Unarchiver.

/**
 Archives the array into user defaults.
 */

public func archive(_ key: String)

/**
 Tries to unarchive the array. If unsuccessfull, returns nil.
 */    

public static func unarchive(_ key: String) -> Array?

Example usage:

let key = "archiveKey"
let dummyArray = [1, 2, 3, 4, 5]

dummyArray.archive(key)
guard let unarchivedArray = Array<Int>.unarchive(key) else {
    assertionFailure("This should not happen.")
}
print(unarchivedArray == dummyArray)

results in

> true

Int+Five module

/**
 Returns a string that represents this integer as an ordinal number, e.g. "1st" for 1, "2nd" for 2 etc.
*/

public var ordinalString: String

Example usage:

print(1.ordinalString)
print(2.ordinalString)
print(3.ordinalString)
print(4.ordinalString)
print(92.ordinalString)

results in

> 1st
> 2nd
> 3rd
> 4th
> 92nd

Authors

Five Utils library team (listed alphabetically)

  • Denis Mendica

  • Kristijan Rožanković

  • Miran Brajsa

  • Niko Mikuličić

License

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

Latest podspec

{
    "name": "FiveUtils",
    "version": "1.1.0",
    "summary": "Five's commonly used iOS utility modules.",
    "description": "A collection of various math extensions, random generators and other utility modules we tend to re-use onnour projects at Five (http://five.agency).",
    "homepage": "https://github.com/fiveagency/ios-five-utils",
    "license": {
        "type": "MIT",
        "file": "LICENSE"
    },
    "authors": {
        "iOS libraries team": "[email protected]"
    },
    "source": {
        "git": "https://github.com/fiveagency/ios-five-utils.git",
        "tag": "1.1.0"
    },
    "platforms": {
        "ios": "8.0",
        "osx": "10.10"
    },
    "source_files": "Sources/**/*",
    "pushed_with_swift_version": "3.0"
}

Pin It on Pinterest

Share This