Natural Language Date Parsing (with SoulverCore)

SoulverCore's flexible & powerful date parser can be used to add a natural language date scheduling feature to your Mac or iOS calendar or reminders app.

Natural language date input features can be found in apps like Things, Fantastical and Raycast and make the user experience better.

Usage

The SoulverCore framework adds the dateValue & dateInterval properties to String:

public extension String {
   var dateValue: Date?
   var dateIntervalValue: DateInterval?
}

Use these properties to extract the last natural language date or date interval found in the string.

The dateValue property extracts single dates, while dateIntervalValue extracts date ranges like "March 12 - 15" or "next Monday to Wednesday".

Installation

You can add SoulverCore to your project via the Swift Package Manager.

See the main SoulverCore repository for installation instructions.

Requirements

• Xcode 14+
• Swift 5.7+

SoulverCore vs Foundation's DataDetector

Apple's Foundation framework includes NSDataDetector for detecting dates in strings.

Here is an example:

let expression = "March 5th, 2023"
let types: NSTextCheckingResult.CheckingType = [.date ]
let detector = try! NSDataDetector(types: types.rawValue)
let match = detector.matches(in: expression, options: .init(rawValue: 0), range: NSRange(location: 0, length: expression.count)).first
let date = match?.date

Compare this to SoulverCore:

let date = "March 5th, 2023".dateValue

In addition to a much nicer API, SoulverCore also adds a number of additional features not supported by NSDataDetector.

Supported Features

Natural language calendar math

Use natural language phrases like 3 weeks from tomorrow and march 12 + 4 weeks 3 days.

SoulverCore supports a large range of different natural language date syntaxes. See the Soulver Documentation for more examples.

Date intervals

SoulverCore can parse date ranges and intervals using natural language:

• "March 12 - 15" (March 12th to March 15th)
• "next Monday to Wednesday"
• "July 4th through July 10th"

Units & unit shorthands

SoulverCore interprets units of time as referring to a future date after the specified amount of time has passed.

For example 2 weeks 2 days will be interpreted as 2 weeks and 2 days from now.

The following time unit shorthands are also supported:

• "1y" (1 year)
• "5mo" (5 months)
• "3w" (3 weeks)
• "2d" (2 days)

Shorthands can be combined together:

• "12-9 9p" means the "12th of September at 9pm" (in a non-US locale)

Half-formed dates

Examples:

• "3/12" (Dec 3, or March 12 in the US)
• "12.2" (Feb 12 or Dec 2 in the US)
• "9-5" (May 9 or Sep 5 in the US)

Day & month shorthands

Examples:

• "Next mon" (next monday)
• "tod" (today)
• "apr3" (April 3)
• "yes" (yesterday)
• "tom" (tomorrow)

AM/PM shorthands

Examples:

• "3p" (3pm)
• "5a" (5am)

Random words ignored

SoulverCore extracts the last date present in the given string, and ignores random words before and after it.

For example, the following are valid inputs:

• "Tom's birthday party this sunday"
• "Schedule the meeting for April 21st next year"
• "June 5 the kids get off school"

Sample Project

This repository includes a sample example SwiftUI app that shows how to build a natural language date input feature using SoulverCore:

Performance

SoulverCore is very efficient and can perform thousands of date-from-string extractions every second.

Localizations

In addition to English, SoulverCore is localized into German, French, Spanish, Russian & Simplified Chinese. The user's system locale will be used for date parsing, and date & time formats specific the particular region are taken into account.

Licence

SoulverCore is a commercially licensable, closed-source Swift framework. The standard licensing terms of SoulverCore do apply for its use in natural language date parsing (see SoulverCore Licence). For personal (non-commercial) projects, you do not need a license. So go ahead and use this great library in your personal projects! There are also attribution-only licences available for a few commercial use cases.