<?xml version="1.0" encoding="UTF-8" ?>
<dt-api group="static">
	<name>DataTable.util.set()</name>
	<summary>Create a write function from a descriptor</summary>
	<since>1.11.0</since>

	<type type="function">
		<signature>set( descriptor )</signature>
		<description>Build a writing function to set data based on the given descriptor.</description>
		<param type="string|function|null" name="descriptor">
			A descriptor that is used to define how to write data to a source object. See above for full details of the options that this can be used as.
		</param>
		<returns type="Function">A write function that will be used to set data into the given object.</returns>
	</type>

	<description>
		Matching `-api DataTable.util.get()`, but in this case to write data to a source object, this method makes it possible to write data to a complex object by using the description of the familiar JSON notation. DataTables uses this method internally for `-init columns.data` when writing data to the data store for rows and this method exposes that ability for plug-ins and other libraries to use.

		The function _that is returned_ from this method expects the following parameters to be given to it:

		1. Target object - into which the data will be written
		2. Value - the value that will be written into the location defined by the descriptor.
		3. Meta information - any extra information you wish to pass on to the descriptor if used as a function.

		An example of using this method to write data:

		```js
		let user = {
			name: {
				first: 'Fiona',
				last: 'Grayling'
			}
		};
		let fn = DataTable.util.set('name.first');
		
		fn(user, 'Airi');
		// Will replace `Fiona` with `Airi`
		```

		The descriptor can be given as:

		* `null`: The returned function is a no-op (no operation) function - i.e. a function that does nothing when executed.
		* A function: When called the writer will execute the descriptor function with the following arguments:
		  1. The target object
		  2. `-string set` (this is used by DataTables for `-init columns.data`)
		  3. The value to set
		  4. Meta information passed in
		* A string: Returns a function that will write the given value to the property defined by a JSON notation string, with the same added abilities as `-api DataTable.util.get()` - i.e. support for both array syntax (`[]`) and function execution syntax (`()`) in the string.
	</description>
</dt-api>