currency

Currency Handling Rules

Use these rules for any iOS app that stores, calculates, or displays money.

Non-Negotiables

Store Money As Decimal

Use Decimal for monetary amounts. Never use Double or Float for stored money, model money, or totals.

// BANNED
let price: Double = 9.99

// CORRECT
let price: Decimal = Decimal(string: "9.99")!

Pair Amount With Currency

An amount without a currency is incomplete. Keep amount and currencyCode together in models, DTOs, storage, and view state. Validate currency codes against Locale.commonISOCurrencyCodes or an app-owned wrapper.

Format With Foundation

Never concatenate currency symbols or force two decimal places.

// BANNED
Text("$\(amount)")
String(format: "%.2f", amount)

// CORRECT
Text(amount.formatted(.currency(code: currencyCode)))

Foundation formatting handles symbol position, separators, minor-unit counts, right-to-left layout, and localized digits.

Do Not Sum Across Currencies

Aggregate money per currency unless the product has an explicit, user-visible FX conversion feature. Cross-currency totals must show the conversion source, timestamp, and any unconverted currencies.

User-Entered Prices

For prices entered by the user or extracted from OCR/imports:

• Store Decimal.
• Store ISO 4217 currency code.
• Mark uncertain or invalid parsed currencies for user review.
• Default new entries to Locale.current.currency?.identifier when appropriate.

Banned Patterns

"$\(amount)"
"\(currency)\(amount)"
String(format: "$%.2f", amount)
Double(amountString)
totals.values.reduce(0, +) // when totals include mixed currencies

Preferred Shape

struct Money: Hashable, Codable {
    var amount: Decimal
    var currencyCode: String
}

Expose a single formatting helper, such as money.formatted(locale:), and use it from SwiftUI views instead of formatting inline.