Description
Look up explicit offset state at an instant, transitions effective inclusively and initial offset valid before the first.
An offset maps a supplied UTC coordinate to local civil coordinates by local = UTC + offset. Half-open spans include their start and exclude their end. A forward offset jump can leave local coordinates uncovered; a backward jump can give several UTC interpretations of one local value. These tools use explicit synthetic civil-second observations rather than a named-zone database.
Look up explicit offset state at an instant, transitions effective inclusively and initial offset valid before the first.
When to use this tool
Use this tool to look up explicit offset state at an instant, transitions effective inclusively and initial offset valid before the first.
How to use the tool and how it works
- Enter transitionsJson, initialOffset, instant using the definitions below. Serialize JSON text fields in the decoded shape shown below.
- Run the operation. Resolve input-format errors before interpreting an output.
- Read result.offset, result.transitionIndex, using the stated boundary, ordering, sign and absence conventions.
Require strictly increasing transition instants, the first before value equal to initialOffset and each later before equal to the previous after. At instant choose the last transition with at≤instant; before all transitions use initialOffset and transitionIndex=null.1
| Input field | Meaning and units | Accepted input |
|---|---|---|
| transitionsJson | JSON array of {at,before,after} second-valued observations; at is UTC and before/after are signed offsets. | Text, at most 8,192 UTF-16 code units; narrower grammar/range rules also apply. |
| initialOffset | Offset before the first supplied transition, in seconds within ±86,400. | Finite numeric value satisfying the stated comparisons. |
| instant | UTC instant in seconds within ±10¹². | Finite numeric value satisfying the stated comparisons. |
These decoded structures show the examples inside JSON text fields. Supply their serialized JSON strings as input.
{
"transitionsJson": [
{
"at": 10,
"before": 0,
"after": 2
},
{
"at": 20,
"before": 2,
"after": 0
}
]
}| Output field | Interpretation |
|---|---|
| result | Object containing the fields below. |
| result.offset | Offset in seconds effective at the supplied instant. |
| result.transitionIndex | Last applied original transition index, or null before all transitions. |
{
"input": {
"transitionsJson": "[{\"at\": 10, \"before\": 0, \"after\": 2}, {\"at\": 20, \"before\": 2, \"after\": 0}]",
"initialOffset": 0,
"instant": 10
},
"output": {
"result": {
"offset": 2,
"transitionIndex": 0
}
}
}Limitations and assumptions
- The after offset takes effect exactly at the transition instant. The explicit chain supplies all rules; no missing history is recovered.
- Span/transition coordinates are finite seconds within ±10¹² and offsets within ±86,400 seconds. Spans require start<end. No IANA database, calendar parsing, daylight-saving inference or leap seconds are included.
- Every declared outer field is required and unknown outer fields are rejected. Strings and JSON text have size limits, lists are bounded to 128 entries, and JSON nesting/node counts are bounded. Tighter operation-specific bounds stated above take precedence.
- Ordinary numeric outputs must be finite and within safe-integer magnitude. Exact large lengths/counts use decimal strings. Original record indexes and code-unit positions are zero-based; span ends are exclusive unless stated otherwise.
Alternative or Complementary methods
Keep all timestamps on one origin and in seconds, and retain gaps or competing observations. Use a maintained time-zone library when real dates, named zones or historical rules are required.
References
Similar or alternative tools
- Time Zone Transition Calendar Marker Table
Produce numeric transition calendar marker coordinates on both sides of each jump; no actual Gregorian dates or formatting implied.
- Time Zone Offset Effective Span Table
Derive bounded half-open UTC effective spans from a complete ordered transition chain, clipping to explicit UTC endpoints.