> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cowboy.inc/llms.txt
> Use this file to discover all available pages before exploring further.

# std.calendar

> UTC dates, weekdays and send times in integer milliseconds

`cowboy_sdk.std.calendar` turns block time into calendar dates and back. A day is its number since 1970-01-01 (UTC), and a time is block-time milliseconds, as `runtime.get_timestamp_ms()` returns it. Everything is integer arithmetic, so every validator computes the same date.

```python theme={null}
from cowboy_sdk import runtime
from cowboy_sdk.std import calendar

now_ms = runtime.get_timestamp_ms()
today = now_ms // calendar.DAY_MS
self.storage["day:" + calendar.ymd(today)] = record    # "day:20261102"
send_ms = calendar.next_at(now_ms, hour=7)              # the next 07:00 UTC
weekly_ms = calendar.next_at(now_ms, hour=9, weekday=0) # the next Monday 09:00 UTC
```

| Function | Returns |
| - | - |
| `civil(day)` | `(year, month, day)` |
| `day_number(year, month, day)` | the day number; `ValueError` for a day that does not exist |
| `ymd(day)` / `iso(day)` | `"20261102"` / `"2026-11-02"` |
| `stamp(ms)` | `"20261102T070000Z"`, the iCalendar `DTSTART` form |
| `parse(text)` | the day number of `"YYYYMMDD"` or `"YYYY-MM-DD"`; `ValueError` otherwise |
| `weekday(day)` | `0` for Monday through `6` for Sunday |
| `week_start(day)` | the Monday that starts the day's week |
| `next_at(now_ms, hour, weekday=None)` | the first `hour`:00 UTC strictly after `now_ms`, on `weekday` if given |

Constants: `DAY_MS`, `HOUR_MS`, `MINUTE_MS`, `WEEK_DAYS`.

To arm a timer for a time `next_at` returns, convert it to a height with [`std.clock`](https://docs.cowboy.inc/developers/std/clock).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.