Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

time: Improving time layout docs #11312

Closed
jeremyheiler opened this issue Jun 21, 2015 · 2 comments

Comments

Projects
None yet
3 participants
@jeremyheiler
Copy link

commented Jun 21, 2015

I just spent some time figuring out how time layouts work. It didn't click for me until I read a post on StackOverflow that essentially copied this block of code below into an answer.

    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  )

(from http://golang.org/src/time/format.go)

Can the docs show this block fo code, or display a lookup table? After chatting on IRC, it sounded like questions relating to how layouts work appear often. I feel like this would make the docs clearer.

@adg adg changed the title Improving time layout docs time: Improving time layout docs Jun 22, 2015

@robpike

This comment has been minimized.

Copy link
Contributor

commented Jun 22, 2015

I believe the new (1.6) docs (http://tip.golang.org/pkg/time/#pkg-constants and http://tip.golang.org/pkg/time/#Parse) and example (http://tip.golang.org/pkg/time/#example_Time_Format) example do a much better job than the old docs.

If there are details missing that are covered by the table above, please say so.

@jeremyheiler

This comment has been minimized.

Copy link
Author

commented Jun 29, 2015

Thanks

@golang golang locked and limited conversation to collaborators Jun 28, 2016

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
You can’t perform that action at this time.