Crate fixed_width

The fixed_width crate is designed to facilitate easy reading and writing of fixed width files. It also provides a few useful abstractions to ease serializing and deserializing data into and out of fixed width files.

Users of the crate will primarily use Reader to read fixed width data and Writer to write it.

You can read or write data as Vec<String> or as Vec<Vec<u8>>. If you use serde, then you can also (de)serialize into and out of structs, HashMaps, etc. Since fixed width files are not self describing, you will need to define the set of Field definitions for your data up front so the (de)serialization code can work.

Several errors may occur while using the library. These are defined in the Error type.

Installing

Start by adding the dependency to your project in Cargo.toml:

fixed_width = "0.1"

Then in the root of your project:

extern crate fixed_width;

There is also the fixed_width_derive crate that provides a struct attribute syntax to ease deriving field definitions for your types. It is optional, but if you wish to use it you can add it to your project like so in your Cargo.toml:

fixed_width = "0.1"
fixed_width_derive = "0.1"

Usage

Reading a String:

use fixed_width::Reader;
use std::result;

let mut reader = Reader::from_string("record1record2").width(7);

let records: Vec<String> = reader.string_reader()
                                 .filter_map(result::Result::ok)
                                 .collect();

Reading a String into a Vec of user defined structs:

#[macro_use]
extern crate serde_derive;
extern crate serde;
extern crate fixed_width;

use fixed_width::{Reader, FixedWidth, Field};
use std::result;

#[derive(Deserialize)]
struct Person {
    pub name: String,
    pub age: usize,
}

impl FixedWidth for Person {
    fn fields() -> Vec<Field> {
        vec![
            Field::default().range(0..6),
            Field::default().range(6..9),
        ]
    }
}

fn main() {
    let mut reader = Reader::from_string("foobar 25barfoo 35").width(9);
    let records: Vec<Person> = reader.byte_reader()
                                     .filter_map(result::Result::ok)
                                     .map(|bytes| fixed_width::from_bytes(&bytes).unwrap())
                                     .collect();
}

Structs

ByteReader	An iterator of Vec<u8> records.
Deserializer	A deserialized for fixed width data. Reads from the given bytes using the provided field definitions to determine how many bytes to read for each deserialized value.
Field	Defines a field in a fixed width record. There can be 1 or more fields in a fixed width record.
Reader	A fixed width data reader. It parses fixed width data and provides the data via iterators.
Serializer	A serializer for fixed width data. Writes to the given Writer using the provided field definitions to determine how to serialize data into records.
StringReader	An iterator of String records.
Writer	A fixed width data writer. It writes data provided in iterators to any type that implements io::Write.

Enums

DeserializeError	Errors that occur during deserialization.
Error	An error produced while parsing fixed width data.
Justify	Justification of a fixed width field.
LineBreak	The type of line break between each record that should be inserted or skipped while reading.
SerializeError	Errors that occur during serialization.

Traits

AsByteSlice	A trait to ease converting byte like data into a byte slice. This allows handling these types with one generic function.
FixedWidth	Defines fixed width field definitions for a type.

Functions

from_bytes	Deserializes a &[u8] into the given type that implements FixedWidth and Deserialize.
from_bytes_with_fields	Deserializes &[u8] data to the given writer using the provided Fields.
from_str	Deserializes a &str into the given type that implements FixedWidth and Deserialize.
from_str_with_fields	Deserializes &str data to the given writer using the provided Fields.
to_bytes	Serializes the given type that implements FixedWidth and Serialize to a String.
to_string	Serializes the given type that implements FixedWidth and Serialize to a String.
to_writer	Serializes a type that implements FixedWidth to the given writer. Similar to to_writer_with_fields, but this function uses the fields defined in the trait implementation.
to_writer_with_fields	Serializes data to the given writer using the provided Fields.

Type Definitions

Result

Convenience type for Result types pertaining to this library.