Source Edit

Format Specification

Specifier	Description	Example
{year}	Year in as many digits as needed. Can be negative.	`12012/9/3 -> 12012`
{year/2}	Two digit year, 0-30 represents 2000-2030 while 30-99 is 1930 to 1999.	`2012/9/3 -> 12`
{year/4}	Four digits of the year. Years 0 - 9999.	`2012/9/3 -> 2012`
{month}	Month in digits 1-12	`2012/9/3 -> 9`
{month/2}	Month in two digits 01-12	`2012/9/3 -> 09`
{month/n}	Full name of month	`September -> September`
{month/n/3}	Three letter name of month	`September -> Sep`
{day}	Day in digits 1-31	`2012/9/3 -> 3`
{day/2}	Day in two digits 01-31	`2012/9/3 -> 03`
{hour}	Hour in digits 0-23	`09:08:07 -> 9`
{hour/2}	Hour in two digits 00-23	`09:08:07 -> 09`
{hour/ap}	Hour as 12-hour am/pm as digits 1-12	`13:08:07 -> 1`
{hour/2/ap}	Hour as 12-hour am/pm as two digits 01-12	`13:08:07 -> 01`
{am/pm}	Based on hour outputs "am" or "pm"	`13:08:07 -> pm`
{minute}	Minute in digits 0-59	`09:08:07 -> 8`
{minute/2}	Minute in two digits 00-59	`09:08:07 -> 08`
{second}	Second in digits 0-59	`09:08:07 -> 7`
{second/2}	Second in two digits 00-59	`09:08:07 -> 07`
{secondFraction}	Seconds fraction value.	`09:08:07.123456789123 -> 0.123456789123`
{secondFraction/2}	Seconds fraction 2 digit value.	`09:08:07.12 -> 0.12`
{secondFraction/7}	Seconds fraction 7 digit value.	`09:08:07.1234567 -> 0.1234567`
{weekday}	Full name of weekday	`Saturday -> Saturday`
{weekday/3}	Three letter of name of weekday	`Saturday -> Sat`
{weekday/2}	Two letter of name of weekday	`Saturday -> Sa`
{tzName}	Timezone name (can't be parsed)	`America/Los_Angeles`
{dstName}	Daylight savings name or standard name (can't be parsed)	`PDT`
{offsetDir}	Which direction is the offset going	`+` or `-`
{offsetHour/2}	Offset hour 00-12	`07`
{offsetMinute/2}	Offset minute 00-58	`00`
{offsetSecond/2}	Offset second 00-58	`00`

Any string that is not in {} considered to not be part of the format and is just inserted. "{year/4} and {month/2} and {day/2}" -> "1988 and 02 and 09"

Common Formats

American Date: 01/12/2020 "{month/2}/{day/2}/{year/4}"

Europian Date: 01.12.2020 "{year/4}.{month/2}.{day/2}"

American Time: 8:12pm "{hour/2/ap}:{minute/2}"

Europian Time: 20:12 "{hour/2}:{minute/2}"

ISO with fractional seconds: 2020-01-12T02:00:33.387824Z "{year/4}-{month/2}-{day/2}T{hour/2}:{minute/2}:{second}.{secondFraction/7}Z" parseIso/formatIso are faster but fractional seconds.

chrono/calendars

Calendars are more involved they support more features but come with complexity and are mutable.

I do not recommend storing Calendar objects in files or databases. Store Timestamp instead.

Most useful thing about calendars is that you can add years, months, days, hours, minutes or seconds to them.

var cal = Calendar(year: 2013, month: 12, day: 31, hour: 59, minute: 59, second: 59)
cal.add(Second, 20)
cal.sub(Minute, 15)
cal.add(Day, 40)
cal.sub(Month, 120)
cal.toStartOf(Day)
cal.toEndOf(Month)

It supports same format specification as Timestamp:

echo cal.formatCalendar("{month/2}/{day/2}/{year/4} {hour/2}:{minute/2}:{second/2}")

If you need extra features that calendars provide I recommending creating a Calendar with tsToCalendar doing your work and converting back with calendarToTs.

ts = cal.ts
cal = ts.calendar

Types

Calendar = object year*: int month*: int day*: int hour*: int minute*: int second*: int secondFraction*: float64 tzOffset*: float64 tzName*: string dstName*: string: Source Edit
TimeScale = enum Unknown, Second, Minute, Hour, Day, Week, Month, Quarter, Year: Source Edit

Procs

proc `$`(a: Calendar): string {....raises: [], tags: [], forbids: [].}: Display a Calendar as a ISO 8601 string. Source Edit
proc `<`(a, b: Calendar): bool {....raises: [], tags: [], forbids: [].}: Source Edit
proc `<=`(a, b: Calendar): bool {....raises: [], tags: [], forbids: [].}: Source Edit
proc `==`(a, b: Calendar): bool {....raises: [], tags: [], forbids: [].}: Source Edit
proc `>`(a, b: Calendar): bool {....raises: [], tags: [], forbids: [].}: Source Edit
proc `>=`(a, b: Calendar): bool {....raises: [], tags: [], forbids: [].}: Source Edit
proc add(cal: var Calendar; timeScale: TimeScale; number: float) {....raises: [], tags: [], forbids: [].}: Source Edit
proc add(cal: var Calendar; timeScale: TimeScale; number: int) {....raises: [], tags: [], forbids: [].}: Add a Day, Hour, Year... to calendar. Source Edit
proc compare(a, b: Calendar): int {....raises: [], tags: [], forbids: [].}: Compare two calendars. Source Edit
proc copy(cal: Calendar): Calendar {....raises: [], tags: [], forbids: [].}: Copies the calendar Source Edit
proc daysInMonth(cal: Calendar): int {....raises: [], tags: [], forbids: [].}: Get number of days in a calendar month. Source Edit
proc format(cal: Calendar; format: string): string {....raises: [ValueError], tags: [], forbids: [].}: Formats calendars to a string based on the format specification. Source Edit
proc formatIso(cal: Calendar): string {....raises: [], tags: [], forbids: [].}: Fastest way to convert Calendar to an ISO 8601 string representation. Use this instead of the format function when dealing with ISO format. Warning does minimal checking for speed. Make sure your calendar is valid. Note: Does not support fractional seconds. Source Edit
proc leapYear(cal: Calendar): bool {....raises: [], tags: [], forbids: [].}: Is the calendar in a leap year Source Edit
proc normalize(cal: var Calendar) {....raises: [], tags: [], forbids: [].}: Fixes any issues with calendar such as extra hours, extra days, and negative months. Source Edit
proc parseCalendar(format: string; value: string): Calendar {. ...raises: [ValueError], tags: [], forbids: [].}: Parses calendars from a string based on the format specification. Note that not all valid formats can be parsed, things such as weekdays or am/pm stuff without hours. Source Edit
proc parseCalendar(formats: seq[string]; value: string): Calendar {. ...raises: [ValueError], tags: [], forbids: [].}: Parses calendars from a seq of strings based on the format specification. Returns first format that parses or rases ValueError. Source Edit
proc parseIsoCalendar(iso: string): Calendar {....raises: [ValueError], tags: [], forbids: [].}: Fastest way to convert an ISO 8601 string representation to a Calendar. Use this instead of the parseTimestamp function when dealing with ISO format. Note: Does not support fractional seconds. Source Edit
proc parseTimeScale(timeScale: string): TimeScale {....raises: [], tags: [], forbids: [].}: Turns a time scale string like "second" to the enum Second. Source Edit
proc sub(cal: var Calendar; timeScale: TimeScale; number: float) {....raises: [], tags: [], forbids: [].}: Subtract a Day, Hour, Year... to calendar. Source Edit
proc sub(cal: var Calendar; timeScale: TimeScale; number: int) {....raises: [], tags: [], forbids: [].}: Subtract a Day, Hour, Year... to calendar. Source Edit
proc toEndOf(cal: var Calendar; timeScale: TimeScale) {....raises: [], tags: [], forbids: [].}: Move the calendar to an end of a time scale. Source Edit
proc toStartOf(cal: var Calendar; timeScale: TimeScale) {....raises: [], tags: [], forbids: [].}: Move the time stamp to a start of a time scale. Source Edit
proc weekday(cal: Calendar): int {....raises: [], tags: [], forbids: [].}: Get number of a weekday 0..6. Monday being 0 Source Edit

src/chrono/calendars

Format Specification

Common Formats

chrono/calendars

Types

Procs