IntegerFormatStyle

struct · iOS 15.0+ · SDK 27.1

struct IntegerFormatStyle<Value> where Value : BinaryInteger

A structure that converts between integer values and their textual representations. Instances of ``IntegerFormatStyle`` create localized, human-readable text from <doc://com.apple.documentation/documentation/swift/binaryinteger> numbers and parse string representations of numbers into instances of <doc://com.apple.documentation/documentation/swift/binaryinteger> types. All of the Swift standard library's integer types, such as <doc://com.apple.documentation/documentation/swift/int> and <doc://com.apple.documentation/documentation/swift/uint32>, conform to <doc://com.apple.documentation/documentation/swift/binaryinteger>, and therefore work with this format style. ``IntegerFormatStyle`` includes two nested types, ``Percent`` and ``Currency``, for working with percentages and currencies. Each format style includes a configuration that determines how it represents numeric values, for things like grouping, displaying signs, and variant presentations like scientific notation. ``IntegerFormatStyle`` and ``Percent`` include a ``NumberFormatStyleConfiguration``, and ``Currency`` includes a ``CurrencyFormatStyleConfiguration``. You can customize numeric formatting for a style by adjusting its backing configuration. The system automatically caches unique configurations of a format style to enhance performance. > Note: > Foundation provides another format style type, ``FloatingPointFormatStyle``, for working with numbers that conform to <doc://com.apple.documentation/documentation/swift/binaryfloatingpoint>. For Foundation's ``Decimal`` type, use ``Decimal/FormatStyle``. ### Formatting integers Use the <doc://com.apple.documentation/documentation/swift/binaryinteger/formatted()> method to create a string representation of an integer using the default ``IntegerFormatStyle`` configuration. ```swift let formattedDefault = 123456.formatted() // formattedDefault is "123,456" in en_US locale. // Other locales may use different separator and grouping behavior. ``` You can specify a format style by providing an argument to the <doc://com.apple.documentation/documentation/swift/binaryinteger/formatted(_:)-73k3e> method. The following example shows the number `12345` represented in each of the available styles, in the `en_US` locale: ```swift let number = 123456 let formattedNumber = number.formatted(.number) // formattedNumber is "123,456". let formattedPercent = number.formatted(.percent) // formattedPercent is "123,456%". let formattedCurrency = number.formatted(.currency(code: "USD")) // formattedCurrency is "$123,456.00". ``` Each style provides methods for updating its numeric configuration, including the number of significant digits, grouping length, and more. You can specify a numeric configuration by calling as many of these methods as you need in any order you choose. The following example shows the same number with default and custom configurations: ```swift let exampleNumber = 123456 let defaultFormatting = exampleNumber.formatted(.number) // defaultFormatting is "125 000" for the "fr_FR" locale // defaultFormatting is "125000" for the "jp_JP" locale // defaultFormatting is "125,000" for the "en_US" locale let customFormatting = exampleNumber.formatted( .number .grouping(.never) .sign(strategy: .always())) // customFormatting is "+123456" ``` ### Creating an integer format style instance The previous examples use static factory methods like ``FormatStyle/number-7fxvo`` to create format styles within the call to the <doc://com.apple.documentation/documentation/swift/binaryinteger/formatted(_:)-73k3e> method. You can also create an ``IntegerFormatStyle`` instance and use it to repeatedly format different values with the ``format(_:)`` method: ```swift let percentFormatStyle = IntegerFormatStyle<Int>.Percent() percentFormatStyle.format(50) // "50%" percentFormatStyle.format(85) // "85%" percentFormatStyle.format(100) // "100%" ``` ### Parsing integers You can use ``IntegerFormatStyle`` to parse strings into integer values. You can define the format style within the type's initializer or pass in a format style you create prior to calling the method, as shown here: ```swift let price = try? Int("$123,456", format: .currency(code: "USD")) // 123456 let priceFormatStyle = IntegerFormatStyle<Int>.Currency(code: "USD") let salePrice = try? Int("$120,000", format: priceFormatStyle) // 120000 ``` ### Matching regular expressions Along with parsing numeric values in strings, you can use the Swift regular expression domain-specific language to match and capture numeric substrings. The following example defines a currency format style to match and capture a currency value using US dollars and `en_US` numeric conventions. The rest of the regular expression ignores any characters prior to a `": "` sequence that precedes the currency substring. ```swift import RegexBuilder let source = "Payment due: $123,456" let matcher = Regex { OneOrMore(.any) ": " Capture { One(.localizedIntegerCurrency(code: Locale.Currency("USD"), locale: Locale(identifier: "en_US"))) } } let match = source.firstMatch(of: matcher) let localizedInteger = match?.1 // 123456 ```

Members (0)

This type has no directly callable members in this snapshot. See the framework’s skipped declarations for unsupported APIs.

All Foundation types →