Struct csv::ByteRecord
source · pub struct ByteRecord(/* private fields */);
Expand description
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 deserialization APIs is if you’re using
Serde to read into borrowed data such as a &'a str
or a &'a [u8]
.
Two ByteRecord
s are compared on the basis of their field data. Any
position information associated with the records is ignored.
Implementations§
source§impl ByteRecord
impl ByteRecord
sourcepub fn new() -> 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::ByteRecord;
let record = ByteRecord::new();
assert_eq!(record.len(), 0);
§Example: initialize a record from a Vec
use csv::ByteRecord;
let record = ByteRecord::from(vec!["a", "b", "c"]);
assert_eq!(record.len(), 3);
sourcepub fn with_capacity(buffer: usize, fields: usize) -> ByteRecord
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.
sourcepub fn deserialize<'de, D: Deserialize<'de>>(
&'de self,
headers: Option<&'de ByteRecord>,
) -> Result<D>
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::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::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(())
}
sourcepub fn iter(&self) -> ByteRecordIter<'_> ⓘ
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::ByteRecord;
let record = ByteRecord::from(vec!["a", "b", "c"]);
for field in record.iter() {
assert!(field == b"a" || field == b"b" || field == b"c");
}
sourcepub fn get(&self, i: usize) -> Option<&[u8]>
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::ByteRecord;
let record = ByteRecord::from(vec!["a", "b", "c"]);
assert_eq!(record.get(1), Some(&b"b"[..]));
assert_eq!(record.get(3), None);
sourcepub fn is_empty(&self) -> bool
pub fn is_empty(&self) -> bool
Returns true if and only if this record is empty.
§Example
use csv::ByteRecord;
assert!(ByteRecord::new().is_empty());
sourcepub fn len(&self) -> usize
pub fn len(&self) -> usize
Returns the number of fields in this record.
§Example
use csv::ByteRecord;
let record = ByteRecord::from(vec!["a", "b", "c"]);
assert_eq!(record.len(), 3);
sourcepub fn truncate(&mut self, n: usize)
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::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"]);
sourcepub fn clear(&mut self)
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::ByteRecord;
let mut record = ByteRecord::from(vec!["a", "b", "c"]);
assert_eq!(record.len(), 3);
record.clear();
assert_eq!(record.len(), 0);
sourcepub fn trim(&mut self)
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::ByteRecord;
let mut record = ByteRecord::from(vec![
" ", "\tfoo", "bar ", "b a z",
]);
record.trim();
assert_eq!(record, vec!["", "foo", "bar", "b a z"]);
sourcepub fn push_field(&mut self, field: &[u8])
pub fn push_field(&mut self, field: &[u8])
Add a new field to this record.
§Example
use csv::ByteRecord;
let mut record = ByteRecord::new();
record.push_field(b"foo");
assert_eq!(&record[0], b"foo");
sourcepub fn position(&self) -> Option<&Position>
pub fn position(&self) -> Option<&Position>
Return the position of this record, if available.
§Example
use std::error::Error;
use csv::{ByteRecord, ReaderBuilder};
fn example() -> Result<(), Box<dyn Error>> {
let mut record = ByteRecord::new();
let mut rdr = ReaderBuilder::new()
.has_headers(false)
.from_reader("a,b,c\nx,y,z".as_bytes());
assert!(rdr.read_byte_record(&mut record)?);
{
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)?);
{
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)?);
Ok(())
}
sourcepub fn set_position(&mut self, pos: Option<Position>)
pub fn set_position(&mut self, pos: Option<Position>)
Set the position of this record.
§Example
use csv::{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));
sourcepub fn range(&self, i: usize) -> Option<Range<usize>>
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::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"[..]);
sourcepub fn as_slice(&self) -> &[u8] ⓘ
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::ByteRecord;
let record = ByteRecord::from(vec!["foo", "quux", "z"]);
assert_eq!(record.as_slice(), &b"fooquuxz"[..]);
Trait Implementations§
source§impl Clone for ByteRecord
impl Clone for ByteRecord
source§fn clone(&self) -> ByteRecord
fn clone(&self) -> ByteRecord
1.0.0 · source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source
. Read moresource§impl Debug for ByteRecord
impl Debug for ByteRecord
source§impl Default for ByteRecord
impl Default for ByteRecord
source§fn default() -> ByteRecord
fn default() -> ByteRecord
source§impl<T: AsRef<[u8]>> Extend<T> for ByteRecord
impl<T: AsRef<[u8]>> Extend<T> for ByteRecord
source§fn extend<I: IntoIterator<Item = T>>(&mut self, iter: I)
fn extend<I: IntoIterator<Item = T>>(&mut self, iter: I)
source§fn extend_one(&mut self, item: A)
fn extend_one(&mut self, item: A)
extend_one
)source§fn extend_reserve(&mut self, additional: usize)
fn extend_reserve(&mut self, additional: usize)
extend_one
)source§impl<'a, T: AsRef<[u8]>> From<&'a [T]> for ByteRecord
impl<'a, T: AsRef<[u8]>> From<&'a [T]> for ByteRecord
source§fn from(xs: &'a [T]) -> ByteRecord
fn from(xs: &'a [T]) -> ByteRecord
source§impl From<StringRecord> for ByteRecord
impl From<StringRecord> for ByteRecord
source§fn from(record: StringRecord) -> ByteRecord
fn from(record: StringRecord) -> ByteRecord
source§impl<T: AsRef<[u8]>> From<Vec<T>> for ByteRecord
impl<T: AsRef<[u8]>> From<Vec<T>> for ByteRecord
source§fn from(xs: Vec<T>) -> ByteRecord
fn from(xs: Vec<T>) -> ByteRecord
source§impl<T: AsRef<[u8]>> FromIterator<T> for ByteRecord
impl<T: AsRef<[u8]>> FromIterator<T> for ByteRecord
source§fn from_iter<I: IntoIterator<Item = T>>(iter: I) -> ByteRecord
fn from_iter<I: IntoIterator<Item = T>>(iter: I) -> ByteRecord
source§impl Index<usize> for ByteRecord
impl Index<usize> for ByteRecord
source§impl<'r> IntoIterator for &'r ByteRecord
impl<'r> IntoIterator for &'r ByteRecord
source§impl<'a, T: AsRef<[u8]>> PartialEq<Vec<T>> for &'a ByteRecord
impl<'a, T: AsRef<[u8]>> PartialEq<Vec<T>> for &'a ByteRecord
source§impl<T: AsRef<[u8]>> PartialEq<Vec<T>> for ByteRecord
impl<T: AsRef<[u8]>> PartialEq<Vec<T>> for ByteRecord
source§impl PartialEq for ByteRecord
impl PartialEq for ByteRecord
source§fn eq(&self, other: &ByteRecord) -> bool
fn eq(&self, other: &ByteRecord) -> bool
self
and other
values to be equal, and is used
by ==
.impl Eq for ByteRecord
Auto Trait Implementations§
impl Freeze for ByteRecord
impl RefUnwindSafe for ByteRecord
impl Send for ByteRecord
impl Sync for ByteRecord
impl Unpin for ByteRecord
impl UnwindSafe for ByteRecord
Blanket Implementations§
source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
source§default unsafe fn clone_to_uninit(&self, dst: *mut T)
default unsafe fn clone_to_uninit(&self, dst: *mut T)
clone_to_uninit
)