help texts for sys "date" and sys "time" are swapped

[fzipp]

The help texts for sys "date" and sys "time" say:

"date":      the current time as a vector of numbers:
               year month day hour minute second
"time":      the current time in Unix format

The actual outputs are exactly the other way around:

sys "date"
Sun Jul 30 00:22:20 CEST 2023

sys "time"
2023 7 30 0 22 35.044431

[fzipp]

As a side note: I am somewhat skeptical whether the textual format is particularly useful in a language primarily designed for calculations. My suggestion would be to have a system function to obtain the value of UnixNano, and perhaps also the option to convert back and forth between this timestamp and the date representation as a numeric vector.

[robpike]

Well that's embarrassing, but of course trivial to fix.

Having a date as a string seems helpful to me, but of course you also have the broken down time. Regardless, your suggestion of a single nanosecond counter sounds worthwhile.

[fzipp]

Having a date as a string seems helpful to me

Then it would be nice to have this functionality for any date, not just the current date. I was thinking of something along these lines:

sys "time"
	1690705612844048000

fmttime sys "time"
	Sun Jul 30 10:26:52 CEST 2023

todate sys "time"
	2023 7 30 10 26 52.844048

totime 2023 7 30 10 26 52.844048
	1690705612844048000
	
diff = (totime 2023 7 31 0 0 0) - sys "time"
diff
	55987155952000

24 60 60 1000 1000 1000 encode diff
	15 33 7 155 952 0	             # read as "15h 33m 7s 155ms 952μs 0ns"

The numeric vector representation would also require a time zone offset.

[robpike]

That's too many new functions. Date formatting is a black hole. I suggest instead that
"T" text sys "ns"
produce the Unix date format. Maybe one new function to go the other way, but I want to think about it more.

[robpike]

commit d6118f9 updates this.

[robpike]

Perhaps encode and decode with a special-purpose LHS is the way to pack and unpack a time integer.

[fzipp]

I like that the base unit is now in seconds.

sys "date" and sys "time" are somewhat redundant since there are now "T" text sys "sec" and "T" encode sys "sec". However, if you think that they are common enough to have their own system functions, then I trust your judgement.

I would expect to find the documentation for "T" primarily in the help texts for text and encode/decode, and only secondarily under sys "help".

A future extension could be adding time zone support, for example, "T:JST" text sys "sec" to get the current time in Japan, but this may not be necessary for now. Edit: I see you already created #135 for that.

[fzipp]

I noticed that I intuitively wrote sys "now" several times instead of sys "sec" while trying it out. The former communicates the intent, while the latter communicates the unit. It's certainly just a matter of getting used to it, but I just wanted to note it as an observation.

[robpike]

I went back and forth on where to document these features, but I agree now. I will put it in both places.
I will also add sys "now" as an undocumented synonym, just for you :)