DEP-0007 Type-Safe Limited Collections

documentation/library-reference/source/dylan/index.rst

@@ -371,3 +371,69 @@ a Table-extensions module, which you can read about in
      It returns a hash ID (an integer) and the result of merging the
      initial state with the associated hash state for the object,
      computed in some implementation-dependent manner.
+
+Limited Collections
+-------------------
+
+To improve type safety of limited collections, Open Dylan implements an
+extension to the :drm:`make` and :drm:`limited` functions. Normally, when
+calling :drm:`make` on a collection that supports the ``fill:`` init-keyword,
+that keyword defaults to ``#f``. This value can be inappropriate for a limited
+collection. The :drm:`limited` function in Open Dylan accepts a
+``default-fill:`` keyword argument which replaces the default of ``#f`` with a
+user-specified value; this value is used by :drm:`make` and :drm:`size-setter`
+when initializing or adding elements to those collections.
+
+Open Dylan also implements the :func:`element-type` and
+:func:`element-type-fill` functions to further improve type safety.
+
+.. function:: limited
+
+   Open Dylan implements the following altered signatures.
+
+   :signature: limited singleton(<array>) #key *of* *size* *dimensions* *default-fill* => *type*
+   :signature: limited singleton(<vector>) #key *of* *size* *default-fill* => *type*
+   :signature: limited singleton(<simple-vector>) #key *of* *size* *default-fill* => *type*
+   :signature: limited singleton(<stretchy-vector>) #key *of* *default-fill* => *type*
+   :signature: limited singleton(<deque>) #key *of* *default-fill* => *type*
+   :signature: limited singleton(<string>) #key *of* *size* *default-fill* => *type*
+
+   :param #key default-fill:
+      The default value of the ``fill:`` keyword argument to the :drm:`make`
+      function, replacing ``#f``. Optional. If not supplied, the default
+      value for the ``default-fill:`` argument and thus for the ``fill:``
+      argument to :drm:`make` is ``#f`` (or ``' '`` for strings).
+
+   :example:
+
+      .. code-block:: dylan
+
+        define constant <answers-vector>
+            = limited(<vector>, of: <object>, default-fill: 42);
+        let some-answers = make(<answers-vector>, size: 3);
+        // #[ 42, 42, 42 ]
+
+.. generic-function:: element-type
+   :open:
+
+   Returns the element type of a collection.
+
+   :signature: element-type *collection* => *type*
+
+   :param collection: An instance of :drm:`<collection>`.
+   :value type:       The permitted element type of the collection.
+
+.. generic-function:: element-type-fill
+   :open:
+
+   Returns a valid object that may be used for new elements of a collection.
+
+   :signature: element-type-fill *collection* => *object*
+
+   :param collection: An instance of :drm:`<collection>` that supports the
+                      ``fill:`` init-keyword.
+   :value object:     An object.
+
+   :discussion: For limited collections, this object will be the defaulted or
+                supplied ``default-fill:`` argument to the :func:`limited`
+                function.

documentation/release-notes/source/2014.1.rst

@@ -84,6 +84,26 @@ Common Dylan
 * The function ``integer-to-string`` is now faster.
 
 
+Dylan
+=====
+
+Open Dylan now implements
+`DEP-0007 (Type-Safe Limited Collections) <http://opendylan.org/proposals/dep-0007.html>`_.
+This adds a ``default-fill:`` argument to ``limited``, a corresponding
+``element-type-fill`` generic function, and an ``element-type`` generic
+function applicable to all collections. With this, limited collections will now
+be easier and safer to use—with one caveat:
+
+As described in the DEP-0007 document, Open Dylan had previously ensured that
+some numeric limited collection types would automatically be filled with ``0``
+when instantiated *with* a non-zero size but *without* a ``fill:`` init-keyword.
+This is no longer the case. Code that relied on this behavior must be updated
+to provide valid ``fill:`` or ``default-fill:`` values.
+
+``element`` will no longer signal a type error when it returns its ``default:``
+value and that value does not match the element type of a limited collection.
+
+
 dylan-direct-c-ffi
 ==================
 

sources/common-dylan/byte-vector.dylan

@@ -10,7 +10,7 @@ License:      See License.txt in this distribution for details.
 ///// BYTE-VECTOR
 /////
 
-define constant <byte-vector> = limited(<vector>, of: <byte>);
+define constant <byte-vector> = limited(<vector>, of: <byte>, default-fill: as(<byte>, 0));
 
 /// Fast byte vector copying
 

sources/common-dylan/format.dylan

@@ -10,7 +10,8 @@ Warranty:     Distributed WITHOUT WARRANTY OF ANY KIND
 /// String buffers
 
 //---*** Oh for a stretchy string...
-define constant <string-buffer> = limited(<stretchy-vector>, of: <byte-character>);
+define constant <string-buffer> = limited(<stretchy-vector>, of: <byte-character>,
+                                          default-fill: as(<byte-character>, ' '));
 
 //---*** Is there a more efficient way to do this?
 define function print-string