Skip to content

Commit

Permalink
update readme
Browse files Browse the repository at this point in the history
  • Loading branch information
convto committed May 8, 2022
1 parent 8a4aa91 commit f783d7e
Showing 1 changed file with 16 additions and 7 deletions.
23 changes: 16 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,19 +7,28 @@ For example, a byte represented by the hexadecimal number `ff` would be encoded
Inspired by the standard package encoding/hex. I also got some implementation hints from it.

## Why is this necessary?
Go does not (as far as I can tell) have the flexibility to output raw byte sequences as bit strings.
This can be a problem in log output when, for example, parsing a binary message fails.
Byte sequences can be output as bit strings using the standard package `fmt` as follows

Bit output with padding like `fmt.Sprintf("%08b", buf)` is close,
but I created this package for more flexible handling (e.g. `io.Reader` and `io.Writer` support, Or `Dump()` output support like `xxd -b` ).
```go
for i := 0; i < len(src); i++ {
fmt.Printf("%08b", src[i])
}
```

In some cases, this is sufficient. However, this does not implement `io.Reader` or `io.Writer` , so flexible handling such as stream support is not possible.
In addition, it is tedious to output in a human-readable format such as `xxd -b`.

Therefore, outputting bit strings using the standard package `fmt` is inconvenient, for example, when debugging a program that evaluates binaries.

I created this package for more flexible handling (e.g. `io.Reader` and `io.Writer` support, Or `Dump()` output support like `xxd -b` ).

## Usage

Here are the basics. If you want more details, please refer to example_test or the package documentation.

### Encode

Encode the given byte sequence.
Encode the given byte sequences.

```go
src := []byte("Hello Gopher!")
Expand All @@ -35,7 +44,7 @@ fmt.Printf("%s\n", dst)

### Decode

The input to the decoding process is a bit-encoded byte sequence.
Decode takes as input a bit-encoded byte sequences.
Eight characters represent one byte, so the input must be a multiple of 8 bytes.

```go
Expand All @@ -55,7 +64,7 @@ fmt.Printf("%s\n", dst[:n])

### Dump

Dump returns the same output as `xxd -b` .
Dump returns output like `xxd -b` .

```go
dump := Dump([]byte("dump test"))
Expand Down

0 comments on commit f783d7e

Please sign in to comment.