search

othyn / DateStrings

A Swift 5 Date extension library that adds helpful string accessors and a string based initialiser. With new methods and properties that make getting a string from a Date easy.
MIT License
7 stars 2 forks source link
date extension extensions helper helpers ios ios-swift libraries library package string swift swift-package swift-package-manager swift5

readme

🗓 DateStrings

Build and Tests Code Coverage GitHub issues GitHub forks GitHub stars GitHub license Quote Love

A Swift 5 Date extension library that adds helpful string accessors and a string based initialiser. With new methods and properties that make getting a string from a Date easy.

Locale can be handled automatically (if not provided it's handled by the device) or manually (to ensure all devices present the same locale format).

Table of contents

Installation

This is Swift 5 package and makes use of Swift Package Manager (SPM) to integrate it into your Swift project.

Swift Swift Swift.

Adding via Xcode

Add the package via the following menu's whilst in your Xcode project:

File > Swift Packages > Add Package Dependency...

Paste this git repo URL into the search bar at the top:

https://github.com/othyn/DateStrings.git

Press the enter key or Next and for the rules, if not automatically selected, select Version as Up to Next Major: 1.0.0 < 2.0.0.

Hit Finish once Xcode has downloaded and initialised the package to add it to your project.

Adding via SPM Manually

Add the following as a dependency to your Package.swift within your project directory:

.package(url: "https://github.com/othyn/DateStrings.git", .upToNextMajor(from: "1.0.0"))

After specifying "DateStrings" as a dependency of the target in which you want to use it, run swift package update.

Importing The Library Into Your Project

Add import DateStrings to the top of the file you wish to use the library in.

This package is an extension to the base Date object, with all methods and properties accessible via any inherited objects or the Date object itself.

Usage

Initialiser

There is a new initialiser that allows for quickly initialising a Date object from a date string. You can provide a custom format for the string.

By default, the locale will be the locale of the device that the app is being run on. You can stop this by passing a fixed locale string to the method as the locale parameter.

init(fromString dateString: String, format: String = "yyyy-MM-dd", locale: String? = nil) { ... }

This allows for the following to be used to create a Date instance object from a string.

let date = Date(fromString: "2007-06-29")

This also allows for passing in a custom format and/or a locale.

let date = Date(fromString: "2007-06-29 23:49:59", format: "yyyy-MM-dd HH:mm:ss", locale: "en_US_POSIX")

asString

This method allows you to get the date in a format of your choosing, from a DateFormatter.Style or a custom provided format and/or locale.

By default, the locale will be the locale of the device that the app is being run on. You can stop this by passing a fixed locale string to the method as the locale parameter.

func asString(inStyle style: DateFormatter.Style, locale: String? = nil) -> String { ... }

func asString(inFormat format: String, locale: String? = nil) -> String { ... }

An example of the inStyle usage:

let date = Date(fromString: "2007-06-29")

let dateFullString = date.asString(inStyle: .full)

...

Text(dateFullString) // Friday, June 29, 2007

An example of the inFormat usage:

let date = Date(fromString: "2007-06-29 23:49:59", format: "yyyy-MM-dd HH:mm:ss")

let dateCustomString = date.asString(inFormat: "yyyy-MM-dd HH:mm:ss")

...

Text(dateCustomString) // 2007-06-29 23:49:59

toString

There is also an alternative syntax toString, which mirrors the asString methods exactly (uses them internally too, just maps the functions forward). Just a personal preference of naming on this one. As in, use it if you prefer the toString method names.

An example of the inStyle usage:

let date = Date(fromString: "2007-06-29")

let dateFullString = date.toString(inStyle: .full)

...

Text(dateFullString) // Friday, June 29, 2007

An example of the inFormat usage:

let date = Date(fromString: "2007-06-29 23:49:59", format: "yyyy-MM-dd HH:mm:ss")

let dateCustomString = date.toString(inFormat: "yyyy-MM-dd HH:mm:ss")

...

Text(dateCustomString) // 2007-06-29 23:49:59

day

A helpful computed property for getting the day from the Date.

let date = Date(fromString: "2007-06-29")

let day = date.day

...

Text(day) // Friday

dayShort

A helpful computed property for getting the short day from the Date.

let date = Date(fromString: "2007-06-29")

let day = date.dayShort

...

Text(day) // Fri

dayAsSingleDigit

A helpful computed property for getting the single digit day from the Date.

let date = Date(fromString: "2007-06-05")

let day = date.dayAsSingleDigit

...

Text(day) // 5

dayAsDoubleDigit

A helpful computed property for getting the double digit day from the Date.

let date = Date(fromString: "2007-06-05")

let day = date.dayAsDoubleDigit

...

Text(day) // 05

month

A helpful computed property for getting the month from the Date.

let date = Date(fromString: "2007-06-29")

let month = date.month

...

Text(month) // June

monthShort

A helpful computed property for getting the short month from the Date.

let date = Date(fromString: "2007-06-29")

let month = date.monthShort

...

Text(month) // Jun

monthAsSingleDigit

A helpful computed property for getting the single digit month from the Date.

let date = Date(fromString: "2007-06-29")

let month = date.monthAsSingleDigit

...

Text(month) // 6

monthAsDoubleDigit

A helpful computed property for getting the double digit month from the Date.

let date = Date(fromString: "2007-06-29")

let month = date.monthAsDoubleDigit

...

Text(month) // 06

year

A helpful computed property for getting the year from the Date.

let date = Date(fromString: "2007-06-29")

let year = date.year

...

Text(year) // 2007

yearShort

A helpful computed property for getting the short year from the Date.

let date = Date(fromString: "2007-06-29")

let year = date.yearShort

...

Text(year) // 07

datestamp

A helpful computed property for getting the datestamp from the Date.

let date = Date(fromString: "2007-06-29 10:00:00", format: "yyyy-MM-dd HH:mm:ss")

let datestamp = date.datestamp

...

Text(datestamp) // 2007-06-29 10:00:00

iso8601Python

A helpful computed property for getting the ISO 8601 Python format from the Date.

let date = Date(fromString: "2007-06-29 10:00:00", format: "yyyy-MM-dd HH:mm:ss")

let iso8601Python = date.iso8601Python

...

Text(iso8601Python) // 2007-06-29T10:00:00.000

Building

To build, use Xcode's standard build tools via ⌘ + B or use the swift CLI command in the project root directory:

swift build

Testing

To run the tests, use Xcode's standard test tools via ⌘ + U or use the swift CLI command in the project root directory:

swift test

Useful Reference Material

Below are some really useful references that I found when building this extension Library to aid with date formatting and converting formats.

Especially as Apple don't really document this themselves anywhere. Although if someone does find it, please submit a PR and correct me.

There is also something to note around how creating NSDateFormatter and DateFormatter are an expensive operation, with Apple even stating so in their 2014 docs. If anyone has any ways to optimise this, I'm all ears. I've tried to be as performant as possible to what I know.

There is also an easter egg in the library for funsies, if you know what to look for.

Changelog

View the repo's releases to see the change history.

Versioning

This project uses Semantic Versioning.