From 0d615443dc452f85f3d6b1b2c82d92a9c8db1fff Mon Sep 17 00:00:00 2001 From: Bruce Hill Date: Sun, 27 Oct 2024 18:41:00 -0400 Subject: Update DateTime API to have separate methods for getting each component instead of get(...) --- docs/datetime.md | 237 +++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 203 insertions(+), 34 deletions(-) (limited to 'docs/datetime.md') diff --git a/docs/datetime.md b/docs/datetime.md index 96eda14a..334c615b 100644 --- a/docs/datetime.md +++ b/docs/datetime.md @@ -133,6 +133,85 @@ The date in `YYYY-MM-DD` format. --- +### `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:** @@ -188,69 +267,55 @@ A `DateTime` object representing the same moment as the given UNIX timestamp. = Wed Dec 31 19:00:00 1969 ``` ---- - -### `get` +### `get_local_timezone` -**Description:** -Get various components of the given datetime object and store them in the -provided optional fields. +**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(datetime: DateTime, year : &Int? = !&Int, month : &Int? = !&Int, day : &Int? = !&Int, hour : &Int? = !&Int, minute : &Int? = !&Int, second : &Int? = !&Int, nanosecond : &Int? = !&Int, weekday : &Int? = !&Int, timezone : Text? = !Text -> Void) +func get_local_timezone(->Text) ``` **Parameters:** -- `datetime`: The datetime from which to extract information. -- `year`: If non-null, store the year here. -- `month`: If non-null, store the month here (1-12). -- `day`: If non-null, store the day of the month here (1-31). -- `hour`: If non-null, store the hour of the day here (0-23). -- `minute`: If non-null, store the minute of the hour here (0-59). -- `second`: If non-null, store the second of the minute here (0-59). -- `nanosecond`: If non-null, store the nanosecond of the second here (0-1,000,000,000). -- `weekday`: If non-null, store the day of the week here (sunday=1, saturday=7) -- `timezone` (optional): If specified, give values in the given timezone (otherwise, use the current local timezone). +None. **Returns:** -Nothing. +The name of the current local timezone. **Example:** ```tomo -dt := DateTime(2024, 9, 29) -month := 0 -dt:get(month=&month) ->> month -= 9 +>> DateTime.get_local_timezone() += "America/New_York" ``` --- -### `get_local_timezone` +### `hour` -**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(...)`. +**Description:** +Return the hour of the day as an integer (1-24). **Signature:** ```tomo -func get_local_timezone(->Text) +func hour(datetime: DateTime, timezone : Text? = !Text -> Int) ``` **Parameters:** -None. +- `datetime`: The datetime to get the hour from. +- `timezone` (optional): If specified, use the given timezone (otherwise, use the current local timezone). -**Returns:** -The name of the current local timezone. +**Returns:** +The hour of the day as an integer (1-24). **Example:** ```tomo ->> DateTime.get_local_timezone() -= "America/New_York" +>> DateTime(2024, 9, 29, 11, 59):hour() += 11 ``` --- @@ -282,6 +347,32 @@ the_future := now():after(hours=1, minutes=30) --- +### `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:** @@ -309,6 +400,58 @@ the_future := now():after(minutes=1, seconds=30) --- +### `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:** @@ -445,6 +588,32 @@ ago"`, while datetimes in the future will have the suffix `" later"`. --- +### `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:** -- cgit v1.2.3