Data Formatting
Relevant source files
The following files were used as context for generating this wiki page:
- Sources/SwiftDitherKit/DitherFormatting.swift
- Sources/SwiftDitherKit/DitherTypes.swift
- Sources/SwiftDitherKit/DitherCartesianCharts.swift
- Sources/SwiftDitherKit/DitherChartChrome.swift
- Tests/SwiftDitherKitTests/DitherValueAndAccessibilityTests.swift
- Sources/SwiftDitherKit/DitherRadarAccessibility.swift
Data formatting in SwiftDitherKit is a unified system designed to transform raw numeric values into localized, human-readable strings across all user-facing components. This includes chart axes, tooltips, and accessibility descriptors. The system ensures that data presentation remains consistent whether it is being viewed visually or read by assistive technologies.
The core of this system is the DitherValueFormat enumeration, which leverages Foundation's formatting APIs to handle complex requirements such as compact notation, currency localization, and percentage calculations. By centralizing formatting logic, the library maintains synchronization between visual labels and the semantic data exposed via Apple's chart accessibility APIs.
Value Formatting Architecture
The formatting architecture follows a top-down flow where formatting options are defined at the chart configuration level and propagated to specialized rendering components.
The DitherValueFormat Enum
The DitherValueFormat enum defines five distinct formatting presets. It contains a central function string(_:locale:) that converts a Double into a string based on the selected case and the provided Locale.
The system explicitly handles non-finite values (NaN or infinity) by treating them as zero during the formatting process to prevent runtime crashes or nonsensical UI labels.
Sources: Sources/SwiftDitherKit/DitherFormatting.swift:4-60
Formatting Options
The following table summarizes the available formatting presets and their behavior:
| Preset | Description | Example (en_US) |
|---|---|---|
automatic | Uses compact notation for values ≥ 1,000; otherwise uses up to 2 decimal places. | 1.2K or 123.45 |
number | Standard numeric formatting with configurable maximum fractional digits. | 1,234.56 |
compact | Forces compact notation (e.g., K, M, B) with 1 decimal place. | 1.2K |
percent | Formats values as percentages where 1.0 equals 100%. | 25% |
currency | Formats values based on an ISO 4217 currency code. | $12.50 |
Sources: Sources/SwiftDitherKit/DitherFormatting.swift:6-10, Tests/SwiftDitherKitTests/DitherValueAndAccessibilityTests.swift:23-41
Integration with UI Components
Formatting is applied across three primary areas: the chart chrome (axes), the interactive tooltip, and the accessibility layer.
Axis and Chrome Formatting
In Cartesian charts, DitherCartesianChrome utilizes the valueFormat to generate labels for the Y-axis ticks. The DitherLinearScale calculates the numeric tick values, which are then passed through the formatter before being rendered in the UI.
Tooltip Formatting
When a user interacts with a chart via scrubbing or hovering, the DitherTooltip displays the exact value of the data point. It receives the valueFormat and the current Locale from the environment to ensure the displayed value matches the axis formatting.
Sources: Sources/SwiftDitherKit/DitherChartChrome.swift:148, Sources/SwiftDitherKit/DitherCartesianCharts.swift:386-405
Accessibility and Semantic Data
Formatting is critical for accessibility. Descriptors such as AXNumericDataAxisDescriptor use the valueFormat to provide localized descriptions of data points to VoiceOver. This ensures that a value represented as "$12.50" on the axis is also announced as "12 dollars and 50 cents" (or the local equivalent) by assistive technology.
Data Input and Pre-formatting
Before data reaches the formatting layer, it is structured using the DitherDatum and DitherSlice types. These structures enforce basic data integrity.
- DitherDatum: Represents a category (X-axis) and a dictionary of series values. It uses a subscript that defaults missing or non-finite values to
0. - DitherSlice: Represents a single segment in a polar chart (Pie/Donut). Like
DitherDatum, it treats non-finite values as zero during rendering.
Sources: Sources/SwiftDitherKit/DitherTypes.swift:85-104, Sources/SwiftDitherKit/DitherTypes.swift:126-146
Summary of Configuration
The formatting behavior is governed by DitherCartesianOptions and DitherPolarOptions. Developers configure the valueFormat property during chart initialization.
| Option | Type | Default | Description |
|---|---|---|---|
valueFormat | DitherValueFormat | .automatic | The preset used for all numeric to string conversions. |
accessibility | DitherAccessibility | DitherAccessibility() | Localized semantic labels for axes and titles. |
Sources: Sources/SwiftDitherKit/DitherCartesianCharts.swift:34-36, Sources/SwiftDitherKit/DitherAccessibility.swift:2-22
Data formatting in SwiftDitherKit bridges the gap between raw numeric data and a localized user experience. By utilizing the DitherValueFormat abstraction, the library ensures that complex formatting logic is handled consistently across visual rendering, interactive overlays, and accessibility services.