Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/davdroman/periodduration
The ISO 8601 period/duration APIs missing in Foundation
https://github.com/davdroman/periodduration
Last synced: 3 months ago
JSON representation
The ISO 8601 period/duration APIs missing in Foundation
- Host: GitHub
- URL: https://github.com/davdroman/periodduration
- Owner: davdroman
- License: unlicense
- Created: 2021-09-20T19:40:14.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2023-09-24T17:47:22.000Z (over 1 year ago)
- Last Synced: 2024-10-13T14:47:05.905Z (3 months ago)
- Language: Swift
- Homepage:
- Size: 112 KB
- Stars: 30
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# PeriodDuration
[](https://github.com/davdroman/PeriodDuration/actions/workflows/ci.yml)
[](https://swiftpackageindex.com/davdroman/PeriodDuration)
[](https://swiftpackageindex.com/davdroman/PeriodDuration)
This library introduces a close equivalent to [Java's PeriodDuration](https://www.threeten.org/threeten-extra/apidocs/org.threeten.extra/org/threeten/extra/PeriodDuration.html), motivated by the lack of support for this standard in Foundation.
`PeriodDuration` is based off of a [previous library](https://github.com/treatwell/ISO8601PeriodDuration) I worked on, however it goes beyond simple serialization by introducing dedicated types with full ISO 8601 compliant `Codable` support.
## Usage
Available types: `Period`, `Duration` and `PeriodDuration`.
### Period
[ISO 8601](https://en.wikipedia.org/wiki/ISO_8601#Durations) defines a "Period" as a combination of _years_, _months_, and _days_ elapsed. Periods **do not** include _hours_, _minutes_ or _seconds_.
```swift
Period(years: 3, months: 1, days: 5) // = "P3Y1M5D"
```
### Duration
[ISO 8601](https://en.wikipedia.org/wiki/ISO_8601#Durations) defines a "Duration" as a combination of _hours_, _minutes_ or _seconds_ elapsed. Durations **do not** include _years_, _months_, and _days_.
```swift
Duration(hours: 2, minutes: 5, seconds: 0) // = "PT2H5M0S"
```
### PeriodDuration
`PeriodDuration` is a combinations of _years_, _months_, _days_, _hours_, _minutes_ and _seconds_ elapsed. As a type, it holds both a `Period` and a `Duration` instance within it to represent all of these values.
```swift
PeriodDuration(years: 3, months: 1, days: 5, hours: 2, minutes: 5, seconds: 0) // = "P3Y1M5DT2H5M0S"
```
### Conversion to DateComponents
All three types provided allow for easy conversion into the built-in `DateComponents` type in Foundation.
```swift
let dateComponents: DateComponents = Period(years: 3, months: 1, days: 5).asDateComponents
```
This allows for a number of handy things. Namely:
- Date manipulation: adding periods/durations to `Date` instances via [`Calendar.date(byAdding:to:wrappingComponents:)`](https://developer.apple.com/documentation/foundation/calendar/2293676-date/).
- Human-readable formatting via [`DateComponentsFormatter`](https://developer.apple.com/documentation/foundation/datecomponentsformatter).
## Benchmarks
```
MacBook Pro (14-inch, 2021)
Apple M1 Pro (10 cores, 8 performance and 2 efficiency)
32 GB Memory
$ swift run -c release Benchmarks
name time std iterations
------------------------------------------------------
parse PeriodDuration 1041.000 ns ± 26.34 % 1000000
print PeriodDuration 1291.000 ns ± 12.34 % 1000000
parse Period 1333.000 ns ± 13.65 % 1000000
print Period 666.000 ns ± 38.67 % 1000000
parse Duration 1041.000 ns ± 33.51 % 1000000
print Duration 666.000 ns ± 16.86 % 1000000
```