Skip to main content

fixed_record/
io.rs

1#[cfg(feature = "list")]
2use crate::traits::RecordWithList;
3use crate::{Error, FixedRecord, traits::SequenceFields};
4use std::cmp::Ordering;
5use std::io::{self, BufRead, Write};
6use std::marker::PhantomData;
7
8/// Separator written after each record by [`Writer`].
9/// [`Writer`] が各レコードの後ろに書き出す区切りです。
10#[derive(Debug, Clone, Copy, PartialEq, Eq)]
11pub enum RecordSeparator {
12    /// No separator.
13    /// 区切りなしです。
14    None,
15    /// Line feed (`\n`).
16    /// LF (`\n`) です。
17    Lf,
18    /// Carriage return (`\r`).
19    /// CR (`\r`) です。
20    Cr,
21    /// Carriage return and line feed (`\r\n`).
22    /// CRLF (`\r\n`) です。
23    Crlf,
24    /// Comma (`,`).
25    /// カンマ (`,`) です。
26    Comma,
27}
28
29impl RecordSeparator {
30    /// Returns the byte sequence for this separator.
31    /// この区切りを表すバイト列を返します。
32    pub const fn as_bytes(self) -> &'static [u8] {
33        match self {
34            Self::None => b"",
35            Self::Lf => b"\n",
36            Self::Cr => b"\r",
37            Self::Crlf => b"\r\n",
38            Self::Comma => b",",
39        }
40    }
41}
42
43/// Iterator that reads fixed-width records from a stream.
44/// 固定長レコードをストリームから順に読み込むイテレータです。
45///
46/// `Reader::new` expects LF (`\n`) after records. Use [`Reader::with_separator`] when the input
47/// uses a different separator or no separator.
48/// `Reader::new` はレコード後ろに LF (`\n`) がある入力を想定します。別の区切り、または区切りなしの
49/// 入力を読む場合は [`Reader::with_separator`] で指定します。
50///
51/// When a separator is configured, it must appear after every record, including the final record.
52/// 区切りを設定した場合は、最終レコードを含むすべてのレコード後ろにその区切りが必要です。
53///
54/// # Examples
55///
56/// ```
57/// use fixed_record::prelude::*;
58/// use std::io::{BufReader, Cursor};
59///
60/// #[fixed_record]
61/// pub struct Payment {
62///     id: Fixed<4>,
63///     amount: Fixed<6>,
64/// }
65///
66/// let first = Payment::builder()
67///     .with_id("A001")
68///     .with_amount_int(1200)
69///     .build();
70/// let second = Payment::builder()
71///     .with_id("A002")
72///     .with_amount_int(3400)
73///     .build();
74///
75/// let mut input = Vec::new();
76/// input.extend_from_slice(&first.to_bytes());
77/// input.extend_from_slice(b"\r\n");
78/// input.extend_from_slice(&second.to_bytes());
79/// input.extend_from_slice(b"\r\n");
80///
81/// let mut reader = Reader::<_, Payment>::new(BufReader::new(Cursor::new(input)))
82///     .with_separator(RecordSeparator::Crlf);
83///
84/// assert_eq!(
85///     reader.next().unwrap().unwrap().get_field_trimmed(PaymentField::Id).unwrap(),
86///     "A001"
87/// );
88/// assert_eq!(
89///     reader.next().unwrap().unwrap().get_field_trimmed(PaymentField::Amount).unwrap(),
90///     "003400"
91/// );
92/// assert!(reader.next().is_none());
93/// ```
94pub struct Reader<R, T: FixedRecord> {
95    reader: R,
96    separator: RecordSeparator,
97    sequence_fields: Vec<T::Field>,
98    allow_equal_sequence: bool,
99    previous_sequence_key: Option<Vec<Vec<u8>>>,
100    _marker: PhantomData<T>,
101}
102
103impl<R: BufRead, T: FixedRecord> Reader<R, T> {
104    /// Creates a new reader.
105    /// 新しいリーダーを作成します。
106    pub fn new(reader: R) -> Self {
107        Self {
108            reader,
109            separator: RecordSeparator::Lf,
110            sequence_fields: Vec::new(),
111            allow_equal_sequence: true,
112            previous_sequence_key: None,
113            _marker: PhantomData,
114        }
115    }
116
117    /// Configures the separator expected after records.
118    /// レコードの後ろに期待する区切りを設定します。
119    ///
120    /// `RecordSeparator::None` means records are adjacent with no bytes between them.
121    /// `RecordSeparator::None` は、レコード間に区切りバイトがないことを表します。
122    pub fn with_separator(mut self, separator: RecordSeparator) -> Self {
123        self.separator = separator;
124        self
125    }
126
127    /// Enables ascending sequence checks using the specified fields as the key.
128    /// 指定フィールドをキーにした昇順シーケンスチェックを有効にします。
129    pub fn with_sequence_check<F>(mut self, fields: F) -> Self
130    where
131        F: SequenceFields<T>,
132    {
133        self.set_sequence_check_fields(fields.to_sequence_fields());
134        self
135    }
136
137    /// Configures ascending sequence checks using the specified fields as the key.
138    /// 指定フィールドをキーにした昇順シーケンスチェックを設定します。
139    pub fn with_sequence_check_options<F>(mut self, fields: F, allow_equal: bool) -> Self
140    where
141        F: SequenceFields<T>,
142    {
143        self.set_sequence_check_fields(fields.to_sequence_fields());
144        self.allow_equal_sequence = allow_equal;
145        self
146    }
147
148    /// Stores the fields used for sequence checks.
149    /// シーケンスチェック対象フィールドを設定します。
150    fn set_sequence_check_fields(&mut self, fields: Vec<T::Field>) {
151        for (index, field) in fields.iter().enumerate() {
152            if fields[index + 1..].contains(field) {
153                panic!("duplicate sequence check field `{}`", T::field_name(*field));
154            }
155        }
156
157        self.sequence_fields = fields;
158    }
159
160    /// Verifies that the loaded record is ordered after the previous record.
161    /// 読み込んだレコードが前回レコード以降の順序になっているか確認します。
162    fn check_sequence(&mut self, record: &T) -> Result<(), Error> {
163        if self.sequence_fields.is_empty() {
164            return Ok(());
165        }
166
167        let current_key: Vec<Vec<u8>> = self
168            .sequence_fields
169            .iter()
170            .map(|field| record.field_bytes(*field).to_vec())
171            .collect();
172
173        if let Some(previous_key) = &self.previous_sequence_key {
174            let ordering = current_key.cmp(previous_key);
175            let is_error = ordering == Ordering::Less
176                || (ordering == Ordering::Equal && !self.allow_equal_sequence);
177            if is_error {
178                return Err(Error::SequenceError {
179                    fields: self
180                        .sequence_fields
181                        .iter()
182                        .map(|field| T::field_name(*field))
183                        .collect(),
184                    previous: previous_key.clone(),
185                    current: current_key,
186                });
187            }
188        }
189
190        self.previous_sequence_key = Some(current_key);
191        Ok(())
192    }
193}
194
195impl<R: BufRead, T: FixedRecord> Iterator for Reader<R, T> {
196    type Item = Result<T, Error>;
197
198    /// Reads the next fixed-width record, returning end-of-stream or an error when appropriate.
199    /// 次の固定長レコードを読み込み、終端またはエラーを返します。
200    fn next(&mut self) -> Option<Self::Item> {
201        let mut buf = vec![0u8; T::TOTAL_LEN];
202        let mut read_len = 0;
203
204        while read_len < T::TOTAL_LEN {
205            match self.reader.read(&mut buf[read_len..]) {
206                Ok(0) if read_len == 0 => return None,
207                Ok(0) => {
208                    return Some(Err(Error::IncompleteRecord {
209                        expected: T::TOTAL_LEN,
210                        actual: read_len,
211                    }));
212                }
213                Ok(n) => read_len += n,
214                Err(err) => return Some(Err(Error::Io(err))),
215            }
216        }
217
218        let record = match T::parse(&buf) {
219            Ok(record) => record,
220            Err(err) => return Some(Err(err)),
221        };
222
223        let separator = self.separator.as_bytes();
224        if !separator.is_empty() {
225            let available = match self.reader.fill_buf() {
226                Ok(bytes) => bytes,
227                Err(err) => return Some(Err(Error::Io(err))),
228            };
229
230            if available.starts_with(separator) {
231                self.reader.consume(separator.len());
232            } else {
233                let actual_len = available.len().min(separator.len());
234                return Some(Err(Error::UnexpectedSeparator {
235                    expected: separator,
236                    actual: available[..actual_len].to_vec(),
237                }));
238            }
239        }
240
241        if let Err(err) = self.check_sequence(&record) {
242            return Some(Err(err));
243        }
244
245        Some(Ok(record))
246    }
247}
248
249#[cfg(feature = "list")]
250impl<R: BufRead, T: RecordWithList> Reader<R, T> {
251    /// Reads all remaining records and builds their generated List with field indexes.
252    /// 残りの全レコードを読み込み、フィールド索引を持つ生成済み List を構築します。
253    ///
254    /// Returns the first parsing, separator, sequence, or I/O error without producing a partial List.
255    /// parse、separator、sequence、I/O の最初のエラーを返し、途中までの List は返しません。
256    pub fn collect_list(self) -> Result<T::List, Error> {
257        let records = self.collect::<Result<Vec<_>, _>>()?;
258        Ok(records.into())
259    }
260}
261
262/// Writer for fixed-width records.
263/// 固定長レコードをストリームへ書き出すライターです。
264///
265/// During writing, NUL bytes (`0x00`) are replaced with spaces (`0x20`) and a separator is appended.
266/// 書き込み時は NUL (`0x00`) をスペース (`0x20`) に置換し、レコード末尾に区切りを付けます。
267///
268/// The inner writer is flushed automatically when `Writer` is dropped, but explicit [`Writer::flush`]
269/// is recommended when callers need to handle I/O errors before the writer goes out of scope.
270/// `Writer` が drop されるときに内部 writer は自動的に flush されます。ただし、I/O エラーを明示的に扱いたい場合は
271/// [`Writer::flush`] を呼び出してください。
272///
273/// # Examples
274///
275/// ```
276/// use fixed_record::prelude::*;
277///
278/// #[fixed_record]
279/// pub struct Payment {
280///     id: Fixed<4>,
281///     amount: Fixed<6>,
282/// }
283///
284/// let first = Payment::builder()
285///     .with_id("A001")
286///     .with_amount_int(1200)
287///     .build();
288/// let second = Payment::builder()
289///     .with_id("A002")
290///     .with_amount_int(3400)
291///     .build();
292///
293/// let mut output = Vec::new();
294/// let mut writer = Writer::new(&mut output)
295///     .with_separator(RecordSeparator::Comma);
296///
297/// writer.write_all([&first, &second]).unwrap();
298/// writer.flush().unwrap();
299/// drop(writer);
300///
301/// let mut expected = Vec::new();
302/// expected.extend_from_slice(&first.to_bytes());
303/// expected.push(b',');
304/// expected.extend_from_slice(&second.to_bytes());
305/// expected.push(b',');
306///
307/// assert_eq!(output, expected);
308/// ```
309pub struct Writer<W: Write> {
310    writer: W,
311    separator: &'static [u8],
312}
313
314impl<W: Write> Writer<W> {
315    /// Creates a writer that uses `\n` as the default separator.
316    /// デフォルト区切り `\n` でライターを作成します。
317    pub fn new(writer: W) -> Self {
318        Self {
319            writer,
320            separator: RecordSeparator::Lf.as_bytes(),
321        }
322    }
323
324    /// Changes the separator used after each record.
325    /// レコードごとの区切りを変更します。
326    pub fn with_separator(mut self, separator: RecordSeparator) -> Self {
327        self.separator = separator.as_bytes();
328        self
329    }
330
331    /// Writes one record.
332    /// レコードを1件書き込みます。
333    pub fn write_record<T: FixedRecord>(&mut self, record: &T) -> io::Result<()> {
334        let mut bytes = record.to_bytes();
335        for byte in &mut bytes {
336            if *byte == 0x00 {
337                *byte = b' ';
338            }
339        }
340
341        self.writer.write_all(&bytes)?;
342        self.writer.write_all(self.separator)?;
343        Ok(())
344    }
345
346    /// Writes all borrowed records in iterator order.
347    /// 借用した全レコードをイテレータの順序で書き込みます。
348    ///
349    /// Each record uses the configured separator. Writing stops at the first I/O error.
350    /// 各レコードには設定済みの区切りを使います。最初の I/O エラーで書き込みを停止します。
351    pub fn write_all<'a, T, I>(&mut self, records: I) -> io::Result<()>
352    where
353        T: FixedRecord + 'a,
354        I: IntoIterator<Item = &'a T>,
355    {
356        for record in records {
357            self.write_record(record)?;
358        }
359        Ok(())
360    }
361
362    /// Flushes the inner writer.
363    /// 内部ライターを flush します。
364    pub fn flush(&mut self) -> io::Result<()> {
365        self.writer.flush()
366    }
367}
368
369impl<W: Write> Drop for Writer<W> {
370    /// Flushes the inner writer when this writer goes out of scope.
371    /// スコープを抜けるときに内部 writer を flush します。
372    fn drop(&mut self) {
373        let _ = self.writer.flush();
374    }
375}
376
377#[cfg(test)]
378mod tests {
379    use super::*;
380    use std::cell::RefCell;
381    use std::io::{BufReader, Cursor, Read, Write};
382    use std::rc::Rc;
383
384    #[derive(Debug, PartialEq, Eq)]
385    struct TestRecord([u8; 4]);
386
387    impl FixedRecord for TestRecord {
388        type Field = ();
389
390        const TOTAL_LEN: usize = 4;
391
392        /// Creates the test record from a 4-byte input.
393        /// 4バイトの入力からテスト用レコードを作成します。
394        fn parse(src: &[u8]) -> Result<Self, Error> {
395            if src.len() < Self::TOTAL_LEN {
396                return Err(Error::TooShort);
397            }
398            let mut bytes = [0; 4];
399            bytes.copy_from_slice(&src[..4]);
400            Ok(Self(bytes))
401        }
402
403        /// Returns the internal bytes of the test record.
404        /// テスト用レコードの内部バイト列を返します。
405        fn to_bytes(&self) -> Vec<u8> {
406            self.0.to_vec()
407        }
408
409        /// Returns a fixed name because this test record has no named fields.
410        /// テスト用レコードには名前付きフィールドがないため固定名を返します。
411        fn field_name(_field: Self::Field) -> &'static str {
412            "record"
413        }
414
415        /// Returns the entire test record as the sequence-check byte key.
416        /// テスト用レコード全体をシーケンスチェック用バイト列として返します。
417        fn field_bytes(&self, _field: Self::Field) -> &[u8] {
418            &self.0
419        }
420    }
421
422    struct FillBufErrorAfterRead {
423        cursor: Cursor<Vec<u8>>,
424    }
425
426    impl Read for FillBufErrorAfterRead {
427        /// Reads bytes normally from the inner cursor.
428        /// 内部カーソルから通常どおりバイト列を読み込みます。
429        fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
430            self.cursor.read(buf)
431        }
432    }
433
434    impl BufRead for FillBufErrorAfterRead {
435        /// Produces an I/O error while the reader checks the configured separator.
436        /// 設定された区切りの確認中に I/O エラーを発生させます。
437        fn fill_buf(&mut self) -> io::Result<&[u8]> {
438            Err(io::Error::other("fill_buf failed"))
439        }
440
441        /// Does nothing because this helper is only used by tests.
442        /// テスト用なのでバッファ消費は何もしません。
443        fn consume(&mut self, _amt: usize) {}
444    }
445
446    struct TrackingBufRead {
447        cursor: Cursor<Vec<u8>>,
448        consume_amounts: Rc<RefCell<Vec<usize>>>,
449    }
450
451    impl Read for TrackingBufRead {
452        /// Reads bytes normally from the inner cursor.
453        /// 内部カーソルから通常どおりバイト列を読み込みます。
454        fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
455            self.cursor.read(buf)
456        }
457    }
458
459    struct FlushTrackingWriter {
460        bytes: Rc<RefCell<Vec<u8>>>,
461        flush_count: Rc<RefCell<usize>>,
462    }
463
464    impl Write for FlushTrackingWriter {
465        /// Appends bytes to the shared buffer.
466        /// 共有バッファにバイト列を追加します。
467        fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
468            self.bytes.borrow_mut().extend_from_slice(buf);
469            Ok(buf.len())
470        }
471
472        /// Records that a flush was requested.
473        /// flush が要求されたことを記録します。
474        fn flush(&mut self) -> io::Result<()> {
475            *self.flush_count.borrow_mut() += 1;
476            Ok(())
477        }
478    }
479
480    impl BufRead for TrackingBufRead {
481        /// Returns the remaining bytes from the current cursor position.
482        /// 現在のカーソル位置から残りのバイト列を返します。
483        fn fill_buf(&mut self) -> io::Result<&[u8]> {
484            let position = self.cursor.position() as usize;
485            Ok(&self.cursor.get_ref()[position..])
486        }
487
488        /// Records the consumed byte count and advances the cursor.
489        /// 消費したバイト数を記録してカーソルを進めます。
490        fn consume(&mut self, amt: usize) {
491            self.consume_amounts.borrow_mut().push(amt);
492            let position = self.cursor.position() + amt as u64;
493            self.cursor.set_position(position);
494        }
495    }
496
497    /// Verifies that empty input is treated as a clean end-of-stream.
498    /// 入力が空のときに正常な終端として `None` を返すことを確認します。
499    #[test]
500    fn reader_returns_none_on_clean_eof() {
501        let mut reader = Reader::<_, TestRecord>::new(BufReader::new(Cursor::new(Vec::new())));
502
503        assert!(reader.next().is_none());
504    }
505
506    /// Verifies that EOF in the middle of a record returns `IncompleteRecord`.
507    /// レコード途中で EOF になったときに `IncompleteRecord` を返すことを確認します。
508    #[test]
509    fn reader_returns_incomplete_record_on_short_tail() {
510        let mut reader = Reader::<_, TestRecord>::new(BufReader::new(Cursor::new(b"abc".to_vec())));
511
512        let err = reader.next().unwrap().unwrap_err();
513        assert!(matches!(
514            err,
515            Error::IncompleteRecord {
516                expected: 4,
517                actual: 3
518            }
519        ));
520    }
521
522    /// Verifies that an I/O error while checking a configured separator is returned as `Error::Io`.
523    /// 設定された区切りを確認する途中の I/O エラーが `Error::Io` として返ることを確認します。
524    #[test]
525    fn reader_returns_io_error_from_fill_buf() {
526        let mut reader = Reader::<_, TestRecord>::new(FillBufErrorAfterRead {
527            cursor: Cursor::new(b"abcd".to_vec()),
528        })
529        .with_separator(RecordSeparator::Lf);
530
531        let err = reader.next().unwrap().unwrap_err();
532        assert!(matches!(err, Error::Io(_)));
533    }
534
535    /// Verifies that adjacent records are read when no separator is explicitly configured.
536    /// 区切りなしを明示設定した場合に連続したレコードを読めることを確認します。
537    #[test]
538    fn reader_accepts_adjacent_records_with_none_separator() {
539        let mut reader =
540            Reader::<_, TestRecord>::new(BufReader::new(Cursor::new(b"abcdefgh".to_vec())))
541                .with_separator(RecordSeparator::None);
542
543        assert_eq!(reader.next().unwrap().unwrap(), TestRecord(*b"abcd"));
544        assert_eq!(reader.next().unwrap().unwrap(), TestRecord(*b"efgh"));
545        assert!(reader.next().is_none());
546    }
547
548    /// Verifies that a configured separator must match the input.
549    /// 設定した区切りが入力と一致する必要があることを確認します。
550    #[test]
551    fn reader_rejects_unexpected_separator() {
552        let mut reader =
553            Reader::<_, TestRecord>::new(BufReader::new(Cursor::new(b"abcd,efgh".to_vec())))
554                .with_separator(RecordSeparator::Lf);
555
556        assert_eq!(
557            reader.next().unwrap().unwrap_err(),
558            Error::UnexpectedSeparator {
559                expected: b"\n",
560                actual: b",".to_vec(),
561            }
562        );
563    }
564
565    /// Verifies that a configured separator is required after the final record too.
566    /// 設定した区切りが最終レコードの後ろにも必要であることを確認します。
567    #[test]
568    fn reader_rejects_missing_configured_separator_at_eof() {
569        let mut reader =
570            Reader::<_, TestRecord>::new(BufReader::new(Cursor::new(b"abcd".to_vec())))
571                .with_separator(RecordSeparator::Lf);
572
573        assert_eq!(
574            reader.next().unwrap().unwrap_err(),
575            Error::UnexpectedSeparator {
576                expected: b"\n",
577                actual: Vec::new(),
578            }
579        );
580    }
581
582    /// Verifies that CRLF separators are consumed as a single two-byte separator.
583    /// CRLF 区切りが 2 バイトの区切りとしてまとめて消費されることを確認します。
584    #[test]
585    fn reader_consumes_crlf_separator_together() {
586        let consume_amounts = Rc::new(RefCell::new(Vec::new()));
587        let input = b"abcd\r\nefgh\r\n".to_vec();
588        let mut reader = Reader::<_, TestRecord>::new(TrackingBufRead {
589            cursor: Cursor::new(input),
590            consume_amounts: Rc::clone(&consume_amounts),
591        })
592        .with_separator(RecordSeparator::Crlf);
593
594        assert_eq!(reader.next().unwrap().unwrap(), TestRecord(*b"abcd"));
595        assert_eq!(reader.next().unwrap().unwrap(), TestRecord(*b"efgh"));
596        assert!(reader.next().is_none());
597        assert_eq!(*consume_amounts.borrow(), vec![2, 2]);
598    }
599
600    /// Verifies that dropping `Writer` flushes the inner writer.
601    /// `Writer` の drop 時に内部 writer が flush されることを確認します。
602    #[test]
603    fn writer_flushes_inner_writer_on_drop() {
604        let bytes = Rc::new(RefCell::new(Vec::new()));
605        let flush_count = Rc::new(RefCell::new(0));
606
607        {
608            let inner = FlushTrackingWriter {
609                bytes: Rc::clone(&bytes),
610                flush_count: Rc::clone(&flush_count),
611            };
612            let mut writer = Writer::new(inner);
613            writer.write_record(&TestRecord(*b"abcd")).unwrap();
614        }
615
616        assert_eq!(&*bytes.borrow(), b"abcd\n");
617        assert_eq!(*flush_count.borrow(), 1);
618    }
619}