diff --git a/src/md/parse/options/cast.md b/src/md/parse/options/cast.md index 3a02003d9..3bf16ca77 100644 --- a/src/md/parse/options/cast.md +++ b/src/md/parse/options/cast.md @@ -7,7 +7,7 @@ keywords: ['csv', 'parse', 'options', 'cast', 'context', 'lines', 'quoting'] # Option `cast` -The `cast` option alter a value. It works at the field level of a record. It is possible to transform its value or change its type. +The `cast` option works at the field-level to alter its value. It is possible to transform the field's value or change its type. * Type: `function` * Optional @@ -15,20 +15,21 @@ The `cast` option alter a value. It works at the field level of a record. It is * Since: 2.2.0 * Related: `cast_date`, [`info`](/parse/options/info/), [`on_record`](/parse/options/on_record/) — see [Available Options](/parse/options/#available-options) -Its value is expected to be a function which receives a context rich of information. It gives full control over a field. The [`test/option.cast.coffee`](https://github.com/adaltas/node-csv/blob/master/packages/csv-parse/test/option.cast.coffee) test provides insights on how to use it and its supported functionalities. +The `cast` value is expected to be a function that receives context-rich information. The function has full control over a field. The [`test/option.cast.coffee`](https://github.com/adaltas/node-csv/blob/master/packages/csv-parse/test/option.cast.coffee) test provides insights on how to use it and its supported functionalities. ## Context -The function is called with 2 arguments: the field value and a context object. The context object expose the following properties: +The `cast` function is called with 2 arguments: the field `value` and the `context` object. +The `context` object exposes the following properties: * `column` (number|string) - The column name if the `columns` options is defined or the field position. + The column name if the `columns` options is defined, or the field position. * `empty_lines` (number) Internal counter of empty lines encountered until this field. * `header` (boolean) A boolean indicating if the provided value is a part of the header. * `index` (number) - The field position starting at 0. + The field position within the current record starting at 0. * `invalid_field_length` (number) Number of records with a non uniform length when [`relax_column_count`](/parse/options/relax_column_count/) is true. It was named `skipped_lines` until version 3. * `lines` (number) @@ -38,15 +39,15 @@ The function is called with 2 arguments: the field value and a context object. T * `records` (number) The number of records which have been fully parsed. It was named `count` until version 3. -The [cast example](https://github.com/adaltas/node-csv/blob/master/packages/csv-parse/samples/option.cast.js) uses the context to transform the first filed into a date and replace the second field with the injected context: +The [cast example](https://github.com/adaltas/node-csv/blob/master/packages/csv-parse/samples/option.cast.js) uses the context to transform the first field into a date and replace the second field with the injected context: `embed:packages/csv-parse/samples/option.cast.js` ## Using the `cast` and `columns` functions conjointly -The `cast` function is called field by field, whether it is considered a header or not. The `columns` function is called once the first record is created (if treated as a header). For this reason, `cast` is executed before `columns`. +The `cast` function is called for each and every field, whether it is considered a header or not. The `columns` function is called once the first record is created (if treated as a header). For this reason, `cast` is executed before `columns`. -To distinguish a header field from a data field in the `cast` function, use the [`context.header` property](https://github.com/adaltas/node-csv/blob/master/packages/csv-parse/samples/option.cast.header.column.fn.js) in the second argument of the `cast` function: +To distinguish a header field from a data field in the `cast` function, use the [`context.header` property](https://github.com/adaltas/node-csv/blob/master/packages/csv-parse/samples/option.cast.header.column.fn.js) from the second argument to the `cast` function: `embed:packages/csv-parse/samples/option.cast.header.column.fn.js`