1csv-core
2========
3A fast CSV reader and write for use in a `no_std` context. This crate will
4never use the Rust standard library.
5
6[![Linux build status](https://api.travis-ci.org/BurntSushi/rust-csv.png)](https://travis-ci.org/BurntSushi/rust-csv)
7[![Windows build status](https://ci.appveyor.com/api/projects/status/github/BurntSushi/rust-csv?svg=true)](https://ci.appveyor.com/project/BurntSushi/rust-csv)
8[![](http://meritbadge.herokuapp.com/csv-core)](https://crates.io/crates/csv-core)
9
10Dual-licensed under MIT or the [UNLICENSE](http://unlicense.org).
11
12### Documentation
13
14https://docs.rs/csv-core
15
16### Usage
17
18Add this to your `Cargo.toml`:
19
20```toml
21[dependencies]
22csv-core = "0.1.6"
23```
24
25### Build features
26
27This crate by default links with `libc`, which is done via the `libc` feature.
28Disabling this feature will drop `csv-core`'s dependency on `libc`.
29
30
31### Example: reading CSV
32
33This example shows how to count the number of fields and records in CSV data.
34
35```rust
36use csv_core::{Reader, ReadFieldResult};
37
38let data = "
39foo,bar,baz
40a,b,c
41xxx,yyy,zzz
42";
43
44let mut rdr = Reader::new();
45let mut bytes = data.as_bytes();
46let mut count_fields = 0;
47let mut count_records = 0;
48loop {
49    // We skip handling the output since we don't need it for counting.
50    let (result, nin, _) = rdr.read_field(bytes, &mut [0; 1024]);
51    bytes = &bytes[nin..];
52    match result {
53        ReadFieldResult::InputEmpty => {},
54        ReadFieldResult::OutputFull => panic!("field too large"),
55        ReadFieldResult::Field { record_end } => {
56            count_fields += 1;
57            if record_end {
58                count_records += 1;
59            }
60        }
61        ReadFieldResult::End => break,
62    }
63}
64assert_eq!(3, count_records);
65assert_eq!(9, count_fields);
66```
67
68
69### Example: writing CSV
70
71This example shows how to use the `Writer` API to write valid CSV data. Proper
72quoting is handled automatically.
73
74```rust
75use csv_core::Writer;
76
77// This is where we'll write out CSV data.
78let mut out = &mut [0; 1024];
79// The number of bytes we've written to `out`.
80let mut nout = 0;
81// Create a CSV writer with a default configuration.
82let mut wtr = Writer::new();
83
84// Write a single field. Note that we ignore the `WriteResult` and the number
85// of input bytes consumed since we're doing this by hand.
86let (_, _, n) = wtr.field(&b"foo"[..], &mut out[nout..]);
87nout += n;
88
89// Write a delimiter and then another field that requires quotes.
90let (_, n) = wtr.delimiter(&mut out[nout..]);
91nout += n;
92let (_, _, n) = wtr.field(&b"bar,baz"[..], &mut out[nout..]);
93nout += n;
94let (_, n) = wtr.terminator(&mut out[nout..]);
95nout += n;
96
97// Now write another record.
98let (_, _, n) = wtr.field(&b"a \"b\" c"[..], &mut out[nout..]);
99nout += n;
100let (_, n) = wtr.delimiter(&mut out[nout..]);
101nout += n;
102let (_, _, n) = wtr.field(&b"quux"[..], &mut out[nout..]);
103nout += n;
104
105// We must always call finish once done writing.
106// This ensures that any closing quotes are written.
107let (_, n) = wtr.finish(&mut out[nout..]);
108nout += n;
109
110assert_eq!(&out[..nout], &b"\
111foo,\"bar,baz\"
112\"a \"\"b\"\" c\",quux"[..]);
113```
114