dotnet / dotnet/dotnet-api-docs

DateTimeStyles.AdjustToUniversal documentation misleading

Open
#9,521 0 comments 1 reaction 0 assignees View on GitHub
area-System.DateTime Pri3 untriaged
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.