diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 76 |
1 files changed, 42 insertions, 34 deletions
| @@ -1,64 +1,72 @@ | |||
| 1 | # BitReader [](https://goreportcard.com/report/github.com/pektezol/bitreader) [](https://github.com/pektezol/bitreader/blob/main/LICENSE) [](https://pkg.go.dev/github.com/pektezol/bitreader) | 1 | # BitReader [](https://pkg.go.dev/github.com/pektezol/bitreader) [](https://goreportcard.com/report/github.com/pektezol/bitreader) [](https://github.com/pektezol/bitreader/blob/main/LICENSE) |
| 2 | A simple bit reader with big/little-endian support for golang.\ | 2 | A simple bit reader with big/little-endian support for golang. |
| 3 | Reads stream data from an io.Reader; can read from os.File and a byte array with bytes.NewReader(array).\ | ||
| 4 | Uses bitwise operations.\ | ||
| 5 | Support reading up to 64 bits at one time.\ | ||
| 6 | Includes wrapper functions for most used data types.\ | ||
| 7 | Error checking on all but wrapper functions. | ||
| 8 | 3 | ||
| 9 | ## Installation | 4 | ## Installation |
| 10 | ```bash | 5 | ```bash |
| 11 | $ go get github.com/pektezol/bitreader | 6 | $ go get github.com/pektezol/bitreader |
| 12 | ``` | 7 | ``` |
| 13 | 8 | ||
| 14 | ## Usage | 9 | ## Usage Examples |
| 15 | 10 | ||
| 16 | ```go | 11 | ```go |
| 17 | import "github.com/pektezol/bitreader" | 12 | import "github.com/pektezol/bitreader" |
| 18 | 13 | ||
| 19 | // data: io.Reader Data to read from an io stream | 14 | // ioStream: io.Reader Data to read from an io stream |
| 20 | // le: bool Little-endian(true) or big-endian(false) state | 15 | // byteStream: []byte Data to read from a byte slice |
| 21 | reader := bitreader.Reader(data, le) | 16 | // littleEndian: bool Little-endian(true) or big-endian(false) state |
| 17 | reader := bitreader.NewReader(ioStream, le) | ||
| 18 | reader := bitreader.NewReaderFromBytes(byteStream, le) | ||
| 19 | |||
| 20 | // Fork Reader, Copies Current Reader | ||
| 21 | newReader, err := reader.Fork() | ||
| 22 | |||
| 23 | // Read Total Number of Bits Left | ||
| 24 | bits, err := reader.ReadRemainingBits() | ||
| 22 | 25 | ||
| 23 | // Read First Bit | 26 | // Read First Bit |
| 24 | state, err := reader.ReadBool() | 27 | state, err := reader.ReadBool() |
| 25 | 28 | ||
| 26 | // Skip Bits/Bytes | ||
| 27 | err := reader.SkipBits(8) | ||
| 28 | err := reader.SkipBytes(4) | ||
| 29 | |||
| 30 | // Read Bits/Bytes | 29 | // Read Bits/Bytes |
| 31 | value, err := reader.ReadBytes(4) // up to 8 bytes | ||
| 32 | value, err := reader.ReadBits(64) // up to 64 bits | 30 | value, err := reader.ReadBits(64) // up to 64 bits |
| 31 | value, err := reader.ReadBytes(8) // up to 8 bytes | ||
| 33 | 32 | ||
| 34 | // Read String | 33 | // Read String |
| 35 | text, err := reader.ReadString() // null-terminated | 34 | text, err := reader.ReadString() // null-terminated |
| 36 | text, err := reader.ReadStringLen(256) // length-specified | 35 | text, err := reader.ReadStringLength(256) // length-specified |
| 37 | 36 | ||
| 38 | // Read Bits/Bytes into Slice | 37 | // Read Bits/Bytes into Slice |
| 39 | arr, err := reader.ReadBitsToSlice(128) | 38 | arr, err := reader.ReadBitsToSlice(128) |
| 40 | arr, err := reader.ReadBytesToSlice(64) | 39 | arr, err := reader.ReadBytesToSlice(64) |
| 41 | 40 | ||
| 41 | // Skip Bits/Bytes | ||
| 42 | err := reader.SkipBits(8) | ||
| 43 | err := reader.SkipBytes(4) | ||
| 44 | |||
| 42 | // Wrapper functions | 45 | // Wrapper functions |
| 43 | text := reader.TryReadString() // string | 46 | state := reader.TryReadBool() // bool |
| 44 | text := reader.TryReadStringLen(64) // string | 47 | value := reader.TryReadInt1() // uint8 |
| 45 | arr := reader.ReadBitsToSlice(128) // []byte | 48 | value := reader.TryReadUInt8() // uint8 |
| 46 | arr := reader.ReadBytesToSlice(64) // []byte | 49 | value := reader.TryReadSInt8() // int8 |
| 47 | state := reader.TryReadBool() // bool | 50 | value := reader.TryReadUInt16() // uint16 |
| 48 | value := reader.TryReadInt1() // uint8 | 51 | value := reader.TryReadSInt16() // int16 |
| 49 | value := reader.TryReadInt8() // uint8 | 52 | value := reader.TryReadUInt32() // uint32 |
| 50 | value := reader.TryReadInt16() // uint16 | 53 | value := reader.TryReadSInt32() // int32 |
| 51 | value := reader.TryReadInt32() // uint32 | 54 | value := reader.TryReadUInt64() // uint64 |
| 52 | value := reader.TryReadInt64() // uint64 | 55 | value := reader.TryReadSInt64() // int64 |
| 53 | value := reader.TryReadFloat32() // float32 | 56 | value := reader.TryReadFloat32() // float32 |
| 54 | value := reader.TryReadFloat64() // float64 | 57 | value := reader.TryReadFloat64() // float64 |
| 55 | value := reader.TryReadBits(64) // uint64 | 58 | value := reader.TryReadBits(64) // uint64 |
| 56 | value := reader.TryReadBytes(8) // uint64 | 59 | value := reader.TryReadBytes(8) // uint64 |
| 60 | text := reader.TryReadString() // string | ||
| 61 | text := reader.TryReadStringLength(64) // string | ||
| 62 | arr := reader.TryReadBitsToSlice(1024) // []byte | ||
| 63 | arr := reader.TryReadBytesToSlice(128) // []byte | ||
| 64 | bits := reader.TryReadRemainingBits() // uint64 | ||
| 57 | ``` | 65 | ``` |
| 58 | 66 | ||
| 59 | ## Error Handling | 67 | ## Error Handling |
| 60 | ReadBits(x), ReadBytes(x), ReadBool(), ReadString(), ReadStringLen(x), ReadBitsToSlice(x), ReadBytesToSlice(x), SkipBits(x) and SkipBytes(x) functions returns an error message when they don't work as expected. It is advised to always handle errors. \ | 68 | All ReadXXX(), SkipXXX() and Fork() functions returns an error message when they don't work as expected. It is advised to always handle errors. \ |
| 61 | Wrapper functions, however, only returns the value and panics if an error is encountered. | 69 | Wrapper functions, however, only returns the value and panics if an error is encountered, for the sake of ease of use. |
| 62 | 70 | ||
| 63 | ## Bug Report / Feature Request | 71 | ## Bug Report / Feature Request |
| 64 | Using [Github Issues](https://github.com/pektezol/BitReader/issues/new/choose), you can report a bug that you encountered and/or request a feature that you would like to be added. | 72 | Using [Github Issues](https://github.com/pektezol/BitReader/issues/new/choose), you can report a bug that you encountered and/or request a feature that you would like to be added. |