From 4231789b71bb42c4ab04e125f98fe5eb3cf030b6 Mon Sep 17 00:00:00 2001 From: Bruce Hill Date: Sun, 17 Nov 2024 14:49:03 -0500 Subject: Rename datetime -> moment --- docs/README.md | 8 +- docs/datetime.md | 732 ------------------------------------------------------ docs/moments.md | 733 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 737 insertions(+), 736 deletions(-) delete mode 100644 docs/datetime.md create mode 100644 docs/moments.md (limited to 'docs') diff --git a/docs/README.md b/docs/README.md index 6d3567df..960ed4af 100644 --- a/docs/README.md +++ b/docs/README.md @@ -22,7 +22,7 @@ Information about Tomo's built-in types can be found here: - [Booleans](booleans.md) - [Bytes](bytes.md) - [Channels](channels.md) -- [DateTime](datetime.md) +- [Moment](moments.md) - [Enums](enums.md) - [Floating point numbers](nums.md) - [Integer Ranges](ranges.md) @@ -177,11 +177,11 @@ fail("Oh no!") ### `now` **Description:** -Gets the current time. This is an alias for `DateTime.now()`. +Gets the current time. This is an alias for `Moment.now()`. **Signature:** ```tomo -func now(->DateTime) +func now(->Moment) ``` **Parameters:** @@ -189,7 +189,7 @@ func now(->DateTime) None. **Returns:** -The current moment as a DateTime. +The current moment as a Moment. **Example:** ```tomo diff --git a/docs/datetime.md b/docs/datetime.md deleted file mode 100644 index 334c615b..00000000 --- a/docs/datetime.md +++ /dev/null @@ -1,732 +0,0 @@ -# DateTime - -Tomo has a builtin datatype for representing a specific single point in time: -`DateTime`. A DateTime object is internally represented using a UNIX timestamp -in seconds and a number of nanoseconds to represent sub-second times (in C, the -equivalent of `struct timeval`). DateTime values do not represent calendar -dates or clock times, they represent an exact moment in time, such as the -moment when a file was last modified on the filesystem or the current moment -(`DateTime.now()`). - -⚠️⚠️⚠️ **WARNING** ⚠️⚠️⚠️ Dates and times are deeply counterintuitive and you should -be extremely cautious when writing code that deals with dates and times. Effort -has been made to ensure that Tomo's `DateTime` code uses standard libraries and -is as correct as possible, but counterintuitive behaviors around time zones, -daylight savings time, leap seconds, and other anomalous time situations can -still cause bugs if you're not extremely careful. - -## Syntax - -DateTime literals can be specified using [ISO -8601](https://en.wikipedia.org/wiki/ISO_8601) syntax with an optional -square-bracket delimited time zone name afterwards. A space may be used instead -of a `T` in the ISO 8601 format for readability, and spaces may come before the -timezone. - -```tomo -2024-09-30 -2024-09-30T13:57 -2024-09-30 13:57 -2024-09-30 13:57:01 -2024-09-30 13:57:01 +04:00 -2024-09-30 13:57:01 [America/New_York] -``` - -## Time Zones - -Because humans are not able to easily understand UNIX timestamps, the default -textual representation of `DateTime` objects uses the current locale's -preferred representation of the DateTime in the current time zone: - -```tomo ->> DateTime.now() -= Sun Sep 29 18:20:12 2024 EDT -``` - -For various methods, it is assumed by default that users wish to perform -calculations and specify datetimes using the local time zone and daylight -savings time rules. For example, if a program is running in New York and it is -currently 11pm on February 28th, 2023 (the last day of the month) in local -time, it is assumed that "one month from now" refers to 11pm on March 28th, -2024 in local time, rather than referring to one month from the current UTC -time. In that example, the initial time would be 3am March 1, 2023 in UTC, so -one month later would be 3am April 1, 2023 in UTC, which is which is 11am March -31st in local time. Most users would be unpleasantly surprised to find out that -when it's February 28th in local time, one month later is March 28th until 8pm, -at which point it becomes March 31st! - -For various functions where time zones matter, there is an optional `timezone` -argument that, if set, will override the timezone when performing calculations. -If unspecified, it is assumed that the current local timezone should be used. -Time zones are specified by name, such as `America/New_York` or `UTC`. - -## DateTime Methods - -### `after` - -**Description:** -Returns a DateTime that occurs after the specified time differences. Time -differences may be either positive or negative. - -**Note:** time offsets for days, months, weeks, and years do not refer to fixed -time intervals, but are relative to which date they are applied to. For -example, one year from January 1, 2024 is January 1, 2025, which is 366 days -later because 2024 is a leap year. Similarly, adding one month may add anywhere -from 28 to 31 days, depending on the starting month. Days and weeks are -affected by leap seconds. For this reason, `after()` takes an argument, -`timezone` which is used to determine in which timezone the offsets should be -calculated. - -**Signature:** -```tomo -func after(datetime: DateTime, seconds : Num = 0.0, minutes : Num = 0.0, hours : Num = 0.0, days : Int = 0, weeks : Int = 0, months : Int = 0, years : Int = 0, timezone : Text? = !Text -> DateTime) -``` - -**Parameters:** - -- `datetime`: The datetime used as a starting point. -- `seconds` (optional): An amount of seconds to offset the datetime (default: 0). -- `minutes` (optional): An amount of minutes to offset the datetime (default: 0). -- `hours` (optional): An amount of hours to offset the datetime (default: 0). -- `days` (optional): An amount of days to offset the datetime (default: 0). -- `weeks` (optional): An amount of weeks to offset the datetime (default: 0). -- `months` (optional): An amount of months to offset the datetime (default: 0). -- `years` (optional): An amount of years to offset the datetime (default: 0). -- `timezone` (optional): If specified, perform perform the calculations in the - given timezone. If unspecified, the current local timezone will be used. - -**Returns:** -A new `DateTime` offset by the given amount. - -**Example:** -```tomo ->> DateTime(2024, 9, 29, hour=19):after(days=1, minutes=30) -= Mon Sep 30 19:30:00 2024 EDT -``` - ---- - -### `date` - -**Description:** -Return a text representation of the datetime using the `"%F"` format -specifier, which gives the date in `YYYY-MM-DD` form. - -**Signature:** -```tomo -func date(datetime: DateTime, timezone : Text? = !Text -> Text) -``` - -**Parameters:** - -- `datetime`: The datetime to get the date from. -- `timezone` (optional): If specified, give the date in the given timezone (otherwise, use the current local timezone). - -**Returns:** -The date in `YYYY-MM-DD` format. - -**Example:** -```tomo ->> DateTime(2024, 9, 29):date() -= "2024-09-29" -``` - ---- - -### `day_of_month` - -**Description:** -Return the integer day of the month (1-31). - -**Signature:** -```tomo -func day_of_month(datetime: DateTime, timezone : Text? = !Text -> Int) -``` - -**Parameters:** - -- `datetime`: The datetime to get the day of the month from. -- `timezone` (optional): If specified, use the given timezone (otherwise, use the current local timezone). - -**Returns:** -The day of the month as an integer (1-31). - -**Example:** -```tomo ->> DateTime(2024, 9, 29):day_of_month() -= 29 -``` - ---- - -### `day_of_week` - -**Description:** -Return the integer day of the week (1-7), where 1 = Sunday, 2 = Monday, -3 = Tuesday, 4 = Wednesday, 5 = Thursday, 6 = Friday, 7 = Saturday. - -**Signature:** -```tomo -func day_of_week(datetime: DateTime, timezone : Text? = !Text -> Int) -``` - -**Parameters:** - -- `datetime`: The datetime to get the day of the week from. -- `timezone` (optional): If specified, use the given timezone (otherwise, use the current local timezone). - -**Returns:** -The day of the week as an integer (1-7). - -**Example:** -```tomo ->> DateTime(2024, 9, 29):day_of_week() -= 1 -``` - ---- - -### `day_of_year` - -**Description:** -Return the integer day of the year (1-366, including leap years). - -**Signature:** -```tomo -func day_of_year(datetime: DateTime, timezone : Text? = !Text -> Int) -``` - -**Parameters:** - -- `datetime`: The datetime to get the day of the year from. -- `timezone` (optional): If specified, use the given timezone (otherwise, use the current local timezone). - -**Returns:** -The day of the year as an integer (1-366). - -**Example:** -```tomo ->> DateTime(2024, 9, 29):day_of_year() -= 272 -``` - ---- - -### `format` - -**Description:** -Using the C-style [`strftime`](https://linux.die.net/man/3/strftime) format -options, return a text representation of the given date in the given format. If -`timezone` is specified, use that timezone instead of the current local -timezone. - -**Signature:** -```tomo -func format(datetime: DateTime, format: Text = "%Y-%m-%dT%H:%M:%S%z", timezone : Text? = !Text -> Text) -``` - -**Parameters:** - -- `datetime`: The datetime to format. -- `format`: The `strftime` format to use (default: `"%Y-%m-%dT%H:%M:%S%z"`). -- `timezone` (optional): If specified, use the given timezone (otherwise, use the current local timezone). - -**Returns:** -Nothing. - -**Example:** -```tomo ->> DateTime(2024, 9, 29):format("%A") -= "Sunday" -``` - ---- - -### `from_unix_timestamp` - -**Description:** -Return a datetime object that represents the same moment in time as -the given UNIX epoch timestamp (seconds since January 1, 1970 UTC). - -**Signature:** -```tomo -func from_unix_timestamp(timestamp: Int64 -> DateTime) -``` - -**Parameters:** - -- `timestamp`: The UNIX timestamp. - -**Returns:** -A `DateTime` object representing the same moment as the given UNIX timestamp. - -**Example:** -```tomo -# In the New York timezone: ->> DateTime.from_unix_timestamp(0) -= Wed Dec 31 19:00:00 1969 -``` - -### `get_local_timezone` - -**Description:** -Get the local timezone's name (e.g. `America/New_York` or `UTC`. By default, -this value is read from `/etc/localtime`, however, this can be overridden by -calling `DateTime.set_local_timezone(...)`. - -**Signature:** -```tomo -func get_local_timezone(->Text) -``` - -**Parameters:** - -None. - -**Returns:** -The name of the current local timezone. - -**Example:** -```tomo ->> DateTime.get_local_timezone() -= "America/New_York" -``` - ---- - -### `hour` - -**Description:** -Return the hour of the day as an integer (1-24). - -**Signature:** -```tomo -func hour(datetime: DateTime, timezone : Text? = !Text -> Int) -``` - -**Parameters:** - -- `datetime`: The datetime to get the hour from. -- `timezone` (optional): If specified, use the given timezone (otherwise, use the current local timezone). - -**Returns:** -The hour of the day as an integer (1-24). - -**Example:** -```tomo ->> DateTime(2024, 9, 29, 11, 59):hour() -= 11 -``` - ---- - -### `hours_till` - -**Description:** -Return the number of hours until a given datetime. - -**Signature:** -```tomo -func hours_till(datetime: DateTime, then:DateTime -> Num) -``` - -**Parameters:** - -- `datetime`: The starting point datetime. -- `then`: Another datetime that we want to calculate the time offset from (in hours). - -**Returns:** -The number of hours (possibly fractional, possibly negative) until the given time. - -**Example:** -```tomo -the_future := now():after(hours=1, minutes=30) ->> now():hours_till(the_future) -= 1.5 -``` - ---- - -### `minute` - -**Description:** -Return the minute of the day as an integer (0-59). - -**Signature:** -```tomo -func minute(datetime: DateTime, timezone : Text? = !Text -> Int) -``` - -**Parameters:** - -- `datetime`: The datetime to get the minute from. -- `timezone` (optional): If specified, use the given timezone (otherwise, use the current local timezone). - -**Returns:** -The minute of the hour as an integer (0-59). - -**Example:** -```tomo ->> DateTime(2024, 9, 29, 11, 59):minute() -= 59 -``` - ---- - -### `minutes_till` - -**Description:** -Return the number of minutes until a given datetime. - -**Signature:** -```tomo -func minutes_till(datetime: DateTime, then:DateTime -> Num) -``` - -**Parameters:** - -- `datetime`: The starting point datetime. -- `then`: Another datetime that we want to calculate the time offset from (in minutes). - -**Returns:** -The number of minutes (possibly fractional, possibly negative) until the given time. - -**Example:** -```tomo -the_future := now():after(minutes=1, seconds=30) ->> now():minutes_till(the_future) -= 1.5 -``` - ---- - -### `month` - -**Description:** -Return the month of the year as an integer (1-12). - -**Signature:** -```tomo -func month(datetime: DateTime, timezone : Text? = !Text -> Int) -``` - -**Parameters:** - -- `datetime`: The datetime to get the month from. -- `timezone` (optional): If specified, use the given timezone (otherwise, use the current local timezone). - -**Returns:** -The month of the year as an integer (1-12). - -**Example:** -```tomo ->> DateTime(2024, 9, 29, 11, 59):month() -= 9 -``` - ---- - -### `nanosecond` - -**Description:** -Return the nanosecond of the second as an integer (0-999,999,999). - -**Signature:** -```tomo -func nanosecond(datetime: DateTime, timezone : Text? = !Text -> Int) -``` - -**Parameters:** - -- `datetime`: The datetime to get the nanosecond from. -- `timezone` (optional): If specified, use the given timezone (otherwise, use the current local timezone). - -**Returns:** -The nanosecond of the second as an integer (0-999,999,999). - -**Example:** -```tomo ->> DateTime(2024, 9, 29, 11, 59):month() -= 9 -``` - ---- - -### `new` - -**Description:** -Return a new `DateTime` object representing the given time parameters expressed -in local time. This function is the same as calling `DateTime` directly as a -constructor. - -**Signature:** -```tomo -func new(year : Int, month : Int, day : Int, hour : Int = 0, minute : Int = 0, second : Num = 0.0 -> DateTime) -``` - -**Parameters:** - -- `year`: The year. -- `month`: The month of the year (1-12). -- `day`: The day of the month (1-31). -- `hour`: The hour of the day (0-23) (default: 0). -- `minute`: The minute of the hour (0-59) (default: 0). -- `second`: The second of the minute (0-59) (default: 0.0). - -**Returns:** -A `DateTime` representing the given information in local time. If the given -parameters exceed reasonable bounds, the time values will wrap around. For -example, `DateTime.new(..., hour=3, minute=65)` is the same as -`DateTime.new(..., hour=4, minute=5)`. If any arguments cannot fit in a 32-bit -integer, an error will be raised. - -**Example:** -```tomo ->> DateTime.new(2024, 9, 29) -= Mon Sep 30 00:00:00 2024 EDT - -# March 1642, 2020: ->> DateTime(2020, 4, 1643) -= Sat Sep 28 00:00:00 2024 EDT -``` - ---- - -### `now` - -**Description:** -Get a `DateTime` object representing the current date and time. This function -is the same as the global function `now()`. - -**Signature:** -```tomo -func now(->DateTime) -``` - -**Parameters:** - -None. - -**Returns:** -Returns a `DateTime` object representing the current date and time. - -**Example:** -```tomo ->> DateTime.now() -= Sun Sep 29 20:22:48 2024 EDT -``` - ---- - -### `parse` - -**Description:** -Return a new `DateTime` object parsed from the given string in the given format, -or a null value if the value could not be successfully parsed. - -**Signature:** -```tomo -func parse(text: Text, format: Text = "%Y-%m-%dT%H:%M:%S%z" -> DateTime?) -``` - -**Parameters:** - -- `text`: The text to parse. -- `format`: The date format of the text being parsed (see: - [strptime](https://linux.die.net/man/3/strptime) for more info on this - format) (default: `"%Y-%m-%dT%H:%M:%S%z"`). - -**Returns:** -If the text was successfully parsed according to the given format, return a -`DateTime` representing that information. Otherwise, return a null value. - -**Example:** -```tomo ->> DateTime.parse("2024-09-29", "%Y-%m-%d")! -= Sun Sep 29 00:00:00 2024 EDT - ->> DateTime.parse("???", "%Y-%m-%d") -= !DateTime -``` - ---- - -### `relative` - -**Description:** -Return a plain English textual representation of the approximate time difference -between two `DateTime`s. For example: `5 minutes ago` or `1 day later` - -**Signature:** -```tomo -func relative(datetime: DateTime, relative_to : DateTime = DateTime.now(), timezone : Text? = !Text -> Text) -``` - -**Parameters:** - -- `datetime`: The datetime whose relative time you're getting. -- `relative_to` (optional): The time against which the relative time is calculated (default: `DateTime.now()`). -- `timezone` (optional): If specified, perform calculations in the given - timezone (otherwise, use the current local timezone). - -**Returns:** -Return a plain English textual representation of the approximate time -difference between two `DateTime`s. For example: `5 minutes ago` or `1 day -later`. Return values are approximate and use only one significant unit of -measure with one significant digit, so a difference of 1.6 days will be -represented as `2 days later`. Datetimes in the past will have the suffix `" -ago"`, while datetimes in the future will have the suffix `" later"`. - -**Example:** -```tomo ->> now():after(days=2):relative() -= "2 days later" - ->> now():after(minutes=-65):relative() -= "1 hour ago" -``` - ---- - -### `second` - -**Description:** -Return the second of the minute as an integer (0-59). - -**Signature:** -```tomo -func second(datetime: DateTime, timezone : Text? = !Text -> Int) -``` - -**Parameters:** - -- `datetime`: The datetime to get the second from. -- `timezone` (optional): If specified, use the given timezone (otherwise, use the current local timezone). - -**Returns:** -The second of the hour as an integer (0-59). - -**Example:** -```tomo ->> DateTime(2024, 9, 29, 11, 30, 59):second() -= 59 -``` - ---- - -### `seconds_till` - -**Description:** -Return the number of seconds until a given datetime. - -**Signature:** -```tomo -func seconds_till(datetime: DateTime, then:DateTime -> Num) -``` - -**Parameters:** - -- `datetime`: The starting point datetime. -- `then`: Another datetime that we want to calculate the time offset from (in seconds). - -**Returns:** -The number of seconds (possibly fractional, possibly negative) until the given time. - -**Example:** -```tomo -the_future := now():after(seconds=1) ->> now():seconds_till(the_future) -= 1 -``` - ---- - -### `set_local_timezone` - -**Description:** -Set the current local timezone to a given value by name (e.g. -`America/New_York` or `UTC`). The local timezone is used as the default -timezone for performing calculations and constructing `DateTime` objects from -component parts. It's also used as the default way that `DateTime` objects are -converted to text. - -**Signature:** -```tomo -func set_local_timezone(timezone : Text? = !Text -> Void) -``` - -**Parameters:** - -- `timezone` (optional): if specified, set the current local timezone to the - timezone with the given name. If null, reset the current local timezone to - the system default (the value referenced in `/etc/localtime`). - -**Returns:** -Nothing. - -**Example:** -```tomo -DateTime.set_local_timezone("America/Los_Angeles") -``` - ---- - -### `time` - -**Description:** -Return a text representation of the time component of the given datetime. - -**Signature:** -```tomo -func time(datetime: DateTime, seconds : Bool = no, am_pm : Bool = yes, timezone : Text? = !Text -> Text) -``` - -**Parameters:** - -- `datetime`: The datetime whose time value you want to get. -- `seconds`: Whether to include seconds in the time (default: `no`). -- `am_pm`: Whether to use am/pm in the representation or use a 24-hour clock (default: `yes`). -- `timezone` (optional): If specified, give the time in the given timezone (otherwise, use the current local timezone). - -**Returns:** -A text representation of the time component of the datetime. - -**Example:** -```tomo -dt := DateTime(2024, 9, 29, hours=13, minutes=59, seconds=30) - ->> dt:time() -= "1:59pm" - ->> dt:time(am_pm=no) -= "13:59" - ->> dt:time(seconds=yes) -= "1:59:30pm" -``` - ---- - -### `unix_timestamp` - -**Description:** -Get the UNIX timestamp of the given datetime (seconds since the UNIX epoch: -January 1, 1970 UTC). - -**Signature:** -```tomo -func unix_timestamp(datetime:DateTime->Int64) -``` - -**Parameters:** - -`datetime`: The datetime whose UNIX timestamp you want to get. - -**Returns:** -A 64-bit integer representation of the UNIX timestamp. - -**Example:** -```tomo ->> now():unix_timestamp() -= 1727654730[64] -``` diff --git a/docs/moments.md b/docs/moments.md new file mode 100644 index 00000000..1c3900c4 --- /dev/null +++ b/docs/moments.md @@ -0,0 +1,733 @@ +# Moments + +Tomo has a builtin datatype for representing a specific single point in time: +`Moment`. This is similar to a "datetime" in other languages, but it does not +represent a locale-specific time with a timezone. A Moment object is internally +represented using a UNIX timestamp in seconds and a number of nanoseconds to +represent sub-second times (in C, the equivalent of `struct timeval`). Moment +values do not represent calendar dates or clock times, they represent an exact +moment in time, such as the moment when a file was last modified on the +filesystem or the current moment (`Moment.now()`). + +⚠️⚠️⚠️ **WARNING** ⚠️⚠️⚠️ Dates and times are deeply counterintuitive and you should +be extremely cautious when writing code that deals with dates and times. Effort +has been made to ensure that Tomo's `Moment` code uses standard libraries and +is as correct as possible, but counterintuitive behaviors around time zones, +daylight savings time, leap seconds, and other anomalous time situations can +still cause bugs if you're not extremely careful. + +## Syntax + +Moment literals can be specified using [ISO +8601](https://en.wikipedia.org/wiki/ISO_8601) syntax with an optional +square-bracket delimited time zone name afterwards. A space may be used instead +of a `T` in the ISO 8601 format for readability, and spaces may come before the +timezone. + +```tomo +2024-09-30 +2024-09-30T13:57 +2024-09-30 13:57 +2024-09-30 13:57:01 +2024-09-30 13:57:01 +04:00 +2024-09-30 13:57:01 [America/New_York] +``` + +## Time Zones + +Because humans are not able to easily understand UNIX timestamps, the default +textual representation of `Moment` objects uses the current locale's +preferred representation of the Moment in the current time zone: + +```tomo +>> Moment.now() += Sun Sep 29 18:20:12 2024 EDT +``` + +For various methods, it is assumed by default that users wish to perform +calculations and specify moments using the local time zone and daylight +savings time rules. For example, if a program is running in New York and it is +currently 11pm on February 28th, 2023 (the last day of the month) in local +time, it is assumed that "one month from now" refers to 11pm on March 28th, +2024 in local time, rather than referring to one month from the current UTC +time. In that example, the initial time would be 3am March 1, 2023 in UTC, so +one month later would be 3am April 1, 2023 in UTC, which is which is 11am March +31st in local time. Most users would be unpleasantly surprised to find out that +when it's February 28th in local time, one month later is March 28th until 8pm, +at which point it becomes March 31st! + +For various functions where time zones matter, there is an optional `timezone` +argument that, if set, will override the timezone when performing calculations. +If unspecified, it is assumed that the current local timezone should be used. +Time zones are specified by name, such as `America/New_York` or `UTC`. + +## Moment Methods + +### `after` + +**Description:** +Returns a Moment that occurs after the specified time differences. Time +differences may be either positive or negative. + +**Note:** time offsets for days, months, weeks, and years do not refer to fixed +time intervals, but are relative to which date they are applied to. For +example, one year from January 1, 2024 is January 1, 2025, which is 366 days +later because 2024 is a leap year. Similarly, adding one month may add anywhere +from 28 to 31 days, depending on the starting month. Days and weeks are +affected by leap seconds. For this reason, `after()` takes an argument, +`timezone` which is used to determine in which timezone the offsets should be +calculated. + +**Signature:** +```tomo +func after(moment: Moment, seconds : Num = 0.0, minutes : Num = 0.0, hours : Num = 0.0, days : Int = 0, weeks : Int = 0, months : Int = 0, years : Int = 0, timezone : Text? = !Text -> Moment) +``` + +**Parameters:** + +- `moment`: The moment used as a starting point. +- `seconds` (optional): An amount of seconds to offset the moment (default: 0). +- `minutes` (optional): An amount of minutes to offset the moment (default: 0). +- `hours` (optional): An amount of hours to offset the moment (default: 0). +- `days` (optional): An amount of days to offset the moment (default: 0). +- `weeks` (optional): An amount of weeks to offset the moment (default: 0). +- `months` (optional): An amount of months to offset the moment (default: 0). +- `years` (optional): An amount of years to offset the moment (default: 0). +- `timezone` (optional): If specified, perform perform the calculations in the + given timezone. If unspecified, the current local timezone will be used. + +**Returns:** +A new `Moment` offset by the given amount. + +**Example:** +```tomo +>> Moment(2024, 9, 29, hour=19):after(days=1, minutes=30) += Mon Sep 30 19:30:00 2024 EDT +``` + +--- + +### `date` + +**Description:** +Return a text representation of the moment using the `"%F"` format +specifier, which gives the date in `YYYY-MM-DD` form. + +**Signature:** +```tomo +func date(moment: Moment, timezone : Text? = !Text -> Text) +``` + +**Parameters:** + +- `moment`: The moment to get the date from. +- `timezone` (optional): If specified, give the date in the given timezone (otherwise, use the current local timezone). + +**Returns:** +The date in `YYYY-MM-DD` format. + +**Example:** +```tomo +>> Moment(2024, 9, 29):date() += "2024-09-29" +``` + +--- + +### `day_of_month` + +**Description:** +Return the integer day of the month (1-31). + +**Signature:** +```tomo +func day_of_month(moment: Moment, timezone : Text? = !Text -> Int) +``` + +**Parameters:** + +- `moment`: The moment to get the day of the month from. +- `timezone` (optional): If specified, use the given timezone (otherwise, use the current local timezone). + +**Returns:** +The day of the month as an integer (1-31). + +**Example:** +```tomo +>> Moment(2024, 9, 29):day_of_month() += 29 +``` + +--- + +### `day_of_week` + +**Description:** +Return the integer day of the week (1-7), where 1 = Sunday, 2 = Monday, +3 = Tuesday, 4 = Wednesday, 5 = Thursday, 6 = Friday, 7 = Saturday. + +**Signature:** +```tomo +func day_of_week(moment: Moment, timezone : Text? = !Text -> Int) +``` + +**Parameters:** + +- `moment`: The moment to get the day of the week from. +- `timezone` (optional): If specified, use the given timezone (otherwise, use the current local timezone). + +**Returns:** +The day of the week as an integer (1-7). + +**Example:** +```tomo +>> Moment(2024, 9, 29):day_of_week() += 1 +``` + +--- + +### `day_of_year` + +**Description:** +Return the integer day of the year (1-366, including leap years). + +**Signature:** +```tomo +func day_of_year(moment: Moment, timezone : Text? = !Text -> Int) +``` + +**Parameters:** + +- `moment`: The moment to get the day of the year from. +- `timezone` (optional): If specified, use the given timezone (otherwise, use the current local timezone). + +**Returns:** +The day of the year as an integer (1-366). + +**Example:** +```tomo +>> Moment(2024, 9, 29):day_of_year() += 272 +``` + +--- + +### `format` + +**Description:** +Using the C-style [`strftime`](https://linux.die.net/man/3/strftime) format +options, return a text representation of the given date in the given format. If +`timezone` is specified, use that timezone instead of the current local +timezone. + +**Signature:** +```tomo +func format(moment: Moment, format: Text = "%Y-%m-%dT%H:%M:%S%z", timezone : Text? = !Text -> Text) +``` + +**Parameters:** + +- `moment`: The moment to format. +- `format`: The `strftime` format to use (default: `"%Y-%m-%dT%H:%M:%S%z"`). +- `timezone` (optional): If specified, use the given timezone (otherwise, use the current local timezone). + +**Returns:** +Nothing. + +**Example:** +```tomo +>> Moment(2024, 9, 29):format("%A") += "Sunday" +``` + +--- + +### `from_unix_timestamp` + +**Description:** +Return a moment object that represents the same moment in time as +the given UNIX epoch timestamp (seconds since January 1, 1970 UTC). + +**Signature:** +```tomo +func from_unix_timestamp(timestamp: Int64 -> Moment) +``` + +**Parameters:** + +- `timestamp`: The UNIX timestamp. + +**Returns:** +A `Moment` object representing the same moment as the given UNIX timestamp. + +**Example:** +```tomo +# In the New York timezone: +>> Moment.from_unix_timestamp(0) += Wed Dec 31 19:00:00 1969 +``` + +### `get_local_timezone` + +**Description:** +Get the local timezone's name (e.g. `America/New_York` or `UTC`. By default, +this value is read from `/etc/localtime`, however, this can be overridden by +calling `Moment.set_local_timezone(...)`. + +**Signature:** +```tomo +func get_local_timezone(->Text) +``` + +**Parameters:** + +None. + +**Returns:** +The name of the current local timezone. + +**Example:** +```tomo +>> Moment.get_local_timezone() += "America/New_York" +``` + +--- + +### `hour` + +**Description:** +Return the hour of the day as an integer (1-24). + +**Signature:** +```tomo +func hour(moment: Moment, timezone : Text? = !Text -> Int) +``` + +**Parameters:** + +- `moment`: The moment to get the hour from. +- `timezone` (optional): If specified, use the given timezone (otherwise, use the current local timezone). + +**Returns:** +The hour of the day as an integer (1-24). + +**Example:** +```tomo +>> Moment(2024, 9, 29, 11, 59):hour() += 11 +``` + +--- + +### `hours_till` + +**Description:** +Return the number of hours until a given moment. + +**Signature:** +```tomo +func hours_till(moment: Moment, then:Moment -> Num) +``` + +**Parameters:** + +- `moment`: The starting point moment. +- `then`: Another moment that we want to calculate the time offset from (in hours). + +**Returns:** +The number of hours (possibly fractional, possibly negative) until the given time. + +**Example:** +```tomo +the_future := now():after(hours=1, minutes=30) +>> now():hours_till(the_future) += 1.5 +``` + +--- + +### `minute` + +**Description:** +Return the minute of the day as an integer (0-59). + +**Signature:** +```tomo +func minute(moment: Moment, timezone : Text? = !Text -> Int) +``` + +**Parameters:** + +- `moment`: The moment to get the minute from. +- `timezone` (optional): If specified, use the given timezone (otherwise, use the current local timezone). + +**Returns:** +The minute of the hour as an integer (0-59). + +**Example:** +```tomo +>> Moment(2024, 9, 29, 11, 59):minute() += 59 +``` + +--- + +### `minutes_till` + +**Description:** +Return the number of minutes until a given moment. + +**Signature:** +```tomo +func minutes_till(moment: Moment, then:Moment -> Num) +``` + +**Parameters:** + +- `moment`: The starting point moment. +- `then`: Another moment that we want to calculate the time offset from (in minutes). + +**Returns:** +The number of minutes (possibly fractional, possibly negative) until the given time. + +**Example:** +```tomo +the_future := now():after(minutes=1, seconds=30) +>> now():minutes_till(the_future) += 1.5 +``` + +--- + +### `month` + +**Description:** +Return the month of the year as an integer (1-12). + +**Signature:** +```tomo +func month(moment: Moment, timezone : Text? = !Text -> Int) +``` + +**Parameters:** + +- `moment`: The moment to get the month from. +- `timezone` (optional): If specified, use the given timezone (otherwise, use the current local timezone). + +**Returns:** +The month of the year as an integer (1-12). + +**Example:** +```tomo +>> Moment(2024, 9, 29, 11, 59):month() += 9 +``` + +--- + +### `nanosecond` + +**Description:** +Return the nanosecond of the second as an integer (0-999,999,999). + +**Signature:** +```tomo +func nanosecond(moment: Moment, timezone : Text? = !Text -> Int) +``` + +**Parameters:** + +- `moment`: The moment to get the nanosecond from. +- `timezone` (optional): If specified, use the given timezone (otherwise, use the current local timezone). + +**Returns:** +The nanosecond of the second as an integer (0-999,999,999). + +**Example:** +```tomo +>> Moment(2024, 9, 29, 11, 59):month() += 9 +``` + +--- + +### `new` + +**Description:** +Return a new `Moment` object representing the given time parameters expressed +in local time. This function is the same as calling `Moment` directly as a +constructor. + +**Signature:** +```tomo +func new(year : Int, month : Int, day : Int, hour : Int = 0, minute : Int = 0, second : Num = 0.0 -> Moment) +``` + +**Parameters:** + +- `year`: The year. +- `month`: The month of the year (1-12). +- `day`: The day of the month (1-31). +- `hour`: The hour of the day (0-23) (default: 0). +- `minute`: The minute of the hour (0-59) (default: 0). +- `second`: The second of the minute (0-59) (default: 0.0). + +**Returns:** +A `Moment` representing the given information in local time. If the given +parameters exceed reasonable bounds, the time values will wrap around. For +example, `Moment.new(..., hour=3, minute=65)` is the same as +`Moment.new(..., hour=4, minute=5)`. If any arguments cannot fit in a 32-bit +integer, an error will be raised. + +**Example:** +```tomo +>> Moment.new(2024, 9, 29) += Mon Sep 30 00:00:00 2024 EDT + +# March 1642, 2020: +>> Moment(2020, 4, 1643) += Sat Sep 28 00:00:00 2024 EDT +``` + +--- + +### `now` + +**Description:** +Get a `Moment` object representing the current date and time. This function +is the same as the global function `now()`. + +**Signature:** +```tomo +func now(->Moment) +``` + +**Parameters:** + +None. + +**Returns:** +Returns a `Moment` object representing the current date and time. + +**Example:** +```tomo +>> Moment.now() += Sun Sep 29 20:22:48 2024 EDT +``` + +--- + +### `parse` + +**Description:** +Return a new `Moment` object parsed from the given string in the given format, +or a null value if the value could not be successfully parsed. + +**Signature:** +```tomo +func parse(text: Text, format: Text = "%Y-%m-%dT%H:%M:%S%z" -> Moment?) +``` + +**Parameters:** + +- `text`: The text to parse. +- `format`: The date format of the text being parsed (see: + [strptime](https://linux.die.net/man/3/strptime) for more info on this + format) (default: `"%Y-%m-%dT%H:%M:%S%z"`). + +**Returns:** +If the text was successfully parsed according to the given format, return a +`Moment` representing that information. Otherwise, return a null value. + +**Example:** +```tomo +>> Moment.parse("2024-09-29", "%Y-%m-%d")! += Sun Sep 29 00:00:00 2024 EDT + +>> Moment.parse("???", "%Y-%m-%d") += !Moment +``` + +--- + +### `relative` + +**Description:** +Return a plain English textual representation of the approximate time difference +between two `Moment`s. For example: `5 minutes ago` or `1 day later` + +**Signature:** +```tomo +func relative(moment: Moment, relative_to : Moment = Moment.now(), timezone : Text? = !Text -> Text) +``` + +**Parameters:** + +- `moment`: The moment whose relative time you're getting. +- `relative_to` (optional): The time against which the relative time is calculated (default: `Moment.now()`). +- `timezone` (optional): If specified, perform calculations in the given + timezone (otherwise, use the current local timezone). + +**Returns:** +Return a plain English textual representation of the approximate time +difference between two `Moment`s. For example: `5 minutes ago` or `1 day +later`. Return values are approximate and use only one significant unit of +measure with one significant digit, so a difference of 1.6 days will be +represented as `2 days later`. moments in the past will have the suffix `" +ago"`, while moments in the future will have the suffix `" later"`. + +**Example:** +```tomo +>> now():after(days=2):relative() += "2 days later" + +>> now():after(minutes=-65):relative() += "1 hour ago" +``` + +--- + +### `second` + +**Description:** +Return the second of the minute as an integer (0-59). + +**Signature:** +```tomo +func second(moment: Moment, timezone : Text? = !Text -> Int) +``` + +**Parameters:** + +- `moment`: The moment to get the second from. +- `timezone` (optional): If specified, use the given timezone (otherwise, use the current local timezone). + +**Returns:** +The second of the hour as an integer (0-59). + +**Example:** +```tomo +>> Moment(2024, 9, 29, 11, 30, 59):second() += 59 +``` + +--- + +### `seconds_till` + +**Description:** +Return the number of seconds until a given moment. + +**Signature:** +```tomo +func seconds_till(moment: Moment, then:Moment -> Num) +``` + +**Parameters:** + +- `moment`: The starting point moment. +- `then`: Another moment that we want to calculate the time offset from (in seconds). + +**Returns:** +The number of seconds (possibly fractional, possibly negative) until the given time. + +**Example:** +```tomo +the_future := now():after(seconds=1) +>> now():seconds_till(the_future) += 1 +``` + +--- + +### `set_local_timezone` + +**Description:** +Set the current local timezone to a given value by name (e.g. +`America/New_York` or `UTC`). The local timezone is used as the default +timezone for performing calculations and constructing `Moment` objects from +component parts. It's also used as the default way that `Moment` objects are +converted to text. + +**Signature:** +```tomo +func set_local_timezone(timezone : Text? = !Text -> Void) +``` + +**Parameters:** + +- `timezone` (optional): if specified, set the current local timezone to the + timezone with the given name. If null, reset the current local timezone to + the system default (the value referenced in `/etc/localtime`). + +**Returns:** +Nothing. + +**Example:** +```tomo +Moment.set_local_timezone("America/Los_Angeles") +``` + +--- + +### `time` + +**Description:** +Return a text representation of the time component of the given moment. + +**Signature:** +```tomo +func time(moment: Moment, seconds : Bool = no, am_pm : Bool = yes, timezone : Text? = !Text -> Text) +``` + +**Parameters:** + +- `moment`: The moment whose time value you want to get. +- `seconds`: Whether to include seconds in the time (default: `no`). +- `am_pm`: Whether to use am/pm in the representation or use a 24-hour clock (default: `yes`). +- `timezone` (optional): If specified, give the time in the given timezone (otherwise, use the current local timezone). + +**Returns:** +A text representation of the time component of the moment. + +**Example:** +```tomo +moment := Moment(2024, 9, 29, hours=13, minutes=59, seconds=30) + +>> dt:time() += "1:59pm" + +>> dt:time(am_pm=no) += "13:59" + +>> dt:time(seconds=yes) += "1:59:30pm" +``` + +--- + +### `unix_timestamp` + +**Description:** +Get the UNIX timestamp of the given moment (seconds since the UNIX epoch: +January 1, 1970 UTC). + +**Signature:** +```tomo +func unix_timestamp(moment:Moment->Int64) +``` + +**Parameters:** + +`moment`: The moment whose UNIX timestamp you want to get. + +**Returns:** +A 64-bit integer representation of the UNIX timestamp. + +**Example:** +```tomo +>> now():unix_timestamp() += 1727654730[64] +``` -- cgit v1.2.3