Struct csv_async::ByteRecord

pub struct ByteRecord(/* private fields */);

A single CSV record stored as raw bytes.

A byte record permits reading or writing CSV rows that are not UTF-8. In general, you should prefer using a StringRecord since it is more ergonomic, but a ByteRecord is provided in case you need it.

If you are using the Serde (de)serialization APIs, then you probably never need to interact with a ByteRecord or a StringRecord. However, there are some circumstances in which you might need to use a raw record type while still using Serde. For example, if you need to deserialize possibly invalid UTF-8 fields, then you’ll need to first read your record into a ByteRecord, and then use ByteRecord::deserialize to run Serde. Another reason for using the raw record de-serialization APIs is if you’re using Serde to read into borrowed data such as a &'a str or a &'a [u8].

Two ByteRecords are compared on the basis of their field data. Any position information associated with the records is ignored.

Implementations

impl ByteRecord

pub fn new() -> ByteRecord

Create a new empty ByteRecord.

Note that you may find the ByteRecord::from constructor more convenient, which is provided by an impl on the From trait.

Example: create an empty record

use csv_async::ByteRecord;

let record = ByteRecord::new();
assert_eq!(record.len(), 0);

Example: initialize a record from a Vec

use csv_async::ByteRecord;

let record = ByteRecord::from(vec!["a", "b", "c"]);
assert_eq!(record.len(), 3);

pub fn with_capacity(buffer: usize, fields: usize) -> ByteRecord

Create a new empty ByteRecord with the given capacity settings.

buffer refers to the capacity of the buffer used to store the actual row contents. fields refers to the number of fields one might expect to store.

pub fn iter(&self) -> ByteRecordIter<'_>

Returns an iterator over all fields in this record.

Example

This example shows how to iterate over each field in a ByteRecord.

use csv_async::ByteRecord;

let record = ByteRecord::from(vec!["a", "b", "c"]);
for field in record.iter() {
    assert!(field == b"a" || field == b"b" || field == b"c");
}

pub fn get(&self, i: usize) -> Option<&[u8]>

Return the field at index i.

If no field at index i exists, then this returns None.

Example

use csv_async::ByteRecord;

let record = ByteRecord::from(vec!["a", "b", "c"]);
assert_eq!(record.get(1), Some(&b"b"[..]));
assert_eq!(record.get(3), None);

pub fn is_empty(&self) -> bool

Returns true if and only if this record is empty.

Example

use csv_async::ByteRecord;

assert!(ByteRecord::new().is_empty());

pub fn len(&self) -> usize

Returns the number of fields in this record.

Example

use csv_async::ByteRecord;

let record = ByteRecord::from(vec!["a", "b", "c"]);
assert_eq!(record.len(), 3);

pub fn truncate(&mut self, n: usize)

Truncate this record to n fields.

If n is greater than the number of fields in this record, then this has no effect.

Example

use csv_async::ByteRecord;

let mut record = ByteRecord::from(vec!["a", "b", "c"]);
assert_eq!(record.len(), 3);
record.truncate(1);
assert_eq!(record.len(), 1);
assert_eq!(record, vec!["a"]);

pub fn clear(&mut self)

Clear this record so that it has zero fields.

This is equivalent to calling truncate(0).

Note that it is not necessary to clear the record to reuse it with the CSV reader.

Example

use csv_async::ByteRecord;

let mut record = ByteRecord::from(vec!["a", "b", "c"]);
assert_eq!(record.len(), 3);
record.clear();
assert_eq!(record.len(), 0);

pub fn trim(&mut self)

Trim the fields of this record so that leading and trailing whitespace is removed.

This method uses the ASCII definition of whitespace. That is, only bytes in the class [\t\n\v\f\r ] are trimmed.

Example

use csv_async::ByteRecord;

let mut record = ByteRecord::from(vec![
    "  ", "\tfoo", "bar  ", "b a z",
]);
record.trim();
assert_eq!(record, vec!["", "foo", "bar", "b a z"]);

pub fn push_field(&mut self, field: &[u8])

Add a new field to this record.

Example

use csv_async::ByteRecord;

let mut record = ByteRecord::new();
record.push_field(b"foo");
assert_eq!(&record[0], b"foo");

pub fn position(&self) -> Option<&Position>

Return the position of this record, if available.

Example

use std::error::Error;
use futures::stream::{self, StreamExt};
use csv_async::{ByteRecord, AsyncReaderBuilder};

async fn example() -> Result<(), Box<dyn Error>> {
    let mut record = ByteRecord::new();
    let mut rdr = AsyncReaderBuilder::new()
        .has_headers(false)
        .create_reader("a,b,c\nx,y,z".as_bytes());

    assert!(rdr.read_byte_record(&mut record).await?);
    {
        let pos = record.position().expect("a record position");
        assert_eq!(pos.byte(), 0);
        assert_eq!(pos.line(), 1);
        assert_eq!(pos.record(), 0);
    }

    assert!(rdr.read_byte_record(&mut record).await?);
    {
        let pos = record.position().expect("a record position");
        assert_eq!(pos.byte(), 6);
        assert_eq!(pos.line(), 2);
        assert_eq!(pos.record(), 1);
    }

    // Finish the CSV reader for good measure.
    assert!(!rdr.read_byte_record(&mut record).await?);
    Ok(())
}

pub fn set_position(&mut self, pos: Option<Position>)

Set the position of this record.

Example

use csv_async::{ByteRecord, Position};

let mut record = ByteRecord::from(vec!["a", "b", "c"]);
let mut pos = Position::new();
pos.set_byte(100);
pos.set_line(4);
pos.set_record(2);

record.set_position(Some(pos.clone()));
assert_eq!(record.position(), Some(&pos));

pub fn range(&self, i: usize) -> Option<Range<usize>>

Return the start and end position of a field in this record.

If no such field exists at the given index, then return None.

The range returned can be used with the slice returned by as_slice.

Example

use csv_async::ByteRecord;

let record = ByteRecord::from(vec!["foo", "quux", "z"]);
let range = record.range(1).expect("a record range");
assert_eq!(&record.as_slice()[range], &b"quux"[..]);

pub fn as_slice(&self) -> &[u8]

Return the entire row as a single byte slice. The slice returned stores all fields contiguously. The boundaries of each field can be determined via the range method.

Example

use csv_async::ByteRecord;

let record = ByteRecord::from(vec!["foo", "quux", "z"]);
assert_eq!(record.as_slice(), &b"fooquuxz"[..]);

pub fn deserialize<'de, D: Deserialize<'de>>( &'de self, headers: Option<&'de ByteRecord> ) -> Result<D>

Deserialize this record.

The D type parameter refers to the type that this record should be deserialized into. The 'de lifetime refers to the lifetime of the ByteRecord. The 'de lifetime permits deserializing into structs that borrow field data from this record.

An optional headers parameter permits deserializing into a struct based on its field names (corresponding to header values) rather than the order in which the fields are defined.

Example: without headers

This shows how to deserialize a single row into a struct based on the order in which fields occur. This example also shows how to borrow fields from the ByteRecord, which results in zero allocation deserialization.

use std::error::Error;

use csv_async::ByteRecord;
use serde::Deserialize;

#[derive(Deserialize)]
struct Row<'a> {
    city: &'a str,
    country: &'a str,
    population: u64,
}

fn example() -> Result<(), Box<dyn Error>> {
    let record = ByteRecord::from(vec![
        "Boston", "United States", "4628910",
    ]);

    let row: Row = record.deserialize(None)?;
    assert_eq!(row.city, "Boston");
    assert_eq!(row.country, "United States");
    assert_eq!(row.population, 4628910);
    Ok(())
}

Example: with headers

This example is like the previous one, but shows how to deserialize into a struct based on the struct’s field names. For this to work, you must provide a header row.

This example also shows that you can deserialize into owned data types (e.g., String) instead of borrowed data types (e.g., &str).

use std::error::Error;

use csv_async::ByteRecord;
use serde::Deserialize;

#[derive(Deserialize)]
struct Row {
    city: String,
    country: String,
    population: u64,
}

fn example() -> Result<(), Box<dyn Error>> {
    // Notice that the fields are not in the same order
    // as the fields in the struct!
    let header = ByteRecord::from(vec![
        "country", "city", "population",
    ]);
    let record = ByteRecord::from(vec![
        "United States", "Boston", "4628910",
    ]);

    let row: Row = record.deserialize(Some(&header))?;
    assert_eq!(row.city, "Boston");
    assert_eq!(row.country, "United States");
    assert_eq!(row.population, 4628910);
    Ok(())
}

Trait Implementations

impl Clone for ByteRecord

fn clone(&self) -> ByteRecord

Clone this record, but only copy fields up to the end of bounds. This is useful when one wants to copy a record, but not necessarily any excess capacity in that record.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ByteRecord

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for ByteRecord

fn default() -> ByteRecord

Returns the “default value” for a type.

impl<T: AsRef<[u8]>> Extend<T> for ByteRecord

fn extend<I: IntoIterator<Item = T>>(&mut self, iter: I)

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

🔬This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl<'a, T: AsRef<[u8]>> From<&'a [T]> for ByteRecord

fn from(xs: &'a [T]) -> ByteRecord

Converts to this type from the input type.

impl From<StringRecord> for ByteRecord

fn from(record: StringRecord) -> ByteRecord

Converts to this type from the input type.

impl<T: AsRef<[u8]>> From<Vec<T>> for ByteRecord

fn from(xs: Vec<T>) -> ByteRecord

Converts to this type from the input type.

impl<T: AsRef<[u8]>> FromIterator<T> for ByteRecord

fn from_iter<I: IntoIterator<Item = T>>(iter: I) -> ByteRecord

Creates a value from an iterator.

impl Index<usize> for ByteRecord

type Output = [u8]

The returned type after indexing.

fn index(&self, i: usize) -> &[u8]

Performs the indexing (container[index]) operation.

impl<'r> IntoIterator for &'r ByteRecord

type IntoIter = ByteRecordIter<'r>

Which kind of iterator are we turning this into?

type Item = &'r [u8]

The type of the elements being iterated over.

fn into_iter(self) -> ByteRecordIter<'r>

Creates an iterator from a value.

impl<'a, T: AsRef<[u8]>> PartialEq<[T]> for &'a ByteRecord

fn eq(&self, other: &[T]) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T: AsRef<[u8]>> PartialEq<[T]> for ByteRecord

fn eq(&self, other: &[T]) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'a, T: AsRef<[u8]>> PartialEq<Vec<T>> for &'a ByteRecord

fn eq(&self, other: &Vec<T>) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T: AsRef<[u8]>> PartialEq<Vec<T>> for ByteRecord

fn eq(&self, other: &Vec<T>) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq for ByteRecord

fn eq(&self, other: &ByteRecord) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Eq for ByteRecord