sindresorhus / percentage

A percentage type for Swift

Percentage

A percentage type for Swift

Makes percentages more readable and type-safe, for example, for APIs that currently accept a fraction Double.

-.opacity(0.45)
+.opacity(45%)

Install

Add the following to Package.swift:

.package(url: "https://github.com/sindresorhus/Percentage", from: "1.2.0")

Or add the package in Xcode.

Usage

See the source for docs.

import Percentage

10% + 5.5%
//=> 15.5%

-10% / 2
//=> -5%

(40% + 93%) * 3
//=> 399%

50% * 50%
//=> 25%

30% > 25%
//=> true

50%.of(200)
//=> 100

Percentage(50)
//=> 50%

Percentage(fraction: 0.5)
//=> 50%

50%.fraction
//=> 0.5

10%.rawValue
//=> 10

110%.clampedZeroToHundred
//=> 100%

print("\(1%)")
//=> "1%"

Percent.random(in: 10%...20%)
//=> "14.3%"

The type conforms to Hashable, Codable, RawRepresentable, Comparable, ExpressibleByFloatLiteral, ExpressibleByIntegerLiteral, Numeric, and supports all the arithmetic operators.

Codable

The percentage value is encoded as a single value:

struct Foo: Codable {
	let alpha: Percentage
}

let foo = Foo(alpha: 1%)
let data = try! JSONEncoder().encode(foo)
let string = String(data: data, encoding: .utf8)!

print(string)
//=> "{\"alpha\":1}"

FAQ

Can you support Carthage and CocoaPods?

No, but you can still use Swift Package Manager for this package even though you mainly use Carthage or CocoaPods.

Related

• Regex - Swifty regular expressions
• Defaults - Swifty and modern UserDefaults
• Preferences - Add a preferences window to your macOS app
• KeyboardShortcuts - Add user-customizable global keyboard shortcuts to your macOS app
• LaunchAtLogin - Add "Launch at Login" functionality to your macOS app
• More…

percentage's Issues

Store it internally as `Decimal`

It would allow us to store bigger values with more precision. We would also accept a Decimal and add arithmetics overloads for it.

I don't intend to do this yet if at all as Decimal has and still is very buggy:

• JSONDecoder Decimal precision error
• Decimal initialized with Double loses precision

Even though I don't plan to do this yet, I'm still looking for feedback on whether it makes sense at all.

Build error: "Use of undeclared type 'CGFloat'"

Just tried pulling this into a new Xcode 11.1 project using the GUI SPM flow, and got this build error.

Adding

import CoreGraphics

at the top of Percent.swift fixed it for me. Happy to submit a PR if you want it!

Feedback

Is this a good idea? Any downsides with such a type? Would it make sense to propose adding this kind of type to Swift itself?

Add overloads for Swift and Cocoa APIs?

Would be nice to be able to use this with Swift/Cocoa APIs that accept a fraction Double.

For example:

• https://developer.apple.com/documentation/uikit/uicolor/1621922-withalphacomponent
• https://developer.apple.com/documentation/appkit/nscolor/1526906-withalphacomponent
• https://developer.apple.com/documentation/swiftui/color/3049763-opacity
• https://developer.apple.com/documentation/swiftui/hstack/3269261-opacity
• https://developer.apple.com/documentation/swiftui/hstack/3269155-brightness
• https://developer.apple.com/documentation/swiftui/hstack/3269164-contrast
• https://developer.apple.com/documentation/swiftui/hstack/3269293-saturation
• https://developer.apple.com/documentation/swiftui/hstack/3269207-grayscale

Does this make sense?

I couldn't use this library on Xcode Cloud

I couldn't use this library on Xcode Cloud because below error occurred.

Conform to `BinaryFloatingPoint` instead of `Numeric`

Since we're just a Double anyway.

Then we could remove #9 as we would get all those methods for free.

Codable Implementation

Hey Sindre, this is a cool library! If I'm reading the source code correctly, suppose I had the following struct:

struct SomeObject: Codable {
    let alpha: Percent
}

That object would be encoded as below (and require the below JSON to decode):

{
    alpha: {
        rawValue: 10
    }
}

it may be a nice enhancement to override the default Encodable/Decodable implementations to parse that struct as:

{
    alpha: 0.1
}

I feel this is more likely what you'd get from an API. Up to you whether you want to keep the implementation as is, entirely change it to the above, or maybe provide some static variable to allow users to choose which Codable representation they want.

Conform it to `Numeric`?

Not sure whether there are any downsides with doing that, but would be nice if Percentage could be used with generic numeric methods.

https://developer.apple.com/documentation/swift/numeric

Add more useful properties

Some ideas:

• .clampedZeroToHundred which clamps the percentage to 0...100.
• Percent.from(100, of: 200) //=> 50%
• Find the original value before a percent increase. E.g. If a value is 120 after a 40% increase, what is the original value before the increase?
• Find the original value before a percent decrease. E.g. If a value is 106 after a 12% decrease, what is the original value before the decrease?
• "x IS y% OF". E.g. 67 is 90% of what?

What else?