Source   Edit  

datetime

bookmark

TLDR

• supports nanosecond resolution, but getTime() depends on platform & backend
• use monotimes when measuring durations with high precision, else cpuTime
• use time Duration when you need units of time, e.g. days/years/etc
• use time TimeInterval when you need to consider timezones in calculations
• all the expected arithmetic operators are available
  • div integer div for durations
  • < > logical stuff works as expected
• durations can be negative; Use abs(a) < abs(b) to compare the absolute duration.
• generally
  • datetimes are singular e.g. month
  • intervals are plural e.g. months

links

• date & times
• mono times
• timezone names, but any unambiguous string can be used

TODOs

• time
  • high, low
  • newTimezone
  • zonedTimeFromAdjTime, zonedTimeFromTime

time

time format strings

• design
  • x atleast 1 digit
  • xx always 2 digits
  • xxx abbreviation
  • xxxx full
  • 'blah' embeds a literal, e.g. yyyy-MM-dd'T'HH:mm:sszzz
• d 1/04/2012 -> 1
• dd 1/04/2012 -> 01
• ddd Saturday -> Sat
• dddd Saturday -> Saturday
• h am/pm hr
• H military hr
• m minutes
• M month
• s seconds
• t A(m) or P(m)
• yy year
• yyyy year 0 padded
• YYYY uint no padding
• uuuu int 0 padded
• UUUU int no padding
• z utc offset e.g. +7/-7
• zz utc offset + leading 0 e.g. +07
  • zzz +07:12
  • zzzz +07:12:21
  • ZZZ +0712
  • ZZZZ 071221
• g AD/BC
• fff milliseconds
• ffffff microseconds
• fffffffff nanoseconds

time design

• 2 groups
  • datetime
  • durations & timeintervals
    • duration
    • intervals: only useful for calculations with timezones

time Duration (see types)

• more performant than timeinterval
• stored as nanoseconds and always normalized (1hr == 60min)
• 1 day = 86400 seconds
  • careful when calcuting 1 day:
    • a single timezone can have multiple UTC offsets (daylight saving)
    • thus parsing 2 dates in this context and diffing may === 25 hours
    • this limitation doest exist in TimeInterval
• int.unit works, e.g. 1.years/months/seconds/etc

time TimeInterval (see types)

• stored as fields of calendar units to support leap years

times types

• DateTime objectenum & int & bool & range
  • leap seconds are supported but not surfaced
• DateTimeLocal objectarray[range, string]
• Duration objectseconds:int & nanosecond:range
  • you likely want this for calculations
• DurationParts arrayFixedTimeUnit, int
• FixedTimeUnit rnageNanoseconds .. Weeks
  • units of time that can be represented by a Duration
• HourRange 0 .. 23
• MinuteRange 0 .. 59
• Month enum(int, string) january = 1
• MonthdayRange 1 .. 31
• NanosecondRange 0 .. bunch of 9s
• SecondRange 0 .. 60
  • 60 included for leap second, but isnt surfaced in a DateTime
• Time objectseconds:int & nanosecond: range
  • a point in time, like a birthday you forgot
• TimeFormat objectpatterns, formatStr
• TimeInterval objectint
  • non-fixed duration of time
  • add/sub from a DateTime/Time
• TimeIntervalParts arrayTimeUnit, int
• TimeUnit enum (see TimeInterval)
• Timezone object(proc & string)
  • uses the systems local time or UTC
• WeekDay enum d(Mon-Sun) -> fullname
• YeardayRange 0 .. 365
• ZonedTime objectTime & int & bool
  • point in time with an associated UTC ffset and DST flag
  • only used for implementing timezones
• DurationZero tuple(seconds: 0, nanosecond: 0)
  • useful for comparing against durations

time exceptions

• TimeFormatParseError: invalid input string
• TimeParseError: invalid TimeFormat

time procs

• cpuTime() is useful for benchmarking
• utc/local convert to/from eachother; shorthand for (dt|time).inZone(utc|local())
• isDst true if daily saving time is in effect (not for js backend)
• isLeapDay true if datetime is leapday, e.g. feb29 in year 2000, affects time offset calculations