1 use std::fs::File; 2 use std::io; 3 use std::path::Path; 4 use std::result; 5 6 use csv_core::{ 7 self, WriteResult, Writer as CoreWriter, 8 WriterBuilder as CoreWriterBuilder, 9 }; 10 use serde::Serialize; 11 12 use crate::byte_record::ByteRecord; 13 use crate::error::{Error, ErrorKind, IntoInnerError, Result}; 14 use crate::serializer::{serialize, serialize_header}; 15 use crate::{QuoteStyle, Terminator}; 16 17 /// Builds a CSV writer with various configuration knobs. 18 /// 19 /// This builder can be used to tweak the field delimiter, record terminator 20 /// and more. Once a CSV `Writer` is built, its configuration cannot be 21 /// changed. 22 #[derive(Debug)] 23 pub struct WriterBuilder { 24 builder: CoreWriterBuilder, 25 capacity: usize, 26 flexible: bool, 27 has_headers: bool, 28 } 29 30 impl Default for WriterBuilder { default() -> WriterBuilder31 fn default() -> WriterBuilder { 32 WriterBuilder { 33 builder: CoreWriterBuilder::default(), 34 capacity: 8 * (1 << 10), 35 flexible: false, 36 has_headers: true, 37 } 38 } 39 } 40 41 impl WriterBuilder { 42 /// Create a new builder for configuring CSV writing. 43 /// 44 /// To convert a builder into a writer, call one of the methods starting 45 /// with `from_`. 46 /// 47 /// # Example 48 /// 49 /// ``` 50 /// use std::error::Error; 51 /// use csv::WriterBuilder; 52 /// 53 /// # fn main() { example().unwrap(); } 54 /// fn example() -> Result<(), Box<dyn Error>> { 55 /// let mut wtr = WriterBuilder::new().from_writer(vec![]); 56 /// wtr.write_record(&["a", "b", "c"])?; 57 /// wtr.write_record(&["x", "y", "z"])?; 58 /// 59 /// let data = String::from_utf8(wtr.into_inner()?)?; 60 /// assert_eq!(data, "a,b,c\nx,y,z\n"); 61 /// Ok(()) 62 /// } 63 /// ``` new() -> WriterBuilder64 pub fn new() -> WriterBuilder { 65 WriterBuilder::default() 66 } 67 68 /// Build a CSV writer from this configuration that writes data to the 69 /// given file path. The file is truncated if it already exists. 70 /// 71 /// If there was a problem opening the file at the given path, then this 72 /// returns the corresponding error. 73 /// 74 /// # Example 75 /// 76 /// ```no_run 77 /// use std::error::Error; 78 /// use csv::WriterBuilder; 79 /// 80 /// # fn main() { example().unwrap(); } 81 /// fn example() -> Result<(), Box<dyn Error>> { 82 /// let mut wtr = WriterBuilder::new().from_path("foo.csv")?; 83 /// wtr.write_record(&["a", "b", "c"])?; 84 /// wtr.write_record(&["x", "y", "z"])?; 85 /// wtr.flush()?; 86 /// Ok(()) 87 /// } 88 /// ``` from_path<P: AsRef<Path>>(&self, path: P) -> Result<Writer<File>>89 pub fn from_path<P: AsRef<Path>>(&self, path: P) -> Result<Writer<File>> { 90 Ok(Writer::new(self, File::create(path)?)) 91 } 92 93 /// Build a CSV writer from this configuration that writes data to `wtr`. 94 /// 95 /// Note that the CSV writer is buffered automatically, so you should not 96 /// wrap `wtr` in a buffered writer like `io::BufWriter`. 97 /// 98 /// # Example 99 /// 100 /// ``` 101 /// use std::error::Error; 102 /// use csv::WriterBuilder; 103 /// 104 /// # fn main() { example().unwrap(); } 105 /// fn example() -> Result<(), Box<dyn Error>> { 106 /// let mut wtr = WriterBuilder::new().from_writer(vec![]); 107 /// wtr.write_record(&["a", "b", "c"])?; 108 /// wtr.write_record(&["x", "y", "z"])?; 109 /// 110 /// let data = String::from_utf8(wtr.into_inner()?)?; 111 /// assert_eq!(data, "a,b,c\nx,y,z\n"); 112 /// Ok(()) 113 /// } 114 /// ``` from_writer<W: io::Write>(&self, wtr: W) -> Writer<W>115 pub fn from_writer<W: io::Write>(&self, wtr: W) -> Writer<W> { 116 Writer::new(self, wtr) 117 } 118 119 /// The field delimiter to use when writing CSV. 120 /// 121 /// The default is `b','`. 122 /// 123 /// # Example 124 /// 125 /// ``` 126 /// use std::error::Error; 127 /// use csv::WriterBuilder; 128 /// 129 /// # fn main() { example().unwrap(); } 130 /// fn example() -> Result<(), Box<dyn Error>> { 131 /// let mut wtr = WriterBuilder::new() 132 /// .delimiter(b';') 133 /// .from_writer(vec![]); 134 /// wtr.write_record(&["a", "b", "c"])?; 135 /// wtr.write_record(&["x", "y", "z"])?; 136 /// 137 /// let data = String::from_utf8(wtr.into_inner()?)?; 138 /// assert_eq!(data, "a;b;c\nx;y;z\n"); 139 /// Ok(()) 140 /// } 141 /// ``` delimiter(&mut self, delimiter: u8) -> &mut WriterBuilder142 pub fn delimiter(&mut self, delimiter: u8) -> &mut WriterBuilder { 143 self.builder.delimiter(delimiter); 144 self 145 } 146 147 /// Whether to write a header row before writing any other row. 148 /// 149 /// When this is enabled and the `serialize` method is used to write data 150 /// with something that contains field names (i.e., a struct), then a 151 /// header row is written containing the field names before any other row 152 /// is written. 153 /// 154 /// This option has no effect when using other methods to write rows. That 155 /// is, if you don't use `serialize`, then you must write your header row 156 /// explicitly if you want a header row. 157 /// 158 /// This is enabled by default. 159 /// 160 /// # Example: with headers 161 /// 162 /// This shows how the header will be automatically written from the field 163 /// names of a struct. 164 /// 165 /// ``` 166 /// use std::error::Error; 167 /// 168 /// use csv::WriterBuilder; 169 /// use serde::Serialize; 170 /// 171 /// #[derive(Serialize)] 172 /// struct Row<'a> { 173 /// city: &'a str, 174 /// country: &'a str, 175 /// // Serde allows us to name our headers exactly, 176 /// // even if they don't match our struct field names. 177 /// #[serde(rename = "popcount")] 178 /// population: u64, 179 /// } 180 /// 181 /// # fn main() { example().unwrap(); } 182 /// fn example() -> Result<(), Box<dyn Error>> { 183 /// let mut wtr = WriterBuilder::new().from_writer(vec![]); 184 /// wtr.serialize(Row { 185 /// city: "Boston", 186 /// country: "United States", 187 /// population: 4628910, 188 /// })?; 189 /// wtr.serialize(Row { 190 /// city: "Concord", 191 /// country: "United States", 192 /// population: 42695, 193 /// })?; 194 /// 195 /// let data = String::from_utf8(wtr.into_inner()?)?; 196 /// assert_eq!(data, "\ 197 /// city,country,popcount 198 /// Boston,United States,4628910 199 /// Concord,United States,42695 200 /// "); 201 /// Ok(()) 202 /// } 203 /// ``` 204 /// 205 /// # Example: without headers 206 /// 207 /// This shows that serializing things that aren't structs (in this case, 208 /// a tuple struct) won't result in a header row being written. This means 209 /// you usually don't need to set `has_headers(false)` unless you 210 /// explicitly want to both write custom headers and serialize structs. 211 /// 212 /// ``` 213 /// use std::error::Error; 214 /// use csv::WriterBuilder; 215 /// 216 /// # fn main() { example().unwrap(); } 217 /// fn example() -> Result<(), Box<dyn Error>> { 218 /// let mut wtr = WriterBuilder::new().from_writer(vec![]); 219 /// wtr.serialize(("Boston", "United States", 4628910))?; 220 /// wtr.serialize(("Concord", "United States", 42695))?; 221 /// 222 /// let data = String::from_utf8(wtr.into_inner()?)?; 223 /// assert_eq!(data, "\ 224 /// Boston,United States,4628910 225 /// Concord,United States,42695 226 /// "); 227 /// Ok(()) 228 /// } 229 /// ``` has_headers(&mut self, yes: bool) -> &mut WriterBuilder230 pub fn has_headers(&mut self, yes: bool) -> &mut WriterBuilder { 231 self.has_headers = yes; 232 self 233 } 234 235 /// Whether the number of fields in records is allowed to change or not. 236 /// 237 /// When disabled (which is the default), writing CSV data will return an 238 /// error if a record is written with a number of fields different from the 239 /// number of fields written in a previous record. 240 /// 241 /// When enabled, this error checking is turned off. 242 /// 243 /// # Example: writing flexible records 244 /// 245 /// ``` 246 /// use std::error::Error; 247 /// use csv::WriterBuilder; 248 /// 249 /// # fn main() { example().unwrap(); } 250 /// fn example() -> Result<(), Box<dyn Error>> { 251 /// let mut wtr = WriterBuilder::new() 252 /// .flexible(true) 253 /// .from_writer(vec![]); 254 /// wtr.write_record(&["a", "b"])?; 255 /// wtr.write_record(&["x", "y", "z"])?; 256 /// 257 /// let data = String::from_utf8(wtr.into_inner()?)?; 258 /// assert_eq!(data, "a,b\nx,y,z\n"); 259 /// Ok(()) 260 /// } 261 /// ``` 262 /// 263 /// # Example: error when `flexible` is disabled 264 /// 265 /// ``` 266 /// use std::error::Error; 267 /// use csv::WriterBuilder; 268 /// 269 /// # fn main() { example().unwrap(); } 270 /// fn example() -> Result<(), Box<dyn Error>> { 271 /// let mut wtr = WriterBuilder::new() 272 /// .flexible(false) 273 /// .from_writer(vec![]); 274 /// wtr.write_record(&["a", "b"])?; 275 /// let err = wtr.write_record(&["x", "y", "z"]).unwrap_err(); 276 /// match *err.kind() { 277 /// csv::ErrorKind::UnequalLengths { expected_len, len, .. } => { 278 /// assert_eq!(expected_len, 2); 279 /// assert_eq!(len, 3); 280 /// } 281 /// ref wrong => { 282 /// panic!("expected UnequalLengths but got {:?}", wrong); 283 /// } 284 /// } 285 /// Ok(()) 286 /// } 287 /// ``` flexible(&mut self, yes: bool) -> &mut WriterBuilder288 pub fn flexible(&mut self, yes: bool) -> &mut WriterBuilder { 289 self.flexible = yes; 290 self 291 } 292 293 /// The record terminator to use when writing CSV. 294 /// 295 /// A record terminator can be any single byte. The default is `\n`. 296 /// 297 /// Note that RFC 4180 specifies that record terminators should be `\r\n`. 298 /// To use `\r\n`, use the special `Terminator::CRLF` value. 299 /// 300 /// # Example: CRLF 301 /// 302 /// This shows how to use RFC 4180 compliant record terminators. 303 /// 304 /// ``` 305 /// use std::error::Error; 306 /// use csv::{Terminator, WriterBuilder}; 307 /// 308 /// # fn main() { example().unwrap(); } 309 /// fn example() -> Result<(), Box<dyn Error>> { 310 /// let mut wtr = WriterBuilder::new() 311 /// .terminator(Terminator::CRLF) 312 /// .from_writer(vec![]); 313 /// wtr.write_record(&["a", "b", "c"])?; 314 /// wtr.write_record(&["x", "y", "z"])?; 315 /// 316 /// let data = String::from_utf8(wtr.into_inner()?)?; 317 /// assert_eq!(data, "a,b,c\r\nx,y,z\r\n"); 318 /// Ok(()) 319 /// } 320 /// ``` terminator(&mut self, term: Terminator) -> &mut WriterBuilder321 pub fn terminator(&mut self, term: Terminator) -> &mut WriterBuilder { 322 self.builder.terminator(term.to_core()); 323 self 324 } 325 326 /// The quoting style to use when writing CSV. 327 /// 328 /// By default, this is set to `QuoteStyle::Necessary`, which will only 329 /// use quotes when they are necessary to preserve the integrity of data. 330 /// 331 /// Note that unless the quote style is set to `Never`, an empty field is 332 /// quoted if it is the only field in a record. 333 /// 334 /// # Example: non-numeric quoting 335 /// 336 /// This shows how to quote non-numeric fields only. 337 /// 338 /// ``` 339 /// use std::error::Error; 340 /// use csv::{QuoteStyle, WriterBuilder}; 341 /// 342 /// # fn main() { example().unwrap(); } 343 /// fn example() -> Result<(), Box<dyn Error>> { 344 /// let mut wtr = WriterBuilder::new() 345 /// .quote_style(QuoteStyle::NonNumeric) 346 /// .from_writer(vec![]); 347 /// wtr.write_record(&["a", "5", "c"])?; 348 /// wtr.write_record(&["3.14", "y", "z"])?; 349 /// 350 /// let data = String::from_utf8(wtr.into_inner()?)?; 351 /// assert_eq!(data, "\"a\",5,\"c\"\n3.14,\"y\",\"z\"\n"); 352 /// Ok(()) 353 /// } 354 /// ``` 355 /// 356 /// # Example: never quote 357 /// 358 /// This shows how the CSV writer can be made to never write quotes, even 359 /// if it sacrifices the integrity of the data. 360 /// 361 /// ``` 362 /// use std::error::Error; 363 /// use csv::{QuoteStyle, WriterBuilder}; 364 /// 365 /// # fn main() { example().unwrap(); } 366 /// fn example() -> Result<(), Box<dyn Error>> { 367 /// let mut wtr = WriterBuilder::new() 368 /// .quote_style(QuoteStyle::Never) 369 /// .from_writer(vec![]); 370 /// wtr.write_record(&["a", "foo\nbar", "c"])?; 371 /// wtr.write_record(&["g\"h\"i", "y", "z"])?; 372 /// 373 /// let data = String::from_utf8(wtr.into_inner()?)?; 374 /// assert_eq!(data, "a,foo\nbar,c\ng\"h\"i,y,z\n"); 375 /// Ok(()) 376 /// } 377 /// ``` quote_style(&mut self, style: QuoteStyle) -> &mut WriterBuilder378 pub fn quote_style(&mut self, style: QuoteStyle) -> &mut WriterBuilder { 379 self.builder.quote_style(style.to_core()); 380 self 381 } 382 383 /// The quote character to use when writing CSV. 384 /// 385 /// The default is `b'"'`. 386 /// 387 /// # Example 388 /// 389 /// ``` 390 /// use std::error::Error; 391 /// use csv::WriterBuilder; 392 /// 393 /// # fn main() { example().unwrap(); } 394 /// fn example() -> Result<(), Box<dyn Error>> { 395 /// let mut wtr = WriterBuilder::new() 396 /// .quote(b'\'') 397 /// .from_writer(vec![]); 398 /// wtr.write_record(&["a", "foo\nbar", "c"])?; 399 /// wtr.write_record(&["g'h'i", "y\"y\"y", "z"])?; 400 /// 401 /// let data = String::from_utf8(wtr.into_inner()?)?; 402 /// assert_eq!(data, "a,'foo\nbar',c\n'g''h''i',y\"y\"y,z\n"); 403 /// Ok(()) 404 /// } 405 /// ``` quote(&mut self, quote: u8) -> &mut WriterBuilder406 pub fn quote(&mut self, quote: u8) -> &mut WriterBuilder { 407 self.builder.quote(quote); 408 self 409 } 410 411 /// Enable double quote escapes. 412 /// 413 /// This is enabled by default, but it may be disabled. When disabled, 414 /// quotes in field data are escaped instead of doubled. 415 /// 416 /// # Example 417 /// 418 /// ``` 419 /// use std::error::Error; 420 /// use csv::WriterBuilder; 421 /// 422 /// # fn main() { example().unwrap(); } 423 /// fn example() -> Result<(), Box<dyn Error>> { 424 /// let mut wtr = WriterBuilder::new() 425 /// .double_quote(false) 426 /// .from_writer(vec![]); 427 /// wtr.write_record(&["a", "foo\"bar", "c"])?; 428 /// wtr.write_record(&["x", "y", "z"])?; 429 /// 430 /// let data = String::from_utf8(wtr.into_inner()?)?; 431 /// assert_eq!(data, "a,\"foo\\\"bar\",c\nx,y,z\n"); 432 /// Ok(()) 433 /// } 434 /// ``` double_quote(&mut self, yes: bool) -> &mut WriterBuilder435 pub fn double_quote(&mut self, yes: bool) -> &mut WriterBuilder { 436 self.builder.double_quote(yes); 437 self 438 } 439 440 /// The escape character to use when writing CSV. 441 /// 442 /// In some variants of CSV, quotes are escaped using a special escape 443 /// character like `\` (instead of escaping quotes by doubling them). 444 /// 445 /// By default, writing these idiosyncratic escapes is disabled, and is 446 /// only used when `double_quote` is disabled. 447 /// 448 /// # Example 449 /// 450 /// ``` 451 /// use std::error::Error; 452 /// use csv::WriterBuilder; 453 /// 454 /// # fn main() { example().unwrap(); } 455 /// fn example() -> Result<(), Box<dyn Error>> { 456 /// let mut wtr = WriterBuilder::new() 457 /// .double_quote(false) 458 /// .escape(b'$') 459 /// .from_writer(vec![]); 460 /// wtr.write_record(&["a", "foo\"bar", "c"])?; 461 /// wtr.write_record(&["x", "y", "z"])?; 462 /// 463 /// let data = String::from_utf8(wtr.into_inner()?)?; 464 /// assert_eq!(data, "a,\"foo$\"bar\",c\nx,y,z\n"); 465 /// Ok(()) 466 /// } 467 /// ``` escape(&mut self, escape: u8) -> &mut WriterBuilder468 pub fn escape(&mut self, escape: u8) -> &mut WriterBuilder { 469 self.builder.escape(escape); 470 self 471 } 472 473 /// Set the capacity (in bytes) of the internal buffer used in the CSV 474 /// writer. This defaults to a reasonable setting. buffer_capacity(&mut self, capacity: usize) -> &mut WriterBuilder475 pub fn buffer_capacity(&mut self, capacity: usize) -> &mut WriterBuilder { 476 self.capacity = capacity; 477 self 478 } 479 } 480 481 /// A already configured CSV writer. 482 /// 483 /// A CSV writer takes as input Rust values and writes those values in a valid 484 /// CSV format as output. 485 /// 486 /// While CSV writing is considerably easier than parsing CSV, a proper writer 487 /// will do a number of things for you: 488 /// 489 /// 1. Quote fields when necessary. 490 /// 2. Check that all records have the same number of fields. 491 /// 3. Write records with a single empty field correctly. 492 /// 4. Automatically serialize normal Rust types to CSV records. When that 493 /// type is a struct, a header row is automatically written corresponding 494 /// to the fields of that struct. 495 /// 5. Use buffering intelligently and otherwise avoid allocation. (This means 496 /// that callers should not do their own buffering.) 497 /// 498 /// All of the above can be configured using a 499 /// [`WriterBuilder`](struct.WriterBuilder.html). 500 /// However, a `Writer` has a couple of convenience constructors (`from_path` 501 /// and `from_writer`) that use the default configuration. 502 /// 503 /// Note that the default configuration of a `Writer` uses `\n` for record 504 /// terminators instead of `\r\n` as specified by RFC 4180. Use the 505 /// `terminator` method on `WriterBuilder` to set the terminator to `\r\n` if 506 /// it's desired. 507 #[derive(Debug)] 508 pub struct Writer<W: io::Write> { 509 core: CoreWriter, 510 wtr: Option<W>, 511 buf: Buffer, 512 state: WriterState, 513 } 514 515 #[derive(Debug)] 516 struct WriterState { 517 /// Whether the Serde serializer should attempt to write a header row. 518 header: HeaderState, 519 /// Whether inconsistent record lengths are allowed. 520 flexible: bool, 521 /// The number of fields writtein in the first record. This is compared 522 /// with `fields_written` on all subsequent records to check for 523 /// inconsistent record lengths. 524 first_field_count: Option<u64>, 525 /// The number of fields written in this record. This is used to report 526 /// errors for inconsistent record lengths if `flexible` is disabled. 527 fields_written: u64, 528 /// This is set immediately before flushing the buffer and then unset 529 /// immediately after flushing the buffer. This avoids flushing the buffer 530 /// twice if the inner writer panics. 531 panicked: bool, 532 } 533 534 /// HeaderState encodes a small state machine for handling header writes. 535 #[derive(Debug)] 536 enum HeaderState { 537 /// Indicates that we should attempt to write a header. 538 Write, 539 /// Indicates that writing a header was attempt, and a header was written. 540 DidWrite, 541 /// Indicates that writing a header was attempted, but no headers were 542 /// written or the attempt failed. 543 DidNotWrite, 544 /// This state is used when headers are disabled. It cannot transition 545 /// to any other state. 546 None, 547 } 548 549 /// A simple internal buffer for buffering writes. 550 /// 551 /// We need this because the `csv_core` APIs want to write into a `&mut [u8]`, 552 /// which is not available with the `std::io::BufWriter` API. 553 #[derive(Debug)] 554 struct Buffer { 555 /// The contents of the buffer. 556 buf: Vec<u8>, 557 /// The number of bytes written to the buffer. 558 len: usize, 559 } 560 561 impl<W: io::Write> Drop for Writer<W> { drop(&mut self)562 fn drop(&mut self) { 563 if self.wtr.is_some() && !self.state.panicked { 564 let _ = self.flush(); 565 } 566 } 567 } 568 569 impl Writer<File> { 570 /// Build a CSV writer with a default configuration that writes data to the 571 /// given file path. The file is truncated if it already exists. 572 /// 573 /// If there was a problem opening the file at the given path, then this 574 /// returns the corresponding error. 575 /// 576 /// # Example 577 /// 578 /// ```no_run 579 /// use std::error::Error; 580 /// use csv::Writer; 581 /// 582 /// # fn main() { example().unwrap(); } 583 /// fn example() -> Result<(), Box<dyn Error>> { 584 /// let mut wtr = Writer::from_path("foo.csv")?; 585 /// wtr.write_record(&["a", "b", "c"])?; 586 /// wtr.write_record(&["x", "y", "z"])?; 587 /// wtr.flush()?; 588 /// Ok(()) 589 /// } 590 /// ``` from_path<P: AsRef<Path>>(path: P) -> Result<Writer<File>>591 pub fn from_path<P: AsRef<Path>>(path: P) -> Result<Writer<File>> { 592 WriterBuilder::new().from_path(path) 593 } 594 } 595 596 impl<W: io::Write> Writer<W> { new(builder: &WriterBuilder, wtr: W) -> Writer<W>597 fn new(builder: &WriterBuilder, wtr: W) -> Writer<W> { 598 let header_state = if builder.has_headers { 599 HeaderState::Write 600 } else { 601 HeaderState::None 602 }; 603 Writer { 604 core: builder.builder.build(), 605 wtr: Some(wtr), 606 buf: Buffer { buf: vec![0; builder.capacity], len: 0 }, 607 state: WriterState { 608 header: header_state, 609 flexible: builder.flexible, 610 first_field_count: None, 611 fields_written: 0, 612 panicked: false, 613 }, 614 } 615 } 616 617 /// Build a CSV writer with a default configuration that writes data to 618 /// `wtr`. 619 /// 620 /// Note that the CSV writer is buffered automatically, so you should not 621 /// wrap `wtr` in a buffered writer like `io::BufWriter`. 622 /// 623 /// # Example 624 /// 625 /// ``` 626 /// use std::error::Error; 627 /// use csv::Writer; 628 /// 629 /// # fn main() { example().unwrap(); } 630 /// fn example() -> Result<(), Box<dyn Error>> { 631 /// let mut wtr = Writer::from_writer(vec![]); 632 /// wtr.write_record(&["a", "b", "c"])?; 633 /// wtr.write_record(&["x", "y", "z"])?; 634 /// 635 /// let data = String::from_utf8(wtr.into_inner()?)?; 636 /// assert_eq!(data, "a,b,c\nx,y,z\n"); 637 /// Ok(()) 638 /// } 639 /// ``` from_writer(wtr: W) -> Writer<W>640 pub fn from_writer(wtr: W) -> Writer<W> { 641 WriterBuilder::new().from_writer(wtr) 642 } 643 644 /// Serialize a single record using Serde. 645 /// 646 /// # Example 647 /// 648 /// This shows how to serialize normal Rust structs as CSV records. The 649 /// fields of the struct are used to write a header row automatically. 650 /// (Writing the header row automatically can be disabled by building the 651 /// CSV writer with a [`WriterBuilder`](struct.WriterBuilder.html) and 652 /// calling the `has_headers` method.) 653 /// 654 /// ``` 655 /// use std::error::Error; 656 /// 657 /// use csv::Writer; 658 /// use serde::Serialize; 659 /// 660 /// #[derive(Serialize)] 661 /// struct Row<'a> { 662 /// city: &'a str, 663 /// country: &'a str, 664 /// // Serde allows us to name our headers exactly, 665 /// // even if they don't match our struct field names. 666 /// #[serde(rename = "popcount")] 667 /// population: u64, 668 /// } 669 /// 670 /// # fn main() { example().unwrap(); } 671 /// fn example() -> Result<(), Box<dyn Error>> { 672 /// let mut wtr = Writer::from_writer(vec![]); 673 /// wtr.serialize(Row { 674 /// city: "Boston", 675 /// country: "United States", 676 /// population: 4628910, 677 /// })?; 678 /// wtr.serialize(Row { 679 /// city: "Concord", 680 /// country: "United States", 681 /// population: 42695, 682 /// })?; 683 /// 684 /// let data = String::from_utf8(wtr.into_inner()?)?; 685 /// assert_eq!(data, "\ 686 /// city,country,popcount 687 /// Boston,United States,4628910 688 /// Concord,United States,42695 689 /// "); 690 /// Ok(()) 691 /// } 692 /// ``` 693 /// 694 /// # Rules 695 /// 696 /// The behavior of `serialize` is fairly simple: 697 /// 698 /// 1. Nested containers (tuples, `Vec`s, structs, etc.) are always 699 /// flattened (depth-first order). 700 /// 701 /// 2. If `has_headers` is `true` and the type contains field names, then 702 /// a header row is automatically generated. 703 /// 704 /// However, some container types cannot be serialized, and if 705 /// `has_headers` is `true`, there are some additional restrictions on the 706 /// types that can be serialized. See below for details. 707 /// 708 /// For the purpose of this section, Rust types can be divided into three 709 /// categories: scalars, non-struct containers, and structs. 710 /// 711 /// ## Scalars 712 /// 713 /// Single values with no field names are written like the following. Note 714 /// that some of the outputs may be quoted, according to the selected 715 /// quoting style. 716 /// 717 /// | Name | Example Type | Example Value | Output | 718 /// | ---- | ---- | ---- | ---- | 719 /// | boolean | `bool` | `true` | `true` | 720 /// | integers | `i8`, `i16`, `i32`, `i64`, `i128`, `u8`, `u16`, `u32`, `u64`, `u128` | `5` | `5` | 721 /// | floats | `f32`, `f64` | `3.14` | `3.14` | 722 /// | character | `char` | `'☃'` | `☃` | 723 /// | string | `&str` | `"hi"` | `hi` | 724 /// | bytes | `&[u8]` | `b"hi"[..]` | `hi` | 725 /// | option | `Option` | `None` | *empty* | 726 /// | option | | `Some(5)` | `5` | 727 /// | unit | `()` | `()` | *empty* | 728 /// | unit struct | `struct Foo;` | `Foo` | `Foo` | 729 /// | unit enum variant | `enum E { A, B }` | `E::A` | `A` | 730 /// | newtype struct | `struct Foo(u8);` | `Foo(5)` | `5` | 731 /// | newtype enum variant | `enum E { A(u8) }` | `E::A(5)` | `5` | 732 /// 733 /// Note that this table includes simple structs and enums. For example, to 734 /// serialize a field from either an integer or a float type, one can do 735 /// this: 736 /// 737 /// ``` 738 /// use std::error::Error; 739 /// 740 /// use csv::Writer; 741 /// use serde::Serialize; 742 /// 743 /// #[derive(Serialize)] 744 /// struct Row { 745 /// label: String, 746 /// value: Value, 747 /// } 748 /// 749 /// #[derive(Serialize)] 750 /// enum Value { 751 /// Integer(i64), 752 /// Float(f64), 753 /// } 754 /// 755 /// # fn main() { example().unwrap(); } 756 /// fn example() -> Result<(), Box<dyn Error>> { 757 /// let mut wtr = Writer::from_writer(vec![]); 758 /// wtr.serialize(Row { 759 /// label: "foo".to_string(), 760 /// value: Value::Integer(3), 761 /// })?; 762 /// wtr.serialize(Row { 763 /// label: "bar".to_string(), 764 /// value: Value::Float(3.14), 765 /// })?; 766 /// 767 /// let data = String::from_utf8(wtr.into_inner()?)?; 768 /// assert_eq!(data, "\ 769 /// label,value 770 /// foo,3 771 /// bar,3.14 772 /// "); 773 /// Ok(()) 774 /// } 775 /// ``` 776 /// 777 /// ## Non-Struct Containers 778 /// 779 /// Nested containers are flattened to their scalar components, with the 780 /// exception of a few types that are not allowed: 781 /// 782 /// | Name | Example Type | Example Value | Output | 783 /// | ---- | ---- | ---- | ---- | 784 /// | sequence | `Vec<u8>` | `vec![1, 2, 3]` | `1,2,3` | 785 /// | tuple | `(u8, bool)` | `(5, true)` | `5,true` | 786 /// | tuple struct | `Foo(u8, bool)` | `Foo(5, true)` | `5,true` | 787 /// | tuple enum variant | `enum E { A(u8, bool) }` | `E::A(5, true)` | *error* | 788 /// | struct enum variant | `enum E { V { a: u8, b: bool } }` | `E::V { a: 5, b: true }` | *error* | 789 /// | map | `BTreeMap<K, V>` | `BTreeMap::new()` | *error* | 790 /// 791 /// ## Structs 792 /// 793 /// Like the other containers, structs are flattened to their scalar 794 /// components: 795 /// 796 /// | Name | Example Type | Example Value | Output | 797 /// | ---- | ---- | ---- | ---- | 798 /// | struct | `struct Foo { a: u8, b: bool }` | `Foo { a: 5, b: true }` | `5,true` | 799 /// 800 /// If `has_headers` is `false`, then there are no additional restrictions; 801 /// types can be nested arbitrarily. For example: 802 /// 803 /// ``` 804 /// use std::error::Error; 805 /// 806 /// use csv::WriterBuilder; 807 /// use serde::Serialize; 808 /// 809 /// #[derive(Serialize)] 810 /// struct Row { 811 /// label: String, 812 /// values: Vec<f64>, 813 /// } 814 /// 815 /// # fn main() { example().unwrap(); } 816 /// fn example() -> Result<(), Box<dyn Error>> { 817 /// let mut wtr = WriterBuilder::new() 818 /// .has_headers(false) 819 /// .from_writer(vec![]); 820 /// wtr.serialize(Row { 821 /// label: "foo".to_string(), 822 /// values: vec![1.1234, 2.5678, 3.14], 823 /// })?; 824 /// 825 /// let data = String::from_utf8(wtr.into_inner()?)?; 826 /// assert_eq!(data, "\ 827 /// foo,1.1234,2.5678,3.14 828 /// "); 829 /// Ok(()) 830 /// } 831 /// ``` 832 /// 833 /// However, if `has_headers` were enabled in the above example, then 834 /// serialization would return an error. Specifically, when `has_headers` is 835 /// `true`, there are two restrictions: 836 /// 837 /// 1. Named field values in structs must be scalars. 838 /// 839 /// 2. All scalars must be named field values in structs. 840 /// 841 /// Other than these two restrictions, types can be nested arbitrarily. 842 /// Here are a few examples: 843 /// 844 /// | Value | Header | Record | 845 /// | ---- | ---- | ---- | 846 /// | `(Foo { x: 5, y: 6 }, Bar { z: true })` | `x,y,z` | `5,6,true` | 847 /// | `vec![Foo { x: 5, y: 6 }, Foo { x: 7, y: 8 }]` | `x,y,x,y` | `5,6,7,8` | 848 /// | `(Foo { x: 5, y: 6 }, vec![Bar { z: Baz(true) }])` | `x,y,z` | `5,6,true` | 849 /// | `Foo { x: 5, y: (6, 7) }` | *error: restriction 1* | `5,6,7` | 850 /// | `(5, Foo { x: 6, y: 7 }` | *error: restriction 2* | `5,6,7` | 851 /// | `(Foo { x: 5, y: 6 }, true)` | *error: restriction 2* | `5,6,true` | serialize<S: Serialize>(&mut self, record: S) -> Result<()>852 pub fn serialize<S: Serialize>(&mut self, record: S) -> Result<()> { 853 if let HeaderState::Write = self.state.header { 854 let wrote_header = serialize_header(self, &record)?; 855 if wrote_header { 856 self.write_terminator()?; 857 self.state.header = HeaderState::DidWrite; 858 } else { 859 self.state.header = HeaderState::DidNotWrite; 860 }; 861 } 862 serialize(self, &record)?; 863 self.write_terminator()?; 864 Ok(()) 865 } 866 867 /// Write a single record. 868 /// 869 /// This method accepts something that can be turned into an iterator that 870 /// yields elements that can be represented by a `&[u8]`. 871 /// 872 /// This may be called with an empty iterator, which will cause a record 873 /// terminator to be written. If no fields had been written, then a single 874 /// empty field is written before the terminator. 875 /// 876 /// # Example 877 /// 878 /// ``` 879 /// use std::error::Error; 880 /// use csv::Writer; 881 /// 882 /// # fn main() { example().unwrap(); } 883 /// fn example() -> Result<(), Box<dyn Error>> { 884 /// let mut wtr = Writer::from_writer(vec![]); 885 /// wtr.write_record(&["a", "b", "c"])?; 886 /// wtr.write_record(&["x", "y", "z"])?; 887 /// 888 /// let data = String::from_utf8(wtr.into_inner()?)?; 889 /// assert_eq!(data, "a,b,c\nx,y,z\n"); 890 /// Ok(()) 891 /// } 892 /// ``` write_record<I, T>(&mut self, record: I) -> Result<()> where I: IntoIterator<Item = T>, T: AsRef<[u8]>,893 pub fn write_record<I, T>(&mut self, record: I) -> Result<()> 894 where 895 I: IntoIterator<Item = T>, 896 T: AsRef<[u8]>, 897 { 898 for field in record.into_iter() { 899 self.write_field_impl(field)?; 900 } 901 self.write_terminator() 902 } 903 904 /// Write a single `ByteRecord`. 905 /// 906 /// This method accepts a borrowed `ByteRecord` and writes its contents 907 /// to the underlying writer. 908 /// 909 /// This is similar to `write_record` except that it specifically requires 910 /// a `ByteRecord`. This permits the writer to possibly write the record 911 /// more quickly than the more generic `write_record`. 912 /// 913 /// This may be called with an empty record, which will cause a record 914 /// terminator to be written. If no fields had been written, then a single 915 /// empty field is written before the terminator. 916 /// 917 /// # Example 918 /// 919 /// ``` 920 /// use std::error::Error; 921 /// use csv::{ByteRecord, Writer}; 922 /// 923 /// # fn main() { example().unwrap(); } 924 /// fn example() -> Result<(), Box<dyn Error>> { 925 /// let mut wtr = Writer::from_writer(vec![]); 926 /// wtr.write_byte_record(&ByteRecord::from(&["a", "b", "c"][..]))?; 927 /// wtr.write_byte_record(&ByteRecord::from(&["x", "y", "z"][..]))?; 928 /// 929 /// let data = String::from_utf8(wtr.into_inner()?)?; 930 /// assert_eq!(data, "a,b,c\nx,y,z\n"); 931 /// Ok(()) 932 /// } 933 /// ``` 934 #[inline(never)] write_byte_record(&mut self, record: &ByteRecord) -> Result<()>935 pub fn write_byte_record(&mut self, record: &ByteRecord) -> Result<()> { 936 if record.as_slice().is_empty() { 937 return self.write_record(record); 938 } 939 // The idea here is to find a fast path for shuffling our record into 940 // our buffer as quickly as possible. We do this because the underlying 941 // "core" CSV writer does a lot of book-keeping to maintain its state 942 // oriented API. 943 // 944 // The fast path occurs when we know our record will fit in whatever 945 // space we have left in our buffer. We can actually quickly compute 946 // the upper bound on the space required: 947 let upper_bound = 948 // The data itself plus the worst case: every byte is a quote. 949 (2 * record.as_slice().len()) 950 // The number of field delimiters. 951 + (record.len().saturating_sub(1)) 952 // The maximum number of quotes inserted around each field. 953 + (2 * record.len()) 954 // The maximum number of bytes for the terminator. 955 + 2; 956 if self.buf.writable().len() < upper_bound { 957 return self.write_record(record); 958 } 959 let mut first = true; 960 for field in record.iter() { 961 if !first { 962 self.buf.writable()[0] = self.core.get_delimiter(); 963 self.buf.written(1); 964 } 965 first = false; 966 967 if !self.core.should_quote(field) { 968 self.buf.writable()[..field.len()].copy_from_slice(field); 969 self.buf.written(field.len()); 970 } else { 971 self.buf.writable()[0] = self.core.get_quote(); 972 self.buf.written(1); 973 let (res, nin, nout) = csv_core::quote( 974 field, 975 self.buf.writable(), 976 self.core.get_quote(), 977 self.core.get_escape(), 978 self.core.get_double_quote(), 979 ); 980 debug_assert!(res == WriteResult::InputEmpty); 981 debug_assert!(nin == field.len()); 982 self.buf.written(nout); 983 self.buf.writable()[0] = self.core.get_quote(); 984 self.buf.written(1); 985 } 986 } 987 self.state.fields_written = record.len() as u64; 988 self.write_terminator_into_buffer() 989 } 990 991 /// Write a single field. 992 /// 993 /// One should prefer using `write_record` over this method. It is provided 994 /// for cases where writing a field at a time is more convenient than 995 /// writing a record at a time. 996 /// 997 /// Note that if this API is used, `write_record` should be called with an 998 /// empty iterator to write a record terminator. 999 /// 1000 /// # Example 1001 /// 1002 /// ``` 1003 /// use std::error::Error; 1004 /// use csv::Writer; 1005 /// 1006 /// # fn main() { example().unwrap(); } 1007 /// fn example() -> Result<(), Box<dyn Error>> { 1008 /// let mut wtr = Writer::from_writer(vec![]); 1009 /// wtr.write_field("a")?; 1010 /// wtr.write_field("b")?; 1011 /// wtr.write_field("c")?; 1012 /// wtr.write_record(None::<&[u8]>)?; 1013 /// wtr.write_field("x")?; 1014 /// wtr.write_field("y")?; 1015 /// wtr.write_field("z")?; 1016 /// wtr.write_record(None::<&[u8]>)?; 1017 /// 1018 /// let data = String::from_utf8(wtr.into_inner()?)?; 1019 /// assert_eq!(data, "a,b,c\nx,y,z\n"); 1020 /// Ok(()) 1021 /// } 1022 /// ``` write_field<T: AsRef<[u8]>>(&mut self, field: T) -> Result<()>1023 pub fn write_field<T: AsRef<[u8]>>(&mut self, field: T) -> Result<()> { 1024 self.write_field_impl(field) 1025 } 1026 1027 /// Implementation of write_field. 1028 /// 1029 /// This is a separate method so we can force the compiler to inline it 1030 /// into write_record. 1031 #[inline(always)] write_field_impl<T: AsRef<[u8]>>(&mut self, field: T) -> Result<()>1032 fn write_field_impl<T: AsRef<[u8]>>(&mut self, field: T) -> Result<()> { 1033 if self.state.fields_written > 0 { 1034 self.write_delimiter()?; 1035 } 1036 let mut field = field.as_ref(); 1037 loop { 1038 let (res, nin, nout) = self.core.field(field, self.buf.writable()); 1039 field = &field[nin..]; 1040 self.buf.written(nout); 1041 match res { 1042 WriteResult::InputEmpty => { 1043 self.state.fields_written += 1; 1044 return Ok(()); 1045 } 1046 WriteResult::OutputFull => self.flush_buf()?, 1047 } 1048 } 1049 } 1050 1051 /// Flush the contents of the internal buffer to the underlying writer. 1052 /// 1053 /// If there was a problem writing to the underlying writer, then an error 1054 /// is returned. 1055 /// 1056 /// Note that this also flushes the underlying writer. flush(&mut self) -> io::Result<()>1057 pub fn flush(&mut self) -> io::Result<()> { 1058 self.flush_buf()?; 1059 self.wtr.as_mut().unwrap().flush()?; 1060 Ok(()) 1061 } 1062 1063 /// Flush the contents of the internal buffer to the underlying writer, 1064 /// without flushing the underlying writer. flush_buf(&mut self) -> io::Result<()>1065 fn flush_buf(&mut self) -> io::Result<()> { 1066 self.state.panicked = true; 1067 let result = self.wtr.as_mut().unwrap().write_all(self.buf.readable()); 1068 self.state.panicked = false; 1069 result?; 1070 self.buf.clear(); 1071 Ok(()) 1072 } 1073 1074 /// Flush the contents of the internal buffer and return the underlying 1075 /// writer. into_inner( mut self, ) -> result::Result<W, IntoInnerError<Writer<W>>>1076 pub fn into_inner( 1077 mut self, 1078 ) -> result::Result<W, IntoInnerError<Writer<W>>> { 1079 match self.flush() { 1080 Ok(()) => Ok(self.wtr.take().unwrap()), 1081 Err(err) => Err(IntoInnerError::new(self, err)), 1082 } 1083 } 1084 1085 /// Write a CSV delimiter. write_delimiter(&mut self) -> Result<()>1086 fn write_delimiter(&mut self) -> Result<()> { 1087 loop { 1088 let (res, nout) = self.core.delimiter(self.buf.writable()); 1089 self.buf.written(nout); 1090 match res { 1091 WriteResult::InputEmpty => return Ok(()), 1092 WriteResult::OutputFull => self.flush_buf()?, 1093 } 1094 } 1095 } 1096 1097 /// Write a CSV terminator. write_terminator(&mut self) -> Result<()>1098 fn write_terminator(&mut self) -> Result<()> { 1099 self.check_field_count()?; 1100 loop { 1101 let (res, nout) = self.core.terminator(self.buf.writable()); 1102 self.buf.written(nout); 1103 match res { 1104 WriteResult::InputEmpty => { 1105 self.state.fields_written = 0; 1106 return Ok(()); 1107 } 1108 WriteResult::OutputFull => self.flush_buf()?, 1109 } 1110 } 1111 } 1112 1113 /// Write a CSV terminator that is guaranteed to fit into the current 1114 /// buffer. 1115 #[inline(never)] write_terminator_into_buffer(&mut self) -> Result<()>1116 fn write_terminator_into_buffer(&mut self) -> Result<()> { 1117 self.check_field_count()?; 1118 match self.core.get_terminator() { 1119 csv_core::Terminator::CRLF => { 1120 self.buf.writable()[0] = b'\r'; 1121 self.buf.writable()[1] = b'\n'; 1122 self.buf.written(2); 1123 } 1124 csv_core::Terminator::Any(b) => { 1125 self.buf.writable()[0] = b; 1126 self.buf.written(1); 1127 } 1128 _ => unreachable!(), 1129 } 1130 self.state.fields_written = 0; 1131 Ok(()) 1132 } 1133 check_field_count(&mut self) -> Result<()>1134 fn check_field_count(&mut self) -> Result<()> { 1135 if !self.state.flexible { 1136 match self.state.first_field_count { 1137 None => { 1138 self.state.first_field_count = 1139 Some(self.state.fields_written); 1140 } 1141 Some(expected) if expected != self.state.fields_written => { 1142 return Err(Error::new(ErrorKind::UnequalLengths { 1143 pos: None, 1144 expected_len: expected, 1145 len: self.state.fields_written, 1146 })) 1147 } 1148 Some(_) => {} 1149 } 1150 } 1151 Ok(()) 1152 } 1153 } 1154 1155 impl Buffer { 1156 /// Returns a slice of the buffer's current contents. 1157 /// 1158 /// The slice returned may be empty. 1159 #[inline] readable(&self) -> &[u8]1160 fn readable(&self) -> &[u8] { 1161 &self.buf[..self.len] 1162 } 1163 1164 /// Returns a mutable slice of the remaining space in this buffer. 1165 /// 1166 /// The slice returned may be empty. 1167 #[inline] writable(&mut self) -> &mut [u8]1168 fn writable(&mut self) -> &mut [u8] { 1169 &mut self.buf[self.len..] 1170 } 1171 1172 /// Indicates that `n` bytes have been written to this buffer. 1173 #[inline] written(&mut self, n: usize)1174 fn written(&mut self, n: usize) { 1175 self.len += n; 1176 } 1177 1178 /// Clear the buffer. 1179 #[inline] clear(&mut self)1180 fn clear(&mut self) { 1181 self.len = 0; 1182 } 1183 } 1184 1185 #[cfg(test)] 1186 mod tests { 1187 use serde::{serde_if_integer128, Serialize}; 1188 1189 use std::io::{self, Write}; 1190 1191 use crate::byte_record::ByteRecord; 1192 use crate::error::ErrorKind; 1193 use crate::string_record::StringRecord; 1194 1195 use super::{Writer, WriterBuilder}; 1196 wtr_as_string(wtr: Writer<Vec<u8>>) -> String1197 fn wtr_as_string(wtr: Writer<Vec<u8>>) -> String { 1198 String::from_utf8(wtr.into_inner().unwrap()).unwrap() 1199 } 1200 1201 #[test] one_record()1202 fn one_record() { 1203 let mut wtr = WriterBuilder::new().from_writer(vec![]); 1204 wtr.write_record(&["a", "b", "c"]).unwrap(); 1205 1206 assert_eq!(wtr_as_string(wtr), "a,b,c\n"); 1207 } 1208 1209 #[test] one_string_record()1210 fn one_string_record() { 1211 let mut wtr = WriterBuilder::new().from_writer(vec![]); 1212 wtr.write_record(&StringRecord::from(vec!["a", "b", "c"])).unwrap(); 1213 1214 assert_eq!(wtr_as_string(wtr), "a,b,c\n"); 1215 } 1216 1217 #[test] one_byte_record()1218 fn one_byte_record() { 1219 let mut wtr = WriterBuilder::new().from_writer(vec![]); 1220 wtr.write_record(&ByteRecord::from(vec!["a", "b", "c"])).unwrap(); 1221 1222 assert_eq!(wtr_as_string(wtr), "a,b,c\n"); 1223 } 1224 1225 #[test] raw_one_byte_record()1226 fn raw_one_byte_record() { 1227 let mut wtr = WriterBuilder::new().from_writer(vec![]); 1228 wtr.write_byte_record(&ByteRecord::from(vec!["a", "b", "c"])).unwrap(); 1229 1230 assert_eq!(wtr_as_string(wtr), "a,b,c\n"); 1231 } 1232 1233 #[test] one_empty_record()1234 fn one_empty_record() { 1235 let mut wtr = WriterBuilder::new().from_writer(vec![]); 1236 wtr.write_record(&[""]).unwrap(); 1237 1238 assert_eq!(wtr_as_string(wtr), "\"\"\n"); 1239 } 1240 1241 #[test] raw_one_empty_record()1242 fn raw_one_empty_record() { 1243 let mut wtr = WriterBuilder::new().from_writer(vec![]); 1244 wtr.write_byte_record(&ByteRecord::from(vec![""])).unwrap(); 1245 1246 assert_eq!(wtr_as_string(wtr), "\"\"\n"); 1247 } 1248 1249 #[test] two_empty_records()1250 fn two_empty_records() { 1251 let mut wtr = WriterBuilder::new().from_writer(vec![]); 1252 wtr.write_record(&[""]).unwrap(); 1253 wtr.write_record(&[""]).unwrap(); 1254 1255 assert_eq!(wtr_as_string(wtr), "\"\"\n\"\"\n"); 1256 } 1257 1258 #[test] raw_two_empty_records()1259 fn raw_two_empty_records() { 1260 let mut wtr = WriterBuilder::new().from_writer(vec![]); 1261 wtr.write_byte_record(&ByteRecord::from(vec![""])).unwrap(); 1262 wtr.write_byte_record(&ByteRecord::from(vec![""])).unwrap(); 1263 1264 assert_eq!(wtr_as_string(wtr), "\"\"\n\"\"\n"); 1265 } 1266 1267 #[test] unequal_records_bad()1268 fn unequal_records_bad() { 1269 let mut wtr = WriterBuilder::new().from_writer(vec![]); 1270 wtr.write_record(&ByteRecord::from(vec!["a", "b", "c"])).unwrap(); 1271 let err = wtr.write_record(&ByteRecord::from(vec!["a"])).unwrap_err(); 1272 match *err.kind() { 1273 ErrorKind::UnequalLengths { ref pos, expected_len, len } => { 1274 assert!(pos.is_none()); 1275 assert_eq!(expected_len, 3); 1276 assert_eq!(len, 1); 1277 } 1278 ref x => { 1279 panic!("expected UnequalLengths error, but got '{:?}'", x); 1280 } 1281 } 1282 } 1283 1284 #[test] raw_unequal_records_bad()1285 fn raw_unequal_records_bad() { 1286 let mut wtr = WriterBuilder::new().from_writer(vec![]); 1287 wtr.write_byte_record(&ByteRecord::from(vec!["a", "b", "c"])).unwrap(); 1288 let err = 1289 wtr.write_byte_record(&ByteRecord::from(vec!["a"])).unwrap_err(); 1290 match *err.kind() { 1291 ErrorKind::UnequalLengths { ref pos, expected_len, len } => { 1292 assert!(pos.is_none()); 1293 assert_eq!(expected_len, 3); 1294 assert_eq!(len, 1); 1295 } 1296 ref x => { 1297 panic!("expected UnequalLengths error, but got '{:?}'", x); 1298 } 1299 } 1300 } 1301 1302 #[test] unequal_records_ok()1303 fn unequal_records_ok() { 1304 let mut wtr = WriterBuilder::new().flexible(true).from_writer(vec![]); 1305 wtr.write_record(&ByteRecord::from(vec!["a", "b", "c"])).unwrap(); 1306 wtr.write_record(&ByteRecord::from(vec!["a"])).unwrap(); 1307 assert_eq!(wtr_as_string(wtr), "a,b,c\na\n"); 1308 } 1309 1310 #[test] raw_unequal_records_ok()1311 fn raw_unequal_records_ok() { 1312 let mut wtr = WriterBuilder::new().flexible(true).from_writer(vec![]); 1313 wtr.write_byte_record(&ByteRecord::from(vec!["a", "b", "c"])).unwrap(); 1314 wtr.write_byte_record(&ByteRecord::from(vec!["a"])).unwrap(); 1315 assert_eq!(wtr_as_string(wtr), "a,b,c\na\n"); 1316 } 1317 1318 #[test] full_buffer_should_not_flush_underlying()1319 fn full_buffer_should_not_flush_underlying() { 1320 struct MarkWriteAndFlush(Vec<u8>); 1321 1322 impl MarkWriteAndFlush { 1323 fn to_str(self) -> String { 1324 String::from_utf8(self.0).unwrap() 1325 } 1326 } 1327 1328 impl Write for MarkWriteAndFlush { 1329 fn write(&mut self, data: &[u8]) -> io::Result<usize> { 1330 self.0.write(b">")?; 1331 let written = self.0.write(data)?; 1332 self.0.write(b"<")?; 1333 1334 Ok(written) 1335 } 1336 1337 fn flush(&mut self) -> io::Result<()> { 1338 self.0.write(b"!")?; 1339 Ok(()) 1340 } 1341 } 1342 1343 let underlying = MarkWriteAndFlush(vec![]); 1344 let mut wtr = 1345 WriterBuilder::new().buffer_capacity(4).from_writer(underlying); 1346 1347 wtr.write_byte_record(&ByteRecord::from(vec!["a", "b"])).unwrap(); 1348 wtr.write_byte_record(&ByteRecord::from(vec!["c", "d"])).unwrap(); 1349 wtr.flush().unwrap(); 1350 wtr.write_byte_record(&ByteRecord::from(vec!["e", "f"])).unwrap(); 1351 1352 let got = wtr.into_inner().unwrap().to_str(); 1353 1354 // As the buffer size is 4 we should write each record separately, and 1355 // flush when explicitly called and implictly in into_inner. 1356 assert_eq!(got, ">a,b\n<>c,d\n<!>e,f\n<!"); 1357 } 1358 1359 #[test] serialize_with_headers()1360 fn serialize_with_headers() { 1361 #[derive(Serialize)] 1362 struct Row { 1363 foo: i32, 1364 bar: f64, 1365 baz: bool, 1366 } 1367 1368 let mut wtr = WriterBuilder::new().from_writer(vec![]); 1369 wtr.serialize(Row { foo: 42, bar: 42.5, baz: true }).unwrap(); 1370 assert_eq!(wtr_as_string(wtr), "foo,bar,baz\n42,42.5,true\n"); 1371 } 1372 1373 #[test] serialize_no_headers()1374 fn serialize_no_headers() { 1375 #[derive(Serialize)] 1376 struct Row { 1377 foo: i32, 1378 bar: f64, 1379 baz: bool, 1380 } 1381 1382 let mut wtr = 1383 WriterBuilder::new().has_headers(false).from_writer(vec![]); 1384 wtr.serialize(Row { foo: 42, bar: 42.5, baz: true }).unwrap(); 1385 assert_eq!(wtr_as_string(wtr), "42,42.5,true\n"); 1386 } 1387 1388 serde_if_integer128! { 1389 #[test] 1390 fn serialize_no_headers_128() { 1391 #[derive(Serialize)] 1392 struct Row { 1393 foo: i128, 1394 bar: f64, 1395 baz: bool, 1396 } 1397 1398 let mut wtr = 1399 WriterBuilder::new().has_headers(false).from_writer(vec![]); 1400 wtr.serialize(Row { 1401 foo: 9_223_372_036_854_775_808, 1402 bar: 42.5, 1403 baz: true, 1404 }).unwrap(); 1405 assert_eq!(wtr_as_string(wtr), "9223372036854775808,42.5,true\n"); 1406 } 1407 } 1408 1409 #[test] serialize_tuple()1410 fn serialize_tuple() { 1411 let mut wtr = WriterBuilder::new().from_writer(vec![]); 1412 wtr.serialize((true, 1.3, "hi")).unwrap(); 1413 assert_eq!(wtr_as_string(wtr), "true,1.3,hi\n"); 1414 } 1415 } 1416