DOC: Add a section documenting 1.6/1.7 datetime64 differences

1 files changed, 127 insertions, 0 deletions

diff --git a/doc/source/reference/arrays.datetime.rst b/doc/source/reference/arrays.datetime.rst
index 9d0c492f3..82316144a 100644
--- a/doc/source/reference/arrays.datetime.rst
+++ b/doc/source/reference/arrays.datetime.rst
@@ -352,3 +352,130 @@ Some examples::
     weekmask = "Mon Tue Wed Thu Fri"
     # any amount of whitespace is allowed; abbreviations are case-sensitive.
     weekmask = "MonTue Wed  Thu\tFri"
+
+Differences Between 1.6 and 1.7 Datetimes
+=========================================
+
+The NumPy 1.6 release includes a more primitive datetime data type
+than 1.7. This section documents many of the changes that have taken
+place.
+
+String Parsing
+``````````````
+
+The datetime string parser in NumPy 1.6 is very liberal in what it accepts,
+and silently allows invalid input without raising errors. The parser in
+NumPy 1.7 is quite strict about only accepting ISO 8601 dates, with a few
+convenience extensions. 1.6 always creates microsecond (us) units by
+default, whereas 1.7 detects a unit based on the format of the string.
+Here is a comparison.::
+
+    # NumPy 1.6.1
+    >>> np.datetime64('1979-03-22')
+    1979-03-22 00:00:00
+    # NumPy 1.7.0
+    >>> np.datetime64('1979-03-22')
+    numpy.datetime64('1979-03-22')
+
+    # NumPy 1.6.1, unit default microseconds
+    >>> np.datetime64('1979-03-22').dtype
+    dtype('datetime64[us]')
+    # NumPy 1.7.0, unit of days detected from string
+    >>> np.datetime64('1979-03-22').dtype
+    dtype('<M8[D]')
+
+    # NumPy 1.6.1, ignores invalid part of string
+    >>> np.datetime64('1979-03-2corruptedstring')
+    1979-03-02 00:00:00
+    # NumPy 1.7.0, raises error for invalid input
+    >>> np.datetime64('1979-03-2corruptedstring')
+    Traceback (most recent call last):
+      File "<stdin>", line 1, in <module>
+    ValueError: Error parsing datetime string "1979-03-2corruptedstring" at position 8
+
+    # NumPy 1.6.1, 'nat' produces today's date
+    >>> np.datetime64('nat')
+    2012-04-30 00:00:00
+    # NumPy 1.7.0, 'nat' produces not-a-time
+    >>> np.datetime64('nat')
+    numpy.datetime64('NaT')
+
+    # NumPy 1.6.1, 'garbage' produces today's date
+    >>> np.datetime64('garbage')
+    2012-04-30 00:00:00
+    # NumPy 1.7.0, 'garbage' raises an exception
+    >>> np.datetime64('garbage')
+    Traceback (most recent call last):
+      File "<stdin>", line 1, in <module>
+    ValueError: Error parsing datetime string "garbage" at position 0
+
+    # NumPy 1.6.1, can't specify unit in scalar constructor
+    >>> np.datetime64('1979-03-22T19:00', 'h')
+    Traceback (most recent call last):
+      File "<stdin>", line 1, in <module>
+    TypeError: function takes at most 1 argument (2 given)
+    # NumPy 1.7.0, unit in scalar constructor
+    >>> np.datetime64('1979-03-22T19:00', 'h')
+    numpy.datetime64('1979-03-22T19:00-0500','h')
+
+    # NumPy 1.6.1, reads ISO 8601 strings w/o TZ as UTC
+    >>> np.array(['1979-03-22T19:00'], dtype='M8[h]')
+    array([1979-03-22 19:00:00], dtype=datetime64[h])
+    # NumPy 1.7.0, reads ISO 8601 strings w/o TZ as local (ISO specifies this)
+    >>> np.array(['1979-03-22T19:00'], dtype='M8[h]')
+    array(['1979-03-22T19-0500'], dtype='datetime64[h]')
+
+    # NumPy 1.6.1, doesn't parse all ISO 8601 strings correctly
+    >>> np.array(['1979-03-22T12'], dtype='M8[h]')
+    array([1979-03-22 00:00:00], dtype=datetime64[h])
+    >>> np.array(['1979-03-22T12:00'], dtype='M8[h]')
+    array([1979-03-22 12:00:00], dtype=datetime64[h])
+    # NumPy 1.7.0, handles this case correctly
+    >>> np.array(['1979-03-22T12'], dtype='M8[h]')
+    array(['1979-03-22T12-0500'], dtype='datetime64[h]')
+    >>> np.array(['1979-03-22T12:00'], dtype='M8[h]')
+    array(['1979-03-22T12-0500'], dtype='datetime64[h]')
+
+Unit Conversion
+```````````````
+
+The 1.6 implementation of datetime does not convert between units correctly.::
+
+    # NumPy 1.6.1, the representation value is untouched
+    >>> np.array(['1979-03-22'], dtype='M8[D]')
+    array([1979-03-22 00:00:00], dtype=datetime64[D])
+    >>> np.array(['1979-03-22'], dtype='M8[D]').astype('M8[M]')
+    array([2250-08-01 00:00:00], dtype=datetime64[M])
+    # NumPy 1.7.0, the representation is scaled accordingly
+    >>> np.array(['1979-03-22'], dtype='M8[D]')
+    array(['1979-03-22'], dtype='datetime64[D]')
+    >>> np.array(['1979-03-22'], dtype='M8[D]').astype('M8[M]')
+    array(['1979-03'], dtype='datetime64[M]')
+
+Datetime Arithmetic
+```````````````````
+
+The 1.6 implementation of datetime only works correctly for a small subset of
+arithmetic operations. Here we show some simple cases.::
+
+    # NumPy 1.6.1, produces invalid results if units are incompatible
+    >>> a = np.array(['1979-03-22T12'], dtype='M8[h]')
+    >>> b = np.array([3*60], dtype='m8[m]')
+    >>> a + b
+    array([1970-01-01 00:00:00.080988], dtype=datetime64[us])
+    # NumPy 1.7.0, promotes to higher-resolution unit
+    >>> a = np.array(['1979-03-22T12'], dtype='M8[h]')
+    >>> b = np.array([3*60], dtype='m8[m]')
+    >>> a + b
+    array(['1979-03-22T15:00-0500'], dtype='datetime64[m]')
+
+    # NumPy 1.6.1, arithmetic works if everything is microseconds
+    >>> a = np.array(['1979-03-22T12:00'], dtype='M8[us]')
+    >>> b = np.array([3*60*60*1000000], dtype='m8[us]')
+    >>> a + b
+    array([1979-03-22 15:00:00], dtype=datetime64[us])
+    # NumPy 1.7.0
+    >>> a = np.array(['1979-03-22T12:00'], dtype='M8[us]')
+    >>> b = np.array([3*60*60*1000000], dtype='m8[us]')
+    >>> a + b
+    array(['1979-03-22T15:00:00.000000-0500'], dtype='datetime64[us]')