diff --git a/pkgdown.yml b/pkgdown.yml index 50f3019..3f620d0 100644 --- a/pkgdown.yml +++ b/pkgdown.yml @@ -2,7 +2,7 @@ pandoc: 2.19.2 pkgdown: 2.0.7 pkgdown_sha: ~ articles: {} -last_built: 2023-05-03T00:43Z +last_built: 2023-07-27T07:01Z urls: reference: https://giperbio.github.io/lubritime/reference article: https://giperbio.github.io/lubritime/articles diff --git a/reference/assign_date.html b/reference/assign_date.html index 76e8e6b..af8eda6 100644 --- a/reference/assign_date.html +++ b/reference/assign_date.html @@ -144,7 +144,7 @@

NA valuesSee also

Other circular time functions: cycle_time(), -shorter_interval()

+shorter_int()

diff --git a/reference/cycle_time.html b/reference/cycle_time.html index ac12f6c..6cbd409 100644 --- a/reference/cycle_time.html +++ b/reference/cycle_time.html @@ -226,7 +226,7 @@

References

See also

Other circular time functions: assign_date(), -shorter_interval()

+shorter_int()

diff --git a/reference/index.html b/reference/index.html index 4bd364e..2d4a5ae 100644 --- a/reference/index.html +++ b/reference/index.html @@ -67,7 +67,7 @@

Circular time

Cycle time objects

-

shorter_interval() longer_interval() shorter_duration() longer_duration()

+

shorter_int() longer_int() shorter_duration() longer_duration()

Find the shorter or longer interval between two hours

diff --git a/reference/shorter_int.html b/reference/shorter_int.html new file mode 100644 index 0000000..3849a7d --- /dev/null +++ b/reference/shorter_int.html @@ -0,0 +1,271 @@ + +Find the shorter or longer interval between two hours — shorter_int • lubritime + + +
+
+ + + +
+
+
+

Find the shorter or longer interval between two hours

+ Source: R/shorter_interval.R + +
+ +
+

[Maturing]

+

shorter_int() returns the shorter interval between two +hms or POSIXt object hours.

+

longer_int() do the inverse of shorter_int(), i.e., returns the +longer interval between two hours.

+

shorter_duration() and longer_duration() return the interval time span +of shorter_int() and longer_int() as +Duration objects.

+
+ +
+ 
shorter_int(x, y)
+
+longer_int(x, y)
+
+shorter_duration(x, y)
+
+longer_duration(x, y)
+
+ +
+

Arguments

+
x, y
+

An hms or POSIXt +object.

+ +
+
+

Value

+ + +

  • For shorter_int() or longer_int(), an +Interval object with the shorter or longer +interval between x and y.

    • +

  • For shorter_duration() or longer_duration(), a +Duration object with the shorter or longer +duration between x and y.

    • +
+
+

Details

+ +
+

The two intervals problem

+ + +

Given two hours, x and y, in a two-day timeline, without date references, +there will be always two possible intervals between them, as illustrated +below.

+

To figure out what interval is the shorter or the longer, +shorter_int() and longer_int() verify two scenarios: 1. When +x comes before y; and 2. when x comes after y. This only works if x +value is smaller than y, therefore, the function will make sure to swap x +and y values if the latter assumption is not true.

+

Because shorter_int() objective is to find the shorter interval, if +x and y are equal, the shorter interval will have a length of 0 hours, +resulting in an interval from x to x. But, if longer_int() is used +instead, the latter condition will return a interval with 24 hours of length +(from x to x + 1 day).

+

In cases when x and y distance themselves by 12 hours, there will be no +shorter or longer interval (they will have equal length). In these cases, +shorter_int() and longer_int() will return the same value +(an interval of 12 hours).

+

             day 1                        day 2
+     x                  y         x                  y
+   06:00              22:00     06:00              22:00
+-----|------------------|---------|------------------|----->
+              16h           8h             16h
+          longer int.  shorter int.   longer int.
+
+              day 1                      day 2
+     y                   x       y                   x
+   13:00               08:00   13:00               08:00
+-----|-------------------|-------|-------------------|----->
+              19h           5h            19h
+          longer int.  shorter int.  longer int.
+
+    x,y             x,y             x,y             x,y
+     x               y               x               y
+   10:00           10:00           10:00           10:00
+-----|---------------|---------------|---------------|----->
+    0h              0h              0h              0h
+            24h             24h             24h
+
+              day 1                      day 2
+     y               x               y               x
+   12:00           00:00           12:00           00:00
+-----|---------------|---------------|---------------|----->
+            12h             12h             12h

+
+ +
+

Base date and timezone

+ + +

shorter_int() and longer_int() use the +Unix epoch (1970-01-01) date as +the start date for creating intervals.

+

The output will always have "UTC" set as timezone. Learn more about +time zones in ?timezone.

+
+ +
+

POSIXt objects

+ + +

POSIXt objects passed as argument to x or y +will be stripped of their dates. Only the time will be considered.

+

Both POSIXct and POSIXlt are +objects that inherits the class POSIXt. Learn more +about it in ?DateTimeClasses.

+
+ +
+

NA values

+ + +

shorter_int() or longer_int() will return an +Interval NA-NA if x or y are NA.

+

shorter_duration() or longer_duration() will return a +Duration NA if x or y are NA.

+
+ +
+
+

See also

+

Other circular time functions: +assign_date(), +cycle_time()

+
+ +
+

Examples

+ 
## Scalar example
+
+x <- hms::parse_hm("23:00")
+y <- hms::parse_hm("01:00")
+
+shorter_int(x, y)
+#> [1] 1970-01-01 23:00:00 UTC--1970-01-02 01:00:00 UTC
+#> [1] 1970-01-01 23:00:00 UTC--1970-01-02 01:00:00 UTC # Expected
+shorter_duration(x, y)
+#> [1] "7200s (~2 hours)"
+#> [1] "7200s (~2 hours)" # Expected
+longer_int(x, y)
+#> [1] 1970-01-01 01:00:00 UTC--1970-01-01 23:00:00 UTC
+#> [1] 1970-01-01 01:00:00 UTC--1970-01-01 23:00:00 UTC # Expected
+longer_duration(x, y)
+#> [1] "79200s (~22 hours)"
+#> [1] "79200s (~22 hours)" # Expected
+
+x <- lubridate::as_datetime("1985-01-15 12:00:00")
+y <- lubridate::as_datetime("2020-09-10 12:00:00")
+
+shorter_int(x, y)
+#> [1] 1970-01-01 12:00:00 UTC--1970-01-01 12:00:00 UTC
+#> [1] 1970-01-01 12:00:00 UTC--1970-01-01 12:00:00 UTC # Expected
+shorter_duration(x, y)
+#> [1] "0s"
+#> [1] "0s" # Expected
+longer_int(x, y)
+#> [1] 1970-01-01 12:00:00 UTC--1970-01-02 12:00:00 UTC
+#> [1] 1970-01-01 12:00:00 UTC--1970-01-02 12:00:00 UTC # Expected
+longer_duration(x, y)
+#> [1] "86400s (~1 days)"
+#> [1] "86400s (~1 days)" # Expected
+
+## Vector example
+
+x <- c(hms::parse_hm("15:30"), hms::parse_hm("21:30"))
+y <- c(hms::parse_hm("19:30"), hms::parse_hm("04:00"))
+
+shorter_int(x, y)
+#> [1] 1970-01-01 15:30:00 UTC--1970-01-01 19:30:00 UTC
+#> [2] 1970-01-01 21:30:00 UTC--1970-01-02 04:00:00 UTC
+#> [1] 1970-01-01 15:30:00 UTC--1970-01-01 19:30:00 UTC # Expected
+#> [2] 1970-01-01 21:30:00 UTC--1970-01-02 04:00:00 UTC # Expected
+shorter_duration(x, y)
+#> [1] "14400s (~4 hours)"   "23400s (~6.5 hours)"
+#> [1] [1] "14400s (~4 hours)"   "23400s (~6.5 hours)" # Expected
+longer_int(x, y)
+#> [1] 1970-01-01 19:30:00 UTC--1970-01-02 15:30:00 UTC
+#> [2] 1970-01-01 04:00:00 UTC--1970-01-01 21:30:00 UTC
+#> [1] 1970-01-01 19:30:00 UTC--1970-01-02 15:30:00 UTC # Expected
+#> [2] 1970-01-01 04:00:00 UTC--1970-01-01 21:30:00 UTC # Expected
+longer_duration(x, y)
+#> [1] "72000s (~20 hours)"   "63000s (~17.5 hours)"
+#> [1] "72000s (~20 hours)"   "63000s (~17.5 hours)" # Expected
+
+
+
+ +
+ + +
+ + + + + + + + diff --git a/sitemap.xml b/sitemap.xml index ea08c8b..21d51bf 100644 --- a/sitemap.xml +++ b/sitemap.xml @@ -40,7 +40,7 @@ https://giperbio.github.io/lubritime/reference/round_time.html - https://giperbio.github.io/lubritime/reference/shorter_interval.html + https://giperbio.github.io/lubritime/reference/shorter_int.html https://giperbio.github.io/lubritime/reference/sum_time.html