date

package module
v0.0.5 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 7, 2026 License: MIT Imports: 14 Imported by: 16

README

Go Date Parser

GoDoc Test Status Go ReportCard

Parse date/time strings without knowing the format in advance. Supports 100+ formats. Validates comprehensively to avoid false positives. Very fast (~single-pass state-machine based approach). See bench_test.go for performance comparison. See the critical note below about timezones.

⚡ Maintained by IT Lightning, a cloud-first logging platform that's uniquely powerful, super-easy (schemaless, point-and-shoot ingestion), and affordable. It automatically extracts and classifies structured data out of your unstructured log messages. Enjoy visual pattern-analysis and robust SQL-like search. It's unique architecture means you can log more and pay less. Check it out and give us feedback! ⚡

🐛💡 Find a bug or have an idea with this package? Issues and pull requests are welcome.

History and Contributors

This is an actively maintained fork of the excellent original dateparse package by @araddon. This fork incorporates many bugfixes from the community, and adds comprehensive validation and extensive performance optimizations. A special thanks to @araddon, other contributors to the original project, as well as those who contributed fixes that got incorporated into this version: @arran4, @bizy01, @BrianLeishman, @dferstay, @jiangxin, @jmdacruz, @krhubert, @mehanizm, @xwjdsh, and @zifengyu.

Ambiguous Date Formats

MM/DD/YYYY VS DD/MM/YYYY Right now this uses mm/dd/yyyy when ambiguous. If this is not desired behavior, use ParseStrict which will fail on ambiguous date strings. This behavior can be adjusted using the PreferMonthFirst parser option. Some ambiguous formats can fail (e.g., trying to parse 31/03/2023 as the default month-first format MM/DD/YYYY), but can be automatically retried with RetryAmbiguousDateWithSwap.


// Normal parse.  Equivalent Timezone rules as time.Parse()
t, err := dateparse.ParseAny("3/1/2014")

// Parse Strict, error on ambigous mm/dd vs dd/mm dates
t, err := dateparse.ParseStrict("3/1/2014")
> returns error 

// Return a string that represents the layout to parse the given date-time.
// For certain highly complex date formats, ParseFormat's return value may
// not be accurate (if this is the case, the returned format string will be a
// different length, than the input). In these cases, ParseAny will still be
// able to successfully parse the format, but this return value will fail to
// parse. For example, anything that starts with a full weekday will fail.
layout, err := dateparse.ParseFormat("May 8, 2009 5:57:51 PM")
> "Jan 2, 2006 3:04:05 PM"

Performance Considerations

Internally a memory pool is used to minimize allocation overhead. If you could be frequently parsing text that does not match any format, consider turning on the the SimpleErrorMessages option. This will make error messages have no contextual details, but will reduce allocation overhead 13x and will be 4x faster (most of the time is spent in generating a complex error message if the option is off (default)).

Timezone Considerations

The location that your server is configured to affects the results! See example or https://play.golang.org/p/IDHRalIyXh and last paragraph here https://golang.org/pkg/time/#Parse.

Important points to understand:

  • If you are parsing a date string that does not reference a timezone, if you use Parse it will assume UTC, or for ParseIn it will use the specified location.
  • If you are parsing a date string that does reference a timezone and does specify an explicit offset (e.g., 2012-08-03 13:31:59 -0600 MST), then it will return a time object with a location that represents a fixed timezone that has the given offset and name (it will not validate that the timezone abbreviation specified in the date string is a potential valid match for the given offset).
    • This can lead to some potentially unexpected results, for example consider the date string 2012-08-03 18:31:59.000+00:00 PST -- this string has an explicit offset of +00:00 (UTC), and so the returned time will have a location with a zero offset (18:31:59.000 UTC) even though the name of the fixed time zone associated with the returned time is PST. Essentially, it will always prioritize an explicit offset as accurate over an explicit
  • If you are parsing a date string that does reference a timezone but without an explicit offset (e.g., 2012-08-03 14:32:59 MST), then it will only recognize and map the timezone name and add an offset if you are using ParseIn and specify a location that knows about the given time zone abbreviation (e.g., in this example, you would need to pass the America/Denver location and it will recognize the MST and MDT time zone names)
    • If a time zone abbreviation is recognized based on the passed location, then it will use the appropriate offset, and make any appropriate adjustment for daylight saving time (e.g., in the above example, the parsed time would actually contain a zone name of MDT because the date is within the range when daylight savings time is active).
    • If a time zone abbreviation is not recognized for the passed location, then it will create a fake time zone with a zero offset but with the specified name. This requires further processing if you are trying to actually get the correct absolute time in the UTC time zone.
    • If you receive a parsed time that has a zero offset but a non-UTC timezone name, then you should use a method to map the (sometimes ambiguous) timezone name (e.g., "EEG") into a location name (e.g., "Africa/Cairo" or "Europe/Bucharest"), and then reconstruct a new time object with the same date/time/nanosecond but with the properly mapped location. (Do not use the time.In method to convert it to the new location, as this will treat the original time as if it was in UTC with a zero offset -- you need to reconstruct the time as if it was constructed with the proper location in the first place.)

cli tool for testing dateformats

Date Parse CLI

Extended example

https://github.com/oarkflow/date/blob/main/example/main.go

package main

import (
	"flag"
	"fmt"
	"time"

	"github.com/oarkflow/date"
	"github.com/scylladb/termtables"
)

var examples = []string{
	// mon day year (time)
	"May 8, 2009 5:57:51 PM",
	"oct 7, 1970",
	"oct 7, '70",
	"oct. 7, 1970",
	"oct. 7, 70",
	"October 7, 1970",
	"October 7th, 1970",
	"Sept. 7, 1970 11:15:26pm",
	"Sep 7 2009 11:15:26.123 PM PST",
	"September 3rd, 2009 11:15:26.123456789pm",
	"September 17 2012 10:09am",
	"September 17, 2012, 10:10:09",
	"Sep 17, 2012 at 10:02am (EST)",
	// (PST-08 will have an offset of -0800, and a zone name of "PST")
	"September 17, 2012 at 10:09am PST-08",
	// (UTC-0700 has the same offset as -0700, and the returned zone name will be empty)
	"September 17 2012 5:00pm UTC-0700",
	"September 17 2012 5:00pm GMT-0700",
	// (weekday) day mon year (time)
	"7 oct 70",
	"7 Oct 1970",
	"7 September 1970 23:15",
	"7 September 1970 11:15:26pm",
	"03 February 2013",
	"12 Feb 2006, 19:17",
	"12 Feb 2006 19:17",
	"14 May 2019 19:11:40.164",
	"4th Sep 2012",
	"1st February 2018 13:58:24",
	"Mon, 02 Jan 2006 15:04:05 MST", // RFC1123
	"Mon, 02 Jan 2006 15:04:05 -0700",
	"Tue, 11 Jul 2017 16:28:13 +0200 (CEST)",
	"Mon 30 Sep 2018 09:09:09 PM UTC",
	"Sun, 07 Jun 2020 00:00:00 +0100",
	"Wed,  8 Feb 2023 19:00:46 +1100 (AEDT)",
	// ANSIC and UnixDate - weekday month day time year
	"Mon Jan  2 15:04:05 2006",
	"Mon Jan  2 15:04:05 MST 2006",
	"Monday Jan 02 15:04:05 -0700 2006",
	"Mon Jan 2 15:04:05.103786 2006",
	// RubyDate - weekday month day time offset year
	"Mon Jan 02 15:04:05 -0700 2006",
	// ANSIC_GLIBC - weekday day month year time
	"Mon 02 Jan 2006 03:04:05 PM UTC",
	"Monday 02 Jan 2006 03:04:05 PM MST",
	// weekday month day time timezone-offset year
	"Mon Aug 10 15:44:11 UTC+0000 2015",
	// git log default date format
	"Thu Apr 7 15:13:13 2005 -0700",
	// variants of git log default date format
	"Thu Apr 7 15:13:13 2005 -07:00",
	"Thu Apr 7 15:13:13 2005 -07:00 PST",
	"Thu Apr 7 15:13:13 2005 -07:00 PST (Pacific Standard Time)",
	"Thu Apr 7 15:13:13 -0700 2005",
	"Thu Apr 7 15:13:13 -07:00 2005",
	"Thu Apr 7 15:13:13 -0700 PST 2005",
	"Thu Apr 7 15:13:13 -07:00 PST 2005",
	"Thu Apr 7 15:13:13 PST 2005",
	// Variants of the above with a (full time zone description)
	"Fri Jul 3 2015 06:04:07 PST-0700 (Pacific Daylight Time)",
	"Fri Jul 03 2015 18:04:07 GMT+0100 (GMT Daylight Time)",
	"Sun, 3 Jan 2021 00:12:23 +0800 (GMT+08:00)",
	// year month day
	"2013 May 2",
	"2013 May 02 11:37:55",
	// dd/Mon/year  alpha Months
	"06/Jan/2008 15:04:05 -0700",
	"06/January/2008 15:04:05 -0700",
	"06/Jan/2008:15:04:05 -0700", // ngnix-log
	"06/January/2008:08:11:17 -0700",
	// mm/dd/year (see also PreferMonthFirst and RetryAmbiguousDateWithSwap options)
	"3/31/2014",
	"03/31/2014",
	"08/21/71",
	"8/1/71",
	"4/8/2014 22:05",
	"04/08/2014 22:05",
	"04/08/2014, 22:05",
	"4/8/14 22:05",
	"04/2/2014 03:00:51",
	"8/8/1965 1:00 PM",
	"8/8/1965 01:00 PM",
	"8/8/1965 12:00 AM",
	"8/8/1965 12:00:00AM",
	"8/8/1965 01:00:01 PM",
	"8/8/1965 01:00:01PM -0700",
	"8/8/1965 13:00:01 -0700 PST",
	"8/8/1965 01:00:01 PM -0700 PST",
	"8/8/1965 01:00:01 PM -07:00 PST (Pacific Standard Time)",
	"4/02/2014 03:00:51",
	"03/19/2012 10:11:59",
	"03/19/2012 10:11:59.3186369",
	// mon/dd/year
	"Oct/ 7/1970",
	"Oct/03/1970 22:33:44",
	"February/03/1970 11:33:44.555 PM PST",
	// yyyy/mm/dd
	"2014/3/31",
	"2014/03/31",
	"2014/4/8 22:05",
	"2014/04/08 22:05",
	"2014/04/2 03:00:51",
	"2014/4/02 03:00:51",
	"2012/03/19 10:11:59",
	"2012/03/19 10:11:59.3186369",
	// weekday, day-mon-yy time
	"Fri, 03-Jul-15 08:08:08 CEST",
	"Monday, 02-Jan-06 15:04:05 MST", // RFC850
	"Monday, 02 Jan 2006 15:04:05 -0600",
	"02-Jan-06 15:04:05 MST",
	// RFC3339 - yyyy-mm-ddThh
	"2006-01-02T15:04:05+0000",
	"2009-08-12T22:15:09-07:00",
	"2009-08-12T22:15:09",
	"2009-08-12T22:15:09.988",
	"2009-08-12T22:15:09Z",
	"2009-08-12T22:15:09.52Z",
	"2017-07-19T03:21:51:897+0100",
	"2019-05-29T08:41-04", // no seconds, 2 digit TZ offset
	// yyyy-mm-dd hh:mm:ss
	"2014-04-26 17:24:37.3186369",
	"2012-08-03 18:31:59.257000000",
	"2014-04-26 17:24:37.123",
	"2014-04-01 12:01am",
	"2014-04-01 12:01:59.765 AM",
	"2014-04-01 12:01:59,765",
	"2014-04-01 22:43",
	"2014-04-01 22:43:22",
	"2014-12-16 06:20:00 UTC",
	"2014-12-16 06:20:00 GMT",
	"2014-04-26 05:24:37 PM",
	"2014-04-26 13:13:43 +0800",
	"2014-04-26 13:13:43 +0800 +08",
	"2014-04-26 13:13:44 +09:00",
	"2012-08-03 18:31:59.257000000 +0000 UTC",
	"2015-09-30 18:48:56.35272715 +0000 UTC",
	"2015-02-18 00:12:00 +0000 GMT", // golang native format
	"2015-02-18 00:12:00 +0000 UTC",
	"2015-02-08 03:02:00 +0300 MSK m=+0.000000001",
	"2015-02-08 03:02:00.001 +0300 MSK m=+0.000000001",
	"2017-07-19 03:21:51+00:00",
	"2017-04-03 22:32:14.322 CET",
	"2017-04-03 22:32:14,322 CET",
	"2017-04-03 22:32:14:322 CET",
	"2018-09-30 08:09:13.123PM PMDT", // PMDT time zone
	"2018-09-30 08:09:13.123 am AMT", // AMT time zone
	"2014-04-26",
	"2014-04",
	"2014",
	// yyyy-mm-dd(offset)
	"2020-07-20+08:00",
	"2020-07-20+0800",
	// year-mon-dd
	"2013-Feb-03",
	"2013-February-03 09:07:08.123",
	// dd-mon-year
	"03-Feb-13",
	"03-Feb-2013",
	"07-Feb-2004 09:07:07 +0200",
	"07-February-2004 09:07:07 +0200",
	// dd-mm-year (this format (common in Europe) always puts the day first, regardless of PreferMonthFirst)
	"28-02-02",
	"28-02-02 15:16:17",
	"28-02-2002",
	"28-02-2002 15:16:17",
	// mm.dd.yy (see also PreferMonthFirst and RetryAmbiguousDateWithSwap options)
	"3.31.2014",
	"03.31.14",
	"03.31.2014",
	"03.31.2014 10:11:59 MST",
	"03.31.2014 10:11:59.3186369Z",
	// year.mm.dd
	"2014.03",
	"2014.03.30",
	"2014.03.30 08:33pm",
	"2014.03.30T08:33:44.555 PM -0700 MST",
	"2014.03.30-0600",
	// yyyy:mm:dd
	"2014:3:31",
	"2014:03:31",
	"2014:4:8 22:05",
	"2014:04:08 22:05",
	"2014:04:2 03:00:51",
	"2014:4:02 03:00:51",
	"2012:03:19 10:11:59",
	"2012:03:19 10:11:59.3186369",
	// mm:dd:yyyy (see also PreferMonthFirst and RetryAmbiguousDateWithSwap options)
	"08:03:2012",
	"08:04:2012 18:31:59+00:00",
	// yyyymmdd and similar
	"20140601",
	"20140722105203",
	"20140722105203.364",
	// Chinese
	"2014年4月25日",
	"2014年04月08日",
	"2014年04月08日 19:17:22 -0700",
	// RabbitMQ log format
	"8-Mar-2018::14:09:27",
	"08-03-2018::02:09:29 PM",
	// yymmdd hh:mm:yy mysql log
	// 080313 05:21:55 mysqld started
	"171113 14:14:20",
	"190910 11:51:49",
	// unix seconds, ms, micro, nano
	"1332151919",
	"1384216367189",
	"1384216367111222",
	"1384216367111222333",
}

var (
	timezone = ""
)

func main() {
	flag.StringVar(&timezone, "timezone", "UTC", "Timezone aka `America/Los_Angeles` formatted time-zone")
	flag.Parse()

	if timezone != "" {
		// NOTE:  This is very, very important to understand
		// time-parsing in go
		loc, err := time.LoadLocation(timezone)
		if err != nil {
			panic(err.Error())
		}
		time.Local = loc
	}

	table := termtables.CreateTable()

	table.AddHeaders("Input", "Parsed, and Output as %v")
	for _, dateExample := range examples {
		t, err := dateparse.ParseLocal(dateExample)
		if err != nil {
			panic(err.Error())
		}
		table.AddRow(dateExample, fmt.Sprintf("%v", t))
	}
	fmt.Println(table.Render())
}

/*
+------------------------------------------------------------+-----------------------------------------+
| Input                                                      | Parsed, and Output as %v                |
+------------------------------------------------------------+-----------------------------------------+
| May 8, 2009 5:57:51 PM                                     | 2009-05-08 17:57:51 +0000 UTC           |
| oct 7, 1970                                                | 1970-10-07 00:00:00 +0000 UTC           |
| oct 7, '70                                                 | 1970-10-07 00:00:00 +0000 UTC           |
| oct. 7, 1970                                               | 1970-10-07 00:00:00 +0000 UTC           |
| oct. 7, 70                                                 | 1970-10-07 00:00:00 +0000 UTC           |
| October 7, 1970                                            | 1970-10-07 00:00:00 +0000 UTC           |
| October 7th, 1970                                          | 1970-10-07 00:00:00 +0000 UTC           |
| Sept. 7, 1970 11:15:26pm                                   | 1970-09-07 23:15:26 +0000 UTC           |
| Sep 7 2009 11:15:26.123 PM PST                             | 2009-09-07 23:15:26.123 +0000 PST       |
| September 3rd, 2009 11:15:26.123456789pm                   | 2009-09-03 23:15:26.123456789 +0000 UTC |
| September 17 2012 10:09am                                  | 2012-09-17 10:09:00 +0000 UTC           |
| September 17, 2012, 10:10:09                               | 2012-09-17 10:10:09 +0000 UTC           |
| Sep 17, 2012 at 10:02am (EST)                              | 2012-09-17 10:02:00 +0000 EST           |
| September 17, 2012 at 10:09am PST-08                       | 2012-09-17 10:09:00 -0800 PST           |
| September 17 2012 5:00pm UTC-0700                          | 2012-09-17 17:00:00 -0700 -0700         |
| September 17 2012 5:00pm GMT-0700                          | 2012-09-17 17:00:00 -0700 -0700         |
| 7 oct 70                                                   | 1970-10-07 00:00:00 +0000 UTC           |
| 7 Oct 1970                                                 | 1970-10-07 00:00:00 +0000 UTC           |
| 7 September 1970 23:15                                     | 1970-09-07 23:15:00 +0000 UTC           |
| 7 September 1970 11:15:26pm                                | 1970-09-07 23:15:26 +0000 UTC           |
| 03 February 2013                                           | 2013-02-03 00:00:00 +0000 UTC           |
| 12 Feb 2006, 19:17                                         | 2006-02-12 19:17:00 +0000 UTC           |
| 12 Feb 2006 19:17                                          | 2006-02-12 19:17:00 +0000 UTC           |
| 14 May 2019 19:11:40.164                                   | 2019-05-14 19:11:40.164 +0000 UTC       |
| 4th Sep 2012                                               | 2012-09-04 00:00:00 +0000 UTC           |
| 1st February 2018 13:58:24                                 | 2018-02-01 13:58:24 +0000 UTC           |
| Mon, 02 Jan 2006 15:04:05 MST                              | 2006-01-02 15:04:05 +0000 MST           |
| Mon, 02 Jan 2006 15:04:05 -0700                            | 2006-01-02 15:04:05 -0700 -0700         |
| Tue, 11 Jul 2017 16:28:13 +0200 (CEST)                     | 2017-07-11 16:28:13 +0200 +0200         |
| Mon 30 Sep 2018 09:09:09 PM UTC                            | 2018-09-30 21:09:09 +0000 UTC           |
| Sun, 07 Jun 2020 00:00:00 +0100                            | 2020-06-07 00:00:00 +0100 +0100         |
| Wed,  8 Feb 2023 19:00:46 +1100 (AEDT)                     | 2023-02-08 19:00:46 +1100 +1100         |
| Mon Jan  2 15:04:05 2006                                   | 2006-01-02 15:04:05 +0000 UTC           |
| Mon Jan  2 15:04:05 MST 2006                               | 2006-01-02 15:04:05 +0000 MST           |
| Monday Jan 02 15:04:05 -0700 2006                          | 2006-01-02 15:04:05 -0700 -0700         |
| Mon Jan 2 15:04:05.103786 2006                             | 2006-01-02 15:04:05.103786 +0000 UTC    |
| Mon Jan 02 15:04:05 -0700 2006                             | 2006-01-02 15:04:05 -0700 -0700         |
| Mon 02 Jan 2006 03:04:05 PM UTC                            | 2006-01-02 15:04:05 +0000 UTC           |
| Monday 02 Jan 2006 03:04:05 PM MST                         | 2006-01-02 15:04:05 +0000 MST           |
| Mon Aug 10 15:44:11 UTC+0000 2015                          | 2015-08-10 15:44:11 +0000 UTC           |
| Thu Apr 7 15:13:13 2005 -0700                              | 2005-04-07 15:13:13 -0700 -0700         |
| Thu Apr 7 15:13:13 2005 -07:00                             | 2005-04-07 15:13:13 -0700 -0700         |
| Thu Apr 7 15:13:13 2005 -07:00 PST                         | 2005-04-07 15:13:13 -0700 PST           |
| Thu Apr 7 15:13:13 2005 -07:00 PST (Pacific Standard Time) | 2005-04-07 15:13:13 -0700 PST           |
| Thu Apr 7 15:13:13 -0700 2005                              | 2005-04-07 15:13:13 -0700 -0700         |
| Thu Apr 7 15:13:13 -07:00 2005                             | 2005-04-07 15:13:13 -0700 -0700         |
| Thu Apr 7 15:13:13 -0700 PST 2005                          | 2005-04-07 15:13:13 -0700 PST           |
| Thu Apr 7 15:13:13 -07:00 PST 2005                         | 2005-04-07 15:13:13 -0700 PST           |
| Thu Apr 7 15:13:13 PST 2005                                | 2005-04-07 15:13:13 +0000 PST           |
| Fri Jul 3 2015 06:04:07 PST-0700 (Pacific Daylight Time)   | 2015-07-03 06:04:07 -0700 PST           |
| Fri Jul 03 2015 18:04:07 GMT+0100 (GMT Daylight Time)      | 2015-07-03 18:04:07 +0100 +0100         |
| Sun, 3 Jan 2021 00:12:23 +0800 (GMT+08:00)                 | 2021-01-03 00:12:23 +0800 +0800         |
| 2013 May 2                                                 | 2013-05-02 00:00:00 +0000 UTC           |
| 2013 May 02 11:37:55                                       | 2013-05-02 11:37:55 +0000 UTC           |
| 06/Jan/2008 15:04:05 -0700                                 | 2008-01-06 15:04:05 -0700 -0700         |
| 06/January/2008 15:04:05 -0700                             | 2008-01-06 15:04:05 -0700 -0700         |
| 06/Jan/2008:15:04:05 -0700                                 | 2008-01-06 15:04:05 -0700 -0700         |
| 06/January/2008:08:11:17 -0700                             | 2008-01-06 08:11:17 -0700 -0700         |
| 3/31/2014                                                  | 2014-03-31 00:00:00 +0000 UTC           |
| 03/31/2014                                                 | 2014-03-31 00:00:00 +0000 UTC           |
| 08/21/71                                                   | 1971-08-21 00:00:00 +0000 UTC           |
| 8/1/71                                                     | 1971-08-01 00:00:00 +0000 UTC           |
| 4/8/2014 22:05                                             | 2014-04-08 22:05:00 +0000 UTC           |
| 04/08/2014 22:05                                           | 2014-04-08 22:05:00 +0000 UTC           |
| 04/08/2014, 22:05                                          | 2014-04-08 22:05:00 +0000 UTC           |
| 4/8/14 22:05                                               | 2014-04-08 22:05:00 +0000 UTC           |
| 04/2/2014 03:00:51                                         | 2014-04-02 03:00:51 +0000 UTC           |
| 8/8/1965 1:00 PM                                           | 1965-08-08 13:00:00 +0000 UTC           |
| 8/8/1965 01:00 PM                                          | 1965-08-08 13:00:00 +0000 UTC           |
| 8/8/1965 12:00 AM                                          | 1965-08-08 00:00:00 +0000 UTC           |
| 8/8/1965 12:00:00AM                                        | 1965-08-08 00:00:00 +0000 UTC           |
| 8/8/1965 01:00:01 PM                                       | 1965-08-08 13:00:01 +0000 UTC           |
| 8/8/1965 01:00:01PM -0700                                  | 1965-08-08 13:00:01 -0700 -0700         |
| 8/8/1965 13:00:01 -0700 PST                                | 1965-08-08 13:00:01 -0700 PST           |
| 8/8/1965 01:00:01 PM -0700 PST                             | 1965-08-08 13:00:01 -0700 PST           |
| 8/8/1965 01:00:01 PM -07:00 PST (Pacific Standard Time)    | 1965-08-08 13:00:01 -0700 PST           |
| 4/02/2014 03:00:51                                         | 2014-04-02 03:00:51 +0000 UTC           |
| 03/19/2012 10:11:59                                        | 2012-03-19 10:11:59 +0000 UTC           |
| 03/19/2012 10:11:59.3186369                                | 2012-03-19 10:11:59.3186369 +0000 UTC   |
| Oct/ 7/1970                                                | 1970-10-07 00:00:00 +0000 UTC           |
| Oct/03/1970 22:33:44                                       | 1970-10-03 22:33:44 +0000 UTC           |
| February/03/1970 11:33:44.555 PM PST                       | 1970-02-03 23:33:44.555 +0000 PST       |
| 2014/3/31                                                  | 2014-03-31 00:00:00 +0000 UTC           |
| 2014/03/31                                                 | 2014-03-31 00:00:00 +0000 UTC           |
| 2014/4/8 22:05                                             | 2014-04-08 22:05:00 +0000 UTC           |
| 2014/04/08 22:05                                           | 2014-04-08 22:05:00 +0000 UTC           |
| 2014/04/2 03:00:51                                         | 2014-04-02 03:00:51 +0000 UTC           |
| 2014/4/02 03:00:51                                         | 2014-04-02 03:00:51 +0000 UTC           |
| 2012/03/19 10:11:59                                        | 2012-03-19 10:11:59 +0000 UTC           |
| 2012/03/19 10:11:59.3186369                                | 2012-03-19 10:11:59.3186369 +0000 UTC   |
| Fri, 03-Jul-15 08:08:08 CEST                               | 2015-07-03 08:08:08 +0000 CEST          |
| Monday, 02-Jan-06 15:04:05 MST                             | 2006-01-02 15:04:05 +0000 MST           |
| Monday, 02 Jan 2006 15:04:05 -0600                         | 2006-01-02 15:04:05 -0600 -0600         |
| 02-Jan-06 15:04:05 MST                                     | 2006-01-02 15:04:05 +0000 MST           |
| 2006-01-02T15:04:05+0000                                   | 2006-01-02 15:04:05 +0000 UTC           |
| 2009-08-12T22:15:09-07:00                                  | 2009-08-12 22:15:09 -0700 -0700         |
| 2009-08-12T22:15:09                                        | 2009-08-12 22:15:09 +0000 UTC           |
| 2009-08-12T22:15:09.988                                    | 2009-08-12 22:15:09.988 +0000 UTC       |
| 2009-08-12T22:15:09Z                                       | 2009-08-12 22:15:09 +0000 UTC           |
| 2009-08-12T22:15:09.52Z                                    | 2009-08-12 22:15:09.52 +0000 UTC        |
| 2017-07-19T03:21:51:897+0100                               | 2017-07-19 03:21:51.897 +0100 +0100     |
| 2019-05-29T08:41-04                                        | 2019-05-29 08:41:00 -0400 -0400         |
| 2014-04-26 17:24:37.3186369                                | 2014-04-26 17:24:37.3186369 +0000 UTC   |
| 2012-08-03 18:31:59.257000000                              | 2012-08-03 18:31:59.257 +0000 UTC       |
| 2014-04-26 17:24:37.123                                    | 2014-04-26 17:24:37.123 +0000 UTC       |
| 2014-04-01 12:01am                                         | 2014-04-01 00:01:00 +0000 UTC           |
| 2014-04-01 12:01:59.765 AM                                 | 2014-04-01 00:01:59.765 +0000 UTC       |
| 2014-04-01 12:01:59,765                                    | 2014-04-01 12:01:59.765 +0000 UTC       |
| 2014-04-01 22:43                                           | 2014-04-01 22:43:00 +0000 UTC           |
| 2014-04-01 22:43:22                                        | 2014-04-01 22:43:22 +0000 UTC           |
| 2014-12-16 06:20:00 UTC                                    | 2014-12-16 06:20:00 +0000 UTC           |
| 2014-12-16 06:20:00 GMT                                    | 2014-12-16 06:20:00 +0000 GMT           |
| 2014-04-26 05:24:37 PM                                     | 2014-04-26 17:24:37 +0000 UTC           |
| 2014-04-26 13:13:43 +0800                                  | 2014-04-26 13:13:43 +0800 +0800         |
| 2014-04-26 13:13:43 +0800 +08                              | 2014-04-26 13:13:43 +0800 +0800         |
| 2014-04-26 13:13:44 +09:00                                 | 2014-04-26 13:13:44 +0900 +0900         |
| 2012-08-03 18:31:59.257000000 +0000 UTC                    | 2012-08-03 18:31:59.257 +0000 UTC       |
| 2015-09-30 18:48:56.35272715 +0000 UTC                     | 2015-09-30 18:48:56.35272715 +0000 UTC  |
| 2015-02-18 00:12:00 +0000 GMT                              | 2015-02-18 00:12:00 +0000 GMT           |
| 2015-02-18 00:12:00 +0000 UTC                              | 2015-02-18 00:12:00 +0000 UTC           |
| 2015-02-08 03:02:00 +0300 MSK m=+0.000000001               | 2015-02-08 03:02:00 +0300 MSK           |
| 2015-02-08 03:02:00.001 +0300 MSK m=+0.000000001           | 2015-02-08 03:02:00.001 +0300 MSK       |
| 2017-07-19 03:21:51+00:00                                  | 2017-07-19 03:21:51 +0000 UTC           |
| 2017-04-03 22:32:14.322 CET                                | 2017-04-03 22:32:14.322 +0000 CET       |
| 2017-04-03 22:32:14,322 CET                                | 2017-04-03 22:32:14.322 +0000 CET       |
| 2017-04-03 22:32:14:322 CET                                | 2017-04-03 22:32:14.322 +0000 CET       |
| 2018-09-30 08:09:13.123PM PMDT                             | 2018-09-30 20:09:13.123 +0000 PMDT      |
| 2018-09-30 08:09:13.123 am AMT                             | 2018-09-30 08:09:13.123 +0000 AMT       |
| 2014-04-26                                                 | 2014-04-26 00:00:00 +0000 UTC           |
| 2014-04                                                    | 2014-04-01 00:00:00 +0000 UTC           |
| 2014                                                       | 2014-01-01 00:00:00 +0000 UTC           |
| 2020-07-20+08:00                                           | 2020-07-20 00:00:00 +0800 +0800         |
| 2020-07-20+0800                                            | 2020-07-20 00:00:00 +0800 +0800         |
| 2013-Feb-03                                                | 2013-02-03 00:00:00 +0000 UTC           |
| 2013-February-03 09:07:08.123                              | 2013-02-03 09:07:08.123 +0000 UTC       |
| 03-Feb-13                                                  | 2013-02-03 00:00:00 +0000 UTC           |
| 03-Feb-2013                                                | 2013-02-03 00:00:00 +0000 UTC           |
| 07-Feb-2004 09:07:07 +0200                                 | 2004-02-07 09:07:07 +0200 +0200         |
| 07-February-2004 09:07:07 +0200                            | 2004-02-07 09:07:07 +0200 +0200         |
| 28-02-02                                                   | 2002-02-28 00:00:00 +0000 UTC           |
| 28-02-02 15:16:17                                          | 2002-02-28 15:16:17 +0000 UTC           |
| 28-02-2002                                                 | 2002-02-28 00:00:00 +0000 UTC           |
| 28-02-2002 15:16:17                                        | 2002-02-28 15:16:17 +0000 UTC           |
| 3.31.2014                                                  | 2014-03-31 00:00:00 +0000 UTC           |
| 03.31.14                                                   | 2014-03-31 00:00:00 +0000 UTC           |
| 03.31.2014                                                 | 2014-03-31 00:00:00 +0000 UTC           |
| 03.31.2014 10:11:59 MST                                    | 2014-03-31 10:11:59 +0000 MST           |
| 03.31.2014 10:11:59.3186369Z                               | 2014-03-31 10:11:59.3186369 +0000 UTC   |
| 2014.03                                                    | 2014-03-01 00:00:00 +0000 UTC           |
| 2014.03.30                                                 | 2014-03-30 00:00:00 +0000 UTC           |
| 2014.03.30 08:33pm                                         | 2014-03-30 20:33:00 +0000 UTC           |
| 2014.03.30T08:33:44.555 PM -0700 MST                       | 2014-03-30 20:33:44.555 -0700 MST       |
| 2014.03.30-0600                                            | 2014-03-30 00:00:00 -0600 -0600         |
| 2014:3:31                                                  | 2014-03-31 00:00:00 +0000 UTC           |
| 2014:03:31                                                 | 2014-03-31 00:00:00 +0000 UTC           |
| 2014:4:8 22:05                                             | 2014-04-08 22:05:00 +0000 UTC           |
| 2014:04:08 22:05                                           | 2014-04-08 22:05:00 +0000 UTC           |
| 2014:04:2 03:00:51                                         | 2014-04-02 03:00:51 +0000 UTC           |
| 2014:4:02 03:00:51                                         | 2014-04-02 03:00:51 +0000 UTC           |
| 2012:03:19 10:11:59                                        | 2012-03-19 10:11:59 +0000 UTC           |
| 2012:03:19 10:11:59.3186369                                | 2012-03-19 10:11:59.3186369 +0000 UTC   |
| 08:03:2012                                                 | 2012-08-03 00:00:00 +0000 UTC           |
| 08:04:2012 18:31:59+00:00                                  | 2012-08-04 18:31:59 +0000 UTC           |
| 20140601                                                   | 2014-06-01 00:00:00 +0000 UTC           |
| 20140722105203                                             | 2014-07-22 10:52:03 +0000 UTC           |
| 20140722105203.364                                         | 2014-07-22 10:52:03.364 +0000 UTC       |
| 2014年4月25日                                              | 2014-04-25 00:00:00 +0000 UTC           |
| 2014年04月08日                                             | 2014-04-08 00:00:00 +0000 UTC           |
| 2014年04月08日 19:17:22 -0700                              | 2014-04-08 19:17:22 -0700 -0700         |
| 8-Mar-2018::14:09:27                                       | 2018-03-08 14:09:27 +0000 UTC           |
| 08-03-2018::02:09:29 PM                                    | 2018-03-08 14:09:29 +0000 UTC           |
| 171113 14:14:20                                            | 2017-11-13 14:14:20 +0000 UTC           |
| 190910 11:51:49                                            | 2019-09-10 11:51:49 +0000 UTC           |
| 1332151919                                                 | 2012-03-19 10:11:59 +0000 UTC           |
| 1384216367189                                              | 2013-11-12 00:32:47.189 +0000 UTC       |
| 1384216367111222                                           | 2013-11-12 00:32:47.111222 +0000 UTC    |
| 1384216367111222333                                        | 2013-11-12 00:32:47.111222333 +0000 UTC |
+------------------------------------------------------------+-----------------------------------------+
*/

Documentation

Overview

Package dateparse parses date-strings without knowing the format in advance, using a fast lex based approach to eliminate shotgun attempts. Validates comprehensively to avoid false positives.

By default it leans towards US style dates when there is a conflict. This can be adjusted using the `PreferMonthFirst` parser option. Some ambiguous formats can fail (e.g., trying to parse `31/03/2023“ as the default month-first format `MM/DD/YYYY`), but can be automatically retried with `RetryAmbiguousDateWithSwap`.

Consider turning on the the `SimpleErrorMessages` option if you will be attempting to parse many strings that do not match any known format and you need to maximize performance.

See README.md for key points on how timezone/location parsing works in go, as this can be counterintuitive initially.

Index

Constants

View Source 
const (
	ExprTypeInvalid = 0
	ExprTypeDate    = ExprType(1 << iota)
	ExprTypeTime
	ExprTypeNow
	ExprTypeRelativeMinutes
	ExprTypeRelativeHours
	ExprTypeRelativeDays
	ExprTypeRelativeWeeks
	ExprTypeRelativeWeekdays
	ExprTypeRelativeMonth
	ExprTypeRelativeYear
	ExprTypeClock12Hour
	ExprTypeClock24Hour
)
View Source 
const (
	Timezone string = "Asia/Kathmandu"
)

Variables

View Source 
var (
	// ErrAmbiguousMMDD for date formats such as 04/02/2014 the mm/dd vs dd/mm are
	// ambiguous, so it is an error for strict parse rules.
	ErrAmbiguousMMDD     = fmt.Errorf("this date has ambiguous mm/dd vs dd/mm type format")
	ErrCouldntFindFormat = fmt.Errorf("could not find format for")
	ErrUnexpectedTail    = fmt.Errorf("unexpected content after date/time: ")
	ErrUnknownTZOffset   = fmt.Errorf("TZ offset not recognized")
	ErrUnknownTimeZone   = fmt.Errorf("timezone not recognized")
	ErrFracSecTooLong    = fmt.Errorf("fractional seconds too long")
)

Functions

func AddBusinessDays added in v0.0.5 

func AddBusinessDays(t time.Time, n int, holidays []time.Time) time.Time

AddBusinessDays adds n business days to t, skipping weekends and any dates in the optional holidays slice. n may be negative to go backwards.

func AgeDetailed added in v0.0.5 

func AgeDetailed(birthDate, targetDate time.Time) (years, months, days int)

AgeDetailed returns the exact difference in years, months, and days between birthDate and targetDate. If targetDate is before birthDate, they are swapped.

func AgeDetailedToNow added in v0.0.5 

func AgeDetailedToNow(birthDate time.Time) (years, months, days int)

AgeDetailedToNow returns the exact difference in years, months, and days between birthDate and now.

func BeginningOfMonth added in v0.0.4 

func BeginningOfMonth(date time.Time) time.Time

func BeginningOfWeek added in v0.0.5 

func BeginningOfWeek(date time.Time) time.Time

func BeginningOfYear added in v0.0.5 

func BeginningOfYear(date time.Time) time.Time

func BusinessDaysBetween added in v0.0.5 

func BusinessDaysBetween(a, b time.Time, holidays []time.Time) int

BusinessDaysBetween counts the number of business days between a and b (exclusive of a, inclusive of b direction), skipping weekends and holidays. Returns a negative number if b is before a.

func Calculate added in v0.0.4 

func Calculate(startTime, endTime time.Time) int

Calculate returns an integer-value age based on the duration between the two times that are given as arguments.

func CalculateToNow added in v0.0.4 

func CalculateToNow(givenTime time.Time) int

CalculateToNow returns an integer-value age based on the duration between the given time and the present time.

func CalendarWeeks added in v0.0.5 

func CalendarWeeks(year int, month time.Month) [][]time.Time

CalendarWeeks returns the weeks of the given year and month as a 2-D slice. Each inner slice is a 7-element array [Sunday … Saturday]; days that fall outside the month are represented as the zero time.Time.

func Clamp added in v0.0.5 

func Clamp(t, minT, maxT time.Time) time.Time

Clamp returns t if it is within [min, max]; otherwise it returns min or max.

func ConvertTZ added in v0.0.5 

func ConvertTZ(t time.Time, to string) (time.Time, error)

ConvertTZ converts t from its current timezone to the named IANA timezone.

func DayOfYear added in v0.0.5 

func DayOfYear(t time.Time) int

DayOfYear returns the day of the year for t (1–365 or 1–366 for leap years).

func DaysInMonth added in v0.0.5 

func DaysInMonth(year int, month time.Month) int

DaysInMonth returns the number of days in the given month and year.

func DaysSince added in v0.0.5 

func DaysSince(t time.Time) int

DaysSince returns the number of whole calendar days that have elapsed since t. Returns a negative number if t is in the future.

func DaysUntil added in v0.0.5 

func DaysUntil(t time.Time) int

DaysUntil returns the number of whole calendar days from now until t. Returns a negative number if t is in the past.

func EasterDate added in v0.0.5 

func EasterDate(year int) time.Time

EasterDate returns the date of Easter Sunday for the given Gregorian year using the Anonymous Gregorian algorithm.

func EndOfDay added in v0.0.5 

func EndOfDay(t time.Time) time.Time

EndOfDay returns the last instant of t's day (23:59:59.999999999).

func EndOfMonth added in v0.0.4 

func EndOfMonth(t time.Time) time.Time

EndOfMonth returns the last instant of t's month.

func EndOfQuarter added in v0.0.5 

func EndOfQuarter(t time.Time) time.Time

EndOfQuarter returns the last instant of the quarter in which t falls.

func EndOfWeek added in v0.0.5 

func EndOfWeek(t time.Time, startDay ...time.Weekday) time.Time

EndOfWeek returns the last instant of the week that contains t. startDay specifies which weekday begins the week (default: time.Monday).

func EndOfYear added in v0.0.5 

func EndOfYear(t time.Time) time.Time

EndOfYear returns the last instant of t's year.

func EnglishToNepali added in v0.0.4 

func EnglishToNepali(year int, month int, day int) (*[3]int, error)

Converts english date to nepali. Accepts the input parameters year, month, day. Returns dates in array and error.

func Format added in v0.0.5 

func Format(t time.Time, layout string) string

Format formats t using a strftime-style layout string. Most POSIX strftime directives are supported.

func FormatDate added in v0.0.5 

func FormatDate(t time.Time) string

FormatDate formats t as "YYYY-MM-DD".

func FormatDateTime added in v0.0.5 

func FormatDateTime(t time.Time) string

FormatDateTime formats t as "YYYY-MM-DD HH:MM:SS".

func FormatDateTimeMs added in v0.0.5 

func FormatDateTimeMs(t time.Time) string

FormatDateTimeMs formats t as "YYYY-MM-DD HH:MM:SS.mmm".

func FormatDuration added in v0.0.5 

func FormatDuration(d time.Duration, short bool) string

FormatDuration formats d as a human-readable string. If short is true, abbreviated units are used (e.g. "2d 3h 15m 5s"). If short is false, full unit names are used (e.g. "2 days 3 hours 15 minutes 5 seconds"). Only non-zero components are included.

func FormatHuman added in v0.0.5 

func FormatHuman(t time.Time) string

FormatHuman returns a friendly date string like "Wednesday, January 15, 2025".

func FormatHumanTime added in v0.0.5 

func FormatHumanTime(t time.Time) string

FormatHumanTime returns a friendly datetime string like "Wednesday, January 15, 2025 at 3:04 PM".

func FormatRFC3339 added in v0.0.5 

func FormatRFC3339(t time.Time) string

FormatRFC3339 formats t as RFC 3339 (a profile of ISO 8601).

func FormatRFC3339Nano added in v0.0.5 

func FormatRFC3339Nano(t time.Time) string

FormatRFC3339Nano formats t as RFC 3339 with nanosecond precision.

func GetCurrentEnglishTime added in v0.0.4 

func GetCurrentEnglishTime() time.Time

Gets current English date along with time level precision. Current Time of Asia/Kathmandu

func GetNepaliLocation added in v0.0.4 

func GetNepaliLocation() *time.Location

Returns location for Asia/Kathmandu (constants.Timezone)

func GuessTimezone added in v0.0.5 

func GuessTimezone(abbr string) (string, bool)

GuessTimezone maps a common timezone abbreviation (e.g. "IST", "PST") to a canonical IANA timezone name. It returns the name and true on success, or ("", false) when the abbreviation is not recognized.

func HumanizeDuration added in v0.0.5 

func HumanizeDuration(d time.Duration) string

HumanizeDuration returns a coarse, human-friendly description of d such as "just now", "about 3 minutes", "2 hours", "3 days", "about 2 months", etc.

func IsHoliday added in v0.0.5 

func IsHoliday(t time.Time, holidays []time.Time) bool

IsHoliday reports whether t (at day granularity) matches any date in the holidays slice.

func IsLeapYear added in v0.0.4 

func IsLeapYear(givenYear int) bool

IsLeapYear returns true only if the given year contains a leap day, meaning that the year is a leap year.

func IsSameDay added in v0.0.5 

func IsSameDay(a, b time.Time) bool

IsSameDay reports whether a and b fall on the same calendar day (ignoring clock time and timezone differences).

func IsSameMonth added in v0.0.5 

func IsSameMonth(a, b time.Time) bool

IsSameMonth reports whether a and b fall in the same month of the same year.

func IsSameWeek added in v0.0.5 

func IsSameWeek(a, b time.Time) bool

IsSameWeek reports whether a and b fall in the same ISO week of the same year.

func IsSameYear added in v0.0.5 

func IsSameYear(a, b time.Time) bool

IsSameYear reports whether a and b fall in the same year.

func IsValidTimezone added in v0.0.5 

func IsValidTimezone(zone string) bool

IsValidTimezone reports whether zone is a recognized IANA timezone name.

func IsWeekday added in v0.0.5 

func IsWeekday(t time.Time) bool

IsWeekday reports whether t falls on a Monday–Friday.

func IsWeekend added in v0.0.5 

func IsWeekend(t time.Time) bool

IsWeekend reports whether t falls on a Saturday or Sunday.

func LastWeekdayOfMonth added in v0.0.5 

func LastWeekdayOfMonth(year int, month time.Month, weekday time.Weekday) time.Time

LastWeekdayOfMonth returns the last occurrence of weekday in the given year and month.

func LoadLocation added in v0.0.5 

func LoadLocation(zone string) (*time.Location, error)

LoadLocation is a convenience wrapper around time.LoadLocation that returns a descriptive error.

func LocalToUTC added in v0.0.5 

func LocalToUTC(t time.Time) time.Time

LocalToUTC converts t to UTC.

func MonthName added in v0.0.5 

func MonthName(m time.Month) string

MonthName returns the full English name of the given month.

func MonthsBetween added in v0.0.5 

func MonthsBetween(a, b time.Time) int

MonthsBetween returns the approximate number of whole calendar months between a and b (based on year/month arithmetic, ignoring day-of-month).

func MustParse 

func MustParse(datestr string, opts ...ParserOption) time.Time

MustParse parse a date, and panic if it can't be parsed. Used for testing. Not recommended for most use-cases.

func NepaliToEnglish added in v0.0.4 

func NepaliToEnglish(year int, month int, day int) (*[3]int, error)

Converts nepali date to english. Accepts the input parameters year, month, day. Returns dates in array and error.

func NextLeapYear added in v0.0.4 

func NextLeapYear(givenYear int) (foundYear int, found bool)

NextLeapYear returns the next leap year after a given year. It also returns a boolean value that is set to false if no such year can be found.

func NthWeekdayOfMonth added in v0.0.5 

func NthWeekdayOfMonth(year int, month time.Month, weekday time.Weekday, n int) time.Time

NthWeekdayOfMonth returns the nth occurrence of weekday in the given year and month. For example, NthWeekdayOfMonth(2024, time.November, time.Thursday, 4) returns the 4th Thursday of November 2024 (US Thanksgiving). n must be in [1, 5]. If the month does not have an nth occurrence, the zero Time is returned.

func Ordinal added in v0.0.5 

func Ordinal(n int) string

Ordinal returns the English ordinal suffix string for n (e.g. 1→"1st", 2→"2nd", 11→"11th", 23→"23rd").

func Parse 

func Parse(datestr string, opts ...ParserOption) (time.Time, error)

Parse parse an unknown date format, detect the layout. Normal parse. Equivalent Timezone rules as time.Parse(). NOTE: please see readme on mmdd vs ddmm ambiguous dates.

func ParseDuration added in v0.0.5 

func ParseDuration(s string) (time.Duration, error)

ParseDuration parses a human-readable duration string and returns the equivalent time.Duration. It supports Go's native format (e.g. "1h30m") as a fallback, plus extended human forms such as: 

"2d 3h 15m"
"1 week 2 days"
"90 seconds"
"2y 3mo 1w 4d 5h 30m 15s"

func ParseFormat 

func ParseFormat(datestr string, opts ...ParserOption) (string, error)

ParseFormat parses an unknown date-time string and returns a layout string that can parse this (and exact same format) other date-time strings.

In certain edge cases, this may produce a format string of a different length than the input string. If this happens, it's an edge case that requires individually parsing each time. 

layout, err := dateparse.ParseFormat("2013-02-01 00:00:00")
// layout = "2006-01-02 15:04:05"

func ParseIn 

func ParseIn(datestr string, loc *time.Location, opts ...ParserOption) (time.Time, error)

ParseIn with Location, equivalent to time.ParseInLocation() timezone/offset rules. Using location arg, if timezone/offset info exists in the datestring, it uses the given location rules for any zone interpretation. That is, MST means one thing when using America/Denver and something else in other locations. See README for a more detailed explanation.

func ParseInTimezone added in v0.0.5 

func ParseInTimezone(s, zone string) (time.Time, error)

ParseInTimezone parses the date string s using dateparse.ParseAny and then reinterprets the resulting time as being in the named IANA timezone. Use this when the date string carries no timezone information.

func ParseLocal 

func ParseLocal(datestr string, opts ...ParserOption) (time.Time, error)

ParseLocal Given an unknown date format, detect the layout, using time.Local, parse.

Set Location to time.Local. Same as ParseIn Location but lazily uses the global time.Local variable for Location argument. 

denverLoc, _ := time.LoadLocation("America/Denver")
time.Local = denverLoc

t, err := dateparse.ParseLocal("3/1/2014")

Equivalent to: 

t, err := dateparse.ParseIn("3/1/2014", denverLoc)

func ParseStrict 

func ParseStrict(datestr string, opts ...ParserOption) (time.Time, error)

ParseStrict parse an unknown date format. IF the date is ambigous mm/dd vs dd/mm then return an error. These return errors: 3.3.2014 , 8/8/71 etc

func ParseTimestamp added in v0.0.5 

func ParseTimestamp(v int64) time.Time

ParseTimestamp auto-detects whether v is a Unix timestamp in seconds, milliseconds, microseconds, or nanoseconds and returns the corresponding time.Time (UTC).

func ParseTimestampString added in v0.0.5 

func ParseTimestampString(s string) (time.Time, error)

ParseTimestampString parses a numeric string as a Unix timestamp, applying the same auto-detection as ParseTimestamp. Returns an error if the string is not a valid integer.

func Pretty added in v0.0.4 

func Pretty(pretty bool) func(*gparser) error

func PrevLeapYear added in v0.0.4 

func PrevLeapYear(givenYear int) (foundYear int, found bool)

PrevLeapYear returns the previous leap year before a given year. It also returns a boolean value that is set to false if no such year can be found.

func Quarter added in v0.0.5 

func Quarter(t time.Time) int

Quarter returns the quarter number (1–4) for t.

func RelativeTime added in v0.0.5 

func RelativeTime(t, ref time.Time) string

RelativeTime returns a human-readable string describing t relative to ref, such as "3 days ago", "in 2 hours", "just now", "yesterday", "tomorrow".

func RoundDuration added in v0.0.5 

func RoundDuration(d, unit time.Duration) time.Duration

RoundDuration rounds d to the nearest multiple of unit.

func ShortMonthName added in v0.0.5 

func ShortMonthName(m time.Month) string

ShortMonthName returns the 3-letter English abbreviation of the given month.

func ShortWeekdayName added in v0.0.5 

func ShortWeekdayName(w time.Weekday) string

ShortWeekdayName returns the 3-letter English abbreviation of the given weekday.

func Size added in v0.0.4 

func Size(size int) func(*gparser) error

func StartOfDay added in v0.0.5 

func StartOfDay(t time.Time) time.Time

StartOfDay returns t truncated to the beginning of its day (00:00:00.000000000).

func StartOfMonth added in v0.0.5 

func StartOfMonth(t time.Time) time.Time

StartOfMonth returns the first moment of t's month.

func StartOfQuarter added in v0.0.5 

func StartOfQuarter(t time.Time) time.Time

StartOfQuarter returns the first moment of the quarter in which t falls.

func StartOfWeek added in v0.0.5 

func StartOfWeek(t time.Time, startDay ...time.Weekday) time.Time

StartOfWeek returns the start of the week that contains t. startDay specifies which weekday begins the week (default: time.Monday).

func StartOfYear added in v0.0.5 

func StartOfYear(t time.Time) time.Time

StartOfYear returns the first moment of t's year.

func TimeElapsed added in v0.0.4 

func TimeElapsed(now time.Time, then time.Time, full bool) string

func TimestampPrecisionOf added in v0.0.5 

func TimestampPrecisionOf(v int64) string

TimestampPrecisionOf returns a string describing the auto-detected precision of a numeric timestamp value ("seconds", "milliseconds", "microseconds", "nanoseconds").

func TimezoneOffset added in v0.0.5 

func TimezoneOffset(zone string, t time.Time) (int, error)

TimezoneOffset returns the UTC offset in seconds for the named IANA timezone at the moment represented by t.

func ToUnix added in v0.0.5 

func ToUnix(t time.Time) int64

ToUnix returns the Unix time (seconds since epoch) of t.

func ToUnixMicro added in v0.0.5 

func ToUnixMicro(t time.Time) int64

ToUnixMicro returns the Unix time in microseconds of t.

func ToUnixMilli added in v0.0.5 

func ToUnixMilli(t time.Time) int64

ToUnixMilli returns the Unix time in milliseconds of t.

func ToUnixNano added in v0.0.5 

func ToUnixNano(t time.Time) int64

ToUnixNano returns the Unix time in nanoseconds of t.

func TruncateDuration added in v0.0.5 

func TruncateDuration(d, unit time.Duration) time.Duration

TruncateDuration truncates d to a multiple of unit (towards zero).

func UTCToLocal added in v0.0.5 

func UTCToLocal(t time.Time) time.Time

UTCToLocal converts a UTC time to the system local timezone.

func UnixMicroToTime added in v0.0.5 

func UnixMicroToTime(us int64) time.Time

UnixMicroToTime converts a Unix timestamp in microseconds to time.Time (UTC).

func UnixMilliToTime added in v0.0.5 

func UnixMilliToTime(ms int64) time.Time

UnixMilliToTime converts a Unix timestamp in milliseconds to time.Time (UTC).

func UnixNanoToTime added in v0.0.5 

func UnixNanoToTime(ns int64) time.Time

UnixNanoToTime converts a Unix timestamp in nanoseconds to time.Time (UTC).

func UnixToTime added in v0.0.5 

func UnixToTime(unix int64) time.Time

UnixToTime converts a Unix timestamp (seconds since epoch) to time.Time (UTC).

func WeekNumber added in v0.0.5 

func WeekNumber(t time.Time) int

WeekNumber returns the ISO 8601 week number for t.

func WeekdayName added in v0.0.5 

func WeekdayName(w time.Weekday) string

WeekdayName returns the full English name of the given weekday.

func WeeksBetween added in v0.0.5 

func WeeksBetween(a, b time.Time) int

WeeksBetween returns the number of complete weeks between a and b.

Types

type DateDiff added in v0.0.5 

type DateDiff struct {
	Years   int
	Months  int
	Weeks   int
	Days    int
	Hours   int
	Minutes int
	Seconds int
}

DateDiff holds the component-wise difference between two time.Time values.

func DiffDetailed added in v0.0.5 

func DiffDetailed(from, to time.Time) DateDiff

DiffDetailed returns the component-wise difference between from and to. All fields are non-negative; the caller can determine direction by comparing the original times.

type DateRange added in v0.0.5 

type DateRange struct {
	Start time.Time
	End   time.Time
}

DateRange represents an inclusive range between two points in time.

func NewDateRange added in v0.0.5 

func NewDateRange(start, end time.Time) (DateRange, error)

NewDateRange creates a DateRange. It returns an error if end is before start.

func NewDateRangeFromDuration added in v0.0.5 

func NewDateRangeFromDuration(start time.Time, d time.Duration) DateRange

NewDateRangeFromDuration creates a DateRange starting at start with the given duration.

func (DateRange) BusinessDays added in v0.0.5 

func (r DateRange) BusinessDays(holidays []time.Time) []time.Time

BusinessDays returns a slice of all business days (Mon–Fri, excluding holidays) within the range, one entry per day at start-of-day.

func (DateRange) Contains added in v0.0.5 

func (r DateRange) Contains(t time.Time) bool

Contains reports whether t falls within [Start, End] (inclusive).

func (DateRange) Days added in v0.0.5 

func (r DateRange) Days() int

Days returns the number of whole calendar days spanned by the range. A range within a single day returns 1.

func (DateRange) Duration added in v0.0.5 

func (r DateRange) Duration() time.Duration

Duration returns the duration of the range (End − Start).

func (DateRange) Each added in v0.0.5 

func (r DateRange) Each(fn func(time.Time) bool)

Each calls fn once for each calendar day in the range (inclusive), passing the start-of-day time. Iteration stops early if fn returns false.

func (DateRange) EachMonth added in v0.0.5 

func (r DateRange) EachMonth(fn func(time.Time) bool)

EachMonth calls fn once for the first day of each calendar month that overlaps the range. Iteration stops early if fn returns false.

func (DateRange) Extend added in v0.0.5 

func (r DateRange) Extend(d time.Duration) DateRange

Extend returns a new DateRange with End advanced by d.

func (DateRange) Intersect added in v0.0.5 

func (r DateRange) Intersect(other DateRange) (DateRange, bool)

Intersect returns the intersection of r and other, plus a boolean indicating whether the intersection is non-empty.

func (DateRange) IsEmpty added in v0.0.5 

func (r DateRange) IsEmpty() bool

IsEmpty reports whether the range has zero duration.

func (DateRange) Overlaps added in v0.0.5 

func (r DateRange) Overlaps(other DateRange) bool

Overlaps reports whether r and other share any point in time.

func (DateRange) Shift added in v0.0.5 

func (r DateRange) Shift(d time.Duration) DateRange

Shift returns a new DateRange shifted forward (positive d) or backward (negative d).

func (DateRange) Split added in v0.0.5 

func (r DateRange) Split(d time.Duration) []DateRange

Split divides the range into sub-ranges each of duration d. The last sub-range may be shorter than d.

func (DateRange) Union added in v0.0.5 

func (r DateRange) Union(other DateRange) DateRange

Union returns the smallest DateRange that contains both r and other.

type Direction added in v0.0.4 

type Direction int

Direction is the direction used for ambiguous expressions. 

const (
	Past Direction = iota
	Future
)

Directions available.

type ExprType added in v0.0.4 

type ExprType int

func ParseNaturalDate added in v0.0.4 

func ParseNaturalDate(s string, ref time.Time, options ...Option) (time.Time, ExprType, error)

ParseNaturalDate query string.

func (ExprType) IsDateOnly added in v0.0.4 

func (t ExprType) IsDateOnly() bool

func (ExprType) IsTimeOnly added in v0.0.4 

func (t ExprType) IsTimeOnly() bool

type NepaliFormatter added in v0.0.4 

type NepaliFormatter struct {
	// contains filtered or unexported fields
}

func NewFormatter added in v0.0.4 

func NewFormatter(nepaliTime *NepaliTime) *NepaliFormatter

func (*NepaliFormatter) Format added in v0.0.4 

func (obj *NepaliFormatter) Format(format string) (string, error)

type NepaliMonthData added in v0.0.4 

type NepaliMonthData struct {
	// contains filtered or unexported fields
}

type NepaliTime added in v0.0.4 

type NepaliTime struct {
	// contains filtered or unexported fields
}

func Date added in v0.0.4 

func Date(year, month, day, hour, min, sec, nsec int) (*NepaliTime, error)

Date returns the Time corresponding to

yyyy-mm-dd hh:mm:ss + nsec nanoseconds

func FromEnglishTime added in v0.0.4 

func FromEnglishTime(englishTime time.Time) (*NepaliTime, error)

Converts Time object to NepaliTime

func Now added in v0.0.4 

func Now() *NepaliTime

Now returns the current nepali time. this function should always work and should not return nil in normal circumstances

func ParseNP added in v0.0.4 

func ParseNP(datetimeStr string, format string) (*NepaliTime, error)

ParseNP equivalent to time.Parse()

func (*NepaliTime) Clock added in v0.0.4 

func (obj *NepaliTime) Clock() (hour, min, sec int)

Clock returns the hour, minute, and second of the day.

func (*NepaliTime) Date added in v0.0.4 

func (obj *NepaliTime) Date() (year, month, day int)

Date returns the year, month, and day

func (*NepaliTime) Day added in v0.0.4 

func (obj *NepaliTime) Day() int

Day returns the day of the month.

func (*NepaliTime) Format added in v0.0.4 

func (obj *NepaliTime) Format(format string) (string, error)

formats the nepalitime object into the passed format

func (*NepaliTime) GetEnglishTime added in v0.0.4 

func (obj *NepaliTime) GetEnglishTime() time.Time

Get's the corresponding english time

func (*NepaliTime) Hour added in v0.0.4 

func (obj *NepaliTime) Hour() int

Hour returns the hour within the day, in the range [0, 23].

func (*NepaliTime) Minute added in v0.0.4 

func (obj *NepaliTime) Minute() int

Minute returns the minute offset within the hour, in the range [0, 59].

func (*NepaliTime) Month added in v0.0.4 

func (obj *NepaliTime) Month() int

Month returns the month of the year.

func (*NepaliTime) Nanosecond added in v0.0.4 

func (obj *NepaliTime) Nanosecond() int

Nanosecond returns the nanosecond offset within the second, in the range [0, 999999999].

func (*NepaliTime) Second added in v0.0.4 

func (obj *NepaliTime) Second() int

Second returns the second offset within the minute, in the range [0, 59].

func (*NepaliTime) String added in v0.0.4 

func (obj *NepaliTime) String() string

String returns a string representing the duration in the form "2079-10-06 01:00:05"

func (*NepaliTime) Weekday added in v0.0.4 

func (obj *NepaliTime) Weekday() time.Weekday

Weekday returns the day of the week. Sunday = 0, Monday = 1, Saturday = 6

func (*NepaliTime) Year added in v0.0.4 

func (obj *NepaliTime) Year() int

Year returns the year in which nepalitime occurs.

type Option added in v0.0.4 

type Option func(*gparser)

Option function.

func WithDirection added in v0.0.4 

func WithDirection(d Direction) Option

WithDirection sets the direction used for ambiguous expressions. By default the Past direction is used, so "sunday" will be the previous Sunday, rather than the next Sunday.

type ParserOption 

type ParserOption func(*parser) error

ParserOption defines a function signature implemented by options Options defined like this accept the parser and operate on the data within

func AllowPartialStringMatch 

func AllowPartialStringMatch(allowPartialStringMatch bool) ParserOption

AllowPartialStringMatch is an option that allows allowPartialStringMatch to be changed from its default. If true, then strings can be attempted to be parsed / matched even if the end of the string might contain more than a date/time. This defaults to false.

func PreferMonthFirst 

func PreferMonthFirst(preferMonthFirst bool) ParserOption

PreferMonthFirst is an option that allows preferMonthFirst to be changed from its default

func RetryAmbiguousDateWithSwap 

func RetryAmbiguousDateWithSwap(retryAmbiguousDateWithSwap bool) ParserOption

RetryAmbiguousDateWithSwap is an option that allows retryAmbiguousDateWithSwap to be changed from its default

func SimpleErrorMessages 

func SimpleErrorMessages(simpleErrorMessages bool) ParserOption

SimpleErrorMessages is an option that will cause returned error messages to contain less detail, but it will avoid allocating any memory for the custom error message. If you expect to attempt to parse a lot of text that is not valid, this could help reduce GC pressure.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.