Black Lives Matter. Support the Equal Justice Initiative.

Source file src/time/format.go

Documentation: time

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

View as plain text