It'd be nice to add a way for a Clock to notify you about significant time changes, like how clocks chime in the real world.

There are a couple API scenarios to consider:

• starting from a provided Value, notify me every time this Difference has elapsed
• starting from now, notify me every time this SISecond/Difference has elapsed
• starting from now, notify me every time a value matching these DateComponents occurs

There will be some interesting challenges when it comes to clocks that scale time (ie, run slower or faster than real time).

What would you think about changing the method signatures such that as a general rule, all zero-argument methods that return a value were replaced with computed properties? For example, func now() -> Instant would be replaced by var now: Instant. I think this would make code that called those methods significantly more concise and easier to read.

Given the purpose of this library it occurs to me that there's something else you could try to help users with: storing and retrieving future date-time values.

To motivate, I'll refer to this post:

• Storing UTC is not a silver bullet

which recommends that developers "preserve local time, using UTC as derived data to be recomputed" in specific use-cases. (There's HackerNews discussion here; one of the comments points to RFC5545. In particular, take a look at section 3.3.5.)

What I'm thinking is that this library could a) enumerate the different kinds of storage, different kinds of trade-offs; and b) provide appropriate encodings/decodings. Bonus points if the encodings/decodings aren't jut BLOBs—e.g., if they work well in CoreData, JSON, etc.!

The discussion on the Swift Forums brought up some objections to the usage of unsafe in the APIs:

init(region: Region, unsafeDateComponents: DateComponents) throws

struct UnsafeAdjustment<...> {
    // ...
}

The primary objection is that "unsafe" is used exclusively in the standard library to refer to memory safety issues, and that having a method declared with throws is enough indication that something can go wrong.

@belkadan brought up this point:

"Unsafe" is not supposed to mean "has preconditions which are the client's responsibility". In a narrow form, it would be "can break type safety, memory safety, or exhaustivity" (because breaking any one can lead to the others breaking), but if you were to make an argument for a broader form, I would say it would be "may corrupt data if you break the preconditions", which Time's usage is almost the opposite of.

These are all valid points.

I'm open to changing the usage of "Unsafe" in Time, but here are some thoughts to consider:

• Unsafe is used for more than just a name in an initializer parameter; it's also used as the name of a type (currently internal, but will be public): UnsafeAdjustment

• Given the two broad categories of adjustments, using the term Unsafe has been nice, because it has a clear and familiar antonym of Safe. I'd prefer any replacement word to also have a clear antonym, to maintain the strong pairing between "safe" and "unsafe" adjustments.

• Any alternative would ideally be succinct, as dealing with MightPossiblyFailAdjustment in code would be tiresome and aesthetically unpleasing.

• Time is not part of the standard library, thus it is not bound by the standard library's style and conventions.

• "Unsafe" is a term familiar to Swift developers, even beyond the explicit context of "memory safety"

Hey there,

Thank you for this fantastic library!! Quick question that I couldn't find in the docs (hopefully I didn't just miss it).

I need to calculate a date 5 minutes from now in UTC. Here's what I'm doing:

let utc = Clock.system.converting(to: TimeZone(identifier: "UTC")!).thisMinute()
let plusFiveMinutes = (utc + .minutes(5)).firstInstant.date

I'm clear on everything up until .firstInstant.date - that was the only way I could find to pull a Foundation Date out of my addition operation. Does that seem right?

Thank you again!

Motivation

DocC is a fantastic tool that was announced at WWDC 2021, and full support was released with Swift 5.5

Supporting documentation within DocC gives additional capabilities to developers who work with Time to have better symbol linking and usage guides available while offline, and generated to render within Xcode itself.

Changes Made

• Add: Documentation catalog to the Time module
• Add: Documentation articles that copy the text from the existing Documentation/ folder almost verbatim
• Add: Package manifest variant for Swift 5.5 to support DocC symbol production
• Change: Base Package manifest to exclude Documentation catalog

Results

DocC support!

The Absolute.approximateMidPoint and Absolute.range getters seem to call each other. I'm running an app which corroborates this.

In Time/5. Absolute Values/Absolute.swift:

public var range: Range<Instant> {
    let date = approximateMidPoint.date  <--
    ...
}

And in Time/5. Absolute Values/Absolute+Internal.swift:

...
internal var approximateMidPoint: Instant {
    let r = self.range  <--
    ...
}

One simply has to call Absolute(...).range to get a hang and then a crash.

The implementations of these seem to make sense when considered independent of each other, but the fact that they depend on each other recursively is an issue.

I'm not enough of an expert yet on working with Foundation.Date or Time to know quite what to do to split these, but I can at least cobble together some test cases to demonstrate it.

Hi,

I'm looking for a way to check, whether a previous call to my networking api was sent more than 5 minutes ago. I thought trying your project for this would be a nice start. On first launch, there was now call at all so I usually use Foundation.Date.distantPast. I ended with the following code ...

let now = Clock.system.thisMinute()
let lastUpdate = Absolute<Minute>(region: .current, instant: .init(date: .distantPast))

let differenceSinceLastUpdate = now - lastUpdate

guard differenceSinceLastUpdate.minutes > 5 else { return }

... and found that it is ending in an infinite loop in Absolute.range.

Here my questions:

1. Is this the right way to solve my issue?
2. Is this infinite loop a known bug?

Thanks in advance.

Added chimes feature, as per discussion in #18.

Could perhaps use some more unit tests, but I built only what I had tests for (took a stab at TDD).

If a client platform can import Combine, then relevant methods are made available on the Clock interface for observing when specific times or time intervals elapse.

I would like to have more control over the formatting of the absolute value. For example I would like to get the day of the week. I would usually just use "E" as a date format in order to get the first letter of the day of the week. However it appears that Template initialisers are internal and therefore unable to use a custom format. What would you suggest in this scenario?

I have the following code:

let utc = Clock.system.converting(to: TimeZone(identifier: "UTC")!).thisMinute()
let plusFiveMinutes = (utc + .minutes(5)).firstInstant.date

Running it causes the following error to be thrown in Xcode:

(Nothing useful in the console, blocked out because it had sensitive API routes)

Any ideas here? It looks like some kind of possible recursion or stack overflow bug because the entire stack is filled with the two same calls (Value.range.getter and Value.approximateMidPoint.getter) but not positive.

Let me know if there's anything I can do to help debug.

Motivation

LTO* and GTO* prefixed protocols act as markers for conditional conformance clauses, and as such need to be public symbols, but for all intents and purposes they are internal to Time.

This means these types appear in autocompletion as well as have symbol documentation generated in DocC.

Changes Made

• Change: LTO* and GTO* prefixed protocols to be prefixed by _

Results

The swift compiler will "hide" _LTO* and _GTO* symbols for purposes such as DocC and autocompletion while still leaving them public.

Motivation

When determining which Clock value to use, it can be less expressive or easily forgotten to use the Clocks namespace to access the several built-in values.

In Swift 5.5 we gain the ability to provide a leading dot syntax, even when dealing in a protocol context where the concrete type isn't (yet) known.

Changes Made

When developers are building the library with a 5.5 compiler or later, new static extensions on Clock will be available that provide the same values as found on Clocks.

This required making some properties and types public, and changing their names to have a _ prefix to hide them in autocompletion. Their initializers are still internal to disallow outside creation of instances.

Results

Developers will now be able to write the following code:

func someClockContext(_ clock: Clock) { /* ... */ }

someClockContext(.system)
someClockContext(.custom(startingFrom: Clocks.system.thisInstant(), rate: 2.0))

Right now TimeDifference provides concrete Int properties of each unit component of a given difference, which leaves users to implement a way of getting a total of a specific unit.

For example, to find the total number of minutes between two TimePeriods (such as an event with a start/end), you need to do:

difference.hours * 60 + difference.minutes

I'd be appreciative to have an API like the following:

extension TimeDifference {
  func total(_ unit: Calendar.Component) -> Double
}

let diff = start - end // hour: 1 minute: 3

print(diff.total(.minute))
// 63
print(diff.total(.hour))
// 1.05

I understand this can get very problematic at higher & lower precision, maybe a first release could just be seconds/minutes/hours?

Hello, first of all, thank you for all your work on this library.

Apart from that, the title says it all, would be nice to be able to use Template values for raw formatting/parsing. I thought about making a micro PR, but I feared there was a reason for it not being public, besides it's a change so small that you could make trough Github edit.

P.S.: Am I missing something or is it not possible to parse a date with the format y-MM-dd without using the rawFormat? I thought that using the iso8601 Calendar would work, but it does not seem to be the case.

When initialising an Absolute TimePeriod we are seeing very slow performance. It is taking 90ms+ to initialise a time period. Also getting bad performance when trying to add or subtract from time periods. Please see the attached image of the time profile I ran which leads me to the TimePeriod initialiser and the subtracting of time period.