Merge pull request #236 from jbms/fix-issue-231

Clarify fill value representation, change nan representation

Author: jstriebel

docs/v3/core/v3.0.rst

@@ -597,30 +597,63 @@ mandatory names:
     Provides an element value to use for uninitialised portions of the
     Zarr array.
 
-    If the data type of the Zarr array is Boolean then the value must
-    be the literal ``false`` or ``true``. If the data type is one of
-    the integer data types defined in this specification, then the
-    value must be a number with no fraction or exponent part and must
-    be within the range of the data type.
-
-    For any data type, the ``fill_value`` is required. The literal
-    ``null`` is not permitted. The fill value needs to be defined
-    so that the data is independent of implementation details. Internally
-    implementations may provide a default ``fill_value``, but that must
-    be converted to a fixed value in the stored metadata.
-
-    If the ``data_type`` of an array is defined in a ``data_type`` extension,
-    then said extension is responsible for interpreting the value of
-    ``fill_value`` and returning a suitable type that can be used.
-
-    For core data types for which fill values are not permitted in JSON or
-    for which decimal representation could be lossy, a string representing of
-    the binary (starting with ``0b``) or hexadecimal value (starting with
-    ``0x``) is accepted. This string must include all leading or trailing
-    zeroes necessary to match the given type size. The string values ``"NaN"``,
-    ``"+Infinity"`` and ``"-Infinity"`` are also understood for floating point
-    data types.
+    The permitted values depend on the data type:
 
+    ``bool``
+      The value must be a JSON boolean (``false`` or ``true``).
+
+    Integers (``{uint,int}{8,16,32,64}``)
+      The value must be a JSON number with no fraction or exponent part that is
+      within the representable range of the data type.
+
+    IEEE 754 floating point numbers (``float{16,32,64}``)
+      The value may be either:
+
+      - A JSON number, that will be rounded to the nearest representable value.
+
+      - A JSON string of the form:
+
+        - ``"Infinity"``, denoting positive infinity;
+        - ``"-Infinity"``, denoting negative infinity;
+        - ``"NaN"``, denoting thenot-a-number (NaN) value where the sign bit is
+          0 (positive), the most significant bit (MSB) of the mantissa is 1, and
+          all other bits of the mantissa are zero;
+        - ``"0xYYYYYYYY"``, specifying the byte representation of the floating
+          point number as an unsigned integer.  For example, for ``float32``,
+          ``"NaN"`` is equivalent to ``"0x7fc00000"``.  This representation is
+          the only way to specify a NaN value other than the specific NaN value
+          denoted by ``"NaN"``.
+
+        .. warning::
+
+           While this NaN syntax is consistent with the syntax accepted by the
+           C99 ``strtod`` function, C99 leaves the meaning of the NaN payload
+           string implementation defined, which may not match the Zarr
+           definition.
+
+    Complex numbers (``complex{64,128}``)
+      The value must be a two-element array, specifying the real and imaginary
+      components respectively, where each component is specified as defined
+      above for floating point number.
+
+      For example, ``[1, 2]`` indicates ``1 + 2i`` and ``["-Infinity", "NaN"]``
+      indicates a complex number with real component of -inf and imaginary
+      component of NaN.
+
+    Raw data types (``r<N>``)
+      An array of integers, with length equal to ``<N>``, where each integer is
+      in the range ``[0, 255]``.
+
+    Extensions to the spec that define new data types must also define the JSON
+    fill value representation.
+
+    .. note::
+
+       The ``fill_value`` metadata field is required, but Zarr implementations
+       may provide an interface for creating a new array with which users can
+       leave the fill value unspecified, in which case a default fill value for
+       the data type will be chosen.  However, the default fill value that is
+       chosen MUST be recorded in the metadata.
 
 The following members are optional: