https://github.com/kojix2/ffi-bitfield
Bit field for Ruby-FFI
https://github.com/kojix2/ffi-bitfield
ffi ruby ruby-ffi
Last synced: about 1 year ago
JSON representation
Bit field for Ruby-FFI
- Host: GitHub
- URL: https://github.com/kojix2/ffi-bitfield
- Owner: kojix2
- License: mit
- Created: 2021-03-04T04:33:28.000Z (about 5 years ago)
- Default Branch: main
- Last Pushed: 2025-04-10T05:29:05.000Z (about 1 year ago)
- Last Synced: 2025-04-10T05:51:21.093Z (about 1 year ago)
- Topics: ffi, ruby, ruby-ffi
- Language: Ruby
- Homepage: https://kojix2.github.io/ffi-bitfield/
- Size: 140 KB
- Stars: 5
- Watchers: 2
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE.txt
Awesome Lists containing this project
README
# ffi-bitfield
[](https://badge.fury.io/rb/ffi-bitfield)
[](https://github.com/kojix2/ffi-bitfield/actions/workflows/ci.yml)
Bit field for [Ruby-FFI](https://github.com/ffi/ffi)
## Installation
```sh
gem install ffi-bitfield
```
## Usage
Classes
* class BitStruct < FFI::Struct
* class ManagedBitStruct < FFI::ManagedStruct
Loading
```ruby
require 'ffi/bit_struct'
require 'ffi/managed_bit_struct'
```
Define your struct
```ruby
class Struct1 < FFI::BitStruct
layout \
:a, :uint8,
:b, :uint8
bit_fields :a,
:u, 2,
:v, 2,
:w, 1,
:x, 1,
:y, 1,
:z, 1
end
```
Reading
```ruby
s = Struct1.new
s[:a] = 63
p s[:u] # 3
p s[:v] # 3
p s[:w] # 1
p s[:x] # 1
p s[:y] # 0
p s[:z] # 0
```
Writing
```ruby
s = Struct1.new
s[:u] = 0
s[:v] = 0
s[:w] = 0
s[:x] = 0
s[:y] = 1
p s[:a] # 64
```
### Inspecting Bit Fields
You can use the `bit_field_members` method to get a hash of bit fields grouped by parent field:
```ruby
class Flags < FFI::BitStruct
layout \
:value, :uint8
bit_fields :value,
:read, 1,
:write, 1,
:execute, 1,
:unused, 5
end
p Flags.bit_field_members
# => {:value=>[:read, :write, :execute, :unused]}
```
For more detailed information, you can use the `bit_field_layout` method:
```ruby
p Flags.bit_field_layout
# => {
# :value => {
# :read => { :start => 0, :width => 1 },
# :write => { :start => 1, :width => 1 },
# :execute => { :start => 2, :width => 1 },
# :unused => { :start => 3, :width => 5 }
# }
# }
```
These methods are useful for custom pretty printing or introspection of your bit struct classes.
### Loading
```ruby
require 'ffi/bit_field'
```
The above is the same as below.
```ruby
require 'ffi/bit_struct'
require 'ffi/managed_bit_struct'
```
## Development
```
git clone https://github.com/kojix2/ffi-bitfield
cd ffi-bitfield
bundle install
bundle exec rake test
```
* [ffi-bitfield - read/write bit fields with Ruby-FFI](https://dev.to/kojix2/ffi-bitfield-g4h)
## Contributing
Your feedback is important.
ffi-bitfield is a library under development, so even small improvements like typofix are welcome! Please feel free to send us your pull requests.
Bug reports and pull requests are welcome on GitHub at https://github.com/kojix2/ffi-bitfield.
Do you need commit rights to my repository?
Do you want to get admin rights and take over the project?
If so, please feel free to contact me @kojix2.
## License
The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).