<commit_before>= Intervals

In _tick_, an interval is a span of time defined by two points in time, the first being before the second.

Intervals are maps containing both a `tick/beginning` and a `tick/end` entry. This flexible design allows any Clojure map to be treated as an interval.

Intervals can be represented two local times as well as instants.

== Construction

Obviously, the Clojure's literal syntax for maps can be used to create intervals.

====
Here we use a literal map syntax to construct an interval representing the last 5 minutes of 2018 (in UTC).

[source,clojure]
----
{:tick/beginning "2018-12-31T23:55:00Z"
 :tick/end "2019-01-01T00:00:00Z"}
----

====

Alternatively, we can use the `t/make-interval` function which takes the two boundaries of the interval as its arguments.

====
[source,clojure]
----
(t/make-interval
  (t/instant "2018-12-31T23:55:00Z")
  (t/instant "2019-01-01T00:00:00Z"))
----
====

== Derivation

Dates, months and years can also be considered to be themselves ranges, and can be converted to intervals with the `t/bounds` function.

====
To return today as an interval:

[source.code,clojure]
----
(t/bounds (t/today))
----
====

The arguments to `t/make-interval` do not have to be instants, they can be any time supported by _tick_.

====
To return a 2-day interval spanning midnight this morning to midnight [#eval-two-days-from-today]#two days from today#:
// Calculate the day today plus 2 days

[source.code,clojure]
----
(t/make-interval (t/today) (t/tomorrow))
----
====

== Comparison

Two intervals can be compared against each other with the `t/relation` function. link:https://en.wikipedia.org/wiki/Allen%27s_interval_algebra[Allen's interval algebra] tells us there are 13 possible relations between two intervals.

.Interval relations
====
Consider the time-span represented by the word 'yesterday' and compare it to the time-span represented by the word 'tomorrow'. Since yesterday is before tomorrow, with a gap between them, we say that yesterday _precedes_ tomorrow:

[source.code#relation-yesterday-tomorrow,clojure]
----
(t/relation (t/yesterday) (t/tomorrow))
----

If the two intervals touch each other, in the case of 'today' and 'tomorrow', then we say the first interval (today) _meets_ the second interval (tomorrow).

[source.code#relation-today-tomorrow,clojure]
----<commit_msg>update interval docs for new fn names<commit_after>= Intervals

In _tick_, an interval is a span of time defined by two points in time, the first being before the second.

Intervals are maps containing both a `tick/beginning` and a `tick/end` entry. This flexible design allows any Clojure map to be treated as an interval.

Intervals can be represented two local times as well as instants.

== Construction

Obviously, the Clojure's literal syntax for maps can be used to create intervals.

====
Here we use a literal map syntax to construct an interval representing the last 5 minutes of 2018 (in UTC).

[source,clojure]
----
{:tick/beginning "2018-12-31T23:55:00Z"
 :tick/end "2019-01-01T00:00:00Z"}
----

====

Alternatively, we can use the `t/new-interval` function which takes the two boundaries of the interval as its arguments.

====
[source,clojure]
----
(t/new-interval
  (t/instant "2018-12-31T23:55:00Z")
  (t/instant "2019-01-01T00:00:00Z"))
----
====

== Derivation

Dates, months and years can also be considered to be themselves ranges, and can be converted to intervals with the `t/bounds` function.

====
To return today as an interval:

[source.code,clojure]
----
(t/bounds (t/today))
----
====

The arguments to `t/new-interval` do not have to be instants, they can be any time supported by _tick_.

====
To return a 2-day interval spanning midnight this morning to midnight [#eval-two-days-from-today]#two days from today#:
// Calculate the day today plus 2 days

[source.code,clojure]
----
(t/new-interval (t/today) (t/tomorrow))
----
====

== Comparison

Two intervals can be compared against each other with the `t/relation` function. link:https://en.wikipedia.org/wiki/Allen%27s_interval_algebra[Allen's interval algebra] tells us there are 13 possible relations between two intervals.

.Interval relations
====
Consider the time-span represented by the word 'yesterday' and compare it to the time-span represented by the word 'tomorrow'. Since yesterday is before tomorrow, with a gap between them, we say that yesterday _precedes_ tomorrow:

[source.code#relation-yesterday-tomorrow,clojure]
----
(t/relation (t/yesterday) (t/tomorrow))
----

If the two intervals touch each other, in the case of 'today' and 'tomorrow', then we say the first interval (today) _meets_ the second interval (tomorrow).

[source.code#relation-today-tomorrow,clojure]
----
{'fraction_non_alphanumeric': 0.11486486486486487, 'fraction_numerical': 0.028293918918918918, 'mean_word_length': 4.177049180327868, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7348492', 'n_tokens_mistral': 1538, 'n_tokens_neox': 1402, 'n_words': 588}