Struct csv::ReaderBuilder [] [src]

pub struct ReaderBuilder { /* fields omitted */ }

Builds a CSV reader with various configuration knobs.

This builder can be used to tweak the field delimiter, record terminator and more. Once a CSV Reader is built, its configuration cannot be changed.

Methods

impl ReaderBuilder
[src]

Create a new builder for configuring CSV parsing.

To convert a builder into a reader, call one of the methods starting with from_.

# Example

extern crate csv;

 use std::error::Error;
 use csv::{ReaderBuilder, StringRecord};

 fn example() -> Result<(), Box<Error>> {
     let data = "\
city,country,pop
Boston,United States,4628910
Concord,United States,42695
";
     let mut rdr = ReaderBuilder::new().from_reader(data.as_bytes());

     let records = rdr
         .records()
         .collect::<Result<Vec<StringRecord>, csv::Error>>()?;
     assert_eq!(records, vec![
         vec!["Boston", "United States", "4628910"],
         vec!["Concord", "United States", "42695"],
     ]);
     Ok(())
 }

Build a CSV parser from this configuration that reads data from the given file path.

If there was a problem opening the file at the given path, then this returns the corresponding error.

Example

extern crate csv;

use std::error::Error;
use csv::ReaderBuilder;

fn example() -> Result<(), Box<Error>> {
    let mut rdr = ReaderBuilder::new().from_path("foo.csv")?;
    for result in rdr.records() {
        let record = result?;
        println!("{:?}", record);
    }
    Ok(())
}

Build a CSV parser from this configuration that reads data from rdr.

Note that the CSV reader is buffered automatically, so you should not wrap rdr in a buffered reader like io::BufReader.

# Example

extern crate csv;

 use std::error::Error;
 use csv::ReaderBuilder;

 fn example() -> Result<(), Box<Error>> {
     let data = "\
city,country,pop
Boston,United States,4628910
Concord,United States,42695
";
     let mut rdr = ReaderBuilder::new().from_reader(data.as_bytes());
     for result in rdr.records() {
         let record = result?;
         println!("{:?}", record);
     }
     Ok(())
 }

The field delimiter to use when parsing CSV.

The default is b','.

# Example

extern crate csv;

 use std::error::Error;
 use csv::ReaderBuilder;

 fn example() -> Result<(), Box<Error>> {
     let data = "\
city;country;pop
Boston;United States;4628910
";
     let mut rdr = ReaderBuilder::new()
         .delimiter(b';')
         .from_reader(data.as_bytes());

     if let Some(result) = rdr.records().next() {
         let record = result?;
         assert_eq!(record, vec!["Boston", "United States", "4628910"]);
         Ok(())
     } else {
         Err(From::from("expected at least one record but got none"))
     }
 }

Whether to treat the first row as a special header row.

By default, the first row is treated as a special header row, which means the header is never returned by any of the record reading methods or iterators. When this is disabled (yes set to false), the first row is not treated specially.

Note that the headers and byte_headers methods are unaffected by whether this is set. Those methods always return the first record.

# Example

This example shows what happens when has_headers is disabled. Namely, the first row is treated just like any other row.

extern crate csv;

 use std::error::Error;
 use csv::ReaderBuilder;

 fn example() -> Result<(), Box<Error>> {
     let data = "\
city,country,pop
Boston,United States,4628910
";
     let mut rdr = ReaderBuilder::new()
         .has_headers(false)
         .from_reader(data.as_bytes());
     let mut iter = rdr.records();

     // Read the first record.
     if let Some(result) = iter.next() {
         let record = result?;
         assert_eq!(record, vec!["city", "country", "pop"]);
     } else {
         return Err(From::from(
             "expected at least two records but got none"));
     }

     // Read the second record.
     if let Some(result) = iter.next() {
         let record = result?;
         assert_eq!(record, vec!["Boston", "United States", "4628910"]);
     } else {
         return Err(From::from(
             "expected at least two records but got one"))
     }
     Ok(())
 }

Whether the number of fields in records is allowed to change or not.

When disabled (which is the default), parsing CSV data will return an error if a record is found with a number of fields different from the number of fields in a previous record.

When enabled, this error checking is turned off.

# Example: flexible records enabled

extern crate csv;

 use std::error::Error;
 use csv::ReaderBuilder;

 fn example() -> Result<(), Box<Error>> {
     // Notice that the first row is missing the population count.
     let data = "\
city,country,pop
Boston,United States
";
     let mut rdr = ReaderBuilder::new()
         .flexible(true)
         .from_reader(data.as_bytes());

     if let Some(result) = rdr.records().next() {
         let record = result?;
         assert_eq!(record, vec!["Boston", "United States"]);
         Ok(())
     } else {
         Err(From::from("expected at least one record but got none"))
     }
 }

# Example: flexible records disabled

This shows the error that appears when records of unequal length are found and flexible records have been disabled (which is the default).

extern crate csv;

 use std::error::Error;
 use csv::{ErrorKind, ReaderBuilder};

 fn example() -> Result<(), Box<Error>> {
     // Notice that the first row is missing the population count.
     let data = "\
city,country,pop
Boston,United States
";
     let mut rdr = ReaderBuilder::new()
         .flexible(false)
         .from_reader(data.as_bytes());

     if let Some(Err(err)) = rdr.records().next() {
         match *err.kind() {
             ErrorKind::UnequalLengths { expected_len, len, .. } => {
                 // The header row has 3 fields...
                 assert_eq!(expected_len, 3);
                 // ... but the first row has only 2 fields.
                 assert_eq!(len, 2);
                 Ok(())
             }
             ref wrong => {
                 Err(From::from(format!(
                     "expected UnequalLengths error but got {:?}",
                     wrong)))
             }
         }
     } else {
         Err(From::from(
             "expected at least one errored record but got none"))
     }
 }

The record terminator to use when parsing CSV.

A record terminator can be any single byte. The default is a special value, Terminator::CRLF, which treats any occurrence of \r, \n or \r\n as a single record terminator.

Example: $ as a record terminator

extern crate csv;

use std::error::Error;
use csv::{ReaderBuilder, Terminator};

fn example() -> Result<(), Box<Error>> {
    let data = "city,country,pop$Boston,United States,4628910";
    let mut rdr = ReaderBuilder::new()
        .terminator(Terminator::Any(b'$'))
        .from_reader(data.as_bytes());

    if let Some(result) = rdr.records().next() {
        let record = result?;
        assert_eq!(record, vec!["Boston", "United States", "4628910"]);
        Ok(())
    } else {
        Err(From::from("expected at least one record but got none"))
    }
}

The quote character to use when parsing CSV.

The default is b'"'.

# Example: single quotes instead of double quotes

extern crate csv;

 use std::error::Error;
 use csv::ReaderBuilder;

 fn example() -> Result<(), Box<Error>> {
     let data = "\
city,country,pop
Boston,'United States',4628910
";
     let mut rdr = ReaderBuilder::new()
         .quote(b'\'')
         .from_reader(data.as_bytes());

     if let Some(result) = rdr.records().next() {
         let record = result?;
         assert_eq!(record, vec!["Boston", "United States", "4628910"]);
         Ok(())
     } else {
         Err(From::from("expected at least one record but got none"))
     }
 }

The escape character to use when parsing CSV.

In some variants of CSV, quotes are escaped using a special escape character like \ (instead of escaping quotes by doubling them).

By default, recognizing these idiosyncratic escapes is disabled.

# Example

extern crate csv;

 use std::error::Error;
 use csv::ReaderBuilder;

 fn example() -> Result<(), Box<Error>> {
     let data = "\
city,country,pop
Boston,\"The \\\"United\\\" States\",4628910
";
     let mut rdr = ReaderBuilder::new()
         .escape(Some(b'\\'))
         .from_reader(data.as_bytes());

     if let Some(result) = rdr.records().next() {
         let record = result?;
         assert_eq!(record, vec![
             "Boston", "The \"United\" States", "4628910",
         ]);
         Ok(())
     } else {
         Err(From::from("expected at least one record but got none"))
     }
 }

Enable double quote escapes.

This is enabled by default, but it may be disabled. When disabled, doubled quotes are not interpreted as escapes.

# Example

extern crate csv;

 use std::error::Error;
 use csv::ReaderBuilder;

 fn example() -> Result<(), Box<Error>> {
     let data = "\
city,country,pop
Boston,\"The \"\"United\"\" States\",4628910
";
     let mut rdr = ReaderBuilder::new()
         .double_quote(false)
         .from_reader(data.as_bytes());

     if let Some(result) = rdr.records().next() {
         let record = result?;
         assert_eq!(record, vec![
             "Boston", "The \"United\"\" States\"", "4628910",
         ]);
         Ok(())
     } else {
         Err(From::from("expected at least one record but got none"))
     }
 }

The comment character to use when parsing CSV.

If the start of a record begins with the byte given here, then that line is ignored by the CSV parser.

This is disabled by default.

# Example

extern crate csv;

 use std::error::Error;
 use csv::ReaderBuilder;

 fn example() -> Result<(), Box<Error>> {
     let data = "\
city,country,pop
#Concord,United States,42695
Boston,United States,4628910
";
     let mut rdr = ReaderBuilder::new()
         .comment(Some(b'#'))
         .from_reader(data.as_bytes());

     if let Some(result) = rdr.records().next() {
         let record = result?;
         assert_eq!(record, vec!["Boston", "United States", "4628910"]);
         Ok(())
     } else {
         Err(From::from("expected at least one record but got none"))
     }
 }

A convenience method for specifying a configuration to read ASCII delimited text.

This sets the delimiter and record terminator to the ASCII unit separator (\x1F) and record separator (\x1E), respectively.

# Example

extern crate csv;

 use std::error::Error;
 use csv::ReaderBuilder;

 fn example() -> Result<(), Box<Error>> {
     let data = "\
city\x1Fcountry\x1Fpop\x1EBoston\x1FUnited States\x1F4628910";
     let mut rdr = ReaderBuilder::new()
         .ascii()
         .from_reader(data.as_bytes());

     if let Some(result) = rdr.records().next() {
         let record = result?;
         assert_eq!(record, vec!["Boston", "United States", "4628910"]);
         Ok(())
     } else {
         Err(From::from("expected at least one record but got none"))
     }
 }

Set the capacity (in bytes) of the buffer used in the CSV reader. This defaults to a reasonable setting.

Trait Implementations

impl Debug for ReaderBuilder
[src]

Formats the value using the given formatter.

impl Default for ReaderBuilder
[src]

Returns the "default value" for a type. Read more