Documentation for NSDateFormatter timeZone is misleading

Number:rdar://37187902 Date Originated:03-Feb-2018 11:37 AM
Status:Open Resolved:
Product:Documentation Product Version:N/A
Classification:Enhancement Reproducible:Always
This is a duplicate of radar #37152907

The documentation for NSDateFormatter’s timeZone property does not tell the whole story.

When parsing a date from a string, if the date format specifies a time zone, then the string will be interpreted using that parsed time zone.

For example a dateFormat of "yyyy-MM-dd'T'HH:mm:ssZZZZZ" has a time zone specifier (the Zs) so the timeZone property is not used for parsing.

Steps to Reproduce:
Look at

Expected Results:
It should say something like this:

For formatting, the date is written using the time zone in this property. If unspecified, the system time zone is used.

For parsing, if the format string has a time zone specifier then this property is ignored and the time zone from the string being parsed is used. Otherwise the time zone from this property is used, and if unspecified, the system time zone is used.

Actual Results:
It just says:

If unspecified, the system time zone is used.


This cost us many hours debugging.


Please note: Reports posted here will not necessarily be seen by Apple. All problems should be submitted at before they are posted here. Please only post information for Radars that you have filed yourself, and please do not include Apple confidential information in your posts. Thank you!