Structure
Crystal's answer to Python's struct and Ruby's Array.pack/unpack.
Installation
-
Add the dependency to your
shard.yml:dependencies: structure: github: watzon/structure -
Run
shards install
Usage
require "structure"
s = Structure.from("2IB")
buf = s.pack(1, 2, 3)
# alternatively
buf = s.pack([1, 2, 3])
pp buf == Bytes[0, 0, 0, 1, 0, 0, 0, 2, 3]
# => true
pp s.unpack(buf)
# => [1u32, 2u32, 3u8]You can also make use of pack_into and unpack_from if you would like to use an existing IO.
require "structure"
io = IO::Memory.new
s = Structure.from("2IB")
buf = s.pack_into(io, 1, 2, 3)
# alternatively
buf = s.pack_into(io, [1, 2, 3])
io2 = IO::Memory.new
pp s.unpack_from(io)
# => [1u32, 2u32, 3u8]Format Strings
Endianness
By default, the endianness is big-endian. It could be determined by specifying one of the following characters at the beginning of the format:
Character | Endianness --------- | ---------- '=' | native (target endian) '<' | little-endian '>' | big-endian '!' | network (= big-endian)
Types
Character | Type
--------- | ----
'b' | i8
'B' | u8
'?' | bool
'h' | i16
'H' | u16
'i' | i32
'I' | u32
'q' | i64
'Q' | u64
'f' | f32
'd' | f64
's' | Bytes (WIP)
'S' | Bytes (WIP)
'P' | Pointer(Void) (WIP)
'x' | padding (0u8)
Any format character may be preceded by an integral repeat count. For example, the format string '4h' means exactly the same as 'hhhh'.
Differences from Python struct library
- Numbers' byte order is big-endian by default (e.g. u32, f64...).
- There is no alignment support.
- 32 bit integer format character is only 'I'/'i' (and not 'L'/'l').
Contributing
- Fork it (https://github.com/watzon/structure/fork)
- Create your feature branch (
git checkout -b my-new-feature) - Commit your changes (
git commit -am 'Add some feature') - Push to the branch (
git push origin my-new-feature) - Create a new Pull Request
Contributors
- Chris Watson - creator and maintainer