Formatting

Formatting

Two layout languages are available. They produce the same output; pick the one your team already reads.

Method	Layout language	Example layout
Time.Format	pattern letters, like ICU or Java	yyyy/MM/dd HH:mm:ss
Time.TimeFormat	the Go reference time	2006/01/02 15:04:05

Predefined layouts

pt := ptime.Date(1394, ptime.Mehr, 2, 12, 59, 59, 52065090, ptime.Iran())

pt.Format(ptime.RFC3339)     // 1394-07-02T12:59:59+03:30
pt.Format(ptime.RFC3339Nano) // 1394-07-02T12:59:59.05206509+03:30
pt.Format(ptime.DateTime)    // 1394-07-02 12:59:59
pt.Format(ptime.DateOnly)    // 1394-07-02
pt.Format(ptime.TimeOnly)    // 12:59:59
pt.Format(ptime.Kitchen)     // 12:59 ب.ظ
pt.Format(ptime.LongDate)    // پنج‌شنبه 2 مهر 1394

Time.String() is Format(RFC3339Nano), so a Time prints sensibly anywhere fmt touches it.

Pattern letters

Anything that is not a pattern letter is copied verbatim.

Date

Pattern	Meaning	Example
yyyy, yyy, y	year, 4 digits	1394
yy	year, last 2 digits	94
MMM	Iranian month name	مهر
MMI	Dari month name	میزان
MM	month, 2 digits	07
M	month	7
dd	day of month, 2 digits	02
d	day of month	2
E	weekday name	پنج‌شنبه
e	weekday abbreviation	پ

Clock

Pattern	Meaning	Range
HH / H	hour, 24-hour	00-23 / 0-23
kk / k	hour, 24-hour, one based	01-24 / 1-24
hh / h	hour, 12-hour, one based	01-12 / 1-12
KK / K	hour, 12-hour, zero based	00-11 / 0-11
mm / m	minute	00-59 / 0-59
ss / s	second	00-59 / 0-59
A	12-hour marker	قبل از ظهر
a	short 12-hour marker	ق.ظ
n	part of the day	صبح

Fractional seconds

Pattern	Meaning	For 52065090 ns
S	milliseconds, 3 digits	052
ns	nanoseconds as a plain number	52065090
.000	fraction, 3 digits	.052
.000000	fraction, 6 digits	.052065
.000000000	fraction, 9 digits	.052065090
.999	fraction, 3 digits, trailing zeros removed	.052
.999999	fraction, 6 digits, trailing zeros removed	.052065
.999999999	fraction, 9 digits, trailing zeros removed	.05206509

A .999 style fraction is omitted entirely, dot included, when the fractional second is zero — the same rule the standard library uses.

Note. ns writes the nanosecond field as a decimal number, not as a zero padded fraction. .ns and .000000000 are different things: for 5 ns the first gives .5 and the second gives .000000005. Prefer the fraction patterns for anything that will be parsed again.

Derived fields

These are computed from the date. They format, and when parsing they are matched and discarded, since the other fields already determine them.

Pattern	Meaning
D	day of year
RD	days remaining in the year
w	week of year
rw	weeks remaining in the year
W	week of month
rd	days remaining in the month

Zone

Pattern	Meaning	Example
z	zone name	Asia/Tehran
Z	zone offset	+03:30

Reference time layouts

TimeFormat uses the same reference moment as the standard library, so a layout you already have for time.Time keeps working.

Layout	Meaning	Example
2006 / 06	year	1394 / 94
01 / 1	month	07 / 7
Jan, January	month name	مهر
02 / 2 / _2	day of month	07 / 7 / " 7"
Mon / Monday	weekday	پ / پنج‌شنبه
Morning	part of the day	صبح
15	hour, 24-hour	12
03 / 3	hour, 12-hour	12 / 12
04 / 4	minute	59 / 59
05 / 5	second	59 / 59
.000 … .999999999	fractional second	.052
PM / pm	12-hour marker	بعد از ظهر / ب.ظ
MST	zone name	Asia/Tehran
-0700, -07, -07:00, Z0700, Z07:00	zone offset	+0330

Iranian and Dari names

Format chooses explicitly: MMM is Iranian, MMI is Dari.

TimeFormat chooses by location — Dari when the location is Asia/Kabul, Iranian otherwise:

kabul := ptime.Date(1394, ptime.Mizan, 2, 0, 0, 0, 0, ptime.Afghanistan())
tehran := kabul.In(ptime.Iran())

kabul.TimeFormat("2 Jan 2006")  // 2 میزان 1394
tehran.TimeFormat("2 Jan 2006") // 2 مهر 1394

Avoiding the allocation

Format allocates one string. When you are writing into a buffer you already have — a bytes.Buffer, a log line, a JSON encoder — use the append forms:

buf = pt.AppendFormat(buf[:0], ptime.DateTime)
buf = pt.AppendTimeFormat(buf[:0], "2006-01-02")

Both take a byte slice and return the extended slice, exactly like time.Time.AppendFormat.