strptime function docs

axoflow · Aug 15, 2024 · 200f4a9 · 200f4a9
1 parent 734b382
commit 200f4a9
Show file tree

Hide file tree

Showing 4 changed files with 71 additions and 55 deletions.
diff --git a/content/chapter-parsers/date-parser/date-parser-options/_index.md b/content/chapter-parsers/date-parser/date-parser-options/_index.md
@@ -16,60 +16,7 @@ The `date-parser()` parser has the following options.
 
 *Description:* Specifies the format how {{% param "product.abbrev" %}} should parse the date. You can use the following format elements:
 
-```shell
-   %%      PERCENT
-    %a      day of the week, abbreviated
-    %A      day of the week
-    %b      month abbr
-    %B      month
-    %c      MM/DD/YY HH:MM:SS
-    %C      ctime format: Sat Nov 19 21:05:57 1994
-    %d      numeric day of the month, with leading zeros (eg 01..31)
-    %e      like %d, but a leading zero is replaced by a space (eg  1..31)
-    %f      microseconds, leading 0's, extra digits are silently discarded
-    %D      MM/DD/YY
-    %G      GPS week number (weeks since January 6, 1980)
-    %h      month, abbreviated
-    %H      hour, 24 hour clock, leading 0's)
-    %I      hour, 12 hour clock, leading 0's)
-    %j      day of the year
-    %k      hour
-    %l      hour, 12 hour clock
-    %L      month number, starting with 1
-    %m      month number, starting with 01
-    %M      minute, leading 0's
-    %n      NEWLINE
-    %o      ornate day of month -- "1st", "2nd", "25th", etc.
-    %p      AM or PM
-    %P      am or pm (Yes %p and %P are backwards :)
-    %q      Quarter number, starting with 1
-    %r      time format: 09:05:57 PM
-    %R      time format: 21:05
-    %s      seconds since the Epoch, UCT
-    %S      seconds, leading 0's
-    %t      TAB
-    %T      time format: 21:05:57
-    %U      week number, Sunday as first day of week
-    %w      day of the week, numerically, Sunday == 0
-    %W      week number, Monday as first day of week
-    %x      date format: 11/19/94
-    %X      time format: 21:05:57
-    %y      year (2 digits)
-    %Y      year (4 digits)
-    %Z      timezone in ascii format (for example, PST), or in format -/+0000
-    %z      timezone in ascii format (for example, PST), or in format -/+0000  (Required element)
-```
-
-{{% alert title="Warning" color="warning" %}}
-
-When using the %z and %Z format elements, consider that while %z strictly expects a specified timezone, and triggers a warning if the timezone is not specified, %Z does not trigger a warning if the timezone is not specified.
-
-For further information about the %z and %Z format elements, see the 'DESCRIPTION' section on the [srtptime(3) - NetBSD Manual Pages](https://man.netbsd.org/NetBSD-7.0/i386/strptime.3).
-
-{{% /alert %}}
-
-
-For example, for the date `01/Jan/2016:13:05:05 PST` use the following format string: `format("%d/%b/%Y:%H:%M:%S %Z")`
+{{< include-headless "chunk/date-string-format.md" >}}
 
 {{% include-headless "chunk/example-date-parser.md" %}}
 

diff --git a/content/filterx/_index.md b/content/filterx/_index.md
@@ -323,6 +323,7 @@ Filterx has the following built-in functions.
 - [`json, json_object`]({{< relref "/filterx/function-reference.md#json" >}}): Convert a value into a JSON object.
 - [`json_array`]({{< relref "/filterx/function-reference.md#json-array" >}}): Convert a value into a JSON array.
 - [`string`]({{< relref "/filterx/function-reference.md#string" >}}): Convert a value into a string.
+- [`strptime`]({{< relref "/filterx/function-reference.md#strptime" >}}): Convert a value into datetime.
 - [`unset`]({{< relref "/filterx/function-reference.md#unset" >}})
 - [`upper`]({{< relref "/filterx/function-reference.md#upper" >}}): Converts a string into uppercase characters.
 - [`vars`]({{< relref "/filterx/function-reference.md#vars" >}}): The variables defined in the filterx block.
@@ -333,7 +334,6 @@ Filterx has the following built-in functions.
 - "double"
 - "regexp_search"
 <!-- FIXME update list , I found these in the tests/files -->
-- strptime
 - parse_kv
 - otel_logrecord
 - regexp_subst

diff --git a/content/filterx/function-reference.md b/content/filterx/function-reference.md
@@ -211,8 +211,23 @@ Sometimes you have to explicitly cast values to strings, for example, when you w
 
 ## strptime
 
+Creates a `datetime` object from a string, similarly to the [`date-parser()`]({{< relref "/chapter-parsers/date-parser/_index.md" >}}) The first argument is the string containing the date. The second argument is a format string that specifies how to parse the date string. Optionally, you can specify additional format strings that are applied in order if the previous one doesn't match the date string.
+
 Usage: `strptime(time_str, format_str_1, ..., format_str_N)`
 
+For example:
+
+```shell
+${MESSSAGE} = strptime("2024-04-10T08:09:10Z", "%Y-%m-%dT%H:%M:%S%z");
+```
+<!-- 
+FIXME what happens if none of the format strings match?
+-->
+
+You can use the following elements in the format string:
+
+{{< include-headless "chunk/date-string-format.md" >}}
+
 ## unset
 
 Deletes a variable, a name-value pair, or a key in a complex object (like JSON).

diff --git a/content/headless/chunk/date-string-format.md b/content/headless/chunk/date-string-format.md
@@ -0,0 +1,54 @@
+```shell
+%%      PERCENT
+%a      day of the week, abbreviated
+%A      day of the week
+%b      month abbr
+%B      month
+%c      MM/DD/YY HH:MM:SS
+%C      ctime format: Sat Nov 19 21:05:57 1994
+%d      numeric day of the month, with leading zeros (eg 01..31)
+%e      like %d, but a leading zero is replaced by a space (eg  1..31)
+%f      microseconds, leading 0's, extra digits are silently discarded
+%D      MM/DD/YY
+%G      GPS week number (weeks since January 6, 1980)
+%h      month, abbreviated
+%H      hour, 24 hour clock, leading 0's)
+%I      hour, 12 hour clock, leading 0's)
+%j      day of the year
+%k      hour
+%l      hour, 12 hour clock
+%L      month number, starting with 1
+%m      month number, starting with 01
+%M      minute, leading 0's
+%n      NEWLINE
+%o      ornate day of month -- "1st", "2nd", "25th", etc.
+%p      AM or PM
+%P      am or pm (Yes %p and %P are backwards :)
+%q      Quarter number, starting with 1
+%r      time format: 09:05:57 PM
+%R      time format: 21:05
+%s      seconds since the Epoch, UCT
+%S      seconds, leading 0's
+%t      TAB
+%T      time format: 21:05:57
+%U      week number, Sunday as first day of week
+%w      day of the week, numerically, Sunday == 0
+%W      week number, Monday as first day of week
+%x      date format: 11/19/94
+%X      time format: 21:05:57
+%y      year (2 digits)
+%Y      year (4 digits)
+%Z      timezone in ascii format (for example, PST), or in format -/+0000
+%z      timezone in ascii format (for example, PST), or in format -/+0000  (Required element)
+```
+
+{{% alert title="Warning" color="warning" %}}
+
+When using the %z and %Z format elements, consider that while %z strictly expects a specified timezone, and triggers a warning if the timezone is not specified, %Z does not trigger a warning if the timezone is not specified.
+
+For further information about the %z and %Z format elements, see the 'DESCRIPTION' section on the [srtptime(3) - NetBSD Manual Pages](https://man.netbsd.org/NetBSD-7.0/i386/strptime.3).
+
+{{% /alert %}}
+
+
+For example, for the date `01/Jan/2016:13:05:05 PST` use the following format string: `"%d/%b/%Y:%H:%M:%S %Z"`