[−][src]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 |
|
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 |
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 |