{"id":15616330,"url":"https://github.com/silviucpp/elocaltime","last_synced_at":"2025-04-28T17:40:50.436Z","repository":{"id":57494932,"uuid":"105516438","full_name":"silviucpp/elocaltime","owner":"silviucpp","description":"Erlang library for conversion from one local time to another based on google cctz","archived":false,"fork":false,"pushed_at":"2025-03-04T16:04:29.000Z","size":45,"stargazers_count":6,"open_issues_count":0,"forks_count":3,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-18T18:33:26.753Z","etag":null,"topics":["cctz","erlang","localtime","timezone"],"latest_commit_sha":null,"homepage":null,"language":"Erlang","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/silviucpp.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2017-10-02T09:10:47.000Z","updated_at":"2025-03-04T16:04:07.000Z","dependencies_parsed_at":"2025-04-20T08:46:09.144Z","dependency_job_id":null,"html_url":"https://github.com/silviucpp/elocaltime","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/silviucpp%2Felocaltime","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/silviucpp%2Felocaltime/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/silviucpp%2Felocaltime/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/silviucpp%2Felocaltime/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/silviucpp","download_url":"https://codeload.github.com/silviucpp/elocaltime/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251191453,"owners_count":21550135,"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":["cctz","erlang","localtime","timezone"],"created_at":"2024-10-03T07:06:35.852Z","updated_at":"2025-04-28T17:40:50.400Z","avatar_url":"https://github.com/silviucpp.png","language":"Erlang","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Build Status](https://app.travis-ci.com/silviucpp/elocaltime.svg?branch=master)](https://travis-ci.com/github/silviucpp/elocaltime)\n[![GitHub License](https://img.shields.io/github/license/silviucpp/elocaltime)](https://github.com/silviucpp/elocaltime/blob/master/LICENSE)\n[![Hex.pm Version](https://img.shields.io/hexpm/v/elocaltime)](https://hex.pm/packages/elocaltime)\n\nErlang library for converting between local times using [Google CCTZ][1].\n\n## Getting Started\n\n### Integration\n\nTo add `elocaltime` to your project, include it as a dependency in `rebar3`:\n\n```erlang\n{deps, [\n  {elocaltime, \".*\", {git, \"https://github.com/silviucpp/elocaltime.git\", \"master\"}}\n]}.\n```\n\n### API\n\nAll public functions support both `calendar:datetime()` and Unix timestamps (seconds since Jan 1, 1970) as input formats.\n\n#### Timezone Specification\n\nTimezones can be defined in the following ways:\n\n- **Named timezones** from the [TZ database][2], e.g., `\u003c\u003c\"Europe/Bucharest\"\u003e\u003e`.\n- **Local timezone** using `?TIMEZONE_LOCAL` (automatically detects the local timezone if not fallback on `UTC`).\n- **UTC timezone** specified with `?TIMEZONE_UTC`.\n- **Fixed time offset from UTC** using `?TIMEZONE_FIXED(Seconds)`. If the absolute offset exceeds 24 hours, it defaults to UTC.\n\n### Converting Between Timezones\n\n- `utc2local_datetime/2` – Converts UTC to local time, returning `calendar:datetime()`.\n- `utc2local_ts/2` – Converts UTC to local time, returning a Unix timestamp.\n- `local2utc_datetime/3` – Converts local time to UTC, returning `calendar:datetime()`.\n- `local2utc_ts/3` – Converts local time to UTC, returning a Unix timestamp.\n\n#### Handling Ambiguous Times\n\nFor `local2utc_xxx/3` functions, the third parameter indicates what to return in case the date is ambiguous. Sometimes, \nwhen you are converting a datetime from one timezone to another, there are potentially two different results if the conversion happens \nto land on in a timezone that's in the middle of a Daylight Saving conversion.\n\nBy default, disambiguation is disabled, and `elocaltime` will just guess as to it's best choice. But if you so desire, you can make \nsure elocaltime does both conversions, and returns both.\n\nYou can change this behaviour using the parameter:\n\n- `?DS_STANDARD`: (default) If an ambiguous result occurs, will return the date in standard time rather than daylight time.\n- `?DS_DAYLIGHT`: If an ambiguous result occurs, will return the preferred daylight time.\n- `?DS_BOTH`: If an ambiguous result occurs both will be returned as a tuple of 3 elements `{ok, Standard, Daylight}`.\n\n### Date Formatting\n\nThis API Formats the given `DateTime` in the given timezone according to the provided format string. Uses [strftime()-like][3] formatting options,\nwith the following extensions:\n\n- `%Ez` – RFC3339-compatible numeric UTC offset (`+hh:mm` or `-hh:mm`).\n- `%E*z` – Full-resolution numeric UTC offset (`+hh:mm:ss` or `-hh:mm:ss`).\n- `%E#S` – Seconds with # digits of fractional precision.\n- `%E*S` – Seconds with full fractional precision (a literal `*`).\n- `%E#f` – Fractional seconds with `#` precision.\n- `%E*f` – Fractional seconds with full precision (a literal `*`).\n- `%E4Y` – Four-character years (-999 ... -001, 0000, 0001 ... 9999).\n\n#### Notes\n\n- `%E0S` behaves like `%S`, and `%E0f` produces no characters. In contrast `%E*f` always produces at least one digit, which may be '0'.\n- `%Y` produces as many characters as it takes to fully render the year. A year outside of [-999:9999] when formatted with `%E4Y` will produce more than four characters, just like `%Y`.\n\n### Additional Public Functions\n\n#### civil_lookup/2\n\nA civil_lookup represents the absolute time(s) that correspond to the given civil time within this time_zone. \nUsually the given civil time represents a unique instant in time, in which case the \nconversion is unambiguous. However, within this time zone, the given civil time may be skipped (e.g., during a positive \nUTC offset shift), or repeated (e.g., during a negative UTC offset shift). To account for these possibilities, civil_lookup \nis richer than just a single timestamp. \n\nReturns the result as a record defined as follows:\n\n```erlang\n-record(civil_lookup, {\n    civil_kind :: civil_kind(),\n    pre :: timestamp(),\n    trans :: timestamp(),\n    post :: timestamp()\n}).\n```\nWhere :\n\n- `civil_kind` - Indicate if it's unique instant in time, in which case the conversion is unambiguous or the given civil time may be skipped (during a positive UTC offset shift), or repeated (during a negative UTC offset shift)\n- `pre` - timestamp that uses the pre-transition offset\n- `trans` - timestamp representing the instant of civil-offset change\n- `post` - timestamp uses the post-transition offset\n\n##### Examples\n\n**Unique Civil Time:**\n\n```erlang\n{ok,{civil_lookup,unique,1293868800,1293868800,1293868800}} =\n    elocaltime:civil_lookup({{2011, 1, 1}, {0, 0, 0}}, \u003c\u003c\"America/Los_Angeles\"\u003e\u003e).\n```\n\n**Spring DST Transition (Time Skipped):**\n\n```erlang\n{ok,{civil_lookup,skipped,1300011300,1300010400,1300007700}} =\n    elocaltime:civil_lookup({{2011, 3, 13}, {2, 15, 0}}, \u003c\u003c\"America/Los_Angeles\"\u003e\u003e).\n```\n\n**Fall DST Transition (Time Repeated):**\n\n```erlang\n{ok,{civil_lookup,repeated,1320567300,1320570000,1320570900}} =\n    elocaltime:civil_lookup({{2011, 11, 6}, {1, 15, 0}}, \u003c\u003c\"America/Los_Angeles\"\u003e\u003e).\n```\n\nIn this example `pre` is `2011/11/06 01:15:00 -0700`, `trans` is `2011/11/06 01:00:00 -0800` and `post` is `2011/11/06 01:15:00 -0800`\n\n#### absolute_lookup/2\n\nAn absolute_lookup represents the civil time within this timezone at the given absolute time. There are additionally a \nfew other fields that may be useful as well. The result is returned as `absolute_lookup` record:\n\n```erlang\n-record(absolute_lookup, {\n    date :: calendar:datetime(),\n    offset :: integer(),\n    is_dst :: boolean(),\n    tz_abbreviation :: binary()\n}).\n```\n\nWhere:\n\n- `date` – Datetime in the target timezone.\n- `offset` – Timezone offset in seconds.\n- `is_dst` – Indicates if the offset is non-standard.\n- `tz_abbreviation` – Timezone abbreviation (e.g., `\u003c\u003c\"PST\"\u003e\u003e`).\n\n## Running Tests\n\nExecute tests using:\n\n```sh\nrebar3 ct\n```\n\n[1]: https://github.com/google/cctz\n[2]: https://www.iana.org/time-zones\n[3]: http://www.cplusplus.com/reference/ctime/strftime/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsilviucpp%2Felocaltime","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsilviucpp%2Felocaltime","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsilviucpp%2Felocaltime/lists"}