time: update doc comments (#14359)
parent
b42e897a5d
commit
66e61d771e
|
@ -6,37 +6,37 @@ module time
|
||||||
import strings
|
import strings
|
||||||
import math
|
import math
|
||||||
|
|
||||||
// format returns a date string in "YYYY-MM-DD HH:MM" format (24h).
|
// format returns a date string in "YYYY-MM-DD HH:mm" format (24h).
|
||||||
pub fn (t Time) format() string {
|
pub fn (t Time) format() string {
|
||||||
return t.get_fmt_str(.hyphen, .hhmm24, .yyyymmdd)
|
return t.get_fmt_str(.hyphen, .hhmm24, .yyyymmdd)
|
||||||
}
|
}
|
||||||
|
|
||||||
// format_ss returns a date string in "YYYY-MM-DD HH:MM:SS" format (24h).
|
// format_ss returns a date string in "YYYY-MM-DD HH:mm:ss" format (24h).
|
||||||
pub fn (t Time) format_ss() string {
|
pub fn (t Time) format_ss() string {
|
||||||
return t.get_fmt_str(.hyphen, .hhmmss24, .yyyymmdd)
|
return t.get_fmt_str(.hyphen, .hhmmss24, .yyyymmdd)
|
||||||
}
|
}
|
||||||
|
|
||||||
// format_ss_milli returns a date string in "YYYY-MM-DD HH:MM:SS.123" format (24h).
|
// format_ss_milli returns a date string in "YYYY-MM-DD HH:mm:ss.123" format (24h).
|
||||||
pub fn (t Time) format_ss_milli() string {
|
pub fn (t Time) format_ss_milli() string {
|
||||||
return t.get_fmt_str(.hyphen, .hhmmss24_milli, .yyyymmdd)
|
return t.get_fmt_str(.hyphen, .hhmmss24_milli, .yyyymmdd)
|
||||||
}
|
}
|
||||||
|
|
||||||
// format_ss_micro returns a date string in "YYYY-MM-DD HH:MM:SS.123456" format (24h).
|
// format_ss_micro returns a date string in "YYYY-MM-DD HH:mm:ss.123456" format (24h).
|
||||||
pub fn (t Time) format_ss_micro() string {
|
pub fn (t Time) format_ss_micro() string {
|
||||||
return t.get_fmt_str(.hyphen, .hhmmss24_micro, .yyyymmdd)
|
return t.get_fmt_str(.hyphen, .hhmmss24_micro, .yyyymmdd)
|
||||||
}
|
}
|
||||||
|
|
||||||
// hhmm returns a date string in "HH:MM" format (24h).
|
// hhmm returns a date string in "HH:mm" format (24h).
|
||||||
pub fn (t Time) hhmm() string {
|
pub fn (t Time) hhmm() string {
|
||||||
return t.get_fmt_time_str(.hhmm24)
|
return t.get_fmt_time_str(.hhmm24)
|
||||||
}
|
}
|
||||||
|
|
||||||
// hhmmss returns a date string in "HH:MM:SS" format (24h).
|
// hhmmss returns a date string in "HH:mm:ss" format (24h).
|
||||||
pub fn (t Time) hhmmss() string {
|
pub fn (t Time) hhmmss() string {
|
||||||
return t.get_fmt_time_str(.hhmmss24)
|
return t.get_fmt_time_str(.hhmmss24)
|
||||||
}
|
}
|
||||||
|
|
||||||
// hhmm12 returns a date string in "HH:MM" format (12h).
|
// hhmm12 returns a date string in "hh:mm" format (12h).
|
||||||
pub fn (t Time) hhmm12() string {
|
pub fn (t Time) hhmm12() string {
|
||||||
return t.get_fmt_time_str(.hhmm12)
|
return t.get_fmt_time_str(.hhmm12)
|
||||||
}
|
}
|
||||||
|
@ -77,12 +77,12 @@ fn ordinal_suffix(n int) string {
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
const tokens_2 = ['MM', 'DD', 'Do', 'YY', 'ss', 'kk', 'NN', 'mm', 'hh', 'HH', 'ZZ', 'dd', 'Qo',
|
const (
|
||||||
'QQ', 'wo', 'ww']
|
tokens_2 = ['MM', 'DD', 'Do', 'YY', 'ss', 'kk', 'NN', 'mm', 'hh', 'HH', 'ZZ', 'dd', 'Qo', 'QQ',
|
||||||
|
'wo', 'ww']
|
||||||
const tokens_3 = ['MMM', 'DDD', 'ZZZ', 'ddd']
|
tokens_3 = ['MMM', 'DDD', 'ZZZ', 'ddd']
|
||||||
|
tokens_4 = ['MMMM', 'DDDD', 'DDDo', 'dddd', 'YYYY']
|
||||||
const tokens_4 = ['MMMM', 'DDDD', 'DDDo', 'dddd', 'YYYY']
|
)
|
||||||
|
|
||||||
// custom_format returns a date with custom format
|
// custom_format returns a date with custom format
|
||||||
//
|
//
|
||||||
|
@ -321,8 +321,8 @@ pub fn (t Time) custom_format(s string) string {
|
||||||
}
|
}
|
||||||
|
|
||||||
// clean returns a date string in a following format:
|
// clean returns a date string in a following format:
|
||||||
// - a date string in "HH:MM" format (24h) for current day
|
// - a date string in "HH:mm" format (24h) for current day
|
||||||
// - a date string in "MMM D HH:MM" format (24h) for date of current year
|
// - a date string in "MMM D HH:mm" format (24h) for date of current year
|
||||||
// - a date string formatted with format function for other dates
|
// - a date string formatted with format function for other dates
|
||||||
pub fn (t Time) clean() string {
|
pub fn (t Time) clean() string {
|
||||||
znow := now()
|
znow := now()
|
||||||
|
@ -338,8 +338,8 @@ pub fn (t Time) clean() string {
|
||||||
}
|
}
|
||||||
|
|
||||||
// clean12 returns a date string in a following format:
|
// clean12 returns a date string in a following format:
|
||||||
// - a date string in "HH:MM" format (12h) for current day
|
// - a date string in "hh:mm" format (12h) for current day
|
||||||
// - a date string in "MMM D HH:MM" format (12h) for date of current year
|
// - a date string in "MMM D hh:mm" format (12h) for date of current year
|
||||||
// - a date string formatted with format function for other dates
|
// - a date string formatted with format function for other dates
|
||||||
pub fn (t Time) clean12() string {
|
pub fn (t Time) clean12() string {
|
||||||
znow := now()
|
znow := now()
|
||||||
|
|
|
@ -57,7 +57,7 @@ pub fn parse_rfc3339(s string) ?Time {
|
||||||
return error_invalid_time(9)
|
return error_invalid_time(9)
|
||||||
}
|
}
|
||||||
|
|
||||||
// parse returns time from a date string in "YYYY-MM-DD HH:MM:SS" format.
|
// parse returns time from a date string in "YYYY-MM-DD HH:mm:ss" format.
|
||||||
pub fn parse(s string) ?Time {
|
pub fn parse(s string) ?Time {
|
||||||
if s == '' {
|
if s == '' {
|
||||||
return error_invalid_time(0)
|
return error_invalid_time(0)
|
||||||
|
|
|
@ -96,15 +96,7 @@ pub fn ticks() i64 {
|
||||||
// # return (double)(* (uint64_t *) &elapsedNano) / 1000000;
|
// # return (double)(* (uint64_t *) &elapsedNano) / 1000000;
|
||||||
}
|
}
|
||||||
|
|
||||||
/*
|
// str returns time in the same format as `parse` expects ("YYYY-MM-DD HH:mm:ss").
|
||||||
// sleep makes the calling thread sleep for a given number of seconds.
|
|
||||||
[deprecated: 'call time.sleep(n * time.second)']
|
|
||||||
pub fn sleep(seconds int) {
|
|
||||||
wait(seconds * time.second)
|
|
||||||
}
|
|
||||||
*/
|
|
||||||
|
|
||||||
// str returns time in the same format as `parse` expects ("YYYY-MM-DD HH:MM:SS").
|
|
||||||
pub fn (t Time) str() string {
|
pub fn (t Time) str() string {
|
||||||
// TODO Define common default format for
|
// TODO Define common default format for
|
||||||
// `str` and `parse` and use it in both ways
|
// `str` and `parse` and use it in both ways
|
||||||
|
|
|
@ -195,15 +195,17 @@ pub fn (t Time) relative() string {
|
||||||
// relative_short returns a string saying how long ago a time occured as follows:
|
// relative_short returns a string saying how long ago a time occured as follows:
|
||||||
// 0-30 seconds: `"now"`; 30-60 seconds: `"1m"`; anything else is rounded to the
|
// 0-30 seconds: `"now"`; 30-60 seconds: `"1m"`; anything else is rounded to the
|
||||||
// nearest minute, hour, day, or year
|
// nearest minute, hour, day, or year
|
||||||
// Some Examples:
|
//
|
||||||
// `0s -> 'now'`;
|
// Sample outputs:
|
||||||
// `20s -> 'now'`;
|
// ```
|
||||||
// `47s -> '1m'`;
|
// // future
|
||||||
// `456s -> '7m'`;
|
// now
|
||||||
// `1234s -> '20m'`;
|
// in 5m
|
||||||
// `16834s -> '4h'`;
|
// in 1d
|
||||||
// `1687440s -> '33d'`;
|
// // past
|
||||||
// `15842354871s -> ''`
|
// 2h ago
|
||||||
|
// 5y ago
|
||||||
|
// ```
|
||||||
pub fn (t Time) relative_short() string {
|
pub fn (t Time) relative_short() string {
|
||||||
znow := now()
|
znow := now()
|
||||||
mut secs := znow.unix - t.unix
|
mut secs := znow.unix - t.unix
|
||||||
|
@ -264,13 +266,13 @@ pub fn (t Time) day_of_week() int {
|
||||||
return day_of_week(t.year, t.month, t.day)
|
return day_of_week(t.year, t.month, t.day)
|
||||||
}
|
}
|
||||||
|
|
||||||
// weekday_str returns the current day as a string abbreviation.
|
// weekday_str returns the current day as a string 3 letter abbreviation.
|
||||||
pub fn (t Time) weekday_str() string {
|
pub fn (t Time) weekday_str() string {
|
||||||
i := t.day_of_week() - 1
|
i := t.day_of_week() - 1
|
||||||
return time.long_days[i][0..3]
|
return time.long_days[i][0..3]
|
||||||
}
|
}
|
||||||
|
|
||||||
// weekday_str returns the current day as a string.
|
// long_weekday_str returns the current day as a string.
|
||||||
pub fn (t Time) long_weekday_str() string {
|
pub fn (t Time) long_weekday_str() string {
|
||||||
i := t.day_of_week() - 1
|
i := t.day_of_week() - 1
|
||||||
return time.long_days[i]
|
return time.long_days[i]
|
||||||
|
@ -291,7 +293,7 @@ pub fn days_in_month(month int, year int) ?int {
|
||||||
return res
|
return res
|
||||||
}
|
}
|
||||||
|
|
||||||
// str returns time in the same format as `parse` expects ("YYYY-MM-DD HH:MM:SS").
|
// debug returns detailed breakdown of time (`Time{ year: YYYY month: MM day: dd hour: HH: minute: mm second: ss microsecond: micros unix: unix }`)
|
||||||
pub fn (t Time) debug() string {
|
pub fn (t Time) debug() string {
|
||||||
return 'Time{ year: ${t.year:04} month: ${t.month:02} day: ${t.day:02} hour: ${t.hour:02} minute: ${t.minute:02} second: ${t.second:02} microsecond: ${t.microsecond:06} unix: ${t.unix:07} }'
|
return 'Time{ year: ${t.year:04} month: ${t.month:02} day: ${t.day:02} hour: ${t.hour:02} minute: ${t.minute:02} second: ${t.second:02} microsecond: ${t.microsecond:06} unix: ${t.unix:07} }'
|
||||||
}
|
}
|
||||||
|
@ -299,19 +301,15 @@ pub fn (t Time) debug() string {
|
||||||
// A lot of these are taken from the Go library.
|
// A lot of these are taken from the Go library.
|
||||||
pub type Duration = i64
|
pub type Duration = i64
|
||||||
|
|
||||||
pub const nanosecond = Duration(1)
|
pub const (
|
||||||
|
nanosecond = Duration(1)
|
||||||
pub const microsecond = Duration(1000 * nanosecond)
|
microsecond = Duration(1000 * nanosecond)
|
||||||
|
millisecond = Duration(1000 * microsecond)
|
||||||
pub const millisecond = Duration(1000 * microsecond)
|
second = Duration(1000 * millisecond)
|
||||||
|
minute = Duration(60 * second)
|
||||||
pub const second = Duration(1000 * millisecond)
|
hour = Duration(60 * minute)
|
||||||
|
infinite = Duration(i64(9223372036854775807))
|
||||||
pub const minute = Duration(60 * second)
|
)
|
||||||
|
|
||||||
pub const hour = Duration(60 * minute)
|
|
||||||
|
|
||||||
pub const infinite = Duration(i64(9223372036854775807))
|
|
||||||
|
|
||||||
// nanoseconds returns the duration as an integer number of nanoseconds.
|
// nanoseconds returns the duration as an integer number of nanoseconds.
|
||||||
pub fn (d Duration) nanoseconds() i64 {
|
pub fn (d Duration) nanoseconds() i64 {
|
||||||
|
@ -320,12 +318,12 @@ pub fn (d Duration) nanoseconds() i64 {
|
||||||
|
|
||||||
// microseconds returns the duration as an integer number of microseconds.
|
// microseconds returns the duration as an integer number of microseconds.
|
||||||
pub fn (d Duration) microseconds() i64 {
|
pub fn (d Duration) microseconds() i64 {
|
||||||
return i64(d) / 1000
|
return i64(d) / time.microsecond
|
||||||
}
|
}
|
||||||
|
|
||||||
// milliseconds returns the duration as an integer number of milliseconds.
|
// milliseconds returns the duration as an integer number of milliseconds.
|
||||||
pub fn (d Duration) milliseconds() i64 {
|
pub fn (d Duration) milliseconds() i64 {
|
||||||
return i64(d) / 1000000
|
return i64(d) / time.millisecond
|
||||||
}
|
}
|
||||||
|
|
||||||
// The following functions return floating point numbers because it's common to
|
// The following functions return floating point numbers because it's common to
|
||||||
|
@ -334,24 +332,33 @@ pub fn (d Duration) milliseconds() i64 {
|
||||||
pub fn (d Duration) seconds() f64 {
|
pub fn (d Duration) seconds() f64 {
|
||||||
sec := d / time.second
|
sec := d / time.second
|
||||||
nsec := d % time.second
|
nsec := d % time.second
|
||||||
return f64(sec) + f64(nsec) / 1e9
|
return f64(sec) + f64(nsec) / time.second
|
||||||
}
|
}
|
||||||
|
|
||||||
// minutes returns the duration as a floating point number of minutes.
|
// minutes returns the duration as a floating point number of minutes.
|
||||||
pub fn (d Duration) minutes() f64 {
|
pub fn (d Duration) minutes() f64 {
|
||||||
min := d / time.minute
|
min := d / time.minute
|
||||||
nsec := d % time.minute
|
nsec := d % time.minute
|
||||||
return f64(min) + f64(nsec) / (60 * 1e9)
|
return f64(min) + f64(nsec) / time.minute
|
||||||
}
|
}
|
||||||
|
|
||||||
// hours returns the duration as a floating point number of hours.
|
// hours returns the duration as a floating point number of hours.
|
||||||
pub fn (d Duration) hours() f64 {
|
pub fn (d Duration) hours() f64 {
|
||||||
hr := d / time.hour
|
hr := d / time.hour
|
||||||
nsec := d % time.hour
|
nsec := d % time.hour
|
||||||
return f64(hr) + f64(nsec) / (60 * 60 * 1e9)
|
return f64(hr) + f64(nsec) / time.hour
|
||||||
}
|
}
|
||||||
|
|
||||||
// str pretty prints the duration.
|
// str pretty prints the duration
|
||||||
|
//
|
||||||
|
// ```
|
||||||
|
// h:m:s // 5:02:33
|
||||||
|
// m:s.mi<s> // 2:33.015
|
||||||
|
// s.mi<s> // 33.015s
|
||||||
|
// mi.mc<ms> // 15.007ms
|
||||||
|
// mc.ns<ns> // 7.234us
|
||||||
|
// ns<ns> // 234ns
|
||||||
|
// ```
|
||||||
pub fn (d Duration) str() string {
|
pub fn (d Duration) str() string {
|
||||||
if d == time.infinite {
|
if d == time.infinite {
|
||||||
return 'inf'
|
return 'inf'
|
||||||
|
|
Loading…
Reference in New Issue