Crate csv_async

The csv-async crate provides a fast and flexible CSV reader and writer, which is intended to be run in asynchronous environment - i.e. inside functions with async attribute called by tasks run by executor. This library does not imply using any particular executor (is executor agnostic). Unit tests and documentation snippets uses async-std crate. Synchronous interface for reading and writing CSV files is not contained in this crate, please use csv crate for this. This crate attempts to closely mimic csv crate API.

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

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

Brief overview

The primary types in this crate are AsyncReader and AsyncWriter, 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 AsyncReaderBuilder or a AsyncWriterBuilder, depending on whether you're reading or writing CSV data.

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-async = "1.0.0"
# or
# csv-async = {version = "1.0.0", features = ["tokio"]}

Example

This example shows how to read and write CSV file in asynchronous context and get into some record details.

Sample input file:

city,region,country,population
Southborough,MA,United States,9686
Northbridge,MA,United States,14061
Marlborough,MA,United States,38334
Springfield,MA,United States,152227
Springfield,MO,United States,150443
Springfield,NJ,United States,14976
Concord,NH,United States,42605

use std::error::Error;
use std::process;
#[cfg(not(feature = "tokio"))]
use futures::stream::StreamExt;
#[cfg(not(feature = "tokio"))]
use async_std::fs::File;
#[cfg(feature = "tokio")]
use tokio::stream::StreamExt;
#[cfg(feature = "tokio")]
use tokio::fs::File;

async fn filter_by_region(region:&str, file_in:&str, file_out:&str) -> Result<(), Box<dyn Error>> {
    // Function reads CSV file that has column named "region"
    // at second position (index = 1).
    // It writes to new file only rows with region equal to passed argument
    // and remove region column.
    let mut rdr = csv_async::AsyncReader::from_reader(
        File::open(file_in).await?
    );
    let mut wri = csv_async::AsyncWriter::from_writer(
        File::create(file_out).await?
    );
    wri.write_record(rdr
        .headers()
        .await?.into_iter()
        .filter(|h| *h != "region")
    ).await?;
    let mut records = rdr.records();
    while let Some(record) = records.next().await {
        let record = record?;
        match record.get(1) {
            Some(reg) if reg == region => 
                wri.write_record(record
                    .iter()
                    .enumerate()
                    .filter(|(i, _)| *i != 1)
                    .map(|(_, s)| s)
                ).await?,
            _ => {},
        }
    }
    Ok(())
}

#[cfg(not(feature = "tokio"))]
fn main() {
    async_std::task::block_on(async {
        if let Err(err) = filter_by_region(
            "MA",
            "/tmp/all_regions.csv",
            "/tmp/MA_only.csv"
        ).await {
            println!("error running filter_by_region: {}", err);
            process::exit(1);
        }
    });
}

#[cfg(feature = "tokio")]
fn main() {
    tokio::runtime::Runtime::new().unwrap().block_on(async {
        if let Err(err) = filter_by_region(
            "MA",
            "/tmp/all_regions.csv",
            "/tmp/MA_only.csv"
        ).await {
            println!("error running filter_by_region: {}", err);
            process::exit(1);
        }
    });
}

TODO: There are more examples in the cookbook.

Structs

AsyncReader	A already configured CSV reader.
AsyncReaderBuilder	Builds a CSV reader with various configuration knobs.
AsyncWriter	A already configured CSV writer.
AsyncWriterBuilder	Builds a CSV writer with various configuration knobs.
ByteRecord	A single CSV record stored as raw bytes.
ByteRecordIter	A double-ended iterator over the fields in a byte record.
ByteRecordsIntoStream	An owned iterator over records as raw bytes.
ByteRecordsStream	A borrowed iterator over records as raw bytes.
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.
StringRecord	A single CSV record stored as valid UTF-8 bytes.
StringRecordIter	An iterator over the fields in a string record.
StringRecordsIntoStream	An owned iterator over records as strings. The lifetime parameter 'r refers to the lifetime of the underlying CSV Reader.
StringRecordsStream	A borrowed iterator over records as strings.
Utf8Error	A UTF-8 validation error.

Enums

ErrorKind	The specific type of an error.
QuoteStyle	The quoting style to use when writing CSV data.
Terminator	A record terminator.
Trim	The whitespace preservation behavior when reading CSV data.

Type Definitions

Result

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