Struct csv::WriterBuilder
source · pub struct WriterBuilder { /* private fields */ }
Expand description
Builds a CSV writer with various configuration knobs.
This builder can be used to tweak the field delimiter, record terminator
and more. Once a CSV Writer
is built, its configuration cannot be
changed.
Implementations§
source§impl WriterBuilder
impl WriterBuilder
sourcepub fn new() -> WriterBuilder
pub fn new() -> WriterBuilder
Create a new builder for configuring CSV writing.
To convert a builder into a writer, call one of the methods starting
with from_
.
Example
use std::error::Error;
use csv::WriterBuilder;
fn example() -> Result<(), Box<dyn Error>> {
let mut wtr = WriterBuilder::new().from_writer(vec![]);
wtr.write_record(&["a", "b", "c"])?;
wtr.write_record(&["x", "y", "z"])?;
let data = String::from_utf8(wtr.into_inner()?)?;
assert_eq!(data, "a,b,c\nx,y,z\n");
Ok(())
}
sourcepub fn from_path<P: AsRef<Path>>(&self, path: P) -> Result<Writer<File>>
pub fn from_path<P: AsRef<Path>>(&self, path: P) -> Result<Writer<File>>
Build a CSV writer from this configuration that writes data to the given file path. The file is truncated if it already exists.
If there was a problem opening the file at the given path, then this returns the corresponding error.
Example
use std::error::Error;
use csv::WriterBuilder;
fn example() -> Result<(), Box<dyn Error>> {
let mut wtr = WriterBuilder::new().from_path("foo.csv")?;
wtr.write_record(&["a", "b", "c"])?;
wtr.write_record(&["x", "y", "z"])?;
wtr.flush()?;
Ok(())
}
sourcepub fn from_writer<W: Write>(&self, wtr: W) -> Writer<W>
pub fn from_writer<W: Write>(&self, wtr: W) -> Writer<W>
Build a CSV writer from this configuration that writes data to wtr
.
Note that the CSV writer is buffered automatically, so you should not
wrap wtr
in a buffered writer like io::BufWriter
.
Example
use std::error::Error;
use csv::WriterBuilder;
fn example() -> Result<(), Box<dyn Error>> {
let mut wtr = WriterBuilder::new().from_writer(vec![]);
wtr.write_record(&["a", "b", "c"])?;
wtr.write_record(&["x", "y", "z"])?;
let data = String::from_utf8(wtr.into_inner()?)?;
assert_eq!(data, "a,b,c\nx,y,z\n");
Ok(())
}
sourcepub fn delimiter(&mut self, delimiter: u8) -> &mut WriterBuilder
pub fn delimiter(&mut self, delimiter: u8) -> &mut WriterBuilder
The field delimiter to use when writing CSV.
The default is b','
.
Example
use std::error::Error;
use csv::WriterBuilder;
fn example() -> Result<(), Box<dyn Error>> {
let mut wtr = WriterBuilder::new()
.delimiter(b';')
.from_writer(vec![]);
wtr.write_record(&["a", "b", "c"])?;
wtr.write_record(&["x", "y", "z"])?;
let data = String::from_utf8(wtr.into_inner()?)?;
assert_eq!(data, "a;b;c\nx;y;z\n");
Ok(())
}
sourcepub fn has_headers(&mut self, yes: bool) -> &mut WriterBuilder
pub fn has_headers(&mut self, yes: bool) -> &mut WriterBuilder
Whether to write a header row before writing any other row.
When this is enabled and the serialize
method is used to write data
with something that contains field names (i.e., a struct), then a
header row is written containing the field names before any other row
is written.
This option has no effect when using other methods to write rows. That
is, if you don’t use serialize
, then you must write your header row
explicitly if you want a header row.
This is enabled by default.
Example: with headers
This shows how the header will be automatically written from the field names of a struct.
use std::error::Error;
use csv::WriterBuilder;
#[derive(serde::Serialize)]
struct Row<'a> {
city: &'a str,
country: &'a str,
// Serde allows us to name our headers exactly,
// even if they don't match our struct field names.
#[serde(rename = "popcount")]
population: u64,
}
fn example() -> Result<(), Box<dyn Error>> {
let mut wtr = WriterBuilder::new().from_writer(vec![]);
wtr.serialize(Row {
city: "Boston",
country: "United States",
population: 4628910,
})?;
wtr.serialize(Row {
city: "Concord",
country: "United States",
population: 42695,
})?;
let data = String::from_utf8(wtr.into_inner()?)?;
assert_eq!(data, "\
city,country,popcount
Boston,United States,4628910
Concord,United States,42695
");
Ok(())
}
Example: without headers
This shows that serializing things that aren’t structs (in this case,
a tuple struct) won’t result in a header row being written. This means
you usually don’t need to set has_headers(false)
unless you
explicitly want to both write custom headers and serialize structs.
use std::error::Error;
use csv::WriterBuilder;
fn example() -> Result<(), Box<dyn Error>> {
let mut wtr = WriterBuilder::new().from_writer(vec![]);
wtr.serialize(("Boston", "United States", 4628910))?;
wtr.serialize(("Concord", "United States", 42695))?;
let data = String::from_utf8(wtr.into_inner()?)?;
assert_eq!(data, "\
Boston,United States,4628910
Concord,United States,42695
");
Ok(())
}
sourcepub fn flexible(&mut self, yes: bool) -> &mut WriterBuilder
pub fn flexible(&mut self, yes: bool) -> &mut WriterBuilder
Whether the number of fields in records is allowed to change or not.
When disabled (which is the default), writing CSV data will return an error if a record is written with a number of fields different from the number of fields written in a previous record.
When enabled, this error checking is turned off.
Example: writing flexible records
use std::error::Error;
use csv::WriterBuilder;
fn example() -> Result<(), Box<dyn Error>> {
let mut wtr = WriterBuilder::new()
.flexible(true)
.from_writer(vec![]);
wtr.write_record(&["a", "b"])?;
wtr.write_record(&["x", "y", "z"])?;
let data = String::from_utf8(wtr.into_inner()?)?;
assert_eq!(data, "a,b\nx,y,z\n");
Ok(())
}
Example: error when flexible
is disabled
use std::error::Error;
use csv::WriterBuilder;
fn example() -> Result<(), Box<dyn Error>> {
let mut wtr = WriterBuilder::new()
.flexible(false)
.from_writer(vec![]);
wtr.write_record(&["a", "b"])?;
let err = wtr.write_record(&["x", "y", "z"]).unwrap_err();
match *err.kind() {
csv::ErrorKind::UnequalLengths { expected_len, len, .. } => {
assert_eq!(expected_len, 2);
assert_eq!(len, 3);
}
ref wrong => {
panic!("expected UnequalLengths but got {:?}", wrong);
}
}
Ok(())
}
sourcepub fn terminator(&mut self, term: Terminator) -> &mut WriterBuilder
pub fn terminator(&mut self, term: Terminator) -> &mut WriterBuilder
The record terminator to use when writing CSV.
A record terminator can be any single byte. The default is \n
.
Note that RFC 4180 specifies that record terminators should be \r\n
.
To use \r\n
, use the special Terminator::CRLF
value.
Example: CRLF
This shows how to use RFC 4180 compliant record terminators.
use std::error::Error;
use csv::{Terminator, WriterBuilder};
fn example() -> Result<(), Box<dyn Error>> {
let mut wtr = WriterBuilder::new()
.terminator(Terminator::CRLF)
.from_writer(vec![]);
wtr.write_record(&["a", "b", "c"])?;
wtr.write_record(&["x", "y", "z"])?;
let data = String::from_utf8(wtr.into_inner()?)?;
assert_eq!(data, "a,b,c\r\nx,y,z\r\n");
Ok(())
}
sourcepub fn quote_style(&mut self, style: QuoteStyle) -> &mut WriterBuilder
pub fn quote_style(&mut self, style: QuoteStyle) -> &mut WriterBuilder
The quoting style to use when writing CSV.
By default, this is set to QuoteStyle::Necessary
, which will only
use quotes when they are necessary to preserve the integrity of data.
Note that unless the quote style is set to Never
, an empty field is
quoted if it is the only field in a record.
Example: non-numeric quoting
This shows how to quote non-numeric fields only.
use std::error::Error;
use csv::{QuoteStyle, WriterBuilder};
fn example() -> Result<(), Box<dyn Error>> {
let mut wtr = WriterBuilder::new()
.quote_style(QuoteStyle::NonNumeric)
.from_writer(vec![]);
wtr.write_record(&["a", "5", "c"])?;
wtr.write_record(&["3.14", "y", "z"])?;
let data = String::from_utf8(wtr.into_inner()?)?;
assert_eq!(data, "\"a\",5,\"c\"\n3.14,\"y\",\"z\"\n");
Ok(())
}
Example: never quote
This shows how the CSV writer can be made to never write quotes, even if it sacrifices the integrity of the data.
use std::error::Error;
use csv::{QuoteStyle, WriterBuilder};
fn example() -> Result<(), Box<dyn Error>> {
let mut wtr = WriterBuilder::new()
.quote_style(QuoteStyle::Never)
.from_writer(vec![]);
wtr.write_record(&["a", "foo\nbar", "c"])?;
wtr.write_record(&["g\"h\"i", "y", "z"])?;
let data = String::from_utf8(wtr.into_inner()?)?;
assert_eq!(data, "a,foo\nbar,c\ng\"h\"i,y,z\n");
Ok(())
}
sourcepub fn quote(&mut self, quote: u8) -> &mut WriterBuilder
pub fn quote(&mut self, quote: u8) -> &mut WriterBuilder
The quote character to use when writing CSV.
The default is b'"'
.
Example
use std::error::Error;
use csv::WriterBuilder;
fn example() -> Result<(), Box<dyn Error>> {
let mut wtr = WriterBuilder::new()
.quote(b'\'')
.from_writer(vec![]);
wtr.write_record(&["a", "foo\nbar", "c"])?;
wtr.write_record(&["g'h'i", "y\"y\"y", "z"])?;
let data = String::from_utf8(wtr.into_inner()?)?;
assert_eq!(data, "a,'foo\nbar',c\n'g''h''i',y\"y\"y,z\n");
Ok(())
}
sourcepub fn double_quote(&mut self, yes: bool) -> &mut WriterBuilder
pub fn double_quote(&mut self, yes: bool) -> &mut WriterBuilder
Enable double quote escapes.
This is enabled by default, but it may be disabled. When disabled, quotes in field data are escaped instead of doubled.
Example
use std::error::Error;
use csv::WriterBuilder;
fn example() -> Result<(), Box<dyn Error>> {
let mut wtr = WriterBuilder::new()
.double_quote(false)
.from_writer(vec![]);
wtr.write_record(&["a", "foo\"bar", "c"])?;
wtr.write_record(&["x", "y", "z"])?;
let data = String::from_utf8(wtr.into_inner()?)?;
assert_eq!(data, "a,\"foo\\\"bar\",c\nx,y,z\n");
Ok(())
}
sourcepub fn escape(&mut self, escape: u8) -> &mut WriterBuilder
pub fn escape(&mut self, escape: u8) -> &mut WriterBuilder
The escape character to use when writing CSV.
In some variants of CSV, quotes are escaped using a special escape
character like \
(instead of escaping quotes by doubling them).
By default, writing these idiosyncratic escapes is disabled, and is
only used when double_quote
is disabled.
Example
use std::error::Error;
use csv::WriterBuilder;
fn example() -> Result<(), Box<dyn Error>> {
let mut wtr = WriterBuilder::new()
.double_quote(false)
.escape(b'$')
.from_writer(vec![]);
wtr.write_record(&["a", "foo\"bar", "c"])?;
wtr.write_record(&["x", "y", "z"])?;
let data = String::from_utf8(wtr.into_inner()?)?;
assert_eq!(data, "a,\"foo$\"bar\",c\nx,y,z\n");
Ok(())
}
sourcepub fn comment(&mut self, comment: Option<u8>) -> &mut WriterBuilder
pub fn comment(&mut self, comment: Option<u8>) -> &mut WriterBuilder
The comment character that will be used when later reading the file.
If quote_style
is set to QuoteStyle::Necessary
, a field will
be quoted if the comment character is detected anywhere in the field.
The default value is None.
Example
use std::error::Error;
use csv::WriterBuilder;
fn example() -> Result<(), Box<dyn Error>> {
let mut wtr =
WriterBuilder::new().comment(Some(b'#')).from_writer(Vec::new());
wtr.write_record(&["# comment", "another"]).unwrap();
let buf = wtr.into_inner().unwrap();
assert_eq!(String::from_utf8(buf).unwrap(), "\"# comment\",another\n");
Ok(())
}
sourcepub fn buffer_capacity(&mut self, capacity: usize) -> &mut WriterBuilder
pub fn buffer_capacity(&mut self, capacity: usize) -> &mut WriterBuilder
Set the capacity (in bytes) of the internal buffer used in the CSV writer. This defaults to a reasonable setting.