Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

WIP: added text allowing "Z" for timezone offset. #586

Open
wants to merge 6 commits into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 12 additions & 7 deletions ch04.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -237,24 +237,25 @@ All the alternatives have exactly the same meaning in UDUNITS.
For compatibility with other software, CF strongly recommends that `since` should be used.

The reference datetime string (appearing after the identifier **`since`**) is required.
It may include date alone, or date and time, or date, time and time zone offset.
Its format is __y__-__m__-__d__ [__H__:__M__:__S__ [__Z__]], where [...] indicates an optional element,
It must include the date, which may optionally be followed by time or time zone offset or both. Its format is __y__-__m__-__d__ [__H__:__M__:__S__] [__Z__], where [...] indicates an optional element:

* _y_ is year, _m_ month, _d_ day, _H_ hour and _M_ minute, which are all integers of one or more digits, and _y_ may be prefixed with a sign (but note that some CF calendars do not permit negative years; see <<calendar>>),

* _S_ is second, which may be integer or floating point (see <<leap-seconds>> regarding __S__>59),

* _Z_ is the time zone offset with respect to UTC.
* _Z_ is the time zone offset.
This is an interval of time, specified in one of the formats described below.
Only numbers (digits, `+`, `-` and `:`) are allowed in _Z_, not time zone names or acronyms.
Only numbers (digits, `+`, `-` and `:`) or the letter "Z" are allowed in _Z_, not time zone names or acronyms.

The default time zone offset is zero.
In a time zone with zero offset, time (approximately) equals mean solar time for 0 `degrees_east` of longitude.
(Although this may be exact in a model, in reality the time with zero time zone offset differs by some seconds from mean solar time; see the discussion of UTC and leap seconds in <<calendar>>.)
If both time and time zone offset are omitted the time is 00:00:00 (the beginning of the day i.e. midnight at 0 `degrees_east`).
Thus, **`units = "days since 1990-1-1"`** means the same as **`units = "days since 1990-1-1 0:0:0"`**.
Thus, **`units = "days since 1990-1-1"`** means the same as **`units = "days since 1990-1-1 00:00:00"`**.

The time zone offset _Z_ must be in one of the following four formats, any of which may be prefixed with a sign:
The time zone offset _Z_ must be in one of the following five formats, where numeric hours may optionally be prefixed with a `+` or `-` sign:

** The letter `Z` indicating zero offset, sometimes referred to as "Zulu Time".

** _H_, the hour alone, of one or two digits e.g. **`-6`**, **`2`**, **`+11`**, which is sufficient for many time zones.

Expand All @@ -264,6 +265,10 @@ The time zone offset _Z_ must be in one of the following four formats, any of wh

** three digits, of which the first is the hour (0--9) e.g. **`530`**.

If the time zone offset is the letter `Z` or begins with a sign, the space before it may be omitted.

While the default (of omitting the _Z_ component) is an offset of zero, we suggest that a zero offset be specified to avoid any confusion where omitting it might be misunderstood as indicating local time.

For example, **`seconds since 1992-10-8 15:15:42.5 -6:00`** indicates seconds since October 8th, 1992 at 3 hours, 15 minutes and 42.5 seconds in the afternoon, in a time zone where the datetime is six hours behind the default.
Subtracting the time zone offset from a given datetime converts it to the equivalent datetime with zero time zone offset e.g. **`1989-12-31 18:00:00 -6`** identifies the same instant as **`1990-1-1 0:0:0`**.

Expand Down Expand Up @@ -400,7 +405,7 @@ When these calendars are being be used for timelines _with_ leap seconds (i.e. c
* A datetime in the excluded range must not be used as a reference datetime e.g. **`seconds since 2016-12-31 23:59:60`** is not a permitted value for **`units`**.

* The coordinate value does not count any leap seconds which occurred between the reference datetime and the datetime represented by the coordinate.
For instance, 60 **`seconds after 23:59:00`** always means 00:00:00 on the next day, even if there is a leap second at 23:59:60, which makes the actual interval 61 seconds between 23:59:00 and 00:00:00 on the next day.
For instance, 60 **`seconds after 23:59:00`** always means 0:0:0 on the next day, even if there is a leap second at 23:59:60, which makes the actual interval 61 seconds between 23:59:00 and 0:0:0 on the next day.

Because of the last point, the difference between two coordinate values with the same **`units`** string does not exactly equal the length of the interval between instants they represent if there were any leap seconds between them.
This discrepancy can happen in cases 2, 3 and 4 of the **`standard`**, **`proleptic_gregorian`**, and **`julian`** calendars.
Expand Down
6 changes: 3 additions & 3 deletions ch07.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -70,7 +70,7 @@ dimensions:
variables:
float time(time);
time:standard_name = "time";
time:units = "days since 2024-11-8 09:00:00";
time:units = "days since 2024-11-8 09:00:00Z";
time:bounds = "time_bnds";
float time_bnds(time,nv);
----
Expand Down Expand Up @@ -330,7 +330,7 @@ variables:
ppn:cell_methods = "time: sum";
double time(time);
time:long_name = "time";
time:units = "h since 1998-4-19 6:0:0";
time:units = "h since 1998-4-19 6:0:0 Z";
Copy link
Contributor

@davidhassell davidhassell Jan 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Edit - just seen the above conversion on this, so I retract the comment!

I found that the lack of space before Z is required: "If the time is in UTCm add a Z directly after the time without a space." (https://en.wikipedia.org/wiki/ISO_8601#Coordinated_Universal_Time_(UTC))

time:bounds = "time_bnds";
double time_bnds(time,nv);
data:
Expand Down Expand Up @@ -400,7 +400,7 @@ variables:
TS_var:units="K2";
TS_var:cell_methods="time: variance (interval: 1 hr comment: sampled instantaneously)";
float time(time);
time:units="days since 1990-01-01 00:00:00";
time:units="days since 1990-01-01 00:00:00 Z";
time:bounds="time_bnds";
float time_bnds(time,nv);
data:
Expand Down
Loading