document Plot.valueof (#873)

* document Plot.valueof

* Update README.md

Co-authored-by: Mike Bostock <[email protected]>

Author: Fil

README.md

@@ -2159,6 +2159,21 @@ While transform functions often produce new *data* or *facets*, they may return
 
 Plot provides a few helpers for implementing transforms.
 
+#### Plot.valueof(*data*, *value*, *type*)
+
+Given an iterable *data* and some *value* accessor, returns an array (a column) of the specified *type* with the corresponding value of each element of the data. The *value* accessor may be one of the following types:
+
+* a string - corresponding to the field accessor (`d => d[value]`)
+* an accessor function - called as *type*.from(*data*, *value*)
+* a number, Date, or boolean — resulting in an array uniformly filled with the *value*
+* an object with a transform method — called as *value*.transform(*data*)
+* an array of values - returning the same
+* null or undefined - returning the same
+
+If *type* is specified, it must be Array or a similar class that implements the [Array.from](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/from) interface such as a typed array. When *type* is Array or a typed array class, the return value of valueof will be an instance of the same (or null or undefined). If *type* is not specified, valueof may return either an array or a typed array (or null or undefined).
+
+Plot.valueof is not guaranteed to return a new array. When a transform method is used, or when the given *value* is an array that is compatible with the requested *type*, the array may be returned as-is without making a copy.
+
 #### Plot.transform(*options*, *transform*)
 
 Given an *options* object that may specify some basic transforms (*filter*, *sort*, or *reverse*) or a custom *transform* function, composes those transforms if any with the given *transform* function, returning a new *options* object. If a custom *transform* function is present on the given *options*, any basic transforms are ignored. Any additional input *options* are passed through in the returned *options* object. This method facilitates applying the basic transforms prior to applying the given custom *transform* and is used internally by Plot’s built-in transforms.