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