Skip to content

fix: minor rewording of cast.md for clarity #137

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
wdavidw merged 1 commit into from
Jun 27, 2023
Merged

fix: minor rewording of cast.md for clarity #137

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 9 additions & 8 deletions src/md/parse/options/cast.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,28 +7,29 @@ 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
* Default: `undefined`
* 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)
Expand All @@ -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`

Expand Down