fixed_width

Crates.iofixed_width
lib.rsfixed_width
version0.6.0
sourcesrc
created_at2018-07-31 23:51:21.596503
updated_at2024-04-23 03:26:45.698501
descriptionA fixed width data parser.
homepage
repositoryhttps://github.com/twking7/fixed_width
max_upload_size
id76889
size101,911
Tom King (twking7)

documentation

README

Fixed Width   [Build Status][tests] Latest Version Documents

The fixed_width crate is designed to facilitate easy reading and writing of fixed width files with serde support.

Fixed width in this case means that each line of the file is the same number of bytes. It supports unicode, but only if the unicode fits in the designated byte size of the record. It also provides a few useful abstractions to ease serializing and deserializing data into and out of fixed width files.

Usage

Add as a dependency:

[dependencies]
fixed_width = "0.6"

# Optionally, if you are running Rust version 1.30.0 or above and want to derive fixed width field definitions:
fixed_width_derive = "0.6"

in the root of your crate:

use fixed_width;

// and if you are using fixed_width_derive:
use fixed_width_derive::FixedWidth;

Example

Read fixed width data from a &str:

use fixed_width::{FixedWidth, Reader};

let data = "1234554321";
let mut reader = Reader::from_string(data).width(5);

for record in reader.string_reader().filter_map(std::result::Result::ok) {
    // Prints "12345" and then "54321"
    println!("{}", record);
}

Read data from a &str using serde, using fixed_width_derive:

use fixed_width::{FixedWidth, Reader};
use fixed_width_derive::FixedWidth;
use serde_derive::Deserialize;

// It is not necessary to use `fixed_width_derive`, you can manually implement the `FixedWidth` trait.
#[derive(FixedWidth, Deserialize)]
struct Record {
    #[fixed_width(range = "0..5")]
    pub n: usize,
}

let data = "1234554321";

let mut reader = Reader::from_string(data).width(5);

for bytes in reader.byte_reader().filter_map(std::result::Result::ok) {
    // You must specify the type for deserialization
    let record: Record = fixed_width::from_bytes(&bytes).unwrap();

    // Prints "12345" and then "54321"
    println!("{}", record.n);
}

Read data where there are different record types in the file:

use fixed_width::{FixedWidth, Reader};
use fixed_width_derive::FixedWidth;
use serde_derive::Deserialize;

#[derive(FixedWidth, Deserialize)]
struct Record1 {
    #[fixed_width(range = "0..1")]
    pub record_type: usize,
    #[fixed_width(range = "1..5")]
    pub state: String,
}

#[derive(FixedWidth, Deserialize)]
struct Record2 {
    #[fixed_width(range = "0..1")]
    pub record_type: usize,
    #[fixed_width(range = "1..5")]
    pub name: String,
}

let data = "0OHIO1 BOB";

let mut reader = Reader::from_string(data).width(5);

while let Some(Ok(bytes)) = reader.next_record() {
    match bytes.get(0) {
        Some(b'0') => {
            let Record1 { state, .. } = fixed_width::from_bytes(bytes).unwrap();
            assert_eq!(state, "OHIO");
        }
        Some(b'1') => {
            let Record2 { name, .. } = fixed_width::from_bytes(bytes).unwrap();
            assert_eq!(name, "BOB");
        }
        Some(_) => {}
        None => {}
    }
}

Read data from a file:

use fixed_width::Reader;
use std::fs;

// from a file path on disk
let filepath = "/path/to/file.txt";
let mut reader = Reader::from_file(filepath).width(5);

// from a file handle
let file = fs::File::open(filepath);
let mut reader = Reader::from_reader(file).width(5);

License

Licensed under MIT.

Contributing

Issues and pull requests are welcome, please add tests and documentation (if necessary) for any changes you submit.

Commit count: 62

cargo fmt