Struct csv::StringRecord
[−]
[src]
pub struct StringRecord(_);
A single CSV record stored as valid UTF-8 bytes.
A string record permits reading or writing CSV rows that are valid UTF-8.
If string records are used to read CSV data that is not valid UTF-8, then
the CSV reader will return an invalid UTF-8 error. If you do need to read
possibly invalid UTF-8 data, then you should prefer using a
ByteRecord
,
since it makes no assumptions about UTF-8.
If you are using the Serde (de)serialization APIs, then you probably never
need to interact with a ByteRecord
or a StringRecord
.
Two StringRecord
s are compared on the basis of their field data. Any
position information associated with the records is ignored.
Methods
impl StringRecord
[src]
fn new() -> StringRecord
Create a new empty StringRecord
.
Note that you may find the StringRecord::from
constructor more
convenient, which is provided by an impl on the From
trait.
Example: create an empty record
use csv::StringRecord; let record = StringRecord::new(); assert_eq!(record.len(), 0);
Example: initialize a record from a Vec
use csv::StringRecord; let record = StringRecord::from(vec!["a", "b", "c"]); assert_eq!(record.len(), 3);
fn with_capacity(buffer: usize, fields: usize) -> StringRecord
Create a new empty StringRecord
with the given capacity.
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.
fn from_byte_record(record: ByteRecord) -> Result<StringRecord, FromUtf8Error>
Create a new StringRecord
from a ByteRecord
.
Note that this does UTF-8 validation. If the given ByteRecord
does
not contain valid UTF-8, then this returns an error. The error includes
the UTF-8 error and the original ByteRecord
.
Example: valid UTF-8
extern crate csv; use std::error::Error; use csv::{ByteRecord, StringRecord}; fn example() -> Result<(), Box<Error>> { let byte_record = ByteRecord::from(vec!["a", "b", "c"]); let str_record = StringRecord::from_byte_record(byte_record)?; assert_eq!(str_record.len(), 3); Ok(()) }
Example: invalid UTF-8
use csv::{ByteRecord, StringRecord}; let byte_record = ByteRecord::from(vec![ &b"quux"[..], &b"foo\xFFbar"[..], &b"c"[..], ]); let err = StringRecord::from_byte_record(byte_record).unwrap_err(); assert_eq!(err.utf8_error().field(), 1); assert_eq!(err.utf8_error().valid_up_to(), 3);
fn from_byte_record_lossy(record: ByteRecord) -> StringRecord
Lossily create a new StringRecord
from a ByteRecord
.
This is like StringRecord::from_byte_record
, except all invalid UTF-8
sequences are replaced with the U+FFFD REPLACEMENT CHARACTER
, which
looks like this: �.
Example: valid UTF-8
use csv::{ByteRecord, StringRecord}; let byte_record = ByteRecord::from(vec!["a", "b", "c"]); let str_record = StringRecord::from_byte_record_lossy(byte_record); assert_eq!(str_record.len(), 3);
Example: invalid UTF-8
use csv::{ByteRecord, StringRecord}; let byte_record = ByteRecord::from(vec![ &b"quux"[..], &b"foo\xFFbar"[..], &b"c"[..], ]); let str_record = StringRecord::from_byte_record_lossy(byte_record); assert_eq!(&str_record[0], "quux"); assert_eq!(&str_record[1], "foo�bar"); assert_eq!(&str_record[2], "c");
fn deserialize<'de, D: Deserialize<'de>>(
&'de self,
headers: Option<&'de StringRecord>
) -> Result<D>
&'de self,
headers: Option<&'de StringRecord>
) -> 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
StringRecord
. 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 StringRecord
, which results in zero allocation
deserialization.
extern crate csv; #[macro_use] extern crate serde_derive; use std::error::Error; use csv::StringRecord; #[derive(Deserialize)] struct Row<'a> { city: &'a str, country: &'a str, population: u64, } fn example() -> Result<(), Box<Error>> { let record = StringRecord::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
).
extern crate csv; #[macro_use] extern crate serde_derive; use std::error::Error; use csv::StringRecord; #[derive(Deserialize)] struct Row { city: String, country: String, population: u64, } fn example() -> Result<(), Box<Error>> { // Notice that the fields are not in the same order // as the fields in the struct! let header = StringRecord::from(vec![ "country", "city", "population", ]); let record = StringRecord::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(()) }
fn iter(&self) -> StringRecordIter
Returns an iterator over all fields in this record.
Example
This example shows how to iterate over each field in a StringRecord
.
use csv::StringRecord; let record = StringRecord::from(vec!["a", "b", "c"]); for field in record.iter() { assert!(field == "a" || field == "b" || field == "c"); }
fn get(&self, i: usize) -> Option<&str>
Return the field at index i
.
If no field at index i
exists, then this returns None
.
Example
use csv::StringRecord; let record = StringRecord::from(vec!["a", "b", "c"]); assert_eq!(record.get(1), Some("b")); assert_eq!(record.get(3), None);
fn is_empty(&self) -> bool
Returns true if and only if this record is empty.
Example
use csv::StringRecord; assert!(StringRecord::new().is_empty());
fn len(&self) -> usize
Returns the number of fields in this record.
Example
use csv::StringRecord; let record = StringRecord::from(vec!["a", "b", "c"]); assert_eq!(record.len(), 3);
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::StringRecord; let mut record = StringRecord::from(vec!["a", "b", "c"]); assert_eq!(record.len(), 3); record.truncate(1); assert_eq!(record.len(), 1); assert_eq!(record, vec!["a"]);
fn clear(&mut self)
Clear this record so that it has zero fields.
Note that it is not necessary to clear the record to reuse it with the CSV reader.
Example
use csv::StringRecord; let mut record = StringRecord::from(vec!["a", "b", "c"]); assert_eq!(record.len(), 3); record.clear(); assert_eq!(record.len(), 0);
fn push_field(&mut self, field: &str)
Add a new field to this record.
Example
use csv::StringRecord; let mut record = StringRecord::new(); record.push_field("foo"); assert_eq!(&record[0], "foo");
fn position(&self) -> Option<&Position>
Return the position of this record, if available.
Example
extern crate csv; use std::error::Error; use csv::{StringRecord, ReaderBuilder}; fn example() -> Result<(), Box<Error>> { let mut record = StringRecord::new(); let mut rdr = ReaderBuilder::new() .has_headers(false) .from_reader("a,b,c\nx,y,z".as_bytes()); assert!(rdr.read_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_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_record(&mut record)?); Ok(()) }
fn set_position(&mut self, pos: Option<Position>)
Set the position of this record.
Example
use csv::{StringRecord, Position}; let mut record = StringRecord::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));
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
.
Namely, the range returned is guaranteed to start and end at valid
UTF-8 sequence boundaries.
Example
use csv::StringRecord; let record = StringRecord::from(vec!["foo", "quux", "z"]); let range = record.range(1).expect("a record range"); assert_eq!(&record.as_slice()[range], "quux");
fn as_slice(&self) -> &str
Return the entire row as a single string slice. The slice returned
stores all fields contiguously. The boundaries of each field can be
determined via the range
method.
Example
use csv::StringRecord; let record = StringRecord::from(vec!["foo", "quux", "z"]); assert_eq!(record.as_slice(), "fooquuxz");
fn as_byte_record(&self) -> &ByteRecord
Return a reference to this record's raw
ByteRecord
.
Example
use csv::StringRecord; let str_record = StringRecord::from(vec!["a", "b", "c"]); let byte_record = str_record.as_byte_record(); assert_eq!(&byte_record[2], b"c");
fn into_byte_record(self) -> ByteRecord
Convert this StringRecord
into a
ByteRecord
.
Example
use csv::StringRecord; let str_record = StringRecord::from(vec!["a", "b", "c"]); let byte_record = str_record.into_byte_record(); assert_eq!(&byte_record[2], b"c");
Note that this can also be achieved using the From
impl:
use csv::{ByteRecord, StringRecord}; // Using ByteRecord::from... let str_record = StringRecord::from(vec!["a", "b", "c"]); assert_eq!(ByteRecord::from(str_record).len(), 3); // Using StringRecord::into... let str_record = StringRecord::from(vec!["a", "b", "c"]); let byte_record: ByteRecord = str_record.into(); assert_eq!(byte_record.len(), 3);
Trait Implementations
impl Clone for StringRecord
[src]
fn clone(&self) -> StringRecord
Returns a copy of the value. Read more
fn clone_from(&mut self, source: &Self)
1.0.0
Performs copy-assignment from source
. Read more
impl Eq for StringRecord
[src]
impl PartialEq for StringRecord
[src]
fn eq(&self, other: &StringRecord) -> bool
This method tests for self
and other
values to be equal, and is used by ==
. Read more
fn ne(&self, other: &Rhs) -> bool
1.0.0
This method tests for !=
.
impl<T: AsRef<[u8]>> PartialEq<Vec<T>> for StringRecord
[src]
fn eq(&self, other: &Vec<T>) -> bool
This method tests for self
and other
values to be equal, and is used by ==
. Read more
fn ne(&self, other: &Rhs) -> bool
1.0.0
This method tests for !=
.
impl<'a, T: AsRef<[u8]>> PartialEq<Vec<T>> for &'a StringRecord
[src]
fn eq(&self, other: &Vec<T>) -> bool
This method tests for self
and other
values to be equal, and is used by ==
. Read more
fn ne(&self, other: &Rhs) -> bool
1.0.0
This method tests for !=
.
impl<T: AsRef<[u8]>> PartialEq<[T]> for StringRecord
[src]
fn eq(&self, other: &[T]) -> bool
This method tests for self
and other
values to be equal, and is used by ==
. Read more
fn ne(&self, other: &Rhs) -> bool
1.0.0
This method tests for !=
.
impl<'a, T: AsRef<[u8]>> PartialEq<[T]> for &'a StringRecord
[src]
fn eq(&self, other: &[T]) -> bool
This method tests for self
and other
values to be equal, and is used by ==
. Read more
fn ne(&self, other: &Rhs) -> bool
1.0.0
This method tests for !=
.
impl Debug for StringRecord
[src]
impl Default for StringRecord
[src]
fn default() -> StringRecord
Returns the "default value" for a type. Read more
impl Index<usize> for StringRecord
[src]
type Output = str
The returned type after indexing
fn index(&self, i: usize) -> &str
The method for the indexing (container[index]
) operation
impl<T: AsRef<str>> From<Vec<T>> for StringRecord
[src]
fn from(xs: Vec<T>) -> StringRecord
Performs the conversion.
impl<'a, T: AsRef<str>> From<&'a [T]> for StringRecord
[src]
fn from(xs: &'a [T]) -> StringRecord
Performs the conversion.
impl<T: AsRef<str>> FromIterator<T> for StringRecord
[src]
fn from_iter<I: IntoIterator<Item = T>>(iter: I) -> StringRecord
Creates a value from an iterator. Read more
impl<T: AsRef<str>> Extend<T> for StringRecord
[src]
fn extend<I: IntoIterator<Item = T>>(&mut self, iter: I)
Extends a collection with the contents of an iterator. Read more
impl<'a> IntoIterator for &'a StringRecord
[src]
type IntoIter = StringRecordIter<'a>
Which kind of iterator are we turning this into?
type Item = &'a str
The type of the elements being iterated over.
fn into_iter(self) -> StringRecordIter<'a>
Creates an iterator from a value. Read more