README.md

Fixcol

A library for reading fixed width / column delimited data files.

Basic Usage

Consider the following data file:

Tokyo       13515271   35.689  139.692
Delhi       16753235   28.610   77.230
Shanghai    24870895   31.229  121.475
São Paulo   12252023  -23.550  -46.333
Mexico City  9209944   19.433  -99.133

We can create a basic data structure corresponding to the records in the file and then read the data file as shown.

use fixcol::ReadFixed;
use std::fs::File;

#[derive(ReadFixed)]
struct City {
    #[fixcol(width = 12)]
    name: String,
    #[fixcol(width = 8, align = "right")]
    population: u64,
    #[fixcol(skip = 1, width = 8, align = "right")]
    lat: f32,
    #[fixcol(skip = 1, width = 8, align = "right")]
    lon: f32,
}

let mut file = File::open("cities.txt")?;
let cities: Vec<City> = City::read_fixed_all(file).map(|res| match res {
    Ok(city) => city,
    Err(err) => {
        eprintln!("{}", err);
        std::process::exit(1);
    }
}).collect();

Multiple Record Types

Many data files contain lines corresponding to multiple types of records. Typically the record type is indicated by the first few columns of the line. In Fixcol we call this the key of the record. Multiple record types can be decoded using an enum with a key annotation.

Consider a directed graph with named nodes defined in a data file like the following.

NODE 001 Item A
NODE 002 Item B
EDGE 001 002

This file can be parsed with an enum like the following.

use fixcol::ReadFixed;

#[derive(ReadFixed)]
#[fixcol(key_width = 4)]
enum GraphItem {
   #[fixcol(key = "NODE")]
   Node {
       #[fixcol(skip = 1, width = 3)]
       id: u8,
       #[fixcol(skip = 1, width = 6)]
       name: String,
   },
   #[fixcol(key = "EDGE")]
   Edge {
       #[fixcol(skip = 1, width = 3)]
       from_id: u8,
       #[fixcol(skip = 1, width = 3)]
       to_id: u8,
   },
}

Please see the official documentation for complete usage guidance.

License

Licensed under the MIT license. See: LICENSE.