Source file src/time/format.go

     1  // Copyright 2010 The Go Authors. All rights reserved.
     2  // Use of this source code is governed by a BSD-style
     3  // license that can be found in the LICENSE file.
     4  
     5  package time
     6  
     7  import (
     8  	"errors"
     9  	"internal/stringslite"
    10  	_ "unsafe" // for linkname
    11  )
    12  
    13  // These are predefined layouts for use in [Time.Format] and [time.Parse].
    14  // The reference time used in these layouts is the specific time stamp:
    15  //
    16  //	01/02 03:04:05PM '06 -0700
    17  //
    18  // (January 2, 15:04:05, 2006, in time zone seven hours west of GMT).
    19  // That value is recorded as the constant named [Layout], listed below. As a Unix
    20  // time, this is 1136239445. Since MST is GMT-0700, the reference would be
    21  // printed by the Unix date command as:
    22  //
    23  //	Mon Jan 2 15:04:05 MST 2006
    24  //
    25  // It is a regrettable historic error that the date uses the American convention
    26  // of putting the numerical month before the day.
    27  //
    28  // The example for Time.Format demonstrates the working of the layout string
    29  // in detail and is a good reference.
    30  //
    31  // Note that the [RFC822], [RFC850], and [RFC1123] formats should be applied
    32  // only to local times. Applying them to UTC times will use "UTC" as the
    33  // time zone abbreviation, while strictly speaking those RFCs require the
    34  // use of "GMT" in that case.
    35  // When using the [RFC1123] or [RFC1123Z] formats for parsing, note that these
    36  // formats define a leading zero for the day-in-month portion, which is not
    37  // strictly allowed by RFC 1123. This will result in an error when parsing
    38  // date strings that occur in the first 9 days of a given month.
    39  // In general [RFC1123Z] should be used instead of [RFC1123] for servers
    40  // that insist on that format, and [RFC3339] should be preferred for new protocols.
    41  // [RFC3339], [RFC822], [RFC822Z], [RFC1123], and [RFC1123Z] are useful for formatting;
    42  // when used with time.Parse they do not accept all the time formats
    43  // permitted by the RFCs and they do accept time formats not formally defined.
    44  // The [RFC3339Nano] format removes trailing zeros from the seconds field
    45  // and thus may not sort correctly once formatted.
    46  //
    47  // Most programs can use one of the defined constants as the layout passed to
    48  // Format or Parse. The rest of this comment can be ignored unless you are
    49  // creating a custom layout string.
    50  //
    51  // To define your own format, write down what the reference time would look like
    52  // formatted your way; see the values of constants like [ANSIC], [StampMicro] or
    53  // [Kitchen] for examples. The model is to demonstrate what the reference time
    54  // looks like so that the Format and Parse methods can apply the same
    55  // transformation to a general time value.
    56  //
    57  // Here is a summary of the components of a layout string. Each element shows by
    58  // example the formatting of an element of the reference time. Only these values
    59  // are recognized. Text in the layout string that is not recognized as part of
    60  // the reference time is echoed verbatim during Format and expected to appear
    61  // verbatim in the input to Parse.
    62  //
    63  //	Year: "2006" "06"
    64  //	Month: "Jan" "January" "01" "1"
    65  //	Day of the week: "Mon" "Monday"
    66  //	Day of the month: "2" "_2" "02"
    67  //	Day of the year: "__2" "002"
    68  //	Hour: "15" "3" "03" (PM or AM)
    69  //	Minute: "4" "04"
    70  //	Second: "5" "05"
    71  //	AM/PM mark: "PM"
    72  //
    73  // Numeric time zone offsets format as follows:
    74  //
    75  //	"-0700"     ±hhmm
    76  //	"-07:00"    ±hh:mm
    77  //	"-07"       ±hh
    78  //	"-070000"   ±hhmmss
    79  //	"-07:00:00" ±hh:mm:ss
    80  //
    81  // Replacing the sign in the format with a Z triggers
    82  // the ISO 8601 behavior of printing Z instead of an
    83  // offset for the UTC zone. Thus:
    84  //
    85  //	"Z0700"      Z or ±hhmm
    86  //	"Z07:00"     Z or ±hh:mm
    87  //	"Z07"        Z or ±hh
    88  //	"Z070000"    Z or ±hhmmss
    89  //	"Z07:00:00"  Z or ±hh:mm:ss
    90  //
    91  // Within the format string, the underscores in "_2" and "__2" represent spaces
    92  // that may be replaced by digits if the following number has multiple digits,
    93  // for compatibility with fixed-width Unix time formats. A leading zero represents
    94  // a zero-padded value.
    95  //
    96  // The formats __2 and 002 are space-padded and zero-padded
    97  // three-character day of year; there is no unpadded day of year format.
    98  //
    99  // A comma or decimal point followed by one or more zeros represents
   100  // a fractional second, printed to the given number of decimal places.
   101  // A comma or decimal point followed by one or more nines represents
   102  // a fractional second, printed to the given number of decimal places, with
   103  // trailing zeros removed.
   104  // For example "15:04:05,000" or "15:04:05.000" formats or parses with
   105  // millisecond precision.
   106  //
   107  // Some valid layouts are invalid time values for time.Parse, due to formats
   108  // such as _ for space padding and Z for zone information.
   109  const (
   110  	Layout      = "01/02 03:04:05PM '06 -0700" // The reference time, in numerical order.
   111  	ANSIC       = "Mon Jan _2 15:04:05 2006"
   112  	UnixDate    = "Mon Jan _2 15:04:05 MST 2006"
   113  	RubyDate    = "Mon Jan 02 15:04:05 -0700 2006"
   114  	RFC822      = "02 Jan 06 15:04 MST"
   115  	RFC822Z     = "02 Jan 06 15:04 -0700" // RFC822 with numeric zone
   116  	RFC850      = "Monday, 02-Jan-06 15:04:05 MST"
   117  	RFC1123     = "Mon, 02 Jan 2006 15:04:05 MST"
   118  	RFC1123Z    = "Mon, 02 Jan 2006 15:04:05 -0700" // RFC1123 with numeric zone
   119  	RFC3339     = "2006-01-02T15:04:05Z07:00"
   120  	RFC3339Nano = "2006-01-02T15:04:05.999999999Z07:00"
   121  	Kitchen     = "3:04PM"
   122  	// Handy time stamps.
   123  	Stamp      = "Jan _2 15:04:05"
   124  	StampMilli = "Jan _2 15:04:05.000"
   125  	StampMicro = "Jan _2 15:04:05.000000"
   126  	StampNano  = "Jan _2 15:04:05.000000000"
   127  	DateTime   = "2006-01-02 15:04:05"
   128  	DateOnly   = "2006-01-02"
   129  	TimeOnly   = "15:04:05"
   130  )
   131  
   132  const (
   133  	_                        = iota
   134  	stdLongMonth             = iota + stdNeedDate  // "January"
   135  	stdMonth                                       // "Jan"
   136  	stdNumMonth                                    // "1"
   137  	stdZeroMonth                                   // "01"
   138  	stdLongWeekDay                                 // "Monday"
   139  	stdWeekDay                                     // "Mon"
   140  	stdDay                                         // "2"
   141  	stdUnderDay                                    // "_2"
   142  	stdZeroDay                                     // "02"
   143  	stdUnderYearDay          = iota + stdNeedYday  // "__2"
   144  	stdZeroYearDay                                 // "002"
   145  	stdHour                  = iota + stdNeedClock // "15"
   146  	stdHour12                                      // "3"
   147  	stdZeroHour12                                  // "03"
   148  	stdMinute                                      // "4"
   149  	stdZeroMinute                                  // "04"
   150  	stdSecond                                      // "5"
   151  	stdZeroSecond                                  // "05"
   152  	stdLongYear              = iota + stdNeedDate  // "2006"
   153  	stdYear                                        // "06"
   154  	stdPM                    = iota + stdNeedClock // "PM"
   155  	stdpm                                          // "pm"
   156  	stdTZ                    = iota                // "MST"
   157  	stdISO8601TZ                                   // "Z0700"  // prints Z for UTC
   158  	stdISO8601SecondsTZ                            // "Z070000"
   159  	stdISO8601ShortTZ                              // "Z07"
   160  	stdISO8601ColonTZ                              // "Z07:00" // prints Z for UTC
   161  	stdISO8601ColonSecondsTZ                       // "Z07:00:00"
   162  	stdNumTZ                                       // "-0700"  // always numeric
   163  	stdNumSecondsTz                                // "-070000"
   164  	stdNumShortTZ                                  // "-07"    // always numeric
   165  	stdNumColonTZ                                  // "-07:00" // always numeric
   166  	stdNumColonSecondsTZ                           // "-07:00:00"
   167  	stdFracSecond0                                 // ".0", ".00", ... , trailing zeros included
   168  	stdFracSecond9                                 // ".9", ".99", ..., trailing zeros omitted
   169  
   170  	stdNeedDate       = 1 << 8             // need month, day, year
   171  	stdNeedYday       = 1 << 9             // need yday
   172  	stdNeedClock      = 1 << 10            // need hour, minute, second
   173  	stdArgShift       = 16                 // extra argument in high bits, above low stdArgShift
   174  	stdSeparatorShift = 28                 // extra argument in high 4 bits for fractional second separators
   175  	stdMask           = 1<<stdArgShift - 1 // mask out argument
   176  )
   177  
   178  // std0x records the std values for "01", "02", ..., "06".
   179  var std0x = [...]int{stdZeroMonth, stdZeroDay, stdZeroHour12, stdZeroMinute, stdZeroSecond, stdYear}
   180  
   181  // startsWithLowerCase reports whether the string has a lower-case letter at the beginning.
   182  // Its purpose is to prevent matching strings like "Month" when looking for "Mon".
   183  func startsWithLowerCase(str string) bool {
   184  	if len(str) == 0 {
   185  		return false
   186  	}
   187  	c := str[0]
   188  	return 'a' <= c && c <= 'z'
   189  }
   190  
   191  // nextStdChunk finds the first occurrence of a std string in
   192  // layout and returns the text before, the std string, and the text after.
   193  //
   194  // nextStdChunk should be an internal detail,
   195  // but widely used packages access it using linkname.
   196  // Notable members of the hall of shame include:
   197  //   - github.com/searKing/golang/go
   198  //
   199  // Do not remove or change the type signature.
   200  // See go.dev/issue/67401.
   201  //
   202  //go:linkname nextStdChunk
   203  func nextStdChunk(layout string) (prefix string, std int, suffix string) {
   204  	for i := 0; i < len(layout); i++ {
   205  		switch c := int(layout[i]); c {
   206  		case 'J': // January, Jan
   207  			if len(layout) >= i+3 && layout[i:i+3] == "Jan" {
   208  				if len(layout) >= i+7 && layout[i:i+7] == "January" {
   209  					return layout[0:i], stdLongMonth, layout[i+7:]
   210  				}
   211  				if !startsWithLowerCase(layout[i+3:]) {
   212  					return layout[0:i], stdMonth, layout[i+3:]
   213  				}
   214  			}
   215  
   216  		case 'M': // Monday, Mon, MST
   217  			if len(layout) >= i+3 {
   218  				if layout[i:i+3] == "Mon" {
   219  					if len(layout) >= i+6 && layout[i:i+6] == "Monday" {
   220  						return layout[0:i], stdLongWeekDay, layout[i+6:]
   221  					}
   222  					if !startsWithLowerCase(layout[i+3:]) {
   223  						return layout[0:i], stdWeekDay, layout[i+3:]
   224  					}
   225  				}
   226  				if layout[i:i+3] == "MST" {
   227  					return layout[0:i], stdTZ, layout[i+3:]
   228  				}
   229  			}
   230  
   231  		case '0': // 01, 02, 03, 04, 05, 06, 002
   232  			if len(layout) >= i+2 && '1' <= layout[i+1] && layout[i+1] <= '6' {
   233  				return layout[0:i], std0x[layout[i+1]-'1'], layout[i+2:]
   234  			}
   235  			if len(layout) >= i+3 && layout[i+1] == '0' && layout[i+2] == '2' {
   236  				return layout[0:i], stdZeroYearDay, layout[i+3:]
   237  			}
   238  
   239  		case '1': // 15, 1
   240  			if len(layout) >= i+2 && layout[i+1] == '5' {
   241  				return layout[0:i], stdHour, layout[i+2:]
   242  			}
   243  			return layout[0:i], stdNumMonth, layout[i+1:]
   244  
   245  		case '2': // 2006, 2
   246  			if len(layout) >= i+4 && layout[i:i+4] == "2006" {
   247  				return layout[0:i], stdLongYear, layout[i+4:]
   248  			}
   249  			return layout[0:i], stdDay, layout[i+1:]
   250  
   251  		case '_': // _2, _2006, __2
   252  			if len(layout) >= i+2 && layout[i+1] == '2' {
   253  				// _2006 is really a literal _, followed by stdLongYear
   254  				if len(layout) >= i+5 && layout[i+1:i+5] == "2006" {
   255  					return layout[0 : i+1], stdLongYear, layout[i+5:]
   256  				}
   257  				return layout[0:i], stdUnderDay, layout[i+2:]
   258  			}
   259  			if len(layout) >= i+3 && layout[i+1] == '_' && layout[i+2] == '2' {
   260  				return layout[0:i], stdUnderYearDay, layout[i+3:]
   261  			}
   262  
   263  		case '3':
   264  			return layout[0:i], stdHour12, layout[i+1:]
   265  
   266  		case '4':
   267  			return layout[0:i], stdMinute, layout[i+1:]
   268  
   269  		case '5':
   270  			return layout[0:i], stdSecond, layout[i+1:]
   271  
   272  		case 'P': // PM
   273  			if len(layout) >= i+2 && layout[i+1] == 'M' {
   274  				return layout[0:i], stdPM, layout[i+2:]
   275  			}
   276  
   277  		case 'p': // pm
   278  			if len(layout) >= i+2 && layout[i+1] == 'm' {
   279  				return layout[0:i], stdpm, layout[i+2:]
   280  			}
   281  
   282  		case '-': // -070000, -07:00:00, -0700, -07:00, -07
   283  			if len(layout) >= i+7 && layout[i:i+7] == "-070000" {
   284  				return layout[0:i], stdNumSecondsTz, layout[i+7:]
   285  			}
   286  			if len(layout) >= i+9 && layout[i:i+9] == "-07:00:00" {
   287  				return layout[0:i], stdNumColonSecondsTZ, layout[i+9:]
   288  			}
   289  			if len(layout) >= i+5 && layout[i:i+5] == "-0700" {
   290  				return layout[0:i], stdNumTZ, layout[i+5:]
   291  			}
   292  			if len(layout) >= i+6 && layout[i:i+6] == "-07:00" {
   293  				return layout[0:i], stdNumColonTZ, layout[i+6:]
   294  			}
   295  			if len(layout) >= i+3 && layout[i:i+3] == "-07" {
   296  				return layout[0:i], stdNumShortTZ, layout[i+3:]
   297  			}
   298  
   299  		case 'Z': // Z070000, Z07:00:00, Z0700, Z07:00,
   300  			if len(layout) >= i+7 && layout[i:i+7] == "Z070000" {
   301  				return layout[0:i], stdISO8601SecondsTZ, layout[i+7:]
   302  			}
   303  			if len(layout) >= i+9 && layout[i:i+9] == "Z07:00:00" {
   304  				return layout[0:i], stdISO8601ColonSecondsTZ, layout[i+9:]
   305  			}
   306  			if len(layout) >= i+5 && layout[i:i+5] == "Z0700" {
   307  				return layout[0:i], stdISO8601TZ, layout[i+5:]
   308  			}
   309  			if len(layout) >= i+6 && layout[i:i+6] == "Z07:00" {
   310  				return layout[0:i], stdISO8601ColonTZ, layout[i+6:]
   311  			}
   312  			if len(layout) >= i+3 && layout[i:i+3] == "Z07" {
   313  				return layout[0:i], stdISO8601ShortTZ, layout[i+3:]
   314  			}
   315  
   316  		case '.', ',': // ,000, or .000, or ,999, or .999 - repeated digits for fractional seconds.
   317  			if i+1 < len(layout) && (layout[i+1] == '0' || layout[i+1] == '9') {
   318  				ch := layout[i+1]
   319  				j := i + 1
   320  				for j < len(layout) && layout[j] == ch {
   321  					j++
   322  				}
   323  				// String of digits must end here - only fractional second is all digits.
   324  				if !isDigit(layout, j) {
   325  					code := stdFracSecond0
   326  					if layout[i+1] == '9' {
   327  						code = stdFracSecond9
   328  					}
   329  					std := stdFracSecond(code, j-(i+1), c)
   330  					return layout[0:i], std, layout[j:]
   331  				}
   332  			}
   333  		}
   334  	}
   335  	return layout, 0, ""
   336  }
   337  
   338  var longDayNames = []string{
   339  	"Sunday",
   340  	"Monday",
   341  	"Tuesday",
   342  	"Wednesday",
   343  	"Thursday",
   344  	"Friday",
   345  	"Saturday",
   346  }
   347  
   348  var shortDayNames = []string{
   349  	"Sun",
   350  	"Mon",
   351  	"Tue",
   352  	"Wed",
   353  	"Thu",
   354  	"Fri",
   355  	"Sat",
   356  }
   357  
   358  var shortMonthNames = []string{
   359  	"Jan",
   360  	"Feb",
   361  	"Mar",
   362  	"Apr",
   363  	"May",
   364  	"Jun",
   365  	"Jul",
   366  	"Aug",
   367  	"Sep",
   368  	"Oct",
   369  	"Nov",
   370  	"Dec",
   371  }
   372  
   373  var longMonthNames = []string{
   374  	"January",
   375  	"February",
   376  	"March",
   377  	"April",
   378  	"May",
   379  	"June",
   380  	"July",
   381  	"August",
   382  	"September",
   383  	"October",
   384  	"November",
   385  	"December",
   386  }
   387  
   388  // match reports whether s1 and s2 match ignoring case.
   389  // It is assumed s1 and s2 are the same length.
   390  func match(s1, s2 string) bool {
   391  	for i := 0; i < len(s1); i++ {
   392  		c1 := s1[i]
   393  		c2 := s2[i]
   394  		if c1 != c2 {
   395  			// Switch to lower-case; 'a'-'A' is known to be a single bit.
   396  			c1 |= 'a' - 'A'
   397  			c2 |= 'a' - 'A'
   398  			if c1 != c2 || c1 < 'a' || c1 > 'z' {
   399  				return false
   400  			}
   401  		}
   402  	}
   403  	return true
   404  }
   405  
   406  func lookup(tab []string, val string) (int, string, error) {
   407  	for i, v := range tab {
   408  		if len(val) >= len(v) && match(val[:len(v)], v) {
   409  			return i, val[len(v):], nil
   410  		}
   411  	}
   412  	return -1, val, errBad
   413  }
   414  
   415  // appendInt appends the decimal form of x to b and returns the result.
   416  // If the decimal form (excluding sign) is shorter than width, the result is padded with leading 0's.
   417  // Duplicates functionality in strconv, but avoids dependency.
   418  func appendInt(b []byte, x int, width int) []byte {
   419  	u := uint(x)
   420  	if x < 0 {
   421  		b = append(b, '-')
   422  		u = uint(-x)
   423  	}
   424  
   425  	// 2-digit and 4-digit fields are the most common in time formats.
   426  	utod := func(u uint) byte { return '0' + byte(u) }
   427  	switch {
   428  	case width == 2 && u < 1e2:
   429  		return append(b, utod(u/1e1), utod(u%1e1))
   430  	case width == 4 && u < 1e4:
   431  		return append(b, utod(u/1e3), utod(u/1e2%1e1), utod(u/1e1%1e1), utod(u%1e1))
   432  	}
   433  
   434  	// Compute the number of decimal digits.
   435  	var n int
   436  	if u == 0 {
   437  		n = 1
   438  	}
   439  	for u2 := u; u2 > 0; u2 /= 10 {
   440  		n++
   441  	}
   442  
   443  	// Add 0-padding.
   444  	for pad := width - n; pad > 0; pad-- {
   445  		b = append(b, '0')
   446  	}
   447  
   448  	// Ensure capacity.
   449  	if len(b)+n <= cap(b) {
   450  		b = b[:len(b)+n]
   451  	} else {
   452  		b = append(b, make([]byte, n)...)
   453  	}
   454  
   455  	// Assemble decimal in reverse order.
   456  	i := len(b) - 1
   457  	for u >= 10 && i > 0 {
   458  		q := u / 10
   459  		b[i] = utod(u - q*10)
   460  		u = q
   461  		i--
   462  	}
   463  	b[i] = utod(u)
   464  	return b
   465  }
   466  
   467  // Never printed, just needs to be non-nil for return by atoi.
   468  var errAtoi = errors.New("time: invalid number")
   469  
   470  // Duplicates functionality in strconv, but avoids dependency.
   471  func atoi[bytes []byte | string](s bytes) (x int, err error) {
   472  	neg := false
   473  	if len(s) > 0 && (s[0] == '-' || s[0] == '+') {
   474  		neg = s[0] == '-'
   475  		s = s[1:]
   476  	}
   477  	q, rem, err := leadingInt(s)
   478  	x = int(q)
   479  	if err != nil || len(rem) > 0 {
   480  		return 0, errAtoi
   481  	}
   482  	if neg {
   483  		x = -x
   484  	}
   485  	return x, nil
   486  }
   487  
   488  // The "std" value passed to appendNano contains two packed fields: the number of
   489  // digits after the decimal and the separator character (period or comma).
   490  // These functions pack and unpack that variable.
   491  func stdFracSecond(code, n, c int) int {
   492  	// Use 0xfff to make the failure case even more absurd.
   493  	if c == '.' {
   494  		return code | ((n & 0xfff) << stdArgShift)
   495  	}
   496  	return code | ((n & 0xfff) << stdArgShift) | 1<<stdSeparatorShift
   497  }
   498  
   499  func digitsLen(std int) int {
   500  	return (std >> stdArgShift) & 0xfff
   501  }
   502  
   503  func separator(std int) byte {
   504  	if (std >> stdSeparatorShift) == 0 {
   505  		return '.'
   506  	}
   507  	return ','
   508  }
   509  
   510  // appendNano appends a fractional second, as nanoseconds, to b
   511  // and returns the result. The nanosec must be within [0, 999999999].
   512  func appendNano(b []byte, nanosec int, std int) []byte {
   513  	trim := std&stdMask == stdFracSecond9
   514  	n := digitsLen(std)
   515  	if trim && (n == 0 || nanosec == 0) {
   516  		return b
   517  	}
   518  	dot := separator(std)
   519  	b = append(b, dot)
   520  	b = appendInt(b, nanosec, 9)
   521  	if n < 9 {
   522  		b = b[:len(b)-9+n]
   523  	}
   524  	if trim {
   525  		for len(b) > 0 && b[len(b)-1] == '0' {
   526  			b = b[:len(b)-1]
   527  		}
   528  		if len(b) > 0 && b[len(b)-1] == dot {
   529  			b = b[:len(b)-1]
   530  		}
   531  	}
   532  	return b
   533  }
   534  
   535  // String returns the time formatted using the format string
   536  //
   537  //	"2006-01-02 15:04:05.999999999 -0700 MST"
   538  //
   539  // If the time has a monotonic clock reading, the returned string
   540  // includes a final field "m=±<value>", where value is the monotonic
   541  // clock reading formatted as a decimal number of seconds.
   542  //
   543  // The returned string is meant for debugging; for a stable serialized
   544  // representation, use t.MarshalText, t.MarshalBinary, or t.Format
   545  // with an explicit format string.
   546  func (t Time) String() string {
   547  	s := t.Format("2006-01-02 15:04:05.999999999 -0700 MST")
   548  
   549  	// Format monotonic clock reading as m=±ddd.nnnnnnnnn.
   550  	if t.wall&hasMonotonic != 0 {
   551  		m2 := uint64(t.ext)
   552  		sign := byte('+')
   553  		if t.ext < 0 {
   554  			sign = '-'
   555  			m2 = -m2
   556  		}
   557  		m1, m2 := m2/1e9, m2%1e9
   558  		m0, m1 := m1/1e9, m1%1e9
   559  		buf := make([]byte, 0, 24)
   560  		buf = append(buf, " m="...)
   561  		buf = append(buf, sign)
   562  		wid := 0
   563  		if m0 != 0 {
   564  			buf = appendInt(buf, int(m0), 0)
   565  			wid = 9
   566  		}
   567  		buf = appendInt(buf, int(m1), wid)
   568  		buf = append(buf, '.')
   569  		buf = appendInt(buf, int(m2), 9)
   570  		s += string(buf)
   571  	}
   572  	return s
   573  }
   574  
   575  // GoString implements [fmt.GoStringer] and formats t to be printed in Go source
   576  // code.
   577  func (t Time) GoString() string {
   578  	abs := t.absSec()
   579  	year, month, day := abs.days().date()
   580  	hour, minute, second := abs.clock()
   581  
   582  	buf := make([]byte, 0, len("time.Date(9999, time.September, 31, 23, 59, 59, 999999999, time.Local)"))
   583  	buf = append(buf, "time.Date("...)
   584  	buf = appendInt(buf, year, 0)
   585  	if January <= month && month <= December {
   586  		buf = append(buf, ", time."...)
   587  		buf = append(buf, longMonthNames[month-1]...)
   588  	} else {
   589  		// It's difficult to construct a time.Time with a date outside the
   590  		// standard range but we might as well try to handle the case.
   591  		buf = appendInt(buf, int(month), 0)
   592  	}
   593  	buf = append(buf, ", "...)
   594  	buf = appendInt(buf, day, 0)
   595  	buf = append(buf, ", "...)
   596  	buf = appendInt(buf, hour, 0)
   597  	buf = append(buf, ", "...)
   598  	buf = appendInt(buf, minute, 0)
   599  	buf = append(buf, ", "...)
   600  	buf = appendInt(buf, second, 0)
   601  	buf = append(buf, ", "...)
   602  	buf = appendInt(buf, t.Nanosecond(), 0)
   603  	buf = append(buf, ", "...)
   604  	switch loc := t.Location(); loc {
   605  	case UTC, nil:
   606  		buf = append(buf, "time.UTC"...)
   607  	case Local:
   608  		buf = append(buf, "time.Local"...)
   609  	default:
   610  		// there are several options for how we could display this, none of
   611  		// which are great:
   612  		//
   613  		// - use Location(loc.name), which is not technically valid syntax
   614  		// - use LoadLocation(loc.name), which will cause a syntax error when
   615  		// embedded and also would require us to escape the string without
   616  		// importing fmt or strconv
   617  		// - try to use FixedZone, which would also require escaping the name
   618  		// and would represent e.g. "America/Los_Angeles" daylight saving time
   619  		// shifts inaccurately
   620  		// - use the pointer format, which is no worse than you'd get with the
   621  		// old fmt.Sprintf("%#v", t) format.
   622  		//
   623  		// Of these, Location(loc.name) is the least disruptive. This is an edge
   624  		// case we hope not to hit too often.
   625  		buf = append(buf, `time.Location(`...)
   626  		buf = append(buf, quote(loc.name)...)
   627  		buf = append(buf, ')')
   628  	}
   629  	buf = append(buf, ')')
   630  	return string(buf)
   631  }
   632  
   633  // Format returns a textual representation of the time value formatted according
   634  // to the layout defined by the argument. See the documentation for the
   635  // constant called [Layout] to see how to represent the layout format.
   636  //
   637  // The executable example for [Time.Format] demonstrates the working
   638  // of the layout string in detail and is a good reference.
   639  func (t Time) Format(layout string) string {
   640  	const bufSize = 64
   641  	var b []byte
   642  	max := len(layout) + 10
   643  	if max < bufSize {
   644  		var buf [bufSize]byte
   645  		b = buf[:0]
   646  	} else {
   647  		b = make([]byte, 0, max)
   648  	}
   649  	b = t.AppendFormat(b, layout)
   650  	return string(b)
   651  }
   652  
   653  // AppendFormat is like [Time.Format] but appends the textual
   654  // representation to b and returns the extended buffer.
   655  func (t Time) AppendFormat(b []byte, layout string) []byte {
   656  	// Optimize for RFC3339 as it accounts for over half of all representations.
   657  	switch layout {
   658  	case RFC3339:
   659  		return t.appendFormatRFC3339(b, false)
   660  	case RFC3339Nano:
   661  		return t.appendFormatRFC3339(b, true)
   662  	default:
   663  		return t.appendFormat(b, layout)
   664  	}
   665  }
   666  
   667  func (t Time) appendFormat(b []byte, layout string) []byte {
   668  	name, offset, abs := t.locabs()
   669  	days := abs.days()
   670  
   671  	var (
   672  		year  int = -1
   673  		month Month
   674  		day   int
   675  		yday  int = -1
   676  		hour  int = -1
   677  		min   int
   678  		sec   int
   679  	)
   680  
   681  	// Each iteration generates one std value.
   682  	for layout != "" {
   683  		prefix, std, suffix := nextStdChunk(layout)
   684  		if prefix != "" {
   685  			b = append(b, prefix...)
   686  		}
   687  		if std == 0 {
   688  			break
   689  		}
   690  		layout = suffix
   691  
   692  		// Compute year, month, day if needed.
   693  		if year < 0 && std&stdNeedDate != 0 {
   694  			year, month, day = days.date()
   695  		}
   696  		if yday < 0 && std&stdNeedYday != 0 {
   697  			_, yday = days.yearYday()
   698  		}
   699  
   700  		// Compute hour, minute, second if needed.
   701  		if hour < 0 && std&stdNeedClock != 0 {
   702  			hour, min, sec = abs.clock()
   703  		}
   704  
   705  		switch std & stdMask {
   706  		case stdYear:
   707  			y := year
   708  			if y < 0 {
   709  				y = -y
   710  			}
   711  			b = appendInt(b, y%100, 2)
   712  		case stdLongYear:
   713  			b = appendInt(b, year, 4)
   714  		case stdMonth:
   715  			b = append(b, month.String()[:3]...)
   716  		case stdLongMonth:
   717  			m := month.String()
   718  			b = append(b, m...)
   719  		case stdNumMonth:
   720  			b = appendInt(b, int(month), 0)
   721  		case stdZeroMonth:
   722  			b = appendInt(b, int(month), 2)
   723  		case stdWeekDay:
   724  			b = append(b, days.weekday().String()[:3]...)
   725  		case stdLongWeekDay:
   726  			s := days.weekday().String()
   727  			b = append(b, s...)
   728  		case stdDay:
   729  			b = appendInt(b, day, 0)
   730  		case stdUnderDay:
   731  			if day < 10 {
   732  				b = append(b, ' ')
   733  			}
   734  			b = appendInt(b, day, 0)
   735  		case stdZeroDay:
   736  			b = appendInt(b, day, 2)
   737  		case stdUnderYearDay:
   738  			if yday < 100 {
   739  				b = append(b, ' ')
   740  				if yday < 10 {
   741  					b = append(b, ' ')
   742  				}
   743  			}
   744  			b = appendInt(b, yday, 0)
   745  		case stdZeroYearDay:
   746  			b = appendInt(b, yday, 3)
   747  		case stdHour:
   748  			b = appendInt(b, hour, 2)
   749  		case stdHour12:
   750  			// Noon is 12PM, midnight is 12AM.
   751  			hr := hour % 12
   752  			if hr == 0 {
   753  				hr = 12
   754  			}
   755  			b = appendInt(b, hr, 0)
   756  		case stdZeroHour12:
   757  			// Noon is 12PM, midnight is 12AM.
   758  			hr := hour % 12
   759  			if hr == 0 {
   760  				hr = 12
   761  			}
   762  			b = appendInt(b, hr, 2)
   763  		case stdMinute:
   764  			b = appendInt(b, min, 0)
   765  		case stdZeroMinute:
   766  			b = appendInt(b, min, 2)
   767  		case stdSecond:
   768  			b = appendInt(b, sec, 0)
   769  		case stdZeroSecond:
   770  			b = appendInt(b, sec, 2)
   771  		case stdPM:
   772  			if hour >= 12 {
   773  				b = append(b, "PM"...)
   774  			} else {
   775  				b = append(b, "AM"...)
   776  			}
   777  		case stdpm:
   778  			if hour >= 12 {
   779  				b = append(b, "pm"...)
   780  			} else {
   781  				b = append(b, "am"...)
   782  			}
   783  		case stdISO8601TZ, stdISO8601ColonTZ, stdISO8601SecondsTZ, stdISO8601ShortTZ, stdISO8601ColonSecondsTZ, stdNumTZ, stdNumColonTZ, stdNumSecondsTz, stdNumShortTZ, stdNumColonSecondsTZ:
   784  			// Ugly special case. We cheat and take the "Z" variants
   785  			// to mean "the time zone as formatted for ISO 8601".
   786  			if offset == 0 && (std == stdISO8601TZ || std == stdISO8601ColonTZ || std == stdISO8601SecondsTZ || std == stdISO8601ShortTZ || std == stdISO8601ColonSecondsTZ) {
   787  				b = append(b, 'Z')
   788  				break
   789  			}
   790  			zone := offset / 60 // convert to minutes
   791  			absoffset := offset
   792  			if zone < 0 {
   793  				b = append(b, '-')
   794  				zone = -zone
   795  				absoffset = -absoffset
   796  			} else {
   797  				b = append(b, '+')
   798  			}
   799  			b = appendInt(b, zone/60, 2)
   800  			if std == stdISO8601ColonTZ || std == stdNumColonTZ || std == stdISO8601ColonSecondsTZ || std == stdNumColonSecondsTZ {
   801  				b = append(b, ':')
   802  			}
   803  			if std != stdNumShortTZ && std != stdISO8601ShortTZ {
   804  				b = appendInt(b, zone%60, 2)
   805  			}
   806  
   807  			// append seconds if appropriate
   808  			if std == stdISO8601SecondsTZ || std == stdNumSecondsTz || std == stdNumColonSecondsTZ || std == stdISO8601ColonSecondsTZ {
   809  				if std == stdNumColonSecondsTZ || std == stdISO8601ColonSecondsTZ {
   810  					b = append(b, ':')
   811  				}
   812  				b = appendInt(b, absoffset%60, 2)
   813  			}
   814  
   815  		case stdTZ:
   816  			if name != "" {
   817  				b = append(b, name...)
   818  				break
   819  			}
   820  			// No time zone known for this time, but we must print one.
   821  			// Use the -0700 format.
   822  			zone := offset / 60 // convert to minutes
   823  			if zone < 0 {
   824  				b = append(b, '-')
   825  				zone = -zone
   826  			} else {
   827  				b = append(b, '+')
   828  			}
   829  			b = appendInt(b, zone/60, 2)
   830  			b = appendInt(b, zone%60, 2)
   831  		case stdFracSecond0, stdFracSecond9:
   832  			b = appendNano(b, t.Nanosecond(), std)
   833  		}
   834  	}
   835  	return b
   836  }
   837  
   838  var errBad = errors.New("bad value for field") // placeholder not passed to user
   839  
   840  // ParseError describes a problem parsing a time string.
   841  type ParseError struct {
   842  	Layout     string
   843  	Value      string
   844  	LayoutElem string
   845  	ValueElem  string
   846  	Message    string
   847  }
   848  
   849  // newParseError creates a new ParseError.
   850  // The provided value and valueElem are cloned to avoid escaping their values.
   851  func newParseError(layout, value, layoutElem, valueElem, message string) *ParseError {
   852  	valueCopy := stringslite.Clone(value)
   853  	valueElemCopy := stringslite.Clone(valueElem)
   854  	return &ParseError{layout, valueCopy, layoutElem, valueElemCopy, message}
   855  }
   856  
   857  // These are borrowed from unicode/utf8 and strconv and replicate behavior in
   858  // that package, since we can't take a dependency on either.
   859  const (
   860  	lowerhex  = "0123456789abcdef"
   861  	runeSelf  = 0x80
   862  	runeError = '\uFFFD'
   863  )
   864  
   865  func quote(s string) string {
   866  	buf := make([]byte, 1, len(s)+2) // slice will be at least len(s) + quotes
   867  	buf[0] = '"'
   868  	for i, c := range s {
   869  		if c >= runeSelf || c < ' ' {
   870  			// This means you are asking us to parse a time.Duration or
   871  			// time.Location with unprintable or non-ASCII characters in it.
   872  			// We don't expect to hit this case very often. We could try to
   873  			// reproduce strconv.Quote's behavior with full fidelity but
   874  			// given how rarely we expect to hit these edge cases, speed and
   875  			// conciseness are better.
   876  			var width int
   877  			if c == runeError {
   878  				width = 1
   879  				if i+2 < len(s) && s[i:i+3] == string(runeError) {
   880  					width = 3
   881  				}
   882  			} else {
   883  				width = len(string(c))
   884  			}
   885  			for j := 0; j < width; j++ {
   886  				buf = append(buf, `\x`...)
   887  				buf = append(buf, lowerhex[s[i+j]>>4])
   888  				buf = append(buf, lowerhex[s[i+j]&0xF])
   889  			}
   890  		} else {
   891  			if c == '"' || c == '\\' {
   892  				buf = append(buf, '\\')
   893  			}
   894  			buf = append(buf, byte(c))
   895  		}
   896  	}
   897  	buf = append(buf, '"')
   898  	return string(buf)
   899  }
   900  
   901  // Error returns the string representation of a ParseError.
   902  func (e *ParseError) Error() string {
   903  	if e.Message == "" {
   904  		return "parsing time " +
   905  			quote(e.Value) + " as " +
   906  			quote(e.Layout) + ": cannot parse " +
   907  			quote(e.ValueElem) + " as " +
   908  			quote(e.LayoutElem)
   909  	}
   910  	return "parsing time " +
   911  		quote(e.Value) + e.Message
   912  }
   913  
   914  // isDigit reports whether s[i] is in range and is a decimal digit.
   915  func isDigit[bytes []byte | string](s bytes, i int) bool {
   916  	if len(s) <= i {
   917  		return false
   918  	}
   919  	c := s[i]
   920  	return '0' <= c && c <= '9'
   921  }
   922  
   923  // getnum parses s[0:1] or s[0:2] (fixed forces s[0:2])
   924  // as a decimal integer and returns the integer and the
   925  // remainder of the string.
   926  func getnum(s string, fixed bool) (int, string, error) {
   927  	if !isDigit(s, 0) {
   928  		return 0, s, errBad
   929  	}
   930  	if !isDigit(s, 1) {
   931  		if fixed {
   932  			return 0, s, errBad
   933  		}
   934  		return int(s[0] - '0'), s[1:], nil
   935  	}
   936  	return int(s[0]-'0')*10 + int(s[1]-'0'), s[2:], nil
   937  }
   938  
   939  // getnum3 parses s[0:1], s[0:2], or s[0:3] (fixed forces s[0:3])
   940  // as a decimal integer and returns the integer and the remainder
   941  // of the string.
   942  func getnum3(s string, fixed bool) (int, string, error) {
   943  	var n, i int
   944  	for i = 0; i < 3 && isDigit(s, i); i++ {
   945  		n = n*10 + int(s[i]-'0')
   946  	}
   947  	if i == 0 || fixed && i != 3 {
   948  		return 0, s, errBad
   949  	}
   950  	return n, s[i:], nil
   951  }
   952  
   953  func cutspace(s string) string {
   954  	for len(s) > 0 && s[0] == ' ' {
   955  		s = s[1:]
   956  	}
   957  	return s
   958  }
   959  
   960  // skip removes the given prefix from value,
   961  // treating runs of space characters as equivalent.
   962  func skip(value, prefix string) (string, error) {
   963  	for len(prefix) > 0 {
   964  		if prefix[0] == ' ' {
   965  			if len(value) > 0 && value[0] != ' ' {
   966  				return value, errBad
   967  			}
   968  			prefix = cutspace(prefix)
   969  			value = cutspace(value)
   970  			continue
   971  		}
   972  		if len(value) == 0 || value[0] != prefix[0] {
   973  			return value, errBad
   974  		}
   975  		prefix = prefix[1:]
   976  		value = value[1:]
   977  	}
   978  	return value, nil
   979  }
   980  
   981  // Parse parses a formatted string and returns the time value it represents.
   982  // See the documentation for the constant called [Layout] to see how to
   983  // represent the format. The second argument must be parseable using
   984  // the format string (layout) provided as the first argument.
   985  //
   986  // The example for [Time.Format] demonstrates the working of the layout string
   987  // in detail and is a good reference.
   988  //
   989  // When parsing (only), the input may contain a fractional second
   990  // field immediately after the seconds field, even if the layout does not
   991  // signify its presence. In that case either a comma or a decimal point
   992  // followed by a maximal series of digits is parsed as a fractional second.
   993  // Fractional seconds are truncated to nanosecond precision.
   994  //
   995  // Elements omitted from the layout are assumed to be zero or, when
   996  // zero is impossible, one, so parsing "3:04pm" returns the time
   997  // corresponding to Jan 1, year 0, 15:04:00 UTC (note that because the year is
   998  // 0, this time is before the zero Time).
   999  // Years must be in the range 0000..9999. The day of the week is checked
  1000  // for syntax but it is otherwise ignored.
  1001  //
  1002  // For layouts specifying the two-digit year 06, a value NN >= 69 will be treated
  1003  // as 19NN and a value NN < 69 will be treated as 20NN.
  1004  //
  1005  // Timestamps representing leap seconds (second 60) cannot be parsed.
  1006  // These are not representable by [Time].
  1007  //
  1008  // The remainder of this comment describes the handling of time zones.
  1009  //
  1010  // In the absence of a time zone indicator, Parse returns a time in UTC.
  1011  //
  1012  // When parsing a time with a zone offset like -0700, if the offset corresponds
  1013  // to a time zone used by the current location ([Local]), then Parse uses that
  1014  // location and zone in the returned time. Otherwise it records the time as
  1015  // being in a fabricated location with time fixed at the given zone offset.
  1016  //
  1017  // When parsing a time with a zone abbreviation like MST, if the zone abbreviation
  1018  // has a defined offset in the current location, then that offset is used.
  1019  // The zone abbreviation "UTC" is recognized as UTC regardless of location.
  1020  // If the zone abbreviation is unknown, Parse records the time as being
  1021  // in a fabricated location with the given zone abbreviation and a zero offset.
  1022  // This choice means that such a time can be parsed and reformatted with the
  1023  // same layout losslessly, but the exact instant used in the representation will
  1024  // differ by the actual zone offset. To avoid such problems, prefer time layouts
  1025  // that use a numeric zone offset, or use [ParseInLocation].
  1026  func Parse(layout, value string) (Time, error) {
  1027  	// Optimize for RFC3339 as it accounts for over half of all representations.
  1028  	if layout == RFC3339 || layout == RFC3339Nano {
  1029  		if t, ok := parseRFC3339(value, Local); ok {
  1030  			return t, nil
  1031  		}
  1032  	}
  1033  	return parse(layout, value, UTC, Local)
  1034  }
  1035  
  1036  // ParseInLocation is like Parse but differs in two important ways.
  1037  // First, in the absence of time zone information, Parse interprets a time as UTC;
  1038  // ParseInLocation interprets the time as in the given location.
  1039  // Second, when given a zone offset or abbreviation, Parse tries to match it
  1040  // against the Local location; ParseInLocation uses the given location.
  1041  func ParseInLocation(layout, value string, loc *Location) (Time, error) {
  1042  	// Optimize for RFC3339 as it accounts for over half of all representations.
  1043  	if layout == RFC3339 || layout == RFC3339Nano {
  1044  		if t, ok := parseRFC3339(value, loc); ok {
  1045  			return t, nil
  1046  		}
  1047  	}
  1048  	return parse(layout, value, loc, loc)
  1049  }
  1050  
  1051  func parse(layout, value string, defaultLocation, local *Location) (Time, error) {
  1052  	alayout, avalue := layout, value
  1053  	rangeErrString := "" // set if a value is out of range
  1054  	amSet := false       // do we need to subtract 12 from the hour for midnight?
  1055  	pmSet := false       // do we need to add 12 to the hour?
  1056  
  1057  	// Time being constructed.
  1058  	var (
  1059  		year       int
  1060  		month      int = -1
  1061  		day        int = -1
  1062  		yday       int = -1
  1063  		hour       int
  1064  		min        int
  1065  		sec        int
  1066  		nsec       int
  1067  		z          *Location
  1068  		zoneOffset int = -1
  1069  		zoneName   string
  1070  	)
  1071  
  1072  	// Each iteration processes one std value.
  1073  	for {
  1074  		var err error
  1075  		prefix, std, suffix := nextStdChunk(layout)
  1076  		stdstr := layout[len(prefix) : len(layout)-len(suffix)]
  1077  		value, err = skip(value, prefix)
  1078  		if err != nil {
  1079  			return Time{}, newParseError(alayout, avalue, prefix, value, "")
  1080  		}
  1081  		if std == 0 {
  1082  			if len(value) != 0 {
  1083  				return Time{}, newParseError(alayout, avalue, "", value, ": extra text: "+quote(value))
  1084  			}
  1085  			break
  1086  		}
  1087  		layout = suffix
  1088  		var p string
  1089  		hold := value
  1090  		switch std & stdMask {
  1091  		case stdYear:
  1092  			if len(value) < 2 {
  1093  				err = errBad
  1094  				break
  1095  			}
  1096  			p, value = value[0:2], value[2:]
  1097  			year, err = atoi(p)
  1098  			if err != nil {
  1099  				break
  1100  			}
  1101  			if year >= 69 { // Unix time starts Dec 31 1969 in some time zones
  1102  				year += 1900
  1103  			} else {
  1104  				year += 2000
  1105  			}
  1106  		case stdLongYear:
  1107  			if len(value) < 4 || !isDigit(value, 0) {
  1108  				err = errBad
  1109  				break
  1110  			}
  1111  			p, value = value[0:4], value[4:]
  1112  			year, err = atoi(p)
  1113  		case stdMonth:
  1114  			month, value, err = lookup(shortMonthNames, value)
  1115  			month++
  1116  		case stdLongMonth:
  1117  			month, value, err = lookup(longMonthNames, value)
  1118  			month++
  1119  		case stdNumMonth, stdZeroMonth:
  1120  			month, value, err = getnum(value, std == stdZeroMonth)
  1121  			if err == nil && (month <= 0 || 12 < month) {
  1122  				rangeErrString = "month"
  1123  			}
  1124  		case stdWeekDay:
  1125  			// Ignore weekday except for error checking.
  1126  			_, value, err = lookup(shortDayNames, value)
  1127  		case stdLongWeekDay:
  1128  			_, value, err = lookup(longDayNames, value)
  1129  		case stdDay, stdUnderDay, stdZeroDay:
  1130  			if std == stdUnderDay && len(value) > 0 && value[0] == ' ' {
  1131  				value = value[1:]
  1132  			}
  1133  			day, value, err = getnum(value, std == stdZeroDay)
  1134  			// Note that we allow any one- or two-digit day here.
  1135  			// The month, day, year combination is validated after we've completed parsing.
  1136  		case stdUnderYearDay, stdZeroYearDay:
  1137  			for i := 0; i < 2; i++ {
  1138  				if std == stdUnderYearDay && len(value) > 0 && value[0] == ' ' {
  1139  					value = value[1:]
  1140  				}
  1141  			}
  1142  			yday, value, err = getnum3(value, std == stdZeroYearDay)
  1143  			// Note that we allow any one-, two-, or three-digit year-day here.
  1144  			// The year-day, year combination is validated after we've completed parsing.
  1145  		case stdHour:
  1146  			hour, value, err = getnum(value, false)
  1147  			if hour < 0 || 24 <= hour {
  1148  				rangeErrString = "hour"
  1149  			}
  1150  		case stdHour12, stdZeroHour12:
  1151  			hour, value, err = getnum(value, std == stdZeroHour12)
  1152  			if hour < 0 || 12 < hour {
  1153  				rangeErrString = "hour"
  1154  			}
  1155  		case stdMinute, stdZeroMinute:
  1156  			min, value, err = getnum(value, std == stdZeroMinute)
  1157  			if min < 0 || 60 <= min {
  1158  				rangeErrString = "minute"
  1159  			}
  1160  		case stdSecond, stdZeroSecond:
  1161  			sec, value, err = getnum(value, std == stdZeroSecond)
  1162  			if err != nil {
  1163  				break
  1164  			}
  1165  			if sec < 0 || 60 <= sec {
  1166  				rangeErrString = "second"
  1167  				break
  1168  			}
  1169  			// Special case: do we have a fractional second but no
  1170  			// fractional second in the format?
  1171  			if len(value) >= 2 && commaOrPeriod(value[0]) && isDigit(value, 1) {
  1172  				_, std, _ = nextStdChunk(layout)
  1173  				std &= stdMask
  1174  				if std == stdFracSecond0 || std == stdFracSecond9 {
  1175  					// Fractional second in the layout; proceed normally
  1176  					break
  1177  				}
  1178  				// No fractional second in the layout but we have one in the input.
  1179  				n := 2
  1180  				for ; n < len(value) && isDigit(value, n); n++ {
  1181  				}
  1182  				nsec, rangeErrString, err = parseNanoseconds(value, n)
  1183  				value = value[n:]
  1184  			}
  1185  		case stdPM:
  1186  			if len(value) < 2 {
  1187  				err = errBad
  1188  				break
  1189  			}
  1190  			p, value = value[0:2], value[2:]
  1191  			switch p {
  1192  			case "PM":
  1193  				pmSet = true
  1194  			case "AM":
  1195  				amSet = true
  1196  			default:
  1197  				err = errBad
  1198  			}
  1199  		case stdpm:
  1200  			if len(value) < 2 {
  1201  				err = errBad
  1202  				break
  1203  			}
  1204  			p, value = value[0:2], value[2:]
  1205  			switch p {
  1206  			case "pm":
  1207  				pmSet = true
  1208  			case "am":
  1209  				amSet = true
  1210  			default:
  1211  				err = errBad
  1212  			}
  1213  		case stdISO8601TZ, stdISO8601ShortTZ, stdISO8601ColonTZ, stdISO8601SecondsTZ, stdISO8601ColonSecondsTZ:
  1214  			if len(value) >= 1 && value[0] == 'Z' {
  1215  				value = value[1:]
  1216  				z = UTC
  1217  				break
  1218  			}
  1219  			fallthrough
  1220  		case stdNumTZ, stdNumShortTZ, stdNumColonTZ, stdNumSecondsTz, stdNumColonSecondsTZ:
  1221  			var sign, hour, min, seconds string
  1222  			if std == stdISO8601ColonTZ || std == stdNumColonTZ {
  1223  				if len(value) < 6 {
  1224  					err = errBad
  1225  					break
  1226  				}
  1227  				if value[3] != ':' {
  1228  					err = errBad
  1229  					break
  1230  				}
  1231  				sign, hour, min, seconds, value = value[0:1], value[1:3], value[4:6], "00", value[6:]
  1232  			} else if std == stdNumShortTZ || std == stdISO8601ShortTZ {
  1233  				if len(value) < 3 {
  1234  					err = errBad
  1235  					break
  1236  				}
  1237  				sign, hour, min, seconds, value = value[0:1], value[1:3], "00", "00", value[3:]
  1238  			} else if std == stdISO8601ColonSecondsTZ || std == stdNumColonSecondsTZ {
  1239  				if len(value) < 9 {
  1240  					err = errBad
  1241  					break
  1242  				}
  1243  				if value[3] != ':' || value[6] != ':' {
  1244  					err = errBad
  1245  					break
  1246  				}
  1247  				sign, hour, min, seconds, value = value[0:1], value[1:3], value[4:6], value[7:9], value[9:]
  1248  			} else if std == stdISO8601SecondsTZ || std == stdNumSecondsTz {
  1249  				if len(value) < 7 {
  1250  					err = errBad
  1251  					break
  1252  				}
  1253  				sign, hour, min, seconds, value = value[0:1], value[1:3], value[3:5], value[5:7], value[7:]
  1254  			} else {
  1255  				if len(value) < 5 {
  1256  					err = errBad
  1257  					break
  1258  				}
  1259  				sign, hour, min, seconds, value = value[0:1], value[1:3], value[3:5], "00", value[5:]
  1260  			}
  1261  			var hr, mm, ss int
  1262  			hr, _, err = getnum(hour, true)
  1263  			if err == nil {
  1264  				mm, _, err = getnum(min, true)
  1265  				if err == nil {
  1266  					ss, _, err = getnum(seconds, true)
  1267  				}
  1268  			}
  1269  
  1270  			// The range test use > rather than >=,
  1271  			// as some people do write offsets of 24 hours
  1272  			// or 60 minutes or 60 seconds.
  1273  			if hr > 24 {
  1274  				rangeErrString = "time zone offset hour"
  1275  			}
  1276  			if mm > 60 {
  1277  				rangeErrString = "time zone offset minute"
  1278  			}
  1279  			if ss > 60 {
  1280  				rangeErrString = "time zone offset second"
  1281  			}
  1282  
  1283  			zoneOffset = (hr*60+mm)*60 + ss // offset is in seconds
  1284  			switch sign[0] {
  1285  			case '+':
  1286  			case '-':
  1287  				zoneOffset = -zoneOffset
  1288  			default:
  1289  				err = errBad
  1290  			}
  1291  		case stdTZ:
  1292  			// Does it look like a time zone?
  1293  			if len(value) >= 3 && value[0:3] == "UTC" {
  1294  				z = UTC
  1295  				value = value[3:]
  1296  				break
  1297  			}
  1298  			n, ok := parseTimeZone(value)
  1299  			if !ok {
  1300  				err = errBad
  1301  				break
  1302  			}
  1303  			zoneName, value = value[:n], value[n:]
  1304  
  1305  		case stdFracSecond0:
  1306  			// stdFracSecond0 requires the exact number of digits as specified in
  1307  			// the layout.
  1308  			ndigit := 1 + digitsLen(std)
  1309  			if len(value) < ndigit {
  1310  				err = errBad
  1311  				break
  1312  			}
  1313  			nsec, rangeErrString, err = parseNanoseconds(value, ndigit)
  1314  			value = value[ndigit:]
  1315  
  1316  		case stdFracSecond9:
  1317  			if len(value) < 2 || !commaOrPeriod(value[0]) || value[1] < '0' || '9' < value[1] {
  1318  				// Fractional second omitted.
  1319  				break
  1320  			}
  1321  			// Take any number of digits, even more than asked for,
  1322  			// because it is what the stdSecond case would do.
  1323  			i := 0
  1324  			for i+1 < len(value) && '0' <= value[i+1] && value[i+1] <= '9' {
  1325  				i++
  1326  			}
  1327  			nsec, rangeErrString, err = parseNanoseconds(value, 1+i)
  1328  			value = value[1+i:]
  1329  		}
  1330  		if rangeErrString != "" {
  1331  			return Time{}, newParseError(alayout, avalue, stdstr, value, ": "+rangeErrString+" out of range")
  1332  		}
  1333  		if err != nil {
  1334  			return Time{}, newParseError(alayout, avalue, stdstr, hold, "")
  1335  		}
  1336  	}
  1337  	if pmSet && hour < 12 {
  1338  		hour += 12
  1339  	} else if amSet && hour == 12 {
  1340  		hour = 0
  1341  	}
  1342  
  1343  	// Convert yday to day, month.
  1344  	if yday >= 0 {
  1345  		var d int
  1346  		var m int
  1347  		if isLeap(year) {
  1348  			if yday == 31+29 {
  1349  				m = int(February)
  1350  				d = 29
  1351  			} else if yday > 31+29 {
  1352  				yday--
  1353  			}
  1354  		}
  1355  		if yday < 1 || yday > 365 {
  1356  			return Time{}, newParseError(alayout, avalue, "", value, ": day-of-year out of range")
  1357  		}
  1358  		if m == 0 {
  1359  			m = (yday-1)/31 + 1
  1360  			if daysBefore(Month(m+1)) < yday {
  1361  				m++
  1362  			}
  1363  			d = yday - daysBefore(Month(m))
  1364  		}
  1365  		// If month, day already seen, yday's m, d must match.
  1366  		// Otherwise, set them from m, d.
  1367  		if month >= 0 && month != m {
  1368  			return Time{}, newParseError(alayout, avalue, "", value, ": day-of-year does not match month")
  1369  		}
  1370  		month = m
  1371  		if day >= 0 && day != d {
  1372  			return Time{}, newParseError(alayout, avalue, "", value, ": day-of-year does not match day")
  1373  		}
  1374  		day = d
  1375  	} else {
  1376  		if month < 0 {
  1377  			month = int(January)
  1378  		}
  1379  		if day < 0 {
  1380  			day = 1
  1381  		}
  1382  	}
  1383  
  1384  	// Validate the day of the month.
  1385  	if day < 1 || day > daysIn(Month(month), year) {
  1386  		return Time{}, newParseError(alayout, avalue, "", value, ": day out of range")
  1387  	}
  1388  
  1389  	if z != nil {
  1390  		return Date(year, Month(month), day, hour, min, sec, nsec, z), nil
  1391  	}
  1392  
  1393  	if zoneOffset != -1 {
  1394  		t := Date(year, Month(month), day, hour, min, sec, nsec, UTC)
  1395  		t.addSec(-int64(zoneOffset))
  1396  
  1397  		// Look for local zone with the given offset.
  1398  		// If that zone was in effect at the given time, use it.
  1399  		name, offset, _, _, _ := local.lookup(t.unixSec())
  1400  		if offset == zoneOffset && (zoneName == "" || name == zoneName) {
  1401  			t.setLoc(local)
  1402  			return t, nil
  1403  		}
  1404  
  1405  		// Otherwise create fake zone to record offset.
  1406  		zoneNameCopy := stringslite.Clone(zoneName) // avoid leaking the input value
  1407  		t.setLoc(FixedZone(zoneNameCopy, zoneOffset))
  1408  		return t, nil
  1409  	}
  1410  
  1411  	if zoneName != "" {
  1412  		t := Date(year, Month(month), day, hour, min, sec, nsec, UTC)
  1413  		// Look for local zone with the given offset.
  1414  		// If that zone was in effect at the given time, use it.
  1415  		offset, ok := local.lookupName(zoneName, t.unixSec())
  1416  		if ok {
  1417  			t.addSec(-int64(offset))
  1418  			t.setLoc(local)
  1419  			return t, nil
  1420  		}
  1421  
  1422  		// Otherwise, create fake zone with unknown offset.
  1423  		if len(zoneName) > 3 && zoneName[:3] == "GMT" {
  1424  			offset, _ = atoi(zoneName[3:]) // Guaranteed OK by parseGMT.
  1425  			offset *= 3600
  1426  		}
  1427  		zoneNameCopy := stringslite.Clone(zoneName) // avoid leaking the input value
  1428  		t.setLoc(FixedZone(zoneNameCopy, offset))
  1429  		return t, nil
  1430  	}
  1431  
  1432  	// Otherwise, fall back to default.
  1433  	return Date(year, Month(month), day, hour, min, sec, nsec, defaultLocation), nil
  1434  }
  1435  
  1436  // parseTimeZone parses a time zone string and returns its length. Time zones
  1437  // are human-generated and unpredictable. We can't do precise error checking.
  1438  // On the other hand, for a correct parse there must be a time zone at the
  1439  // beginning of the string, so it's almost always true that there's one
  1440  // there. We look at the beginning of the string for a run of upper-case letters.
  1441  // If there are more than 5, it's an error.
  1442  // If there are 4 or 5 and the last is a T, it's a time zone.
  1443  // If there are 3, it's a time zone.
  1444  // Otherwise, other than special cases, it's not a time zone.
  1445  // GMT is special because it can have an hour offset.
  1446  func parseTimeZone(value string) (length int, ok bool) {
  1447  	if len(value) < 3 {
  1448  		return 0, false
  1449  	}
  1450  	// Special case 1: ChST and MeST are the only zones with a lower-case letter.
  1451  	if len(value) >= 4 && (value[:4] == "ChST" || value[:4] == "MeST") {
  1452  		return 4, true
  1453  	}
  1454  	// Special case 2: GMT may have an hour offset; treat it specially.
  1455  	if value[:3] == "GMT" {
  1456  		length = parseGMT(value)
  1457  		return length, true
  1458  	}
  1459  	// Special Case 3: Some time zones are not named, but have +/-00 format
  1460  	if value[0] == '+' || value[0] == '-' {
  1461  		length = parseSignedOffset(value)
  1462  		ok := length > 0 // parseSignedOffset returns 0 in case of bad input
  1463  		return length, ok
  1464  	}
  1465  	// How many upper-case letters are there? Need at least three, at most five.
  1466  	var nUpper int
  1467  	for nUpper = 0; nUpper < 6; nUpper++ {
  1468  		if nUpper >= len(value) {
  1469  			break
  1470  		}
  1471  		if c := value[nUpper]; c < 'A' || 'Z' < c {
  1472  			break
  1473  		}
  1474  	}
  1475  	switch nUpper {
  1476  	case 0, 1, 2, 6:
  1477  		return 0, false
  1478  	case 5: // Must end in T to match.
  1479  		if value[4] == 'T' {
  1480  			return 5, true
  1481  		}
  1482  	case 4:
  1483  		// Must end in T, except one special case.
  1484  		if value[3] == 'T' || value[:4] == "WITA" {
  1485  			return 4, true
  1486  		}
  1487  	case 3:
  1488  		return 3, true
  1489  	}
  1490  	return 0, false
  1491  }
  1492  
  1493  // parseGMT parses a GMT time zone. The input string is known to start "GMT".
  1494  // The function checks whether that is followed by a sign and a number in the
  1495  // range -23 through +23 excluding zero.
  1496  func parseGMT(value string) int {
  1497  	value = value[3:]
  1498  	if len(value) == 0 {
  1499  		return 3
  1500  	}
  1501  
  1502  	return 3 + parseSignedOffset(value)
  1503  }
  1504  
  1505  // parseSignedOffset parses a signed timezone offset (e.g. "+03" or "-04").
  1506  // The function checks for a signed number in the range -23 through +23 excluding zero.
  1507  // Returns length of the found offset string or 0 otherwise.
  1508  func parseSignedOffset(value string) int {
  1509  	sign := value[0]
  1510  	if sign != '-' && sign != '+' {
  1511  		return 0
  1512  	}
  1513  	x, rem, err := leadingInt(value[1:])
  1514  
  1515  	// fail if nothing consumed by leadingInt
  1516  	if err != nil || value[1:] == rem {
  1517  		return 0
  1518  	}
  1519  	if x > 23 {
  1520  		return 0
  1521  	}
  1522  	return len(value) - len(rem)
  1523  }
  1524  
  1525  func commaOrPeriod(b byte) bool {
  1526  	return b == '.' || b == ','
  1527  }
  1528  
  1529  func parseNanoseconds[bytes []byte | string](value bytes, nbytes int) (ns int, rangeErrString string, err error) {
  1530  	if !commaOrPeriod(value[0]) {
  1531  		err = errBad
  1532  		return
  1533  	}
  1534  	if nbytes > 10 {
  1535  		value = value[:10]
  1536  		nbytes = 10
  1537  	}
  1538  	if ns, err = atoi(value[1:nbytes]); err != nil {
  1539  		return
  1540  	}
  1541  	if ns < 0 {
  1542  		rangeErrString = "fractional second"
  1543  		return
  1544  	}
  1545  	// We need nanoseconds, which means scaling by the number
  1546  	// of missing digits in the format, maximum length 10.
  1547  	scaleDigits := 10 - nbytes
  1548  	for i := 0; i < scaleDigits; i++ {
  1549  		ns *= 10
  1550  	}
  1551  	return
  1552  }
  1553  
  1554  var errLeadingInt = errors.New("time: bad [0-9]*") // never printed
  1555  
  1556  // leadingInt consumes the leading [0-9]* from s.
  1557  func leadingInt[bytes []byte | string](s bytes) (x uint64, rem bytes, err error) {
  1558  	i := 0
  1559  	for ; i < len(s); i++ {
  1560  		c := s[i]
  1561  		if c < '0' || c > '9' {
  1562  			break
  1563  		}
  1564  		if x > 1<<63/10 {
  1565  			// overflow
  1566  			return 0, rem, errLeadingInt
  1567  		}
  1568  		x = x*10 + uint64(c) - '0'
  1569  		if x > 1<<63 {
  1570  			// overflow
  1571  			return 0, rem, errLeadingInt
  1572  		}
  1573  	}
  1574  	return x, s[i:], nil
  1575  }
  1576  
  1577  // leadingFraction consumes the leading [0-9]* from s.
  1578  // It is used only for fractions, so does not return an error on overflow,
  1579  // it just stops accumulating precision.
  1580  func leadingFraction(s string) (x uint64, scale float64, rem string) {
  1581  	i := 0
  1582  	scale = 1
  1583  	overflow := false
  1584  	for ; i < len(s); i++ {
  1585  		c := s[i]
  1586  		if c < '0' || c > '9' {
  1587  			break
  1588  		}
  1589  		if overflow {
  1590  			continue
  1591  		}
  1592  		if x > (1<<63-1)/10 {
  1593  			// It's possible for overflow to give a positive number, so take care.
  1594  			overflow = true
  1595  			continue
  1596  		}
  1597  		y := x*10 + uint64(c) - '0'
  1598  		if y > 1<<63 {
  1599  			overflow = true
  1600  			continue
  1601  		}
  1602  		x = y
  1603  		scale *= 10
  1604  	}
  1605  	return x, scale, s[i:]
  1606  }
  1607  
  1608  // parseDurationError describes a problem parsing a duration string.
  1609  type parseDurationError struct {
  1610  	message string
  1611  	value   string
  1612  }
  1613  
  1614  func (e *parseDurationError) Error() string {
  1615  	return "time: " + e.message + " " + quote(e.value)
  1616  }
  1617  
  1618  var unitMap = map[string]uint64{
  1619  	"ns": uint64(Nanosecond),
  1620  	"us": uint64(Microsecond),
  1621  	"µs": uint64(Microsecond), // U+00B5 = micro symbol
  1622  	"μs": uint64(Microsecond), // U+03BC = Greek letter mu
  1623  	"ms": uint64(Millisecond),
  1624  	"s":  uint64(Second),
  1625  	"m":  uint64(Minute),
  1626  	"h":  uint64(Hour),
  1627  }
  1628  
  1629  // ParseDuration parses a duration string.
  1630  // A duration string is a possibly signed sequence of
  1631  // decimal numbers, each with optional fraction and a unit suffix,
  1632  // such as "300ms", "-1.5h" or "2h45m".
  1633  // Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h".
  1634  func ParseDuration(s string) (Duration, error) {
  1635  	// [-+]?([0-9]*(\.[0-9]*)?[a-z]+)+
  1636  	orig := s
  1637  	var d uint64
  1638  	neg := false
  1639  
  1640  	// Consume [-+]?
  1641  	if s != "" {
  1642  		c := s[0]
  1643  		if c == '-' || c == '+' {
  1644  			neg = c == '-'
  1645  			s = s[1:]
  1646  		}
  1647  	}
  1648  	// Special case: if all that is left is "0", this is zero.
  1649  	if s == "0" {
  1650  		return 0, nil
  1651  	}
  1652  	if s == "" {
  1653  		return 0, &parseDurationError{"invalid duration", orig}
  1654  	}
  1655  	for s != "" {
  1656  		var (
  1657  			v, f  uint64      // integers before, after decimal point
  1658  			scale float64 = 1 // value = v + f/scale
  1659  		)
  1660  
  1661  		var err error
  1662  
  1663  		// The next character must be [0-9.]
  1664  		if !(s[0] == '.' || '0' <= s[0] && s[0] <= '9') {
  1665  			return 0, &parseDurationError{"invalid duration", orig}
  1666  		}
  1667  		// Consume [0-9]*
  1668  		pl := len(s)
  1669  		v, s, err = leadingInt(s)
  1670  		if err != nil {
  1671  			return 0, &parseDurationError{"invalid duration", orig}
  1672  		}
  1673  		pre := pl != len(s) // whether we consumed anything before a period
  1674  
  1675  		// Consume (\.[0-9]*)?
  1676  		post := false
  1677  		if s != "" && s[0] == '.' {
  1678  			s = s[1:]
  1679  			pl := len(s)
  1680  			f, scale, s = leadingFraction(s)
  1681  			post = pl != len(s)
  1682  		}
  1683  		if !pre && !post {
  1684  			// no digits (e.g. ".s" or "-.s")
  1685  			return 0, &parseDurationError{"invalid duration", orig}
  1686  		}
  1687  
  1688  		// Consume unit.
  1689  		i := 0
  1690  		for ; i < len(s); i++ {
  1691  			c := s[i]
  1692  			if c == '.' || '0' <= c && c <= '9' {
  1693  				break
  1694  			}
  1695  		}
  1696  		if i == 0 {
  1697  			return 0, &parseDurationError{"missing unit in duration", orig}
  1698  		}
  1699  		u := s[:i]
  1700  		s = s[i:]
  1701  		unit, ok := unitMap[u]
  1702  		if !ok {
  1703  			return 0, &parseDurationError{"unknown unit " + quote(u) + " in duration", orig}
  1704  		}
  1705  		if v > 1<<63/unit {
  1706  			// overflow
  1707  			return 0, &parseDurationError{"invalid duration", orig}
  1708  		}
  1709  		v *= unit
  1710  		if f > 0 {
  1711  			// float64 is needed to be nanosecond accurate for fractions of hours.
  1712  			// v >= 0 && (f*unit/scale) <= 3.6e+12 (ns/h, h is the largest unit)
  1713  			v += uint64(float64(f) * (float64(unit) / scale))
  1714  			if v > 1<<63 {
  1715  				// overflow
  1716  				return 0, &parseDurationError{"invalid duration", orig}
  1717  			}
  1718  		}
  1719  		d += v
  1720  		if d > 1<<63 {
  1721  			return 0, &parseDurationError{"invalid duration", orig}
  1722  		}
  1723  	}
  1724  	if neg {
  1725  		return -Duration(d), nil
  1726  	}
  1727  	if d > 1<<63-1 {
  1728  		return 0, &parseDurationError{"invalid duration", orig}
  1729  	}
  1730  	return Duration(d), nil
  1731  }
  1732  

View as plain text