fixedwidth 0.4.2

  • Readme
  • Changelog
  • Example
  • Installing
  • 59

fixedwidth #

Build Status

A library for working with fixed width files in dart.

This library helps you easily create a Record layout that clearly describes the desired layout size and output formats. You can go both ways - taking a fixed width record and turning it into a dart object, or loading a dart object and outputting a fixed width string.

Usage #

To get started - first define your Record layout. Note that class constructors are not inherited and you'll need to include them in your own Record definition to get the fromString behavior.

import 'package:intl/intl.dart';
import 'package:fixedwidth/fixedwidth.dart';

class PersonRecord extends Record {
  StringField first_name = StringField(20);
  StringField last_name = StringField(20);
  DateTimeField dob =
      DateTimeField(10, format: DateFormat("yyyy-MM-dd"));
  IntegerField num_siblings = IntegerField(2, defaultValue: 0);
  DecimalField amount_due = DecimalField(8, decimals: 2);

  PersonRecord();
  PersonRecord.fromString(String record) : super.fromString(record);
}

You can take a Record, populate it, and turn it to a fixed width string.

var record = PersonRecord()
  ..first_name.value = "John"
  ..last_name.value = "Doe"
  ..dob.value = DateTime(1980, 4, 16)
  ..num_siblings.value = 2
  ..amount_due.value = 24.75;
print(record.toString());
print("Total Record Length: ${record.length()}");

You can also take a fixed width string and turn it into the appropriate dart object. Calling a field's value gives you the dart typed object.

var record2 = PersonRecord.fromString(
  "Benjamin            Franklin            1706-01-171600003.00");
print(record2.first_name);
print(record2.last_name);
print(record2.dob.value);
print(record2.num_siblings.value);
print(record2.amount_due.value);

Field Types: #

StringField #

This is the most common field. Just a string, padded to the right.

StringField name = StringField(15);

String Representation: right padded to the given length i.e.: "Peter          "

Dart Value: the raw string assigned ie. "Peter"

DateTimeField #

DateTimeField is for dates or timestamps. You can set desired output format on the field to control the string output.

Uses the intl library for date formatting.

DateTimeField completedDate = DateTimeField(10, format: DateFormat("yyyy-MM-dd"));

String Representation: Formatted date as defined by format. i.e. 2018-03-16

Dart Value: DateTime - 2018-03-16 14:53:02.030

IntegerField #
IntegerField amount = IntegerField(5);

String Representation: zero padded integer: 00300

Dart Value: int - 300

DecimalField #

A num type that outputs the desired length w/ decimals. Value will be rounded if necessary to shorten decimal precision.

DecimalField amount = DecimalField(8, decimals: 2);

String Representation: zero padded decimal: 00300.50

Dart Value: num - 300.50

ImpliedDecimalField #

With COBOL programs it used to be common to have implied decimals which means a decimal is implied at a certain spot, but not present.

ImpliedDecimalField amount = ImpliedDecimalField(7, decimals: 2);

String Representation: zero padded decimal: 0030075

Dart Value: num - 300.75

SignedImpliedDecimalField #

Same thing as Implied Decimal Field, but has a trailing sign that indicates whether the value is positive or negative.

If you'd like a signed integer field, just set decimals to 0

SignedImpliedDecimalField amount = SignedImpliedDecimalField(8, decimals: 2);

String Representation: : 0030075-

Dart Value: num - -300.75

BooleanField #
BooleanField isActive = BooleanField();

String Representation: 'Y' or 'N'

Dart Value: bool

NullBooleanField #

Like a BooleanField, but can also be null. This is sometimes used when a value is unset or unknown.

NullBooleanField likesPizza = NullBooleanField();

String Representation: 'Y', 'N', or ' '

Dart Value: bool

ListField #

ListField is like a nested record, but it is a list of records. Very similar to COBOL occurs functionality.

class ItemRecord extends Record {
    StringField sku = StringField(10);
    IntegerField qty = IntegerField(2);
    DecimalField amount = StringField(9, decimals: 2);

    ItemRecord();
    ItemRecord.fromString(String record) : super.fromString(record);
}

class Transaction extends Record {
    ListField orderItems = ListField(record: ItemRecord, occurs: 25);
    
    Transaction();
    Transaction.fromString(String record) : super.fromString(record);
}

String Representation: the entire padded string of the list of declared records

Dart Value: List of Record instances

Other Features #

defaultValue #

each field type accepts a defaultValue parameter. A field's value is initially set to the default value when it is instantiated.

StringField name = StringField(10, defaultValue: "Peter");
print("'${name.value}'");
print("'${name.toString()}'");

prints

'Peter'
'Peter     '
autoTruncate #

set autoTruncate = true If you want to automatically truncate the string value to fit the necessary fixed width length (instead of throwing an exception),

This is useful when you store data in fields longer than what the fixed width file layout requirement is.

class MyRecord extends Record {
    bool autoTruncate = true;
    
    StringField description = StringField(10);
}

var record = MyRecord()
  ..description.value = "Pigeons are super cool";
print("'${record.description.value}'");
print("'${record.toString()}'");

prints

'Pigeons are super cool'
'Pigeons ar'
Nested Records #

You can nest an entire record among other record fields.

Useful when parts of a record (like an address) are repeated in multiple places and it is less work to define the "sub-record" only once.

class AddressRecord extends Record {
    StringField address = StringField(60);
    StringField city = StringField(30);
    StringField state = StringField(2);
    StringField postalCode = StringField(12);

    AddressRecord();
    AddressRecord.fromString(String record) : super.fromString(record);
}

class Transaction extends Record {
    AddressRecord billingAddress = AddressRecord();
    AddressRecord shippingAddress = AddressRecord();
    
    Transaction();
    Transaction.fromString(String record) : super.fromString(record);
}

var txn = Transaction()
  ..billingAddress.address.value = "PO Box 255"
  ..billingAddress.city.value = "Des Moines"
  ..billingAddress.state.value = "IA"
  ..billingAddress.state.value = "50306"
  ..shippingAddress.address.value = "123 1st St"
  ..shippingAddress.city.value = "West Des Moines"
  ..shippingAddress.state.value = "IA"
  ..shippingAddress.state.value = "50266";

See the examples for additional usage samples.

Features and bugs #

Please file feature requests and bugs at the issue tracker.

Changelog #

0.4.2 #

  • Fixed more pana violations. No functional changes.

0.4.1 #

  • Fixed style violations. No functional changes.

0.4.0 #

  • Simplified nested records. Removed RecordField. Now you can just place a nested record straight on the parent
class AddressRecord extends Record {
    StringField address = StringField(60);
    StringField city = StringField(30);
    StringField state = StringField(2);
    StringField postalCode = StringField(12);

    AddressRecord();
    AddressRecord.fromString(String record) : super.fromString(record);
}

class Transaction extends Record {
    AddressRecord billingAddress = AddressRecord();
    AddressRecord shippingAddress = AddressRecord();
    
    Transaction();
    Transaction.fromString(String record) : super.fromString(record);
}
var txn = Transaction()
  ..billingAddress.address.value = "PO Box 255"
  ..billingAddress.city.value = "Des Moines"
  ..billingAddress.state.value = "IA"
  ..billingAddress.state.value = "50306"
  ..shippingAddress.address.value = "123 1st St"
  ..shippingAddress.city.value = "West Des Moines"
  ..shippingAddress.state.value = "IA"
  ..shippingAddress.state.value = "50266";

0.3.1 #

  • Changed pubspec sdk constraint to allow Dart 2

0.3.0 #

  • Added autoTruncate feature

    This helps in a scenario where you're storing data and you allow longer field values than the record you need to create. (i.e. format data for a third party service) Instead of always trimming your values for each field, you can just set autoTruncate = true on the record class and each field will be truncated down to the appropriate field record length.

0.2.0 #

  • Added ImpliedDecimalField
  • Added SignedImpliedDecimalField
  • Added RecordField
  • Added ListField
  • Breaking Change: Record.length is now a getter, not a method

0.1.0 #

  • Initial version.

    Contains StringField, IntegerField, DecimalField, DateTimeField, BooleanField, and NullBooleanField

0.0.1 #

  • placeholder to reserve pub.dartlang.org name

example/fixedwidth_example.dart

import 'package:intl/intl.dart';
import 'package:fixedwidth/fixedwidth.dart';

class PhoneNumber extends Record {
  IntegerField area_code = IntegerField(3);
  IntegerField prefix = IntegerField(3);
  IntegerField line_number = IntegerField(4);

  PhoneNumber();
  PhoneNumber.fromString(String record) : super.fromString(record);
}

/// Person Record demonstrates using most field types.
///
/// The phone_number field is a `RecordField` which is comprised of
/// an entire record.
class PersonRecord extends Record {
  StringField first_name = StringField(20);
  StringField last_name = StringField(20);
  DateTimeField dob = DateTimeField(10, format: DateFormat("yyyy-MM-dd"));
  IntegerField num_siblings = IntegerField(2, defaultValue: 0);
  DecimalField amount_due = DecimalField(8, decimals: 2);
  PhoneNumber phone_number = PhoneNumber();

  PersonRecord();
  PersonRecord.fromString(String record) : super.fromString(record);
}

main() {
  // You can take a Record, populate it, and turn it to a fixed width string.
  var record = PersonRecord()
    ..first_name.value = "John"
    ..last_name.value = "Doe"
    ..dob.value = DateTime(1980, 4, 16)
    ..num_siblings.value = 2
    ..amount_due.value = 24.75
    ..phone_number.area_code.value = 215
    ..phone_number.prefix.value = 222
    ..phone_number.line_number.value = 3333;
  print("'${record.toString()}'");
  print("Total Record Length: ${record.length}");

  // You can take a fixed width string and turn it into the appropriate
  // dart object
  var record2 = PersonRecord.fromString(
      "Benjamin            Franklin            1706-01-171600003.002151112222");
  print(record2.first_name);
  print(record2.last_name);
  print(record2.dob.value);
  print(record2.num_siblings.value);
  print(record2.amount_due.value);
  print(record2.phone_number.area_code.value);
  print(record2.phone_number.prefix.value);
  print(record2.phone_number.line_number.value);
}

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  fixedwidth: ^0.4.2

2. Install it

You can install packages from the command line:

with pub:


$ pub get

Alternatively, your editor might support pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:fixedwidth/fixedwidth.dart';
  
Popularity:
Describes how popular the package is relative to other packages. [more]
19
Health:
Code health derived from static analysis. [more]
100
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
100
Overall:
Weighted score of the above. [more]
59
Learn more about scoring.

We analyzed this package on Jan 19, 2020, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.7.0
  • pana: 0.13.4

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.0.0 <3.0.0
intl ^0.16.1 0.16.1
Transitive dependencies
path 1.6.4
Dev dependencies
test ^1.6.3