Skip to content

Commit

Permalink
Merge pull request #13 from Jumpaku/docs/revise-readme
Browse files Browse the repository at this point in the history 
docs: revise README
  • Loading branch information
@Jumpaku
Jumpaku authored Mar 15, 2024
2 parents 1926baa + 7619bbd commit eb30c28
Showing 1 changed file with 53 additions and 81 deletions.
134 changes: 53 additions & 81 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,104 +2,76 @@

## Overview

This repository provides information about timezone offset transitions based on the IANA TZ database.
This repository provides information for timezones based on the IANA TZ database.
The information is available in a JSON file located at `gen/tzot.json`.


## What timezone offset transition is
## What timezone is

A timezone is a geographic region of the Earth that observes the same standard time, encompassing one or more timezone offsets.
The timezone offset represents the difference between the local time in a specific timezone and the Coordinated Universal Time (UTC).
A timezone offset transition indicates a shift between different timezone offsets within a particular timezone, which is often prompted by factors like daylight saving time adjustments or political changes in laws.
A timezone is a geographic region of the Earth that observes the same standard time, encompassing some timezone offsets.
A timezone offset represents the difference between the local time in a specific timezone and the Coordinated Universal Time (UTC).
In a timezone, transitions between timezone offsets may occur due to factors such as daylight saving time adjustments or political changes in laws.
The timezone offset transitions that are going to occur in the future can be scheduled by several types of transition rules.

The IANA Time Zone Database ( https://www.iana.org/time-zones ) is a comprehensive database used to manage timezones.


## What this repository provides

This repository includes a program that parses the IANA Time Zone Database and extracts the information regarding timezone offset transitions as a JSON file to facilitate the handling of the information.
This program is implemented using the `java.time` package in Kotlin.
This repository includes a program that parses the IANA Time Zone Database and extracts the information regarding timezones, each of which consists of timezone offset transitions and transition rules.
The extracted data is then formatted into a simply structured JSON file `gen/tzot.json`, specifically designed for handling the timezone offset transitions in various programming languages.
That program is implemented in Kotlin using the `java.time` package.

Additionally, this repository includes an automated mechanism for detecting updates to the database and overriding the `tzot.json`.
This mechanism is implemented as a GitHub Actions workflow which updates the `tzot.json` monthly if a new version of the database is detected.
Additionally, this repository includes an automated mechanism for detecting updates to the database and overriding the `gen/tzot.json`.
This mechanism is implemented as a GitHub Actions workflow which updates the `gen/tzot.json` monthly if a new version of the database is detected.

The resulting `tzot.json` is a simply structured JSON file, specifically designed for handling timezone offset transitions in various programming languages.

## Format of gen/tzot.json

## Format of tzot.json
The format of the `gen/tzot.json` is a JSON value that can be assigned to a type `TzotJSON`.
The definition of the type is available in `tzot.ts`, which specifies the structure of the JSON.

The `tzot.json` is serialized from a Kotlin object of type `List<Zone>`.

`Zone` is defined as follows:

```kt
/** Timezone consists of a collection of timezone offset transitions. */
@Serializable
data class Zone(
/** Name of a timezone. */
val zone: String,

/** Collection of timezone offset transitions. */
val transitions: List<Transition>,
)
```

`Transition` is defined as follows:

```kt
/** Timezone offset transition between timezone offsets. */
@Serializable
data class Transition(
/** Timestamp indicating when a transition between timezone offsets occurs in form `2024-02-24T18:31:25Z`. */
@SerialName("transition_timestamp")
val transitionTimestamp: String,

/** Amount of timezone offset before the transition in second. */
@SerialName("offset_seconds_before")
val offsetSecondsBefore: Int,

/** Amount of timezone offset after the transition in second. */
@SerialName("offset_seconds_after")
val offsetSecondsAfter: Int,
)
```


### Example
The below shows an example of the JSON value.

```json
[
{
"zone": "Asia/Aden",
"transitions": [
{
"transition_timestamp": "1947-03-13T20:53:08Z",
"offset_seconds_before": 11212,
"offset_seconds_after": 10800
}
]
},
{
"zone": "America/Cuiaba",
"transitions": [
{
"transition_timestamp": "1914-01-01T03:44:20Z",
"offset_seconds_before": -13460,
"offset_seconds_after": -14400
},
{
"transition_timestamp": "1931-10-03T15:00Z",
"offset_seconds_before": -14400,
"offset_seconds_after": -10800
},
{
"transition_timestamp": "1932-04-01T03:00Z",
"offset_seconds_before": -10800,
"offset_seconds_after": -14400
},
...
]
},
...
{
"id": "Europe/Zurich",
"transitions": [
{
"transition_timestamp": "1853-07-15T23:25:52Z",
"offset_seconds_before": 2048,
"offset_seconds_after": 1786
},
{
"transition_timestamp": "1894-05-31T23:30:14Z",
"offset_seconds_before": 1786,
"offset_seconds_after": 3600
},
...
],
"rules": [
{
"type": "net.jumpaku.tzot.Rule.WeekDayPositive",
"offset_seconds_before": 3600,
"offset_seconds_after": 7200,
"month": 3,
"offset_time": "01:00:00Z",
"day_of_week": 7,
"days": 25
},
{
"type": "net.jumpaku.tzot.Rule.WeekDayPositive",
"offset_seconds_before": 7200,
"offset_seconds_after": 3600,
"month": 10,
"offset_time": "01:00:00Z",
"day_of_week": 7,
"days": 25
},
...
]
},
...
]
```

0 comments on commit eb30c28

Please sign in to comment.