Crate csv [] [src]

The csv crate provides a fast and flexible CSV reader and writer, with support for Serde.

The tutorial is a good place to start if you're new to Rust.

The cookbook will give you a variety of complete Rust programs that do CSV reading and writing.

Brief overview

If you're new to Rust, you might find the tutorial to be a good place to start.

The primary types in this crate are Reader and Writer, for reading and writing CSV data respectively. Correspondingly, to support CSV data with custom field or record delimiters (among many other things), you should use either a ReaderBuilder or a WriterBuilder, depending on whether you're reading or writing CSV data.

Unless you're using Serde, the standard CSV record types are StringRecord and ByteRecord. StringRecord should be used when you know your data to be valid UTF-8. For data that may be invalid UTF-8, ByteRecord is suitable.

Finally, the set of errors is described by the Error type.

The rest of the types in this crate mostly correspond to more detailed errors, position information, configuration knobs or iterator types.

Setup

Add this to your Cargo.toml:

[dependencies]
csv = "1.0.0-beta.3"

and this to your crate root:

extern crate csv;

If you want to use Serde's custom derive functionality on your custom structs, then add this to your [dependencies] section of Cargo.toml:

[dependencies]
serde = "1"
serde_derive = "1"

and this to your crate root:

extern crate serde;
#[macro_use]
extern crate serde_derive;

Example

This example shows how to read CSV data from stdin and print each record to stdout.

There are more examples in the cookbook.

extern crate csv;

use std::error::Error;
use std::io;
use std::process;

fn example() -> Result<(), Box<Error>> {
    // Build the CSV reader and iterate over each record.
    let mut rdr = csv::Reader::from_reader(io::stdin());
    for result in rdr.records() {
        // The iterator yields Result<StringRecord, Error>, so we check the
        // error here.
        let record = result?;
        println!("{:?}", record);
    }
    Ok(())
}

fn main() {
    if let Err(err) = example() {
        println!("error running example: {}", err);
        process::exit(1);
    }
}

The above example can be run like so:

$ git clone git://github.com/BurntSushi/rust-csv
$ cd rust-csv
$ cargo run --example cookbook-read-basic < examples/data/smallpop.csv

Example with Serde

This example shows how to read CSV data from stdin into your own custom struct. By default, the member names of the struct are matched with the values in the header record of your CSV data.

extern crate csv;
#[macro_use]
extern crate serde_derive;

use std::error::Error;
use std::io;
use std::process;

#[derive(Debug,Deserialize)]
struct Record {
    city: String,
    region: String,
    country: String,
    population: Option<u64>,
}

fn example() -> Result<(), Box<Error>> {
    let mut rdr = csv::Reader::from_reader(io::stdin());
    for result in rdr.deserialize() {
        // Notice that we need to provide a type hint for automatic
        // deserialization.
        let record: Record = result?;
        println!("{:?}", record);
    }
    Ok(())
}

fn main() {
    if let Err(err) = example() {
        println!("error running example: {}", err);
        process::exit(1);
    }
}

The above example can be run like so:

$ git clone git://github.com/BurntSushi/rust-csv
$ cd rust-csv
$ cargo run --example cookbook-read-serde < examples/data/smallpop.csv

Modules

cookbook

A cookbook of examples for CSV reading and writing.

tutorial

A tutorial for handling CSV data in Rust.

Structs

ByteRecord

A single CSV record stored as raw bytes.

ByteRecordIter

A double-ended iterator over the fields in a byte record.

ByteRecordsIntoIter

An owned iterator over records as raw bytes.

ByteRecordsIter

A borrowed iterator over records as raw bytes.

DeserializeError

An Serde deserialization error.

DeserializeRecordsIntoIter

An owned iterator over deserialized records.

DeserializeRecordsIter

A borrowed iterator over deserialized records.

Error

An error that can occur when processing CSV data.

FromUtf8Error

A UTF-8 validation error during record conversion.

IntoInnerError

IntoInnerError occurs when consuming a Writer fails.

Position

A position in CSV data.

Reader

A already configured CSV reader.

ReaderBuilder

Builds a CSV reader with various configuration knobs.

StringRecord

A single CSV record stored as valid UTF-8 bytes.

StringRecordIter

An iterator over the fields in a string record.

StringRecordsIntoIter

An owned iterator over records as strings.

StringRecordsIter

A borrowed iterator over records as strings.

Utf8Error

A UTF-8 validation error.

Writer

A already configured CSV writer.

WriterBuilder

Builds a CSV writer with various configuration knobs.

Enums

DeserializeErrorKind

The type of a Serde deserialization error.

ErrorKind

The specific type of an error.

QuoteStyle

The quoting style to use when writing CSV data.

Terminator

A record terminator.

Functions

invalid_option

A custom Serde deserializer for possibly invalid Option<T> fields.

Type Definitions

Result

A type alias for Result<T, csv::Error>.