{"id":24314811,"url":"https://github.com/karrick/tparse","last_synced_at":"2025-09-26T21:30:40.812Z","repository":{"id":56200198,"uuid":"44764583","full_name":"karrick/tparse","owner":"karrick","description":"time parsing library for Go; supports more time units than standard library","archived":false,"fork":false,"pushed_at":"2020-11-20T21:51:12.000Z","size":45,"stargazers_count":43,"open_issues_count":2,"forks_count":3,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-01-11T05:24:28.155Z","etag":null,"topics":["duration-string","golang","parse"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/karrick.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-10-22T18:19:05.000Z","updated_at":"2024-11-03T14:44:06.000Z","dependencies_parsed_at":"2022-08-15T14:31:37.598Z","dependency_job_id":null,"html_url":"https://github.com/karrick/tparse","commit_stats":null,"previous_names":[],"tags_count":25,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/karrick%2Ftparse","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/karrick%2Ftparse/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/karrick%2Ftparse/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/karrick%2Ftparse/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/karrick","download_url":"https://codeload.github.com/karrick/tparse/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":234345366,"owners_count":18817558,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["duration-string","golang","parse"],"created_at":"2025-01-17T10:15:46.213Z","updated_at":"2025-09-26T21:30:40.523Z","avatar_url":"https://github.com/karrick.png","language":"Go","readme":"# tparse\n\n`Parse` will return the time corresponding to the layout and value.\nIt also parses floating point epoch values, and values of \"now\",\n\"now+DURATION\", and \"now-DURATION\".\n\nIn addition to the duration abbreviations recognized by\n`time.ParseDuration`, tparse recognizes various tokens for days,\nweeks, months, and years, as well as tokens for seconds, minutes, and\nhours.\n\nLike `time.ParseDuration`, it accepts multiple fractional scalars, so\n\"now+1.5days-3.21hours\" is evaluated properly.\n\n## Documentation\n\nIn addition to this handy README.md file, documentation is available\nin godoc format at\n[![GoDoc](https://godoc.org/github.com/karrick/tparse?status.svg)](https://godoc.org/github.com/karrick/tparse).\n\n## Examples\n\n### ParseNow\n\n`ParseNow` can parse time values that are relative to the current\ntime, by specifying a string starting with \"now\", a '+' or '-' byte,\nfollowed by a time duration.\n\n```Go\n    package main\n\n    import (\n        \"fmt\"\n        \"os\"\n        \"time\"\n        \"github.com/karrick/tparse\"\n    )\n\n    func main() {\n        actual, err := tparse.ParseNow(time.RFC3339, \"now+1d-3w4mo+7y6h4m\")\n        if err != nil {\n            fmt.Fprintf(os.Stderr, \"error: %s\\n\", err)\n            os.Exit(1)\n        }\n        fmt.Printf(\"time is: %s\\n\", actual)\n    }\n```\n\n### ParseWithMap\n\n`ParseWithMap` can parse time values that use a base time other than \"now\".\n\n```Go\n    package main\n\n    import (\n        \"fmt\"\n        \"os\"\n        \"time\"\n        \"github.com/karrick/tparse\"\n    )\n\n    func main() {\n        m := make(map[string]time.Time)\n        m[\"end\"] = time.Now()\n\n        start, err := tparse.ParseWithMap(time.RFC3339, \"end-12h\", m)\n        if err != nil {\n            fmt.Fprintf(os.Stderr, \"error: %s\\n\", err)\n            os.Exit(1)\n        }\n\n        fmt.Printf(\"start: %s; end: %s\\n\", start, end)\n    }\n```\n\n### AddDuration\n\n`AddDuration` is used to compute the value of a duration string and\nadd it to a known time. This function is used by the other library\nfunctions to parse all duration strings.\n\nThe following tokens may be used to specify the respective unit of\ntime:\n\n * Nanosecond: ns\n * Microsecond: us, µs (U+00B5 = micro symbol), μs (U+03BC = Greek letter mu)\n * Millisecond: ms\n * Second: s, sec, second, seconds\n * Minute: m, min, minute, minutes\n * Hour: h, hr, hour, hours\n * Day: d, day, days\n * Week: w, wk, week, weeks\n * Month: mo, mon, month, months\n * Year: y, yr, year, years\n\n```Go\n    package main\n\n    import (\n        \"fmt\"\n        \"os\"\n        \"time\"\n\n        \"github.com/karrick/tparse\"\n    )\n\n    func main() {\n        now := time.Now()\n        another, err := tparse.AddDuration(now, \"+1d3w4mo-7y6h4m\")\n        if err != nil {\n            fmt.Fprintf(os.Stderr, \"error: %s\\n\", err)\n            os.Exit(1)\n        }\n\n        fmt.Printf(\"time is: %s\\n\", another)\n    }\n```\n\n### AbsoluteDuration\n\nWhen you would rather have the `time.Duration` representation of a\nduration string, there is a function for that, but with a\ncaveat.\n\nFirst, not every month has 30 days, and therefore Go does not have a\n`time.Duration` type constant to represent one month. \n\nWhen I add one month to February 3, do I get March 3 or March 4?\nDepends on what the year is and whether or not that year is a leap\nyear.\n\nIs one month always 30 days? Is one month 31 days, or 28, or 29? I did\nnot want to have to answer this question, so I defaulted to saying the\nlength of one month depends on which month and year, and I allowed the\nGo standard library to add duration concretely to a given moment in\ntime.\n\nConsider the below two examples of calling `AbsoluteDuration` with the\nsame duration string, but different base times.\n\n```Go\nfunc ExampleAbsoluteDuration() {\n    t1 := time.Date(2009, time.November, 10, 23, 0, 0, 0, time.UTC)\n\n    d1, err := AbsoluteDuration(t1, \"1.5month\")\n    if err != nil {\n        fmt.Println(err)\n        return\n    }\n\n    fmt.Println(d1)\n\n    t2 := time.Date(2020, time.February, 10, 23, 0, 0, 0, time.UTC)\n\n    d2, err := AbsoluteDuration(t2, \"1.5month\")\n    if err != nil {\n        fmt.Println(err)\n        return\n    }\n\n    fmt.Println(d2)\n    // Output:\n    // 1080h0m0s\n    // 1056h0m0s\n}\n```\n\n## Benchmark against goparsetime\n\n```Bash\nGO111MODULE=on go test -bench=. -tags goparsetime\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkarrick%2Ftparse","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkarrick%2Ftparse","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkarrick%2Ftparse/lists"}