(doc-group time
  «Measuring, manipulating and displaying time.»)

(defdoc (sleep sec)
  «Halt the StreetLISP VM for the specified duration of time in seconds.b»
  :doc-example
  «(sleep 0.1) ; sleep for 100ms»
  :doc-group time)

(defdoc (nanoseconds-monotonic)
  «Return the number of nanoseconds passed since the first call to this
   function.

   The first call will always return 0.»
  :doc-example
  «(nanoseconds-monotonic)
   ; ↳ #u64(0)
   (nanoseconds-monotonic)
   ; ↳ #u64(47840)»
  :doc-group time
  :doc-see time-now)

(defdoc (time-now)
  «Return the number of nanoseconds since Epoch (1970-01-01 00:00:00).

   This measures the system-wide real (wall-clock) time.»
  :doc-example
  «(time-now)
   ; ↳ 1746494461277334928»
  :doc-group time
  :doc-see nanoseconds-monotonic)

(defdoc (time->str sec)
  «Return the number of nanoseconds since Epoch formatted as time and date.

   This is the opposite of `str->time`.»
  :doc-example
  «(time->str (time-now))
   ; ↳ "Tue May  6 03:21:01 CES 2025"»
  :doc-group time
  :doc-see str->time
  :doc-see time-now)

(defdoc (str->time str)
  «Return the number of nanoseconds since Epoch from a time and date
   formatted as a string.

   Because the supported format is limited, the returned value will have
   precision in seconds at most.»
  :doc-example
  «(str->time "Tue May  6 03:21:01 CES 2025")
   ; ↳ 1746494461»
  :doc-group time
  :doc-see time->str
  :doc-see time-now)