wooly

README

wooly

about

Package wooly wraps Gos default time.Time type to be more fluffy.

The Time type has a custom UnmarshalJSON implementation which trys to parse multiple time formats before failing. Also the Time type is a pointer (in contrast to the default time.Time), so that zero values are not marshalled for omitempty tagged fields by the json package.

The most common use should be to import wooly and set/add custom time formats to Layouts in a init function. This way, all methods of wooly.Time use the same layout strings. For special cases, a own set of layouts can be set to structs, but that should only be used in special cases.

documentation

Documentation on godoc.org

Documentation

Overview

Package wooly wraps Gos default time.Time type to be more fluffy.

The Time type has a custom UnmarshalJSON implementation which trys to parse multiple time formats before failing. Also the Time type is a pointer (in contrast to the default time.Time), so that zero values are not marshalled for omitempty tagged fields by the json package.

The most common use should be to import wooly and set/add custom time formats to Layouts in a init function. This way, all methods of wooly.Time use the same layout strings. For special cases, a own set of layouts can be set to structs, but that should only be used in special cases.

Index

• Variables
• type Time
  • func New(t time.Time) *Time
  • func Parse(layouts []string, value string) (*Time, error)
  • func (t *Time) Layouts() []string
  • func (t *Time) MarshalJSON() ([]byte, error)
  • func (t *Time) SetLayouts(layouts []string)
  • func (t *Time) UnmarshalJSON(data []byte) (err error)

Examples

• Parse
• Parse (Nil)
• Parse (Ownlayouts)
• Time.MarshalJSON
• Time.MarshalJSON (Ownlayouts)
• Time.UnmarshalJSON
• Time.UnmarshalJSON (Fail)
• Time.UnmarshalJSON (Ownlayouts)

Variables

var ErrNoLayout = errors.New("No layouts defined")

ErrNoLayout is returned if no layouts are defined.

var Layouts = []string{time.RFC3339Nano, time.ANSIC, time.UnixDate, time.RubyDate, time.RFC822, time.RFC822Z, time.RFC850, time.RFC1123, time.RFC1123Z, time.RFC3339, time.Kitchen, time.Stamp, time.StampMilli, time.StampMicro, time.StampNano}

Layouts is a collection of time formats used in JSON unmarshaling of type Time. It is used for marshaling and unmarshaling if the Time has no own layouts set, with time.RFC3339Nano used as default format. The default set consists of all constants defined in time.

Types

type Time

type Time struct {
	time.Time
	// contains filtered or unexported fields
}

Time is time.Time with custom json marshaling methods. Each Time object can have its own list of layouts. If it has own layouts these override the package-global layouts.

func New

func New(t time.Time) *Time

New returns a new Time value from a time.Time value.

func Parse

func Parse(layouts []string, value string) (*Time, error)

Parse parses a formatted string and returns the time value it represents. It tries to parse with all layouts, returning the error of the last tried layout if none succeeds. If layouts is nil, wooly.Layouts is used. If it is not nil, the returned time has the supplied layouts set.

Example

// Parse a time string using the layouts defined in wooly.Layouts
t, _ := Parse(nil, "02 Jan 06 15:04 MST")

fmt.Println(t.Format(time.UnixDate))

Output:

Mon Jan  2 15:04:00 MST 2006

Example (Nil)

// When no layouts match, Parse returns nil as Time and an error
t, err := Parse([]string{""}, "02 Jan 06 15:04 MST")
fmt.Println(t)
fmt.Println(err)

Output:

<nil>
parsing time "02 Jan 06 15:04 MST": extra text: 02 Jan 06 15:04 MST

Example (Ownlayouts)

// Parse a time string using a own layout
t, _ := Parse([]string{"2006-01-02 15:04"}, "2015-12-31 23:59")

fmt.Println(t.Format(time.UnixDate))
fmt.Println(t.Layouts())

Output:

Thu Dec 31 23:59:00 UTC 2015
[2006-01-02 15:04]

func (*Time) Layouts

func (t *Time) Layouts() []string

Layouts returns the layouts a Time object uses.

func (*Time) MarshalJSON

func (t *Time) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler interface. To format the date, the first element of layouts is used (with the objects own layouts overriding the packages).

Example

// Parse a time string using the layouts defined in wooly.Layouts
t, _ := Parse(nil, "02 Jan 06 15:04 MST")

// Marshal to JSON, using the first layout in wooly.Layouts
buf, _ := json.Marshal(t)

fmt.Println(string(buf))

Output:

"2006-01-02T15:04:00Z"

Example (Ownlayouts)

// Parse a time string using a own layout
t, _ := Parse([]string{"2006-01-02 15:04"}, "2015-12-31 23:59")

// Marshal to JSON, the first of the objects own layouts ("2006-01-02 15:04" in this case)
buf, _ := json.Marshal(t)

fmt.Println(string(buf))

Output:

"2015-12-31 23:59"

func (*Time) SetLayouts

func (t *Time) SetLayouts(layouts []string)

SetLayouts sets the layouts a Time object uses.

func (*Time) UnmarshalJSON

func (t *Time) UnmarshalJSON(data []byte) (err error)

UnmarshalJSON implements the json.Unmarshaler interface. The unmarshaling only fails when parsing has failed for every layout (with the objects own layouts overriding the packages).

Example

// JSON-RubyDate
buf := []byte(`"Mon Jan 02 15:04:05 -0700 2006"`)

var x Time

json.Unmarshal(buf, &x)

fmt.Println(x.Time.Format(time.RFC850))

Output:

Monday, 02-Jan-06 15:04:05 -0700

Example (Fail)

// Timestamp in a really nasty layout
buf := []byte(`"06 January 2018 11 hours 44 minutes 55 seconds"`)

var x Time

// This will fail as no matching layout is defined.
err := json.Unmarshal(buf, &x)

fmt.Println(err)
fmt.Println(x.Time.Format(time.UnixDate))

Output:

parsing time "06 January 2018 11 hours 44 minutes 55 seconds" as "Jan _2 15:04:05.000000000": cannot parse "06 January 2018 11 hours 44 minutes 55 seconds" as "Jan"
Mon Jan  1 00:00:00 UTC 0001

Example (Ownlayouts)

// Timestamp in a really nasty layout
buf := []byte(`"06 January 2018 11 hours 44 minutes 55 seconds"`)

var x Time
// Set the layouts of the time struct
x.SetLayouts([]string{"02 January 2006 15 hours 04 minutes 05 seconds"})

json.Unmarshal(buf, &x)

fmt.Println(x.Time.Format(time.UnixDate))

Output:

Sat Jan  6 11:44:55 UTC 2018