raw 0.2.0

  • README.md
  • CHANGELOG.md
  • Example
  • Installing
  • Versions
  • 64

Introduction #

A package for writing, reading, and debugging binary data.

Issues & contributing

  • Found a bug? Create an issue in Github.
  • Contributing code? Create a pull request in Github.

A walkthrough #

Key classes #

  • RawWriter:
    • Writes bytes to a buffer.
    • Automatically expands the buffer when isExpanding is true.
  • RawReader:
    • Reads bytes from a buffer.
    • If reading fails, throw descriptive exceptions.
  • SelfEncoder
    • Classes that know how to encode state using RawWriter.
  • SelfDecoder
    • Classes that know how to decode state using RawReader.
  • SelfCodec
    • Classes that implement both SelfEncoder and SelfDecoder.

Example of SelfCodec #

A typical implementation of SelfCodec looks like this:

class MyStruct extends SelfCodec {
  int intField = 0;
  String stringField = "";
  
  @override
  void encodeSelf(RawWriter writer) {
    writer.writeInt32(intField);
    writer.writeUint32(stringField.length, Endian.little);
    writer.writeUtf8(stringField);
  }
  
  @override
  void decodeSelf(RawReader reader) {
    intField = reader.readInt32();
    final stringLength = reader.readUint32(Endian.little);
    stringField = reader.readUtf(stringLength);
  }
}

Supported primitives #

  • Numeric types
    • Unsigned/signed integers
      • Uint8 / Int8
      • Uint16 / Int16
      • Uint32 / Int32
      • FixInt64 / FixInt64 (Int64 from fixnum)
    • Floating- point values
      • Float32
      • Float64
    • Variable-length integers (identical with Protocol Buffers encoding)
      • VarUint
      • VarInt
  • Sequence types
    • Uint8List
    • ByteData
    • Strings
      • Utf8 / Utf8NullEnding
      • Utf8Simple / Utf8SimpleNullEnding
        • Validates that every byte is less than 128.
    • Zeroes

Helpers for testing #

import 'package:test/test.dart';
import 'package:raw/raw_test.dart';

void main() {
  test("an example", () {
    final value = [9,8,7];
    final expected = [1,2,3];
    expect(value, byteListEquals(expected));
    
    // Output:
    // 0x0000: 0908 07
    //     (0) ^^^^ ^^
    //         0102 03
  });
}

If your class implements SelfEncoder, use selfEncoderEquals:

class MyStruct extends SelfCodec {
  // ...
}

void main() {
  test("an example", () {
    // ...
    expect(myStruct, selfEncoderEquals(expected));
  });
}

Converting hex formats to bytes #

DebugHexDecoder is able to import hex formats such as:

  • "0000000: 0123 4567 89ab cdef 0123 4567 89ab cdef ................"
  • "0000010: 012345678 ............ # comment"
  • "012345678abcdef // no prefix"

Converting bytes to hex-based descriptions #

DebugHexEncoder converts bytes to the following format:

0x0000: 0123 4567 89ab cdef  0123 4567 89ab cdef
    (0)
0x0010: 0123 4567 89ab cdef  0123 4567 89ab cdef
   (16)

If expected byte list is specified, bytes are converted to the following format:

0x0000: 0123 5555 89ab cdef  0123 4567 89ab cdef
    (0)      ^ ^^                                 <-- index of the first error: 0x02 (decimal: 2)
             4 67
0x0010: 0123 4567 89ab cdef  0123 4567 89
   (16)                                  ^^ ^^^^  <-- index of the first error: 0x0D (decimal: 13)
                                         ab cdef

0.0.1 #

  • Initial Release

example/raw.dart

import 'package:raw/raw.dart';

class ExampleStruct extends SelfCodec {
  int intField = 0;
  String stringField = "";

  @override
  void decodeSelf(RawReader reader) {
    intField = reader.readVarInt();
    stringField = reader.readUtf8NullEnding();
  }

  @override
  void encodeSelf(RawWriter writer) {
    writer.writeVarInt(intField);
    writer.writeUtf8(stringField);
  }
}

Use this package as a library

1. Depend on it

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


dependencies:
  raw: ^0.2.0

2. Install it

You can install packages from the command line:

with pub:


$ pub get

with Flutter:


$ flutter packages get

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

3. Import it

Now in your Dart code, you can use:


import 'package:raw/raw.dart';
  
Version Uploaded Documentation Archive
0.2.0 Feb 17, 2019 Go to the documentation of raw 0.2.0 Download raw 0.2.0 archive
0.1.0 Feb 16, 2019 Go to the documentation of raw 0.1.0 Download raw 0.1.0 archive
0.0.1 Feb 15, 2019 Go to the documentation of raw 0.0.1 Download raw 0.0.1 archive
Popularity:
Describes how popular the package is relative to other packages. [more]
30
Health:
Code health derived from static analysis. [more]
99
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
98
Overall:
Weighted score of the above. [more]
64
Learn more about scoring.

We analyzed this package on Mar 6, 2019, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.2.0
  • pana: 0.12.14

Platforms

Detected platforms: Flutter, web, other

No platform restriction found in primary library package:raw/raw.dart.

Health suggestions

Fix lib/src/raw_reader.dart. (-1 points)

Analysis of lib/src/raw_reader.dart reported 2 hints:

line 20 col 15: Use = to separate a named parameter from its default value.

line 21 col 22: Use = to separate a named parameter from its default value.

Format lib/src/raw_writer.dart.

Run dartfmt to format lib/src/raw_writer.dart.

Maintenance suggestions

The package description is too short. (-2 points)

Add more detail to the description field of pubspec.yaml. Use 60 to 180 characters to describe the package, what it does, and its target use case.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.0.0 <3.0.0
collection ^1.0.0 1.14.11
fixnum ^0.10.0 0.10.9
matcher >=0.9.0 <2.0.0 0.12.4
meta ^1.0.0 1.1.7
Transitive dependencies
path 1.6.2
stack_trace 1.9.3
Dev dependencies
benchmark_harness ^1.0.0
test ^1.0.0