I think I need to change the documentation format

2026-04-22 01:32:05 +00:00
parent b53eb6e4f1
commit 8223dcc6b3
222 changed files with 1932 additions and 39753 deletions
@@ -0,0 +1,55 @@
+:sig
+String time_format_relative(u64 timestamp, String format_very_recent = "", u64 medium_recency_seconds = 0, String format_medium_recent = "", u64 not_recent_seconds = 0, String format_not_recent = "")
+
+:params
+timestamp : Unix timestamp to compare against the current time
+format_very_recent : output format for very recent timestamps, defaults to `just now`
+medium_recency_seconds : cutoff between the very-recent and medium-recent formats, defaults to `90`
+format_medium_recent : output format for medium-recent timestamps, defaults to `%deltaM minutes ago`
+not_recent_seconds : cutoff between the medium-recent and not-recent formats, defaults to `5400`
+format_not_recent : output format for older timestamps, defaults to `%deltaH hours ago`
+return value : a formatted relative-time string
+
+:desc
+Formats a timestamp relative to the current time using the same formatting engine as `time_format_local()` and `time_format_utc()`.
+
+The chosen format depends on the elapsed time:
+- if `now - timestamp` is less than `medium_recency_seconds`, use `format_very_recent`
+- else if it is less than `not_recent_seconds`, use `format_medium_recent`
+- otherwise use `format_not_recent`
+
+The custom relative-time sequences available in all time formatters are:
+
+:pre
+       %deltaS total elapsed seconds between the timestamp and now
+
+       %deltaM total elapsed minutes between the timestamp and now
+
+       %deltaH total elapsed hours between the timestamp and now
+
+       %deltad total elapsed days between the timestamp and now
+
+       %deltam total elapsed 30-day months between the timestamp and now
+
+       %deltaY total elapsed 365-day years between the timestamp and now
+
+:pre
+Default behavior examples:
+
+       time_format_relative(time() - 12)
+       => just now
+
+       time_format_relative(time() - 600)
+       => 10 minutes ago
+
+       time_format_relative(time() - 7200)
+       => 2 hours ago
+
+:see
+>time
+>time_format_local
+>time_format_utc
+
+:related
+**PHP:** `DateTimeImmutable` diff formatting or libraries such as Carbon `diffForHumans()`
+**JavaScript / Node.js:** relative time helpers such as `Intl.RelativeTimeFormat`, `date-fns/formatDistanceToNow`, or Luxon