Skip to content

Deprecate a decimal hour in a zone offset - #190

Merged
jeremyevans merged 4 commits into
ruby:masterfrom
youdie006:fix-string-fractional-offset
Nov 17, 2026
Merged

jeremyevans merged 4 commits into
ruby:masterfrom
youdie006:fix-string-fractional-offset

Conversation

@youdie006

@youdie006 youdie006 commented Sep 10, 2026 •

Copy link
Copy Markdown
Contributor

Deprecates a decimal hour in a zone offset (for example +05.5), as discussed below. No method returns a different value yet.

  • The parse methods (Date._parse, Date._strptime and the methods built on them) warn when the zone has a fractional hour, including +01.0, since :offset or :zone will change once the fraction is ignored.
  • offset_to_sec (DateTime.civil, jd, new_offset and the other constructors) warns only when it accepts the offset and the fraction changes it. An offset it already ignores as invalid gets only the existing "invalid offset is ignored" warning.

Both use rb_category_warn(RB_WARN_CATEGORY_DEPRECATED, ...), so on Ruby 2.7+ they appear only with deprecation warnings enabled.

Tests are in test_date_new.rb, test_date_parse.rb and test_date_strptime.rb; the existing fractional rows in test__parse and test__strptime__3 moved into the deprecation tests. The full suite passes on Ruby 3.4 and 2.6 with this branch merged into master.

I used an AI assistant to help prepare this change; I reviewed and tested it.

@jeremyevans jeremyevans left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

I think it would be better to deprecate fractional hour support in offsets, and only handle full hour or hour:minute. From some brief searching, I couldn't find any popular programming language support for fractional hour offsets, and Ruby's Time does not support it either.

@youdie006

Copy link
Copy Markdown
Contributor Author

That makes sense to me, and your premise checks out — Time does reject fractional-hour offsets. I measured every offset spelling on ruby 3.2.11 / date 3.3.3, offsets shown in seconds:

zone Time.new DateTime.civil
+05 18000 18000
+0530 19800 19800
+05:30 19800 19800
+05:30:30 19830 19830
+053030 19830 19830
+05.5 ArgumentError 19800
+05:30.5 ArgumentError 19800
+00.123 ArgumentError 0

One adjustment to the scope, and it is the reason I am posting the table rather than just agreeing: "only full hour or hour:minute" would also drop +HH:MM:SS and +HHMMSS, and those are not part of the divergence — Time accepts both and the two libraries already return identical values for them. What Time rejects is specifically the decimal-fraction form, +HH.f and +HH:MM.f. So the deprecation target would be the decimal point, not the seconds field.

The other thing worth noting is the last row. +00.123 does not currently give a fractional offset — it gives 0, silently. Date._parse produces (2214/5) (442.8s) and offset_to_sec then drops it on the floor because it is not a Fixnum. So the status quo is wrong under either plan; this PR treats it as a rounding bug, and your plan treats it as an input that should never have been accepted. I think yours is the better framing, and it also removes the odd case where +05.5 is silently a synonym for +05:30.

Happy to redo this PR as the deprecation. Two questions on shape:

  1. Deprecate for one release and then raise Date::Error, matching what we settled on for the RFC 3339 separator in Only allow "T" or a space as the RFC 3339 separator time#85, or raise straight away since the current answer for +00.123 is already wrong?
  2. Should the warning fire for every decimal-fraction offset, including +05.5 where the value we return happens to be correct, or only where the fraction is actually lost?

One implementation note carried over from #191: rb_warning_category_enabled_p is not usable from an extension — it is in no public header and nm -D finds it 0 times in libruby on 3.4, and building with it fails on both 2.7 and 3.4. So the warning would go through rb_category_warn, which ext/date/extconf.rb:10 already probes and date_core.c:4690 already shims.

@jeremyevans

Copy link
Copy Markdown
Contributor

Deprecation similar to #191 is best.

In terms of the warning, we should warn any case where a parsing the fractional offset hour affects the resulting return value. If the fractional offset part is already ignored, there is no need to warn, because the behavior will change to ignoring the value.

@youdie006

Copy link
Copy Markdown
Contributor Author

Understood on the shape — deprecation like #191. Before I write it, one thing your rule decides differently depending on which API is asked, so I would rather show you than guess.

Measured on 3.2.11, decimal-fraction offsets only (the +HH:MM forms are untouched):

zone Date._parse[:offset] DateTime.civil(...,s).offset with the fraction removed changes the value?
+05.0 18000 18000 18000 no
+05.000 18000 18000 18000 no
+05.5 19800 19800 18000 yes
+00.5 1800 1800 0 yes
-05.5 -19800 -19800 -18000 yes
+05.123 (92214/5) 0 18000 yes
+00.123 (2214/5) 0 0 depends

The last two rows are the awkward ones. Three or more fractional digits make date_zone_to_diff return a Rational (date_parse.c:524-535), and offset_to_sec drops any non-Fixnum on the floor (date_core.c:2639), so DateTime.civil already answers 0 — while Date._parse hands the Rational straight back.

So for +00.123: DateTime.civil gives 0 today and would give 0 after the change, which is your "already ignored, no need to warn" case. But Date._parse gives (2214/5) today and would give 0, which is a changed return value and by the same rule should warn.

Two ways to resolve it:

  1. Warn in date_zone_to_diff whenever the fractional digits are non-zero. Simple, one site, catches _parse too. Cost: +00.123 warns even though DateTime.civil users see no change.
  2. Warn in offset_to_sec only when the value actually differs there. Matches your sentence exactly for DateTime.civil, but Date._parse/Date._rfc3339 and friends never reach offset_to_sec, so the syntax would go un-deprecated on the parse APIs and then change under them silently.

I lean towards (1) — the thing being deprecated is the +HH.f spelling, and _parse is where people meet it — but (2) is the literal reading of what you wrote. Which do you want? I will send the patch either way, plus the Warning[:deprecated] mechanism from #191.

@jeremyevans

Copy link
Copy Markdown
Contributor

It's really bad to emit a deprecation warning when the behavior will not change. You are not limited to adding a deprecation warning in a single place. You can add a warning in offset_to_sec and add a separate warning for Date._parse and related methods. The principle remains the same, warn if behavior will change, do not warn if behavior will not change.

Date._parse and friends honour a fractional hour, so ignoring it later
will change what they return; they warn whenever the fraction is not
zero.

DateTime.civil goes through offset_to_sec, which already drops a zone
whose fraction makes the offset non-integral. It warns only where the
offset it returns today differs from the one the whole hour alone would
give, so '+00.123' stays quiet while '+01.123' does not.

date_zone_to_diff keeps its signature and warns; offset_to_sec uses a
new date_zone_to_diff_frac that reports the fraction instead.
@youdie006
youdie006 force-pushed the fix-string-fractional-offset branch from d4b23cf to dc922c2 Compare September 14, 2026 16:00
@youdie006

Copy link
Copy Markdown
Contributor Author

Reworked to deprecation only; nothing returns a different value than before.

Two warnings, gated separately as you described. date_zone_to_diff keeps its signature and warns whenever the fractional hour is non-zero, which covers Date._parse and the other parse entry points, since they store the fraction and so will change when it is ignored. offset_to_sec now calls a new date_zone_to_diff_frac, which reports the fraction instead of warning, and warns only where the offset it returns today differs from the whole hour alone.

That second gate is what splits the two cases you asked about. Measured on master, then on this branch:

zone Date._parse[:offset] warns DateTime.civil offset (s) warns
+00.5 1800 yes 1800 yes
+00.123 (2214/5) yes 0 no
-00.123 (-2214/5) yes 0 no
+01.123 (20214/5) yes 0 yes
+01.0 3600 no 3600 no
+00:30 1800 no 1800 no

+00.123 is quiet on the civil side because offset_to_sec already drops the whole zone there, so ignoring the fraction lands on the same 0. +01.123 is not quiet, because dropping the fraction gives 3600 rather than the 0 it returns now. The colon forms have no fractional hour and never warn.

Writing the test for the quiet rows caught something worth mentioning: DateTime.civil(..., "+00.123") already emits invalid offset is ignored, so the assertion is that the new deprecation does not appear, not that nothing is warned.

rake test equivalent: 147 tests 0 failures on master, 149 tests 0 failures here.


Disclosure: written with the help of Claude (an AI assistant). The tables are from runs on my machine.

Comment thread ext/date/date_parse.c Outdated

if (frac)
rb_warning("fraction of hour in a zone offset is deprecated"
" and will be ignored");

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Suggested change
" and will be ignored");
" and will be ignored in a future version");

Similar change for the other warning.

Comment thread test/date/test_date_parse.rb Outdated
assert_equal(1800, Date._parse('2001-02-03T00:00:00+00.5')[:offset])
end
# A zero fraction changes nothing, so it must stay quiet.
assert_warning('') do

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

This should warn, because while the :offset entry returned may not change, the :zone entry should change to remove the .0

Comment thread test/date/test_date_new.rb Outdated
end
end

def capture_zone_warning

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Is there a reason for this approach instead of assert_warning?

Comment thread ext/date/date_parse.c Outdated
VALUE offset = date_zone_to_diff_frac(str, &frac, &whole);

if (frac)
rb_warning("fraction of hour in a zone offset is deprecated"

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Add the following block up to near the top of the file (copied from date_core.c):

#ifndef HAVE_RB_CATEGORY_WARN
#define rb_category_warn(category, fmt) rb_warn(fmt)
#endif

then switch to:

Suggested change
rb_warning("fraction of hour in a zone offset is deprecated"
rb_category_warn(RB_WARN_CATEGORY_DEPRECATED, "fraction of hour in a zone offset is deprecated"

Similar change for the other warning, except there you would just move the block up in the same file.

Comment thread ext/date/date_parse.c
if (out_of_range(sec, 0, 59)) return Qnil;
}
}
else if (*p == ',' || *p == '.') {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Crazy, this supports , in addition to .

We should do a manual check that removing this else if branch only breaks the deprecated behavior tests and no other tests.


class TestDateParse < Test::Unit::TestCase

def test__parse_fractional_zone_offset_deprecated

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

There should be tests added for Date._strptime, which should have appropriate warnings

Address review: warn through rb_category_warn(RB_WARN_CATEGORY_DEPRECATED),
say the fraction will be ignored in a future version, and warn from the
parse methods for a zero fraction too, since :zone will change. Tests use
assert_warning, cover Date._strptime, and the existing fractional-offset
rows of the parse and strptime tables move into the deprecation tests.
@youdie006

Copy link
Copy Markdown
Contributor Author

Updated in 37182a3:

  • Both warnings use rb_category_warn(RB_WARN_CATEGORY_DEPRECATED, ...) and end in "will be ignored in a future version". The HAVE_RB_CATEGORY_WARN fallback is now near the top of date_parse.c and moved up in date_core.c.
  • The parse methods now warn for a zero fraction too (+01.0), because :zone will change. DateTime.civil with +01.0 still does not warn, since its offset stays the same.
  • The tests use assert_warning and turn on Warning[:deprecated] when it is available. I added Date._strptime cases for %z and %Z.
  • The existing fractional rows in test__parse (6) and test__strptime__3 (3) emitted the new warning, so I moved them into the deprecation tests with the same expected values.

Manual check on the , branch: with ',' removed from that condition, only test__parse_fractional_zone_offset_deprecated and test__strptime_fractional_zone_offset_deprecated fail. Removing the whole fractional branch also breaks test__strptime__3 on the out-of-range row +9999999999999999999999.0. The 0..23 hour check for that form lives in the branch, so without it that row returns 362439 rather than nil.

Tests pass on Ruby 2.6, 2.7, 3.0 and 3.4 (150 tests).

@jeremyevans

Copy link
Copy Markdown
Contributor

It looks like we will be replacing the C implementation of DateTime with a Ruby implementation before Ruby 4.1 (see #155). Considering that, I would like to delay review of this PR until after the replacement. Then this issue can be fixed in the Ruby implementation (assuming it exists there).

@jeremyevans

Copy link
Copy Markdown
Contributor

The revised plan now has us merging the Ruby implementation of Date after Ruby 4.1, so I think we should merge this support now, so the deprecation makes it into Ruby 4.1, and that way the Ruby implementation of Date will not need this complexity.

@jeremyevans

Copy link
Copy Markdown
Contributor

This looks mostly ready. However, I found one issue. This has DateTime.civil and potentially other methods warn twice for offsets with fractional hours:

DateTime.civil(2000, 1, 2, 3, 4, 5, '+01.123')
# warning: fraction of hour in a zone offset is deprecated and will be ignored in a future version
# warning: invalid offset is ignored

If we are already warning that we are ignoring the offset, I don't think we need to add a deprecation warning for this case. Additionally, the deprecation warning implies that we currently are respecting the fractional hour and will start ignoring it in the future, when we are already ignoring it.

DateTime.civil with '+01.123' warned both that the fraction is
deprecated and that the invalid offset is ignored. Warn about the
fraction only when offset_to_sec accepts the offset.
@youdie006

Copy link
Copy Markdown
Contributor Author

Fixed in 43c5f2d. offset_to_sec now emits the deprecation warning only when it accepts the offset, so DateTime.civil(2000, 1, 2, 3, 4, 5, '+01.123') warns only "invalid offset is ignored".

I checked the other methods with $VERBOSE and deprecation warnings on, on this branch merged with master: civil, jd, new_offset, parse and strptime with +01.123, +00.5, +23.5, +24.5, +30.5, +01.0 and +00:30. Each call emits at most one warning, and every offset matches master. parse and strptime still warn for +01.123, because they keep the fraction today (offset 2021/43200), so their result will change.

@youdie006 youdie006 changed the title Round a fractional offset given as a string Deprecate the fraction of an hour in a zone offset Nov 16, 2026
@wtn

wtn commented Nov 16, 2026

Copy link
Copy Markdown
Contributor

Perhaps "decimal hour" would be a little clearer than "fraction of hour" in the warning. While the code calls it a fractional hour internally, it was non-obvious to me at first glance.

I was also wondering if raising Date::Error might be better than ignoring the decimal part in the future, as #191 does for the RFC 3339 separators. Ignoring it would quietly turn +05.5 into +05:00, which could be overlooked (if it doesn't raise).

@jeremyevans

Copy link
Copy Markdown
Contributor

Perhaps "decimal hour" would be a little clearer than "fraction of hour" in the warning. While the code calls it a fractional hour internally, it was non-obvious to me at first glance.

I agree that "decimal hour" would be clearer.

I was also wondering if raising Date::Error might be better than ignoring the decimal part in the future, as #191 does for the RFC 3339 separators. Ignoring it would quietly turn +05.5 into +05:00, which could be overlooked (if it doesn't raise).

I think that would be inconsistent unless we start raising for invalid offsets in civil and related constructors. I'm not necessarily against that, but it goes beyond what we are trying to do in this pull request. Maybe after this goes in, we could consider a separate PR that changes the warning messages to indicate they will raise an error in a future version (both for these new warnings and the existing warnings for constructors), and then later make the Ruby implementation raise an error.

Regarding #191, it makes sense to raise, because the format is invalid and rfc3339 and similar methods such as iso8601 are designed to use strict parsing. So I don't think the same argument applies directly.

We should never raise for parse/_parse, since those are designed to be tolerant to garbage input.

@youdie006

Copy link
Copy Markdown
Contributor Author

Changed the warning to "decimal hour in a zone offset is deprecated and will be ignored in a future version" in 52bdb78, for both the parse methods and the constructors. The suite passes on Ruby 3.4 and 2.6 with this branch merged into master.

@youdie006 youdie006 changed the title Deprecate the fraction of an hour in a zone offset Deprecate a decimal hour in a zone offset Nov 16, 2026
@jeremyevans
jeremyevans merged commit e476c04 into ruby:master Nov 17, 2026
30 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants