Struct csv::Writer

pub struct Writer<W: Write> {
    // some fields omitted
}

A CSV writer.

This writer provides a convenient interface for encoding CSV data. While creating CSV data is much easier than parsing it, having a writer can be convenient because it can handle quoting for you automatically. Moreover, this particular writer supports Encodable types, which makes it easy to write your custom types as CSV records.

All CSV data produced by this writer, with default options, conforms with RFC 4180. (If certain options like flexible record lengths are enabled, then compliance with RFC 4180 cannot be guaranteed.)

One slight deviation is that records with a single empty field are always encoded as "". This ensures that the record is not skipped since some CSV parsers will ignore consecutive record terminators (like the one in this crate).

Example

Here's an example that encodes word pairs and their edit distances:

let records = vec![
    ("sticker", "mortals", 7),
    ("bribed", "personae", 7),
    ("wobbling", "poncing", 4),
    ("interposed", "emmett", 9),
    ("chocolate", "refile", 7),
];

let mut wtr = csv::Writer::from_memory();
for record in records.into_iter() {
    let result = wtr.encode(record);
    assert!(result.is_ok());
}

Methods

impl Writer<File>

fn from_file<P: AsRef<Path>>(path: P) -> Result<Writer<File>>

Creates a new Writer that writes CSV data to the file path given.

The file is created if it does not already exist and is truncated otherwise.

impl<W: Write> Writer<W>

fn from_writer(w: W) -> Writer<W>

Creates a new CSV writer that writes to the io::Write given.

Note that the writer is buffered for you automatically.

fn from_buffer(buf: BufWriter<W>) -> Writer<W>

Creates a new CSV writer that writes to the buffer given.

This lets you specify your own buffered writer (e.g., use a different capacity). All other constructors wrap the writer given in a buffer with default capacity.

impl Writer<Vec<u8>>

fn from_memory() -> Writer<Vec<u8>>

Creates a new CSV writer that writes to an in memory buffer. At any time, as_string or as_bytes can be called to retrieve the cumulative CSV data.

fn as_string<'r>(&'r mut self) -> &'r str

Returns the written CSV data as a string.

fn as_bytes<'r>(&'r mut self) -> &'r [u8]

Returns the encoded CSV data as raw bytes.

fn into_string(self) -> String

Convert the Writer into a string of written CSV data

fn into_bytes(self) -> Vec<u8>

Convert the Writer into a vector of encoded CSV bytes.

impl<W: Write> Writer<W>

fn encode<E>(&mut self, e: E) -> Result<()> where E: Encodable

Writes a record by encoding any Encodable value.

This is the most convenient way to write CSV data. Most Rust types map to CSV data in a straight forward way. A vector is just a sequence of fields. Similarly for a struct. Enumerations of zero or one arguments are supported too. (Enums with zero arguments encode to their name, while enums of one argument encode to their constituent value.) Option types are also supported (None encodes to an empty field).

Example

This example encodes word pairs that may or may not have their edit distances computed.

extern crate rustc_serialize;

#[derive(RustcEncodable)]
struct Distance {
    name1: &'static str,
    name2: &'static str,
    dist: Option<usize>,
}

let records = vec![
    Distance { name1: "sticker", name2: "mortals", dist: None },
    Distance { name1: "bribed", name2: "personae", dist: Some(7) },
];

let mut wtr = csv::Writer::from_memory();
for record in records.into_iter() {
    let result = wtr.encode(record);
    assert!(result.is_ok());
}
assert_eq!(wtr.as_string(),
           "sticker,mortals,\nbribed,personae,7\n");

fn write<'a, I>(&mut self, r: I) -> Result<()> where I: Iterator, I::Item: BorrowBytes

Writes a record of strings (Unicode or raw bytes).

This is meant to be the standard method provided by most CSV writers. That is, it writes a record of strings---no more and no less.

This method accepts an iterator of fields for a single record. Each field must satisfy BorrowBytes, which allows the caller to control allocation.

Example

This shows how to write string records.

let records = vec![
    vec!["sticker", "mortals", "7"],
    vec!["bribed", "personae", "7"],
    vec!["wobbling", "poncing", "4"],
    vec!["interposed", "emmett", "9"],
    vec!["chocolate", "refile", "7"],
];

let mut wtr = csv::Writer::from_memory();
for record in records.into_iter() {
    let result = wtr.write(record.into_iter());
    assert!(result.is_ok());
}

This shows how to write records that do not correspond to a valid UTF-8 encoding. (Note the use of Rust's byte string syntax!)

let mut wtr = csv::Writer::from_memory();
let result = wtr.write(vec![&b"\xff"[..], &b"\x00"[..]].into_iter());
assert!(result.is_ok());

assert_eq!(wtr.as_bytes(), b"\xff,\x00\n");

fn flush(&mut self) -> Result<()>

Flushes the underlying buffer.

impl<W: Write> Writer<W>

fn delimiter(self, delimiter: u8) -> Writer<W>

The delimiter to use when writing CSV data.

Since the CSV writer is meant to be mostly encoding agnostic, you must specify the delimiter as a single ASCII byte. For example, to write tab-delimited data, you would use b'\t'.

The default value is b','.

fn flexible(self, yes: bool) -> Writer<W>

Whether to allow flexible length records when writing CSV data.

When this is set to true, records in the CSV data can have different lengths. By default, this is disabled, which will cause the CSV writer to return an error if it tries to write a record that has a different length than other records it has already written.

fn record_terminator(self, term: RecordTerminator) -> Writer<W>

Sets the record terminator to use when writing CSV data.

By default, this is RecordTerminator::Any(b'\n'). If you want to use CRLF (\r\n) line endings, then use RecordTerminator:CRLF.

fn quote_style(self, style: QuoteStyle) -> Writer<W>

Set the quoting style to use when writing CSV data.

By default, this is set to QuoteStyle::Necessary, which will only use quotes when they are necessary to preserve the integrity of data.

fn quote(self, quote: u8) -> Writer<W>

Set the quote character to use when writing CSV data.

Since the CSV parser is meant to be mostly encoding agnostic, you must specify the quote as a single ASCII byte. For example, to write single quoted data, you would use b'\''.

The default value is b'"'.

fn escape(self, escape: u8) -> Writer<W>

Set the escape character to use when writing CSV data.

This is only used when double_quote is set to false.

Since the CSV parser is meant to be mostly encoding agnostic, you must specify the escape as a single ASCII byte.

The default value is b'\\'.

fn double_quote(self, yes: bool) -> Writer<W>

Set the quoting escape mechanism.

When enabled (which is the default), quotes are escaped by doubling them. e.g., " escapes to "".

When disabled, quotes are escaped with the escape character (which is \\ by default).