A lightweight framework for formating text field text as currency

CurrencyText

CurrencyText is a lightweight framework for formating text field text as currency heavy_dollar_sign. It provides an easy to use, and extendable UITextFieldDelegate, that can be plugged to any text field. Yes, no need to use a specific UITextField subclass.

Its main core, the CurrencyFormatter class, can also be used a part from text fields to format any value that can be monetary represented.

If you need to present currency formatted text or allow users to input currency data, CurrencyText is going to help you do it in a highly readable and configurable matter.

Introduction to CurrencyFormatter

CurrencyText is made upon CurrencyFormatter, which is an a wrapper around number formatter with currency number style. It can be used alone or injected into a CurrencyTextFieldDelegate to auto format text field's inputs.

Basic setup

The CurrencyFormatter encapsulates number formatter's currency properties.

Creating a CurrencyFormatter instance is pretty simple; you can use the readable builder pattern approach where the init class require a callback in which the self instance is passed, allowing you to configure your properties by keeping the code clean and readable (Inspired by SwiftRichString):

let formatter = CurrencyFormatter {
  $0.currency = .euro
  // ... set any other attribute
}

let formattedString = formatter.string(from: 30.0) //€30.00

Currency and locale - easily defining formatting style

To define the currency style (symbol, formatting, separators) you must make use of currency and locale properties.
It's important to say that when these are not defined, the current user locale is automatically set, and so is the curency formatting.
For example if the user Locale's is set to pt_BR (indentifier), the amount of 100 would be shown as R$ 100,00. What can be made by setting currency to brazilianReal and locale to portugueseBrazil when needed.

Locale - setting currency's locale

All locales were extracted from jacobbubu - ioslocaleidentifiers

The CurrencyLocale type wraps all available Locale identifiers in an enum type.
Formatter's locale property can be set passing a common system Locale or one of CurrencyLocale's cases, such as .italian, .danish or .chinese.
Note that you can define locale and compose it with a different currency of your choice, what is going to change generally only the currency symbol.

public enum CurrencyLocale: String, LocaleConvertible {
    
    case current = "current"
    case autoUpdating = "currentAutoUpdating"
    
    case afrikaans = "af"
    case afrikaansNamibia = "af_NA"
    case afrikaansSouthAfrica = "af_ZA"
    //...
}

Currency - how to choose a specific currency from it's name

encapsulates the cases of ISO 4217 international standard for currency codes

The Currency type contains the currency codes as enum cases raw values, what makes it easier to set up the formatter with the currency that you want, such as .euro, .dollar, .brazilianReal.

public enum Currency: String {
    case afghani = "AFN",
    algerianDinar = "DZD",
    argentinePeso = "ARS"
    //...
}

Note that defining currency does not always goes as planned, because the most part of the format generally changes accordingly to user locale. For example, setting .euro as currency but with default user locale (Brazil), has the euro's currency symbol with separators and remaining style as used in Brazil.

let formatter = CurrencyFormatter {
  $0.currency = .dollar
  $0.locale = CurrencyLocale.englishUnitedStates
}

let formattedString = formatter.string(from: 30.0) //$30.00

Advanced setup

For those cases where your design requires a custom presentation you are able to heavily customize the formatter.
We can remove decimals, set a maximum allowed value, customize grouping size or even set a hole new currency symbol. It is all up to you.

let formatter = CurrencyFormatter {
  $0.hasDecimals = false
  $0.maxValue = 999999
  $0.groupingSize = 2
  $0.groupingSeparator = ";"
  $0.currencySymbol = "?"
}

let formattedString = formatter.string(from: 100000000) //?99;99;99

The CurrencyTextFieldDelegate - formatting user input as currency

CurrencyTextFieldDelegate is a type that inherits from UITextFieldDelegate, and provide a simple interface to configure how the inputs are configured as currency. It can be used with any UITextField.

Setting your text field to format the inputs

To start formatting user's input as currency, you need to initialize a CurrencyTextFieldDelegate instance passing in a currency formatter configured as you wish, and then set it as the text field's delegate.

let currencyFormatter = CurrencyFormatter()
textFieldDelegate = CurrencyUITextFieldDelegate(formatter: currencyFormatter)
textFieldDelegate.clearsWhenValueIsZero = true

textField.delegate = textFieldDelegate

Just by setting a currency text field delegate object to your text field, with given formatter behavior, the user inputs are going to be formatted as expected.

Using the passthrough delegate

The passthroughDelegate property on a CurrencyTextFieldDelegate instance, can be used to
listen and pottentially handle UITextFieldDelegate events that are sent to CurrencyUITextFieldDelegate.
It can be useful to intercept the delegate calls when e.g. tracking analytics events.

But be aware and make sure the implementation of this object does not wrongly interfere with currency formatting, e.g. by returning false ontextField(textField:shouldChangeCharactersIn:replacementString:) no currency formatting is done.

let currencyTextFieldDelegate = CurrencyUITextFieldDelegate(formatter: currencyFormatter)
currencyTextFieldDelegate.passthroughDelegate = selfTextFieldDelegateListener

textField.delegate = currencyTextFieldDelegate

// all call to `currencyTextFieldDelegate` `UITextField` delegate methods will be forwarded to `selfTextFieldDelegateListener`.

Allowing users to input negative values

If you want your users to be able to input negative values just set textField's keyboardType to .numbersAndPunctuation, so whenever users tap the negative symbol it will be correctly presented and handled.

textField.keyboardType = .numbersAndPunctuation

// users inputs "-3456"
// -R$ 34.56

Properties available via CurrencyFormatter class

The following properties are available:

PROPERTY	TYPE	DESCRIPTION
locale	LocaleConvertible	Locale of the currency
currency	Currency	Currency used to format
currencySymbol	String	String shown as currency symbol
showCurrencySymbol	Bool	Show/hide currency symbol
minValue	Double?	The lowest number allowed as input
maxValue	Double?	The highest number allowed as input
decimalDigits	Int	The number of decimal digits shown
hasDecimals	Bool?	Decimal digits are shown or not
decimalSeparator	String	Text used to separate the decimal digits
currencyCode	String	Currency raw code value
alwaysShowsDecimalSeparator	Bool	Shows decimal separator even when there are no decimal digits
groupingSize	Int	The amount of grouped numbers
secondaryGroupingSize	Int	The amount of grouped numbers after the first group
groupingSeparator	String	String that is shown between groups of numbers
hasGroupingSeparator	Bool	Adds separator between all group of numbers
maxIntegers	Int	Maximum allowed number of integers
maxDigitsCount	Int	Returns the maximum amount of digits (integers + decimals)
zeroSymbol	String	Text shown when string's value is equal zero

Requirements

CurrencyText is compatible with Swift 3.x.
Only iOS 9.0+ is supported.
But there are plans to support other apple OS's soon.

Installation

Swift Package Manager

To install it using Swift Package Manager, just add this repository through Xcode built-in Swift Packages, or by manually adding it to your Package.swift Package's dependencies:

dependencies: [
    .package(url: "https://github.com/marinofelipe/CurrencyText.git", from: "2.1.0")
]

Install via CocoaPods

To integrate CurrencyText into your Xcode project using CocoaPods, specify it in your Podfile:

# Podfile
use_frameworks!

target 'YOUR_TARGET_NAME' do
     pod 'CurrencyText'
end

GitHub

https://github.com/marinofelipe/CurrencyText