It was not clear from the documentation whether these methods mutate
the current object, or return a new object with the applied
modification. The fact that these functions have a non-void return
type adds to the confusion.
Clarify this by explicitly mentioning that the functions mutate the
current object, and add a "Returns:" DDoc section documenting that the
methods simply return `this`.
This removes unnecessary uses of scope, adds a lot of necessary uses of
scope, and adds basic tests that ensure that each of the functions in
std.datetime.systime compile when given scope arguments. It also enables
some previously commented out tests involving immutable SysTimes (IIRC,
they didn't use to compile due to compiler bugs related to
Rebindable!(immutable TimeZone), but they now compiler, so they should
be enabled).
This adds a special TimeZone type internal to SysTime which _timezone is
directly initialized to so that SysTime.init will work without
segfaulting but will still be uniquely identifiable with the is
operator. Or at least, _timezone is _supposed_ to be directly
initialized to it, but issue# 17740 currently prevents that. So,
_timezone has been temporarily renamed to _timezoneStorage and private
getters and setters named _timezone have been added. The getter then
does a null check and returns InitTimeZone() for SysTime.init to
simulate the member variable having been initialized to InitTimeZone().
Once issue# 17740 has been fixed, these accessors will be unnecessary,
and the code should be updated so that _timezone is properly a variable
again and is directly initialized with InitTimeZone().
The new TimeZone type - InitTimeZone - is internal to SysTime and can
only be obtained by the timezone getter on SysTime.init. It acts the
same as UTC except that it is not special-cased by the to*String
functions and thus will print out its timezone as +00:00 instead of z,
which is perfectly legitimate per the spec. And as such, if _timezone
were directly initialized with InitTimeZone(), there would be no extra
checks due to this change, and everything would just work. However,
until issue# 17740 is fixed, there will be an extra null check any time
that a function is called on _timezone, because _timezone is currently a
wrapper that does a null check rather than being a member variable
directly like it's supposed to be.
Unlike previous attempts along these lines, this does not make it so
that SysTime.init has NaN behavior such that any operation (other than
assignment) on an an uninitialized SysTime would result in SysTime.init,
and the timezone setter property does not set the SysTime to
SysTime.init if it's passed this TimeZone. So, unfortunately, it _is_
possible to have other SysTime values with the special TimeZone, but it
was deemed unnecessarily complex for too little benefit to add the NaN
behavior. And regardless, SysTime.init is still uniquely identifiable
via the is operator. It's just that it can't technically be uniquely
identified by the timezone getter, which was never a supported feature
anyway.
There was documentation refering to the now deprecated method of getting one of the of the timezone implementations via the static TimeZone.getTimeZone.
Apparently, with gdc and optimizations turned on, the test in question
is optimized enough that the first function being benchmarked sometimes
takes no time at all (since the function being benchmarked does
nothing), causing the test to fail. This fixes that.
