[pull] master from dermesser:master

.github/workflows/test.yml

@@ -0,0 +1,26 @@
+on: [push, pull_request]
+
+name: Actions CI
+
+jobs:
+  build_and_test:
+    name: integer-encoding-rs
+    strategy:
+      fail-fast: false
+      matrix:
+        features: ["tokio_async", "futures_async", ""]
+        platform: [ubuntu-latest, windows-latest, macos-latest]
+    runs-on: ${{ matrix.platform }}
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions-rs/toolchain@v1
+        with:
+          toolchain: stable
+      - uses: actions-rs/cargo@v1
+        with:
+          command: check
+          args: --no-default-features --features=${{ matrix.features }}
+      - uses: actions-rs/cargo@v1
+        with:
+          command: test
+          args: --no-default-features --features=${{ matrix.features }}

.travis.yml

@@ -1,11 +1,20 @@
 language: rust
 
-# Test on the latest versions of all channels.
+os:
+    - linux
+    - osx
+    - windows
+dist: focal
 rust:
-  - stable
-  - beta
-  - nightly
+    - stable
+    - nightly
 
+# Test on the latest versions of all channels.
+script:
+    - cargo test --features tokio_async --verbose
+    - cargo test --features futures_async --verbose
+    - cargo test --verbose
+    - cargo build --examples
 # Run this build on the "container-based infrastructure"
 # See http://docs.travis-ci.com/user/workers/container-based-infrastructure/.
 sudo: false

Cargo.toml

@@ -1,11 +1,41 @@
 [package]
 name = "integer-encoding"
-version = "1.0.7"
+version = "4.0.2"
 authors = ["Lewin Bormann <[email protected]>"]
 description = "varint+zigzag and fixedint integer encoding/decoding (https://developers.google.com/protocol-buffers/docs/encoding)"
 repository = "https://github.com/dermesser/integer-encoding-rs"
 documentation = "https://docs.rs/integer-encoding/"
-license-file = "LICENSE"
+license = "MIT"
 keywords = ["integer", "varint", "zigzag", "protobuf", "serialize"]
+edition = "2018"
 
 [dependencies]
+async-trait = { version = "0.1", optional = true }
+tokio = { version = "1.0", features = ["io-util"], optional = true }
+futures-util = { version = "0.3", optional = true, features = ["io"] }
+
+[dev-dependencies]
+tokio = { version = "1.0", features = ["fs", "rt-multi-thread", "macros"] }
+bencher = "~0.1"
+
+[[example]]
+name = "encode_varint_from_stdin"
+required-features = ["tokio_async"]
+
+[[example]]
+name = "read_write_file"
+required-features = ["tokio_async"]
+
+[[bench]]
+name = "main"
+harness = false
+
+[features]
+# Enable one of these features if you want to use the AsyncRead/AsyncWrite traits from
+# the futures crate instead of those from tokio.
+tokio_async = ["tokio", "async-trait"]
+futures_async = ["futures-util", "async-trait"]
+
+[package.metadata.docs.rs]
+features = ["tokio_async"]
+

LICENSE

@@ -2,6 +2,7 @@ The MIT License (MIT)
 
 Copyright (c) 2016 Google Inc. ([email protected]) -- though not an official
 Google product or in any way related!
+Copyright (c) 2018-2020 Lewin Bormann ([email protected])
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to

README.md

@@ -1,7 +1,7 @@
 # integer-encoding-rs
 
 [![crates.io](https://img.shields.io/crates/v/integer-encoding.svg)](https://crates.io/crates/integer-encoding)
-[![Build Status](https://travis-ci.org/dermesser/integer-encoding-rs.svg?branch=master)](https://travis-ci.org/dermesser/integer-encoding-rs)
+[![Actions CI](https://github.com/dermesser/integer-encoding-rs/workflows/Actions%20CI/badge.svg)](https://github.com/dermesser/integer-encoding-rs/actions)
 
 [full documentation](https://docs.rs/integer-encoding/)
 
@@ -10,11 +10,27 @@ representations.
 
 The format is described here: [Google's protobuf integer encoding technique](https://developers.google.com/protocol-buffers/docs/encoding).
 
+Please feel free to use `cargo bench` to determine the rate at which your
+machine can encode and decode varints and fixedints. Note that one iteration
+comprises each eight rounds of encoding (or decoding) a signed and an unsigned
+integer each -- divide the resulting benchmark time by 16 in order to have a
+rough estimate of time per operation. The integers are very large, so the
+results represent the worst case.
+
+## Crate
+
+If you use Tokio v0.2 and you use the asynchronous types in this crate (feature
+`tokio_async`), you may be interested in the `v2.0` branch. It is still
+maintained with the occasional fix for edge cases and depends on Tokio v0.2.
+
 ## FixedInt
 
 `FixedInt` casts integers to bytes by either copying the underlying memory or
-performing a transmutation. The encoded values use machine endianness
-(little-endian on x86).
+performing a transmutation. The encoded values use are little-endian.
+
+However, a trait method is implemented for all integer types allowing convenient conversion between
+little and big endian. That is, if you receive a big-endian on the wire and decode it, it will first
+be interpreted as little-endian; converting will recover the correct value.
 
 ## VarInt
 

benches/main.rs

@@ -0,0 +1,175 @@
+use bencher::Bencher;
+
+use integer_encoding::*;
+
+fn encode_v(b: &mut Bencher) {
+    let my_u64s = [
+        9494929199119074561,
+        3823923198123425321,
+        2595862268225688522,
+        1231230009321245673,
+        2909812083312547546,
+        3492011001874124465,
+        4848848884210156473,
+        4012941340125654654,
+    ] as [u64; 8];
+    let my_i64s = [
+        -122193043711204545,
+        2446312246543212452,
+        -445854216865433664,
+        3242135654513135465,
+        -543122132545464312,
+        3613543123031434343,
+        -431231254654543211,
+        7854615463131234543,
+    ] as [i64; 8];
+
+    let mut dst = [0 as u8; 10];
+
+    b.iter(|| {
+        // 8x each.
+        my_u64s[0].encode_var(&mut dst);
+        my_u64s[1].encode_var(&mut dst);
+        my_u64s[2].encode_var(&mut dst);
+        my_u64s[3].encode_var(&mut dst);
+        my_u64s[4].encode_var(&mut dst);
+        my_u64s[5].encode_var(&mut dst);
+        my_u64s[6].encode_var(&mut dst);
+        my_u64s[7].encode_var(&mut dst);
+
+        my_i64s[0].encode_var(&mut dst);
+        my_i64s[1].encode_var(&mut dst);
+        my_i64s[2].encode_var(&mut dst);
+        my_i64s[3].encode_var(&mut dst);
+        my_i64s[4].encode_var(&mut dst);
+        my_i64s[5].encode_var(&mut dst);
+        my_i64s[6].encode_var(&mut dst);
+        my_i64s[7].encode_var(&mut dst);
+    });
+}
+
+fn decode_v(b: &mut Bencher) {
+    let my_u64s = [
+        9494929199119074561,
+        3823923198123425321,
+        2595862268225688522,
+        1231230009321245673,
+        2909812083312547546,
+        3492011001874124465,
+        4848848884210156473,
+        4012941340125654654,
+    ] as [u64; 8];
+    let my_i64s = [
+        -122193043711204545,
+        2446312246543212452,
+        -445854216865433664,
+        3242135654513135465,
+        -543122132545464312,
+        3613543123031434343,
+        -431231254654543211,
+        7854615463131234543,
+    ] as [i64; 8];
+
+    let u64_src = [
+        my_u64s[0].encode_var_vec(),
+        my_u64s[1].encode_var_vec(),
+        my_u64s[2].encode_var_vec(),
+        my_u64s[3].encode_var_vec(),
+        my_u64s[4].encode_var_vec(),
+        my_u64s[5].encode_var_vec(),
+        my_u64s[6].encode_var_vec(),
+        my_u64s[7].encode_var_vec(),
+    ] as [Vec<u8>; 8];
+    let i64_src = [
+        my_i64s[0].encode_var_vec(),
+        my_i64s[1].encode_var_vec(),
+        my_i64s[2].encode_var_vec(),
+        my_i64s[3].encode_var_vec(),
+        my_i64s[4].encode_var_vec(),
+        my_i64s[5].encode_var_vec(),
+        my_i64s[6].encode_var_vec(),
+        my_i64s[7].encode_var_vec(),
+    ] as [Vec<u8>; 8];
+
+    b.iter(|| {
+        // 8x each.
+        u64::decode_var(&u64_src[0]).unwrap();
+        u64::decode_var(&u64_src[1]).unwrap();
+        u64::decode_var(&u64_src[2]).unwrap();
+        u64::decode_var(&u64_src[3]).unwrap();
+        u64::decode_var(&u64_src[4]).unwrap();
+        u64::decode_var(&u64_src[5]).unwrap();
+        u64::decode_var(&u64_src[6]).unwrap();
+        u64::decode_var(&u64_src[7]).unwrap();
+
+        i64::decode_var(&i64_src[0]).unwrap();
+        i64::decode_var(&i64_src[1]).unwrap();
+        i64::decode_var(&i64_src[2]).unwrap();
+        i64::decode_var(&i64_src[3]).unwrap();
+        i64::decode_var(&i64_src[4]).unwrap();
+        i64::decode_var(&i64_src[5]).unwrap();
+        i64::decode_var(&i64_src[6]).unwrap();
+        i64::decode_var(&i64_src[7]).unwrap();
+    });
+}
+
+bencher::benchmark_group!(varint_benches, encode_v, decode_v);
+
+fn encode_f(b: &mut Bencher) {
+    let my_u64 = 94949291991190 as u64;
+    let my_i64 = -12219304371120 as i64;
+
+    let mut dst = [0 as u8; 8];
+
+    b.iter(|| {
+        // 8x each.
+        my_u64.encode_fixed(&mut dst);
+        my_u64.encode_fixed(&mut dst);
+        my_u64.encode_fixed(&mut dst);
+        my_u64.encode_fixed(&mut dst);
+        my_u64.encode_fixed(&mut dst);
+        my_u64.encode_fixed(&mut dst);
+        my_u64.encode_fixed(&mut dst);
+
+        my_i64.encode_fixed(&mut dst);
+        my_i64.encode_fixed(&mut dst);
+        my_i64.encode_fixed(&mut dst);
+        my_i64.encode_fixed(&mut dst);
+        my_i64.encode_fixed(&mut dst);
+        my_i64.encode_fixed(&mut dst);
+        my_i64.encode_fixed(&mut dst);
+        my_i64.encode_fixed(&mut dst);
+    });
+}
+
+fn decode_f(b: &mut Bencher) {
+    let my_u64 = 94949291991190 as u64;
+    let my_i64 = -12219304371120 as i64;
+
+    let u64_src = my_u64.encode_fixed_vec();
+    let i64_src = my_i64.encode_fixed_vec();
+
+    b.iter(|| {
+        // 8x each.
+        u64::decode_fixed(&u64_src);
+        u64::decode_fixed(&u64_src);
+        u64::decode_fixed(&u64_src);
+        u64::decode_fixed(&u64_src);
+        u64::decode_fixed(&u64_src);
+        u64::decode_fixed(&u64_src);
+        u64::decode_fixed(&u64_src);
+
+        i64::decode_fixed(&i64_src);
+        i64::decode_fixed(&i64_src);
+        i64::decode_fixed(&i64_src);
+        i64::decode_fixed(&i64_src);
+        i64::decode_fixed(&i64_src);
+        i64::decode_fixed(&i64_src);
+        i64::decode_fixed(&i64_src);
+        i64::decode_fixed(&i64_src);
+    });
+}
+
+bencher::benchmark_group!(fixedint_benches, encode_f, decode_f);
+
+bencher::benchmark_main!(varint_benches, fixedint_benches);

coverage.sh

@@ -0,0 +1,14 @@
+#!/bin/bash
+
+set -x
+
+KCOV=kcov
+KCOV_OPTS="--exclude-pattern=/.cargo,/glibc,/usr/lib,/usr/include"
+KCOV_OUT="./kcov-out/"
+
+export RUSTFLAGS="-C link-dead-code"
+
+TEST_BIN=$(cargo test 2>&1 > /dev/null | awk '/^     Running target\/debug\/deps\// { print $2 }')
+
+echo $TEST_BIN
+${KCOV} ${KCOV_OPTS} ${KCOV_OUT} ${TEST_BIN} && xdg-open ${KCOV_OUT}/index.html

examples/encode_varint_from_stdin.rs

@@ -0,0 +1,37 @@
+use integer_encoding::VarInt;
+
+use std::io::{self, BufRead};
+use std::str::FromStr;
+
+fn binencode(b: &[u8]) -> String {
+    let mut s = String::new();
+    for byte in b {
+        s.push_str(&format!("{:08b} ", byte));
+    }
+    s
+}
+
+fn main() {
+    let stdin = io::BufReader::new(io::stdin());
+
+    println!("Enter decimal numbers here:\n");
+    for l in stdin.lines() {
+        if l.is_err() {
+            break;
+        }
+        let l = l.unwrap();
+        match i64::from_str(&l) {
+            Ok(i) => println!(
+                "fixed: {:b} encoded (unsigned): {} encoded (signed): {}",
+                i,
+                if i >= 0 {
+                    binencode(&(i as u64).encode_var_vec())
+                } else {
+                    "-".to_string()
+                },
+                binencode(&i.encode_var_vec())
+            ),
+            Err(e) => println!("{:?}", e),
+        }
+    }
+}