dotnet / dotnet/dotnet-api-docs
DateTimeStyles.AdjustToUniversal documentation misleading
- Dominant language
- C#
- Stars
- 949
- Forks
- 1.7k
- Avg merge
- 3d 27m
- Merged PRs (30d)
- 49
Description
https://github.com/dotnet/dotnet-api-docs/blob/2cc0a570b4d74b3d3b27aea3ca8f992df9d98862/xml/System.Globalization/DateTimeStyles.xml#L134
The documentation for `AdjustToUniversal` says
> If the input string denotes a UTC time, through a time zone specifier or [AssumeUniversal](https://learn.microsoft.com/en-us/dotnet/api/system.globalization.datetimestyles?view=net-8.0#system-globalization-datetimestyles-assumeuniversal), no conversion occurs.
This is not strictly true. When `AssumeUniversal` is used with [`DateTimeOffset`](https://learn.microsoft.com/en-us/dotnet/api/system.datetimeoffset.parseexact?view=net-8.0):
> If format does not require that input contain an offset value, the returned DateTimeOffset object is given the UTC offset (+00:00).
So `AdjustToUniversal` indeed has no effect.
But when `AssumeUniversal` is used for [`DateTime`](https://learn.microsoft.com/en-us/dotnet/api/system.datetimeoffset.parseexact?view=net-8.0):
> Specifies that if s lacks any time zone information, it is assumed to represent UTC. Unless the DateTimeStyles.AdjustToUniversal flag is present, the method converts the returned DateTime value from UTC to local time and sets its Kind property to DateTimeKind.Local.
So `AdjustToUniversal` will do the following conversation:
> calls ToUniversalTime to convert the returned DateTime value to UTC, and sets the Kind property to DateTimeKind.Utc.
Contributor guide
Assessment
This issue has not been assessed yet.