...
Run Format

Source file src/pkg/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 "errors"
     8	
     9	// These are predefined layouts for use in Time.Format and Time.Parse.
    10	// The reference time used in the layouts is:
    11	//	Mon Jan 2 15:04:05 MST 2006
    12	// which is Unix time 1136239445. Since MST is GMT-0700,
    13	// the reference time can be thought of as
    14	//	01/02 03:04:05PM '06 -0700
    15	// To define your own format, write down what the reference time would look
    16	// like formatted your way; see the values of constants like ANSIC,
    17	// StampMicro or Kitchen for examples. The model is to demonstrate what the
    18	// reference time looks like so that the Format and Parse methods can apply
    19	// the same transformation to a general time value.
    20	//
    21	// Within the format string, an underscore _ represents a space that may be
    22	// replaced by a digit if the following number (a day) has two digits; for
    23	// compatibility with fixed-width Unix time formats.
    24	//
    25	// A decimal point followed by one or more zeros represents a fractional
    26	// second, printed to the given number of decimal places.  A decimal point
    27	// followed by one or more nines represents a fractional second, printed to
    28	// the given number of decimal places, with trailing zeros removed.
    29	// When parsing (only), the input may contain a fractional second
    30	// field immediately after the seconds field, even if the layout does not
    31	// signify its presence. In that case a decimal point followed by a maximal
    32	// series of digits is parsed as a fractional second.
    33	//
    34	// Numeric time zone offsets format as follows:
    35	//	-0700  ±hhmm
    36	//	-07:00 ±hh:mm
    37	// Replacing the sign in the format with a Z triggers
    38	// the ISO 8601 behavior of printing Z instead of an
    39	// offset for the UTC zone.  Thus:
    40	//	Z0700  Z or ±hhmm
    41	//	Z07:00 Z or ±hh:mm
    42	const (
    43		ANSIC       = "Mon Jan _2 15:04:05 2006"
    44		UnixDate    = "Mon Jan _2 15:04:05 MST 2006"
    45		RubyDate    = "Mon Jan 02 15:04:05 -0700 2006"
    46		RFC822      = "02 Jan 06 15:04 MST"
    47		RFC822Z     = "02 Jan 06 15:04 -0700" // RFC822 with numeric zone
    48		RFC850      = "Monday, 02-Jan-06 15:04:05 MST"
    49		RFC1123     = "Mon, 02 Jan 2006 15:04:05 MST"
    50		RFC1123Z    = "Mon, 02 Jan 2006 15:04:05 -0700" // RFC1123 with numeric zone
    51		RFC3339     = "2006-01-02T15:04:05Z07:00"
    52		RFC3339Nano = "2006-01-02T15:04:05.999999999Z07:00"
    53		Kitchen     = "3:04PM"
    54		// Handy time stamps.
    55		Stamp      = "Jan _2 15:04:05"
    56		StampMilli = "Jan _2 15:04:05.000"
    57		StampMicro = "Jan _2 15:04:05.000000"
    58		StampNano  = "Jan _2 15:04:05.000000000"
    59	)
    60	
    61	const (
    62		_                        = iota
    63		stdLongMonth             = iota + stdNeedDate  // "January"
    64		stdMonth                                       // "Jan"
    65		stdNumMonth                                    // "1"
    66		stdZeroMonth                                   // "01"
    67		stdLongWeekDay                                 // "Monday"
    68		stdWeekDay                                     // "Mon"
    69		stdDay                                         // "2"
    70		stdUnderDay                                    // "_2"
    71		stdZeroDay                                     // "02"
    72		stdHour                  = iota + stdNeedClock // "15"
    73		stdHour12                                      // "3"
    74		stdZeroHour12                                  // "03"
    75		stdMinute                                      // "4"
    76		stdZeroMinute                                  // "04"
    77		stdSecond                                      // "5"
    78		stdZeroSecond                                  // "05"
    79		stdLongYear              = iota + stdNeedDate  // "2006"
    80		stdYear                                        // "06"
    81		stdPM                    = iota + stdNeedClock // "PM"
    82		stdpm                                          // "pm"
    83		stdTZ                    = iota                // "MST"
    84		stdISO8601TZ                                   // "Z0700"  // prints Z for UTC
    85		stdISO8601SecondsTZ                            // "Z070000"
    86		stdISO8601ColonTZ                              // "Z07:00" // prints Z for UTC
    87		stdISO8601ColonSecondsTZ                       // "Z07:00:00"
    88		stdNumTZ                                       // "-0700"  // always numeric
    89		stdNumSecondsTz                                // "-070000"
    90		stdNumShortTZ                                  // "-07"    // always numeric
    91		stdNumColonTZ                                  // "-07:00" // always numeric
    92		stdNumColonSecondsTZ                           // "-07:00:00"
    93		stdFracSecond0                                 // ".0", ".00", ... , trailing zeros included
    94		stdFracSecond9                                 // ".9", ".99", ..., trailing zeros omitted
    95	
    96		stdNeedDate  = 1 << 8             // need month, day, year
    97		stdNeedClock = 2 << 8             // need hour, minute, second
    98		stdArgShift  = 16                 // extra argument in high bits, above low stdArgShift
    99		stdMask      = 1<<stdArgShift - 1 // mask out argument
   100	)
   101	
   102	// std0x records the std values for "01", "02", ..., "06".
   103	var std0x = [...]int{stdZeroMonth, stdZeroDay, stdZeroHour12, stdZeroMinute, stdZeroSecond, stdYear}
   104	
   105	// startsWithLowerCase reports whether the string has a lower-case letter at the beginning.
   106	// Its purpose is to prevent matching strings like "Month" when looking for "Mon".
   107	func startsWithLowerCase(str string) bool {
   108		if len(str) == 0 {
   109			return false
   110		}
   111		c := str[0]
   112		return 'a' <= c && c <= 'z'
   113	}
   114	
   115	// nextStdChunk finds the first occurrence of a std string in
   116	// layout and returns the text before, the std string, and the text after.
   117	func nextStdChunk(layout string) (prefix string, std int, suffix string) {
   118		for i := 0; i < len(layout); i++ {
   119			switch c := int(layout[i]); c {
   120			case 'J': // January, Jan
   121				if len(layout) >= i+3 && layout[i:i+3] == "Jan" {
   122					if len(layout) >= i+7 && layout[i:i+7] == "January" {
   123						return layout[0:i], stdLongMonth, layout[i+7:]
   124					}
   125					if !startsWithLowerCase(layout[i+3:]) {
   126						return layout[0:i], stdMonth, layout[i+3:]
   127					}
   128				}
   129	
   130			case 'M': // Monday, Mon, MST
   131				if len(layout) >= i+3 {
   132					if layout[i:i+3] == "Mon" {
   133						if len(layout) >= i+6 && layout[i:i+6] == "Monday" {
   134							return layout[0:i], stdLongWeekDay, layout[i+6:]
   135						}
   136						if !startsWithLowerCase(layout[i+3:]) {
   137							return layout[0:i], stdWeekDay, layout[i+3:]
   138						}
   139					}
   140					if layout[i:i+3] == "MST" {
   141						return layout[0:i], stdTZ, layout[i+3:]
   142					}
   143				}
   144	
   145			case '0': // 01, 02, 03, 04, 05, 06
   146				if len(layout) >= i+2 && '1' <= layout[i+1] && layout[i+1] <= '6' {
   147					return layout[0:i], std0x[layout[i+1]-'1'], layout[i+2:]
   148				}
   149	
   150			case '1': // 15, 1
   151				if len(layout) >= i+2 && layout[i+1] == '5' {
   152					return layout[0:i], stdHour, layout[i+2:]
   153				}
   154				return layout[0:i], stdNumMonth, layout[i+1:]
   155	
   156			case '2': // 2006, 2
   157				if len(layout) >= i+4 && layout[i:i+4] == "2006" {
   158					return layout[0:i], stdLongYear, layout[i+4:]
   159				}
   160				return layout[0:i], stdDay, layout[i+1:]
   161	
   162			case '_': // _2
   163				if len(layout) >= i+2 && layout[i+1] == '2' {
   164					return layout[0:i], stdUnderDay, layout[i+2:]
   165				}
   166	
   167			case '3':
   168				return layout[0:i], stdHour12, layout[i+1:]
   169	
   170			case '4':
   171				return layout[0:i], stdMinute, layout[i+1:]
   172	
   173			case '5':
   174				return layout[0:i], stdSecond, layout[i+1:]
   175	
   176			case 'P': // PM
   177				if len(layout) >= i+2 && layout[i+1] == 'M' {
   178					return layout[0:i], stdPM, layout[i+2:]
   179				}
   180	
   181			case 'p': // pm
   182				if len(layout) >= i+2 && layout[i+1] == 'm' {
   183					return layout[0:i], stdpm, layout[i+2:]
   184				}
   185	
   186			case '-': // -070000, -07:00:00, -0700, -07:00, -07
   187				if len(layout) >= i+7 && layout[i:i+7] == "-070000" {
   188					return layout[0:i], stdNumSecondsTz, layout[i+7:]
   189				}
   190				if len(layout) >= i+9 && layout[i:i+9] == "-07:00:00" {
   191					return layout[0:i], stdNumColonSecondsTZ, layout[i+9:]
   192				}
   193				if len(layout) >= i+5 && layout[i:i+5] == "-0700" {
   194					return layout[0:i], stdNumTZ, layout[i+5:]
   195				}
   196				if len(layout) >= i+6 && layout[i:i+6] == "-07:00" {
   197					return layout[0:i], stdNumColonTZ, layout[i+6:]
   198				}
   199				if len(layout) >= i+3 && layout[i:i+3] == "-07" {
   200					return layout[0:i], stdNumShortTZ, layout[i+3:]
   201				}
   202	
   203			case 'Z': // Z070000, Z07:00:00, Z0700, Z07:00,
   204				if len(layout) >= i+7 && layout[i:i+7] == "Z070000" {
   205					return layout[0:i], stdISO8601SecondsTZ, layout[i+7:]
   206				}
   207				if len(layout) >= i+9 && layout[i:i+9] == "Z07:00:00" {
   208					return layout[0:i], stdISO8601ColonSecondsTZ, layout[i+9:]
   209				}
   210				if len(layout) >= i+5 && layout[i:i+5] == "Z0700" {
   211					return layout[0:i], stdISO8601TZ, layout[i+5:]
   212				}
   213				if len(layout) >= i+6 && layout[i:i+6] == "Z07:00" {
   214					return layout[0:i], stdISO8601ColonTZ, layout[i+6:]
   215				}
   216	
   217			case '.': // .000 or .999 - repeated digits for fractional seconds.
   218				if i+1 < len(layout) && (layout[i+1] == '0' || layout[i+1] == '9') {
   219					ch := layout[i+1]
   220					j := i + 1
   221					for j < len(layout) && layout[j] == ch {
   222						j++
   223					}
   224					// String of digits must end here - only fractional second is all digits.
   225					if !isDigit(layout, j) {
   226						std := stdFracSecond0
   227						if layout[i+1] == '9' {
   228							std = stdFracSecond9
   229						}
   230						std |= (j - (i + 1)) << stdArgShift
   231						return layout[0:i], std, layout[j:]
   232					}
   233				}
   234			}
   235		}
   236		return layout, 0, ""
   237	}
   238	
   239	var longDayNames = []string{
   240		"Sunday",
   241		"Monday",
   242		"Tuesday",
   243		"Wednesday",
   244		"Thursday",
   245		"Friday",
   246		"Saturday",
   247	}
   248	
   249	var shortDayNames = []string{
   250		"Sun",
   251		"Mon",
   252		"Tue",
   253		"Wed",
   254		"Thu",
   255		"Fri",
   256		"Sat",
   257	}
   258	
   259	var shortMonthNames = []string{
   260		"---",
   261		"Jan",
   262		"Feb",
   263		"Mar",
   264		"Apr",
   265		"May",
   266		"Jun",
   267		"Jul",
   268		"Aug",
   269		"Sep",
   270		"Oct",
   271		"Nov",
   272		"Dec",
   273	}
   274	
   275	var longMonthNames = []string{
   276		"---",
   277		"January",
   278		"February",
   279		"March",
   280		"April",
   281		"May",
   282		"June",
   283		"July",
   284		"August",
   285		"September",
   286		"October",
   287		"November",
   288		"December",
   289	}
   290	
   291	// match returns true if s1 and s2 match ignoring case.
   292	// It is assumed s1 and s2 are the same length.
   293	func match(s1, s2 string) bool {
   294		for i := 0; i < len(s1); i++ {
   295			c1 := s1[i]
   296			c2 := s2[i]
   297			if c1 != c2 {
   298				// Switch to lower-case; 'a'-'A' is known to be a single bit.
   299				c1 |= 'a' - 'A'
   300				c2 |= 'a' - 'A'
   301				if c1 != c2 || c1 < 'a' || c1 > 'z' {
   302					return false
   303				}
   304			}
   305		}
   306		return true
   307	}
   308	
   309	func lookup(tab []string, val string) (int, string, error) {
   310		for i, v := range tab {
   311			if len(val) >= len(v) && match(val[0:len(v)], v) {
   312				return i, val[len(v):], nil
   313			}
   314		}
   315		return -1, val, errBad
   316	}
   317	
   318	// appendUint appends the decimal form of x to b and returns the result.
   319	// If x is a single-digit number and pad != 0, appendUint inserts the pad byte
   320	// before the digit.
   321	// Duplicates functionality in strconv, but avoids dependency.
   322	func appendUint(b []byte, x uint, pad byte) []byte {
   323		if x < 10 {
   324			if pad != 0 {
   325				b = append(b, pad)
   326			}
   327			return append(b, byte('0'+x))
   328		}
   329		if x < 100 {
   330			b = append(b, byte('0'+x/10))
   331			b = append(b, byte('0'+x%10))
   332			return b
   333		}
   334	
   335		var buf [32]byte
   336		n := len(buf)
   337		if x == 0 {
   338			return append(b, '0')
   339		}
   340		for x >= 10 {
   341			n--
   342			buf[n] = byte(x%10 + '0')
   343			x /= 10
   344		}
   345		n--
   346		buf[n] = byte(x + '0')
   347		return append(b, buf[n:]...)
   348	}
   349	
   350	// Never printed, just needs to be non-nil for return by atoi.
   351	var atoiError = errors.New("time: invalid number")
   352	
   353	// Duplicates functionality in strconv, but avoids dependency.
   354	func atoi(s string) (x int, err error) {
   355		neg := false
   356		if s != "" && (s[0] == '-' || s[0] == '+') {
   357			neg = s[0] == '-'
   358			s = s[1:]
   359		}
   360		q, rem, err := leadingInt(s)
   361		x = int(q)
   362		if err != nil || rem != "" {
   363			return 0, atoiError
   364		}
   365		if neg {
   366			x = -x
   367		}
   368		return x, nil
   369	}
   370	
   371	// formatNano appends a fractional second, as nanoseconds, to b
   372	// and returns the result.
   373	func formatNano(b []byte, nanosec uint, n int, trim bool) []byte {
   374		u := nanosec
   375		var buf [9]byte
   376		for start := len(buf); start > 0; {
   377			start--
   378			buf[start] = byte(u%10 + '0')
   379			u /= 10
   380		}
   381	
   382		if n > 9 {
   383			n = 9
   384		}
   385		if trim {
   386			for n > 0 && buf[n-1] == '0' {
   387				n--
   388			}
   389			if n == 0 {
   390				return b
   391			}
   392		}
   393		b = append(b, '.')
   394		return append(b, buf[:n]...)
   395	}
   396	
   397	// String returns the time formatted using the format string
   398	//	"2006-01-02 15:04:05.999999999 -0700 MST"
   399	func (t Time) String() string {
   400		return t.Format("2006-01-02 15:04:05.999999999 -0700 MST")
   401	}
   402	
   403	// Format returns a textual representation of the time value formatted
   404	// according to layout, which defines the format by showing how the reference
   405	// time,
   406	//	Mon Jan 2 15:04:05 -0700 MST 2006
   407	// would be displayed if it were the value; it serves as an example of the
   408	// desired output. The same display rules will then be applied to the time
   409	// value.
   410	// Predefined layouts ANSIC, UnixDate, RFC3339 and others describe standard
   411	// and convenient representations of the reference time. For more information
   412	// about the formats and the definition of the reference time, see the
   413	// documentation for ANSIC and the other constants defined by this package.
   414	func (t Time) Format(layout string) string {
   415		var (
   416			name, offset, abs = t.locabs()
   417	
   418			year  int = -1
   419			month Month
   420			day   int
   421			hour  int = -1
   422			min   int
   423			sec   int
   424	
   425			b   []byte
   426			buf [64]byte
   427		)
   428		max := len(layout) + 10
   429		if max <= len(buf) {
   430			b = buf[:0]
   431		} else {
   432			b = make([]byte, 0, max)
   433		}
   434		// Each iteration generates one std value.
   435		for layout != "" {
   436			prefix, std, suffix := nextStdChunk(layout)
   437			if prefix != "" {
   438				b = append(b, prefix...)
   439			}
   440			if std == 0 {
   441				break
   442			}
   443			layout = suffix
   444	
   445			// Compute year, month, day if needed.
   446			if year < 0 && std&stdNeedDate != 0 {
   447				year, month, day, _ = absDate(abs, true)
   448			}
   449	
   450			// Compute hour, minute, second if needed.
   451			if hour < 0 && std&stdNeedClock != 0 {
   452				hour, min, sec = absClock(abs)
   453			}
   454	
   455			switch std & stdMask {
   456			case stdYear:
   457				y := year
   458				if y < 0 {
   459					y = -y
   460				}
   461				b = appendUint(b, uint(y%100), '0')
   462			case stdLongYear:
   463				// Pad year to at least 4 digits.
   464				y := year
   465				switch {
   466				case year <= -1000:
   467					b = append(b, '-')
   468					y = -y
   469				case year <= -100:
   470					b = append(b, "-0"...)
   471					y = -y
   472				case year <= -10:
   473					b = append(b, "-00"...)
   474					y = -y
   475				case year < 0:
   476					b = append(b, "-000"...)
   477					y = -y
   478				case year < 10:
   479					b = append(b, "000"...)
   480				case year < 100:
   481					b = append(b, "00"...)
   482				case year < 1000:
   483					b = append(b, '0')
   484				}
   485				b = appendUint(b, uint(y), 0)
   486			case stdMonth:
   487				b = append(b, month.String()[:3]...)
   488			case stdLongMonth:
   489				m := month.String()
   490				b = append(b, m...)
   491			case stdNumMonth:
   492				b = appendUint(b, uint(month), 0)
   493			case stdZeroMonth:
   494				b = appendUint(b, uint(month), '0')
   495			case stdWeekDay:
   496				b = append(b, absWeekday(abs).String()[:3]...)
   497			case stdLongWeekDay:
   498				s := absWeekday(abs).String()
   499				b = append(b, s...)
   500			case stdDay:
   501				b = appendUint(b, uint(day), 0)
   502			case stdUnderDay:
   503				b = appendUint(b, uint(day), ' ')
   504			case stdZeroDay:
   505				b = appendUint(b, uint(day), '0')
   506			case stdHour:
   507				b = appendUint(b, uint(hour), '0')
   508			case stdHour12:
   509				// Noon is 12PM, midnight is 12AM.
   510				hr := hour % 12
   511				if hr == 0 {
   512					hr = 12
   513				}
   514				b = appendUint(b, uint(hr), 0)
   515			case stdZeroHour12:
   516				// Noon is 12PM, midnight is 12AM.
   517				hr := hour % 12
   518				if hr == 0 {
   519					hr = 12
   520				}
   521				b = appendUint(b, uint(hr), '0')
   522			case stdMinute:
   523				b = appendUint(b, uint(min), 0)
   524			case stdZeroMinute:
   525				b = appendUint(b, uint(min), '0')
   526			case stdSecond:
   527				b = appendUint(b, uint(sec), 0)
   528			case stdZeroSecond:
   529				b = appendUint(b, uint(sec), '0')
   530			case stdPM:
   531				if hour >= 12 {
   532					b = append(b, "PM"...)
   533				} else {
   534					b = append(b, "AM"...)
   535				}
   536			case stdpm:
   537				if hour >= 12 {
   538					b = append(b, "pm"...)
   539				} else {
   540					b = append(b, "am"...)
   541				}
   542			case stdISO8601TZ, stdISO8601ColonTZ, stdISO8601SecondsTZ, stdISO8601ColonSecondsTZ, stdNumTZ, stdNumColonTZ, stdNumSecondsTz, stdNumColonSecondsTZ:
   543				// Ugly special case.  We cheat and take the "Z" variants
   544				// to mean "the time zone as formatted for ISO 8601".
   545				if offset == 0 && (std == stdISO8601TZ || std == stdISO8601ColonTZ || std == stdISO8601SecondsTZ || std == stdISO8601ColonSecondsTZ) {
   546					b = append(b, 'Z')
   547					break
   548				}
   549				zone := offset / 60 // convert to minutes
   550				absoffset := offset
   551				if zone < 0 {
   552					b = append(b, '-')
   553					zone = -zone
   554					absoffset = -absoffset
   555				} else {
   556					b = append(b, '+')
   557				}
   558				b = appendUint(b, uint(zone/60), '0')
   559				if std == stdISO8601ColonTZ || std == stdNumColonTZ {
   560					b = append(b, ':')
   561				}
   562				b = appendUint(b, uint(zone%60), '0')
   563	
   564				// append seconds if appropriate
   565				if std == stdISO8601SecondsTZ || std == stdNumSecondsTz || std == stdNumColonSecondsTZ || std == stdISO8601ColonSecondsTZ {
   566					if std == stdNumColonSecondsTZ || std == stdISO8601ColonSecondsTZ {
   567						b = append(b, ':')
   568					}
   569					b = appendUint(b, uint(absoffset%60), '0')
   570				}
   571	
   572			case stdTZ:
   573				if name != "" {
   574					b = append(b, name...)
   575					break
   576				}
   577				// No time zone known for this time, but we must print one.
   578				// Use the -0700 format.
   579				zone := offset / 60 // convert to minutes
   580				if zone < 0 {
   581					b = append(b, '-')
   582					zone = -zone
   583				} else {
   584					b = append(b, '+')
   585				}
   586				b = appendUint(b, uint(zone/60), '0')
   587				b = appendUint(b, uint(zone%60), '0')
   588			case stdFracSecond0, stdFracSecond9:
   589				b = formatNano(b, uint(t.Nanosecond()), std>>stdArgShift, std&stdMask == stdFracSecond9)
   590			}
   591		}
   592		return string(b)
   593	}
   594	
   595	var errBad = errors.New("bad value for field") // placeholder not passed to user
   596	
   597	// ParseError describes a problem parsing a time string.
   598	type ParseError struct {
   599		Layout     string
   600		Value      string
   601		LayoutElem string
   602		ValueElem  string
   603		Message    string
   604	}
   605	
   606	func quote(s string) string {
   607		return "\"" + s + "\""
   608	}
   609	
   610	// Error returns the string representation of a ParseError.
   611	func (e *ParseError) Error() string {
   612		if e.Message == "" {
   613			return "parsing time " +
   614				quote(e.Value) + " as " +
   615				quote(e.Layout) + ": cannot parse " +
   616				quote(e.ValueElem) + " as " +
   617				quote(e.LayoutElem)
   618		}
   619		return "parsing time " +
   620			quote(e.Value) + e.Message
   621	}
   622	
   623	// isDigit returns true if s[i] is a decimal digit, false if not or
   624	// if s[i] is out of range.
   625	func isDigit(s string, i int) bool {
   626		if len(s) <= i {
   627			return false
   628		}
   629		c := s[i]
   630		return '0' <= c && c <= '9'
   631	}
   632	
   633	// getnum parses s[0:1] or s[0:2] (fixed forces the latter)
   634	// as a decimal integer and returns the integer and the
   635	// remainder of the string.
   636	func getnum(s string, fixed bool) (int, string, error) {
   637		if !isDigit(s, 0) {
   638			return 0, s, errBad
   639		}
   640		if !isDigit(s, 1) {
   641			if fixed {
   642				return 0, s, errBad
   643			}
   644			return int(s[0] - '0'), s[1:], nil
   645		}
   646		return int(s[0]-'0')*10 + int(s[1]-'0'), s[2:], nil
   647	}
   648	
   649	func cutspace(s string) string {
   650		for len(s) > 0 && s[0] == ' ' {
   651			s = s[1:]
   652		}
   653		return s
   654	}
   655	
   656	// skip removes the given prefix from value,
   657	// treating runs of space characters as equivalent.
   658	func skip(value, prefix string) (string, error) {
   659		for len(prefix) > 0 {
   660			if prefix[0] == ' ' {
   661				if len(value) > 0 && value[0] != ' ' {
   662					return value, errBad
   663				}
   664				prefix = cutspace(prefix)
   665				value = cutspace(value)
   666				continue
   667			}
   668			if len(value) == 0 || value[0] != prefix[0] {
   669				return value, errBad
   670			}
   671			prefix = prefix[1:]
   672			value = value[1:]
   673		}
   674		return value, nil
   675	}
   676	
   677	// Parse parses a formatted string and returns the time value it represents.
   678	// The layout  defines the format by showing how the reference time,
   679	//	Mon Jan 2 15:04:05 -0700 MST 2006
   680	// would be interpreted if it were the value; it serves as an example of
   681	// the input format. The same interpretation will then be made to the
   682	// input string.
   683	// Predefined layouts ANSIC, UnixDate, RFC3339 and others describe standard
   684	// and convenient representations of the reference time. For more information
   685	// about the formats and the definition of the reference time, see the
   686	// documentation for ANSIC and the other constants defined by this package.
   687	//
   688	// Elements omitted from the value are assumed to be zero or, when
   689	// zero is impossible, one, so parsing "3:04pm" returns the time
   690	// corresponding to Jan 1, year 0, 15:04:00 UTC (note that because the year is
   691	// 0, this time is before the zero Time).
   692	// Years must be in the range 0000..9999. The day of the week is checked
   693	// for syntax but it is otherwise ignored.
   694	//
   695	// In the absence of a time zone indicator, Parse returns a time in UTC.
   696	//
   697	// When parsing a time with a zone offset like -0700, if the offset corresponds
   698	// to a time zone used by the current location (Local), then Parse uses that
   699	// location and zone in the returned time. Otherwise it records the time as
   700	// being in a fabricated location with time fixed at the given zone offset.
   701	//
   702	// When parsing a time with a zone abbreviation like MST, if the zone abbreviation
   703	// has a defined offset in the current location, then that offset is used.
   704	// The zone abbreviation "UTC" is recognized as UTC regardless of location.
   705	// If the zone abbreviation is unknown, Parse records the time as being
   706	// in a fabricated location with the given zone abbreviation and a zero offset.
   707	// This choice means that such a time can be parse and reformatted with the
   708	// same layout losslessly, but the exact instant used in the representation will
   709	// differ by the actual zone offset. To avoid such problems, prefer time layouts
   710	// that use a numeric zone offset, or use ParseInLocation.
   711	func Parse(layout, value string) (Time, error) {
   712		return parse(layout, value, UTC, Local)
   713	}
   714	
   715	// ParseInLocation is like Parse but differs in two important ways.
   716	// First, in the absence of time zone information, Parse interprets a time as UTC;
   717	// ParseInLocation interprets the time as in the given location.
   718	// Second, when given a zone offset or abbreviation, Parse tries to match it
   719	// against the Local location; ParseInLocation uses the given location.
   720	func ParseInLocation(layout, value string, loc *Location) (Time, error) {
   721		return parse(layout, value, loc, loc)
   722	}
   723	
   724	func parse(layout, value string, defaultLocation, local *Location) (Time, error) {
   725		alayout, avalue := layout, value
   726		rangeErrString := "" // set if a value is out of range
   727		amSet := false       // do we need to subtract 12 from the hour for midnight?
   728		pmSet := false       // do we need to add 12 to the hour?
   729	
   730		// Time being constructed.
   731		var (
   732			year       int
   733			month      int = 1 // January
   734			day        int = 1
   735			hour       int
   736			min        int
   737			sec        int
   738			nsec       int
   739			z          *Location
   740			zoneOffset int = -1
   741			zoneName   string
   742		)
   743	
   744		// Each iteration processes one std value.
   745		for {
   746			var err error
   747			prefix, std, suffix := nextStdChunk(layout)
   748			stdstr := layout[len(prefix) : len(layout)-len(suffix)]
   749			value, err = skip(value, prefix)
   750			if err != nil {
   751				return Time{}, &ParseError{alayout, avalue, prefix, value, ""}
   752			}
   753			if std == 0 {
   754				if len(value) != 0 {
   755					return Time{}, &ParseError{alayout, avalue, "", value, ": extra text: " + value}
   756				}
   757				break
   758			}
   759			layout = suffix
   760			var p string
   761			switch std & stdMask {
   762			case stdYear:
   763				if len(value) < 2 {
   764					err = errBad
   765					break
   766				}
   767				p, value = value[0:2], value[2:]
   768				year, err = atoi(p)
   769				if year >= 69 { // Unix time starts Dec 31 1969 in some time zones
   770					year += 1900
   771				} else {
   772					year += 2000
   773				}
   774			case stdLongYear:
   775				if len(value) < 4 || !isDigit(value, 0) {
   776					err = errBad
   777					break
   778				}
   779				p, value = value[0:4], value[4:]
   780				year, err = atoi(p)
   781			case stdMonth:
   782				month, value, err = lookup(shortMonthNames, value)
   783			case stdLongMonth:
   784				month, value, err = lookup(longMonthNames, value)
   785			case stdNumMonth, stdZeroMonth:
   786				month, value, err = getnum(value, std == stdZeroMonth)
   787				if month <= 0 || 12 < month {
   788					rangeErrString = "month"
   789				}
   790			case stdWeekDay:
   791				// Ignore weekday except for error checking.
   792				_, value, err = lookup(shortDayNames, value)
   793			case stdLongWeekDay:
   794				_, value, err = lookup(longDayNames, value)
   795			case stdDay, stdUnderDay, stdZeroDay:
   796				if std == stdUnderDay && len(value) > 0 && value[0] == ' ' {
   797					value = value[1:]
   798				}
   799				day, value, err = getnum(value, std == stdZeroDay)
   800				if day < 0 || 31 < day {
   801					rangeErrString = "day"
   802				}
   803			case stdHour:
   804				hour, value, err = getnum(value, false)
   805				if hour < 0 || 24 <= hour {
   806					rangeErrString = "hour"
   807				}
   808			case stdHour12, stdZeroHour12:
   809				hour, value, err = getnum(value, std == stdZeroHour12)
   810				if hour < 0 || 12 < hour {
   811					rangeErrString = "hour"
   812				}
   813			case stdMinute, stdZeroMinute:
   814				min, value, err = getnum(value, std == stdZeroMinute)
   815				if min < 0 || 60 <= min {
   816					rangeErrString = "minute"
   817				}
   818			case stdSecond, stdZeroSecond:
   819				sec, value, err = getnum(value, std == stdZeroSecond)
   820				if sec < 0 || 60 <= sec {
   821					rangeErrString = "second"
   822				}
   823				// Special case: do we have a fractional second but no
   824				// fractional second in the format?
   825				if len(value) >= 2 && value[0] == '.' && isDigit(value, 1) {
   826					_, std, _ = nextStdChunk(layout)
   827					std &= stdMask
   828					if std == stdFracSecond0 || std == stdFracSecond9 {
   829						// Fractional second in the layout; proceed normally
   830						break
   831					}
   832					// No fractional second in the layout but we have one in the input.
   833					n := 2
   834					for ; n < len(value) && isDigit(value, n); n++ {
   835					}
   836					nsec, rangeErrString, err = parseNanoseconds(value, n)
   837					value = value[n:]
   838				}
   839			case stdPM:
   840				if len(value) < 2 {
   841					err = errBad
   842					break
   843				}
   844				p, value = value[0:2], value[2:]
   845				switch p {
   846				case "PM":
   847					pmSet = true
   848				case "AM":
   849					amSet = true
   850				default:
   851					err = errBad
   852				}
   853			case stdpm:
   854				if len(value) < 2 {
   855					err = errBad
   856					break
   857				}
   858				p, value = value[0:2], value[2:]
   859				switch p {
   860				case "pm":
   861					pmSet = true
   862				case "am":
   863					amSet = true
   864				default:
   865					err = errBad
   866				}
   867			case stdISO8601TZ, stdISO8601ColonTZ, stdISO8601SecondsTZ, stdISO8601ColonSecondsTZ, stdNumTZ, stdNumShortTZ, stdNumColonTZ, stdNumSecondsTz, stdNumColonSecondsTZ:
   868				if (std == stdISO8601TZ || std == stdISO8601ColonTZ) && len(value) >= 1 && value[0] == 'Z' {
   869					value = value[1:]
   870					z = UTC
   871					break
   872				}
   873				var sign, hour, min, seconds string
   874				if std == stdISO8601ColonTZ || std == stdNumColonTZ {
   875					if len(value) < 6 {
   876						err = errBad
   877						break
   878					}
   879					if value[3] != ':' {
   880						err = errBad
   881						break
   882					}
   883					sign, hour, min, seconds, value = value[0:1], value[1:3], value[4:6], "00", value[6:]
   884				} else if std == stdNumShortTZ {
   885					if len(value) < 3 {
   886						err = errBad
   887						break
   888					}
   889					sign, hour, min, seconds, value = value[0:1], value[1:3], "00", "00", value[3:]
   890				} else if std == stdISO8601ColonSecondsTZ || std == stdNumColonSecondsTZ {
   891					if len(value) < 9 {
   892						err = errBad
   893						break
   894					}
   895					if value[3] != ':' || value[6] != ':' {
   896						err = errBad
   897						break
   898					}
   899					sign, hour, min, seconds, value = value[0:1], value[1:3], value[4:6], value[7:9], value[9:]
   900				} else if std == stdISO8601SecondsTZ || std == stdNumSecondsTz {
   901					if len(value) < 7 {
   902						err = errBad
   903						break
   904					}
   905					sign, hour, min, seconds, value = value[0:1], value[1:3], value[3:5], value[5:7], value[7:]
   906				} else {
   907					if len(value) < 5 {
   908						err = errBad
   909						break
   910					}
   911					sign, hour, min, seconds, value = value[0:1], value[1:3], value[3:5], "00", value[5:]
   912				}
   913				var hr, mm, ss int
   914				hr, err = atoi(hour)
   915				if err == nil {
   916					mm, err = atoi(min)
   917				}
   918				if err == nil {
   919					ss, err = atoi(seconds)
   920				}
   921				zoneOffset = (hr*60+mm)*60 + ss // offset is in seconds
   922				switch sign[0] {
   923				case '+':
   924				case '-':
   925					zoneOffset = -zoneOffset
   926				default:
   927					err = errBad
   928				}
   929			case stdTZ:
   930				// Does it look like a time zone?
   931				if len(value) >= 3 && value[0:3] == "UTC" {
   932					z = UTC
   933					value = value[3:]
   934					break
   935				}
   936				n, ok := parseTimeZone(value)
   937				if !ok {
   938					err = errBad
   939					break
   940				}
   941				zoneName, value = value[:n], value[n:]
   942	
   943			case stdFracSecond0:
   944				// stdFracSecond0 requires the exact number of digits as specified in
   945				// the layout.
   946				ndigit := 1 + (std >> stdArgShift)
   947				if len(value) < ndigit {
   948					err = errBad
   949					break
   950				}
   951				nsec, rangeErrString, err = parseNanoseconds(value, ndigit)
   952				value = value[ndigit:]
   953	
   954			case stdFracSecond9:
   955				if len(value) < 2 || value[0] != '.' || value[1] < '0' || '9' < value[1] {
   956					// Fractional second omitted.
   957					break
   958				}
   959				// Take any number of digits, even more than asked for,
   960				// because it is what the stdSecond case would do.
   961				i := 0
   962				for i < 9 && i+1 < len(value) && '0' <= value[i+1] && value[i+1] <= '9' {
   963					i++
   964				}
   965				nsec, rangeErrString, err = parseNanoseconds(value, 1+i)
   966				value = value[1+i:]
   967			}
   968			if rangeErrString != "" {
   969				return Time{}, &ParseError{alayout, avalue, stdstr, value, ": " + rangeErrString + " out of range"}
   970			}
   971			if err != nil {
   972				return Time{}, &ParseError{alayout, avalue, stdstr, value, ""}
   973			}
   974		}
   975		if pmSet && hour < 12 {
   976			hour += 12
   977		} else if amSet && hour == 12 {
   978			hour = 0
   979		}
   980	
   981		if z != nil {
   982			return Date(year, Month(month), day, hour, min, sec, nsec, z), nil
   983		}
   984	
   985		if zoneOffset != -1 {
   986			t := Date(year, Month(month), day, hour, min, sec, nsec, UTC)
   987			t.sec -= int64(zoneOffset)
   988	
   989			// Look for local zone with the given offset.
   990			// If that zone was in effect at the given time, use it.
   991			name, offset, _, _, _ := local.lookup(t.sec + internalToUnix)
   992			if offset == zoneOffset && (zoneName == "" || name == zoneName) {
   993				t.loc = local
   994				return t, nil
   995			}
   996	
   997			// Otherwise create fake zone to record offset.
   998			t.loc = FixedZone(zoneName, zoneOffset)
   999			return t, nil
  1000		}
  1001	
  1002		if zoneName != "" {
  1003			t := Date(year, Month(month), day, hour, min, sec, nsec, UTC)
  1004			// Look for local zone with the given offset.
  1005			// If that zone was in effect at the given time, use it.
  1006			offset, _, ok := local.lookupName(zoneName, t.sec+internalToUnix)
  1007			if ok {
  1008				t.sec -= int64(offset)
  1009				t.loc = local
  1010				return t, nil
  1011			}
  1012	
  1013			// Otherwise, create fake zone with unknown offset.
  1014			if len(zoneName) > 3 && zoneName[:3] == "GMT" {
  1015				offset, _ = atoi(zoneName[3:]) // Guaranteed OK by parseGMT.
  1016				offset *= 3600
  1017			}
  1018			t.loc = FixedZone(zoneName, offset)
  1019			return t, nil
  1020		}
  1021	
  1022		// Otherwise, fall back to default.
  1023		return Date(year, Month(month), day, hour, min, sec, nsec, defaultLocation), nil
  1024	}
  1025	
  1026	// parseTimeZone parses a time zone string and returns its length. Time zones
  1027	// are human-generated and unpredictable. We can't do precise error checking.
  1028	// On the other hand, for a correct parse there must be a time zone at the
  1029	// beginning of the string, so it's almost always true that there's one
  1030	// there. We look at the beginning of the string for a run of upper-case letters.
  1031	// If there are more than 5, it's an error.
  1032	// If there are 4 or 5 and the last is a T, it's a time zone.
  1033	// If there are 3, it's a time zone.
  1034	// Otherwise, other than special cases, it's not a time zone.
  1035	// GMT is special because it can have an hour offset.
  1036	func parseTimeZone(value string) (length int, ok bool) {
  1037		if len(value) < 3 {
  1038			return 0, false
  1039		}
  1040		// Special case 1: ChST and MeST are the only zones with a lower-case letter.
  1041		if len(value) >= 4 && (value[:4] == "ChST" || value[:4] == "MeST") {
  1042			return 4, true
  1043		}
  1044		// Special case 2: GMT may have an hour offset; treat it specially.
  1045		if value[:3] == "GMT" {
  1046			length = parseGMT(value)
  1047			return length, true
  1048		}
  1049		// How many upper-case letters are there? Need at least three, at most five.
  1050		var nUpper int
  1051		for nUpper = 0; nUpper < 6; nUpper++ {
  1052			if nUpper >= len(value) {
  1053				break
  1054			}
  1055			if c := value[nUpper]; c < 'A' || 'Z' < c {
  1056				break
  1057			}
  1058		}
  1059		switch nUpper {
  1060		case 0, 1, 2, 6:
  1061			return 0, false
  1062		case 5: // Must end in T to match.
  1063			if value[4] == 'T' {
  1064				return 5, true
  1065			}
  1066		case 4: // Must end in T to match.
  1067			if value[3] == 'T' {
  1068				return 4, true
  1069			}
  1070		case 3:
  1071			return 3, true
  1072		}
  1073		return 0, false
  1074	}
  1075	
  1076	// parseGMT parses a GMT time zone. The input string is known to start "GMT".
  1077	// The function checks whether that is followed by a sign and a number in the
  1078	// range -14 through 12 excluding zero.
  1079	func parseGMT(value string) int {
  1080		value = value[3:]
  1081		if len(value) == 0 {
  1082			return 3
  1083		}
  1084		sign := value[0]
  1085		if sign != '-' && sign != '+' {
  1086			return 3
  1087		}
  1088		x, rem, err := leadingInt(value[1:])
  1089		if err != nil {
  1090			return 3
  1091		}
  1092		if sign == '-' {
  1093			x = -x
  1094		}
  1095		if x == 0 || x < -14 || 12 < x {
  1096			return 3
  1097		}
  1098		return 3 + len(value) - len(rem)
  1099	}
  1100	
  1101	func parseNanoseconds(value string, nbytes int) (ns int, rangeErrString string, err error) {
  1102		if value[0] != '.' {
  1103			err = errBad
  1104			return
  1105		}
  1106		if ns, err = atoi(value[1:nbytes]); err != nil {
  1107			return
  1108		}
  1109		if ns < 0 || 1e9 <= ns {
  1110			rangeErrString = "fractional second"
  1111			return
  1112		}
  1113		// We need nanoseconds, which means scaling by the number
  1114		// of missing digits in the format, maximum length 10. If it's
  1115		// longer than 10, we won't scale.
  1116		scaleDigits := 10 - nbytes
  1117		for i := 0; i < scaleDigits; i++ {
  1118			ns *= 10
  1119		}
  1120		return
  1121	}
  1122	
  1123	var errLeadingInt = errors.New("time: bad [0-9]*") // never printed
  1124	
  1125	// leadingInt consumes the leading [0-9]* from s.
  1126	func leadingInt(s string) (x int64, rem string, err error) {
  1127		i := 0
  1128		for ; i < len(s); i++ {
  1129			c := s[i]
  1130			if c < '0' || c > '9' {
  1131				break
  1132			}
  1133			if x >= (1<<63-10)/10 {
  1134				// overflow
  1135				return 0, "", errLeadingInt
  1136			}
  1137			x = x*10 + int64(c) - '0'
  1138		}
  1139		return x, s[i:], nil
  1140	}
  1141	
  1142	var unitMap = map[string]float64{
  1143		"ns": float64(Nanosecond),
  1144		"us": float64(Microsecond),
  1145		"µs": float64(Microsecond), // U+00B5 = micro symbol
  1146		"μs": float64(Microsecond), // U+03BC = Greek letter mu
  1147		"ms": float64(Millisecond),
  1148		"s":  float64(Second),
  1149		"m":  float64(Minute),
  1150		"h":  float64(Hour),
  1151	}
  1152	
  1153	// ParseDuration parses a duration string.
  1154	// A duration string is a possibly signed sequence of
  1155	// decimal numbers, each with optional fraction and a unit suffix,
  1156	// such as "300ms", "-1.5h" or "2h45m".
  1157	// Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h".
  1158	func ParseDuration(s string) (Duration, error) {
  1159		// [-+]?([0-9]*(\.[0-9]*)?[a-z]+)+
  1160		orig := s
  1161		f := float64(0)
  1162		neg := false
  1163	
  1164		// Consume [-+]?
  1165		if s != "" {
  1166			c := s[0]
  1167			if c == '-' || c == '+' {
  1168				neg = c == '-'
  1169				s = s[1:]
  1170			}
  1171		}
  1172		// Special case: if all that is left is "0", this is zero.
  1173		if s == "0" {
  1174			return 0, nil
  1175		}
  1176		if s == "" {
  1177			return 0, errors.New("time: invalid duration " + orig)
  1178		}
  1179		for s != "" {
  1180			g := float64(0) // this element of the sequence
  1181	
  1182			var x int64
  1183			var err error
  1184	
  1185			// The next character must be [0-9.]
  1186			if !(s[0] == '.' || ('0' <= s[0] && s[0] <= '9')) {
  1187				return 0, errors.New("time: invalid duration " + orig)
  1188			}
  1189			// Consume [0-9]*
  1190			pl := len(s)
  1191			x, s, err = leadingInt(s)
  1192			if err != nil {
  1193				return 0, errors.New("time: invalid duration " + orig)
  1194			}
  1195			g = float64(x)
  1196			pre := pl != len(s) // whether we consumed anything before a period
  1197	
  1198			// Consume (\.[0-9]*)?
  1199			post := false
  1200			if s != "" && s[0] == '.' {
  1201				s = s[1:]
  1202				pl := len(s)
  1203				x, s, err = leadingInt(s)
  1204				if err != nil {
  1205					return 0, errors.New("time: invalid duration " + orig)
  1206				}
  1207				scale := 1.0
  1208				for n := pl - len(s); n > 0; n-- {
  1209					scale *= 10
  1210				}
  1211				g += float64(x) / scale
  1212				post = pl != len(s)
  1213			}
  1214			if !pre && !post {
  1215				// no digits (e.g. ".s" or "-.s")
  1216				return 0, errors.New("time: invalid duration " + orig)
  1217			}
  1218	
  1219			// Consume unit.
  1220			i := 0
  1221			for ; i < len(s); i++ {
  1222				c := s[i]
  1223				if c == '.' || ('0' <= c && c <= '9') {
  1224					break
  1225				}
  1226			}
  1227			if i == 0 {
  1228				return 0, errors.New("time: missing unit in duration " + orig)
  1229			}
  1230			u := s[:i]
  1231			s = s[i:]
  1232			unit, ok := unitMap[u]
  1233			if !ok {
  1234				return 0, errors.New("time: unknown unit " + u + " in duration " + orig)
  1235			}
  1236	
  1237			f += g * unit
  1238		}
  1239	
  1240		if neg {
  1241			f = -f
  1242		}
  1243		if f < float64(-1<<63) || f > float64(1<<63-1) {
  1244			return 0, errors.New("time: overflow parsing duration")
  1245		}
  1246		return Duration(f), nil
  1247	}
  1248	

View as plain text