test and document date comparisons

diff --git a/doc/antora/modules/installation/pages/upgrade.adoc b/doc/antora/modules/installation/pages/upgrade.adoc
index 017c912c62301bbc70e894ae8621b3a915b2b6bc..41b136cb8daa7d0fc2b1184521241f540fd160b8 100644 (file)
--- a/doc/antora/modules/installation/pages/upgrade.adoc
+++ b/doc/antora/modules/installation/pages/upgrade.adoc
@@ -1051,6 +1051,23 @@ The attributes `Time-Of-Day`, `Login-Time`, and `Current-Time` have
 also been removed.  Any configuration which tries to use them will
 result in an error.
 
+Dates and time attributes can be checked against date strings by
+casting them:
+
+```
+if (&Date-attribute < (date) 'Aug 1 2023 01:02:03 UTC') {
+       ...
+}
+```
+
+The current time can also be checked:
+
+```
+if (%time() < (date) 'Aug 1 2023 01:02:03 UTC') {
+       ...
+}
+```
+
 == Deleted Functionality
 
 Many "virtual" or "fake" attributes have been removed or renamed.

diff --git a/doc/antora/modules/reference/pages/xlat/builtin.adoc b/doc/antora/modules/reference/pages/xlat/builtin.adoc
index a467d51918a3bd0761fb1101d4efd4bc9c008d85..27bd14127498e0b9b5cbd9f320d9aff08059f6e2 100644 (file)
--- a/doc/antora/modules/reference/pages/xlat/builtin.adoc
+++ b/doc/antora/modules/reference/pages/xlat/builtin.adoc
@@ -215,6 +215,22 @@ If no argument is passed, it returns the current time.  Otherwise if the argumen
 &Acct-Start-Time := %time(now)
 ----
 
+The current time can also be compared to a known date:
+
+.Example
+[source,unlang]
+----
+if (%time() < (date) 'Aug 1 2023 01:02:03 UTC') {
+       ...
+}
+----
+
+The format of the date strings should be the same format as the server
+prints out.  The parse will try to accept other date formats (raw
+integer, etc.), but not all formats are guaranteed to work.  There are
+hundreds of different date formats used across the world, and the
+server cannot support them all.
+
 [NOTE]
 ====
 This expansion should be used in preference to the xref:xlat/character.adoc[single letter expansions] `%l`.  That expansion returns integer seconds, and is not suitable for millisecond or microsecond resolution.

diff --git a/src/tests/keywords/date b/src/tests/keywords/date
index 370505ab735c84793bd148244e76663420bffcb9..81fbfad4656f9f19154f4fbddb7641cb048710a7 100644 (file)
--- a/src/tests/keywords/date
+++ b/src/tests/keywords/date
@@ -76,4 +76,20 @@ if (!(&Module-Failure-Message == "Can't convert type ipaddr into date")) {
        test_fail
 }
 
+#
+#  Do date comparisons
+#
+if (&test_date != (date) 'Aug  8 2022 19:04:19 UTC') {
+   test_fail
+}
+
+if (&test_date < (date) 'Aug  8 2022 18:00:00 UTC') {
+   test_fail
+}
+
+if (&test_date > (date) 'Aug 9 2022 00:04:19 UTC') {
+   test_fail
+}
+
+
 success