ffi-bitfield 0.0.6 → 0.0.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8e2586353fd6f53337bf3ffef8019d477c279c0284642165fad4d592315ccc1a
-  data.tar.gz: 2772a6b9ef73faeccc105c501494d6fe82079614b6e23bab14de3954d1f1d1f2
+  metadata.gz: 50775cc156bce79d4d20153303484ba80d19d23707d5413ea2557676260e8b38
+  data.tar.gz: 941e057d7cd548da1fd133f81143e573d7795c060d7678334c74cd1ed7cdaa31
 SHA512:
-  metadata.gz: 911015a3478c323f4469076489e68d7634d12188200dea1e8ae76263af368b992fb424c6f086cc46cb30aa501ca12326039a8a6a184524e2f54b6cb35f2495c1
-  data.tar.gz: 82951de5f89c776408d35e656a8ce100c1306899e808569dd181cd5c56bfbee961329ac989455b9814e5815928227e732d4ea1e8d21a09141fadcb00cce49760
+  metadata.gz: 7329ad0a6bf66f580af0fdbbc3219774a53e7624a78e8e3891562150444282c0b2aae26b5eb4382edf8f67e27e66224aaf32592757f6e813105ab432a5e646a5
+  data.tar.gz: 3e4bb498d57114b6f9ccaf140d5789239609ff402f3be888d419fefa66957547659f1d5ab8577439f9fb98ad89fa6d56869f30a985b04486bc9bc90799c9b82a

data/README.md

@@ -13,9 +13,21 @@ 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,
@@ -29,10 +41,14 @@ class Struct1 < FFI::BitStruct
     :y, 1,
     :z, 1
 end
+```
+
+Reading
 
+```ruby
 s = Struct1.new
-s[:a] = 63
 
+s[:a] = 63
 p s[:u] # 3
 p s[:v] # 3
 p s[:w] # 1
@@ -41,6 +57,19 @@ 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
+```
+
 ### Loading
 
 ```ruby
@@ -54,14 +83,6 @@ require 'ffi/bit_struct'
 require 'ffi/managed_bit_struct'
 ```
 
-## API Overview
-
-```md
-* module FFI
-  * class BitStruct < FFI::Struct
-  * class ManagedBitStruct < FFI::ManagedStruct
-```
-
 ## Development
 
 ```
@@ -71,10 +92,18 @@ 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/bitstruct.
+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
 

data/lib/ffi/bit_field/layout.rb

@@ -2,10 +2,24 @@
 
 module FFI
   module BitField
-    # Layout provides the `bit_fields` method for registering field members.
+    # Layout provides methods for defining bit field layouts.
+    # This module is extended by BitStruct and ManagedBitStruct classes.
     module Layout
-      # @param [Array] layout_args
-      # @return [Symbol] parent_name
+      # Defines bit fields within a parent field.
+      #
+      # @param [Array] layout_args An array where the first element is the parent field name,
+      #   followed by alternating field name and bit width pairs
+      # @return [Symbol] parent_name The name of the parent field
+      #
+      # @example Define bit fields in an 8-bit integer
+      #   bit_fields :flags,
+      #     :read,    1,  # 1 bit for read permission
+      #     :write,   1,  # 1 bit for write permission
+      #     :execute, 1,  # 1 bit for execute permission
+      #     :unused,  5   # 5 unused bits
+      #
+      # @note The total bit width should not exceed the size of the parent field.
+      #   For example, a :uint8 field can hold at most 8 bits.
       def bit_fields(*layout_args)
         # The reason for using class instance variable here instead of class variable
         # is not because class instance variables are clean,

data/lib/ffi/bit_field/property.rb

@@ -2,36 +2,95 @@
 
 module FFI
   module BitField
-    # Properties provides methods to read and write bit fields.
+    # Property provides methods for reading and writing bit field values.
+    # This module is included in BitStruct and ManagedBitStruct classes.
     module Property
-      # @param [Symbol] member_name
-      # @return [Integer] value
+      # Reads a value from a bit field or regular field.
+      #
+      # @param [Symbol] member_name The name of the field to read
+      # @return [Integer] The value of the field
+      #
+      # @example Reading a bit field
+      #   struct[:flag1]  # => 1
       def [](member_name)
         parent_name, start, width = member_value_info(member_name)
         if parent_name
           value = get_member_value(parent_name)
-          value[start, width]
+          (value >> start) & ((1 << width) - 1)
         else
           get_member_value(member_name)
         end
       end
 
+      # Writes a value to a bit field or regular field.
+      #
+      # @param [Symbol] member_name The name of the field to write
+      # @param [Integer] value The value to write
+      # @return [Integer] The written value
+      # @raise [ArgumentError] If the value is too large for the bit field
+      # @raise [ArgumentError] If the value is too small (negative) for the bit field
+      # @raise [ArgumentError] If the member name is not a valid bit field
+      # @raise [TypeError] If the value is not an Integer
+      #
+      # @example Writing to a bit field
+      #   struct[:flag1] = 1
+      # @example Writing a negative value (bit-flipped)
+      #   struct[:field] = -1  # Sets all bits to 1
       def []=(member_name, value)
-        parent_name, start, width = member_value_info(member_name)
-        if parent_name
-          raise "Value #{value} is larger than bit_length: #{width}" if value.bit_length > width
+        # Ensure value is an Integer
+        raise TypeError, "Value must be an Integer, got #{value.class}" unless value.is_a?(Integer)
 
-          parent_value = get_member_value(parent_name)
-          new_value = (((1 << width) - 1 << start) & parent_value ^ parent_value) |
-                      (value << start)
-          set_member_value(parent_name, new_value)
-        else
-          set_member_value(member_name, value)
+        # Get bit field information
+        field_info = member_value_info(member_name)
+
+        # If not a bit field, delegate to regular field setter
+        return set_member_value(member_name, value) unless field_info
+
+        # Extract bit field information
+        parent_name, start, width = field_info
+
+        # Calculate max value for this bit width
+        max_value = (1 << width) - 1
+
+        # Handle negative values by bit-flipping
+        if value.negative?
+          # For negative values, we interpret them as bit-flipped positive values
+          # For example, with 4 bits, -1 becomes 1111 (15), -2 becomes 1110 (14), etc.
+
+          # Check if the negative value is within range
+          # For bit-flipping, valid range is -(2^n) to -1
+          min_value = -(1 << width)
+          if value < min_value
+            raise ArgumentError, "Value #{value} is too small for bit_length: #{width}, minimum is #{min_value}"
+          end
+
+          # Convert negative value to bit-flipped positive value
+          # -1 -> 15, -2 -> 14, etc.
+          value = max_value + value + 1
+
+          # Sanity check after conversion
+          if value.negative? || value > max_value
+            raise ArgumentError, "Internal error: converted value #{value} is out of range for bit_length: #{width}"
+          end
+        elsif value > max_value
+          # For positive values, check if they fit in the bit width
+          raise ArgumentError, "Value #{value} is too large for bit_length: #{width}, maximum is #{max_value}"
         end
+
+        # Update the parent field with the new bit field value
+        parent_value = get_member_value(parent_name)
+        mask = ((1 << width) - 1) << start
+        new_value = (parent_value & ~mask) | ((value & ((1 << width) - 1)) << start)
+
+        set_member_value(parent_name, new_value)
       end
 
       private
 
+      # Gets information about a bit field member.
+      #
+      # @param [Symbol] member_name The name of the bit field
+      # @return [Array, nil] An array containing [parent_name, start_bit, width] or nil if not a bit field
       def member_value_info(member_name)
         self.class.instance_variable_get(:@bit_field_hash_table)[member_name]
       end

data/lib/ffi/bit_field/version.rb

@@ -2,6 +2,7 @@
 
 module FFI
   module BitField
-    VERSION = '0.0.6'
+    # Current version of the ffi-bitfield gem.
+    VERSION = '0.0.8'
   end
 end

data/lib/ffi/bit_field.rb

@@ -4,8 +4,26 @@ require_relative 'bit_field/version'
 require_relative 'bit_struct'
 require_relative 'managed_bit_struct'
 
+# Foreign Function Interface module for Ruby.
+# This is the main namespace for the Ruby-FFI library.
 module FFI
-  # This module is just a namespace.
+  # BitField provides bit field functionality for Ruby-FFI.
+  # It allows defining, reading, and writing bit fields within FFI structs.
+  #
+  # @example Basic usage
+  #   class MyStruct < FFI::BitStruct
+  #     layout \
+  #       :flags, :uint8
+  #
+  #     bit_fields :flags,
+  #       :flag1, 1,
+  #       :flag2, 1,
+  #       :value, 6
+  #   end
+  #
+  #   struct = MyStruct.new
+  #   struct[:flag1] = 1
+  #   struct[:value] = 42
   module BitField
   end
 end

data/lib/ffi/bit_struct.rb

@@ -6,7 +6,25 @@ require_relative 'bit_field/layout'
 require_relative 'bit_field/property'
 
 module FFI
-  # Subclass of FFI::Struct that support bit fields.
+  # Subclass of FFI::Struct that supports bit fields.
+  # Allows defining and accessing individual bits within integer fields.
+  #
+  # @example Define a struct with bit fields
+  #   class Flags < FFI::BitStruct
+  #     layout \
+  #       :value, :uint8
+  #
+  #     bit_fields :value,
+  #       :read,    1,  # 1 bit for read permission
+  #       :write,   1,  # 1 bit for write permission
+  #       :execute, 1,  # 1 bit for execute permission
+  #       :unused,  5   # 5 unused bits
+  #   end
+  #
+  #   flags = Flags.new
+  #   flags[:read] = 1
+  #   flags[:write] = 1
+  #   puts flags[:value]  # => 3
   class BitStruct < Struct
     # [] is defined in FFI::Struct
     alias get_member_value []

data/lib/ffi/managed_bit_struct.rb

@@ -6,7 +6,28 @@ require_relative 'bit_field/layout'
 require_relative 'bit_field/property'
 
 module FFI
-  # Subclass of FFI::ManagedStruct that support bit fields.
+  # Subclass of FFI::ManagedStruct that supports bit fields.
+  # Combines memory management with bit field functionality.
+  #
+  # Use this class when you need automatic memory management for your structs
+  # with bit fields. You must implement the self.release method to handle
+  # memory cleanup.
+  #
+  # @example Define a managed struct with bit fields
+  #   class ManagedFlags < FFI::ManagedBitStruct
+  #     layout \
+  #       :value, :uint8
+  #
+  #     bit_fields :value,
+  #       :read,    1,
+  #       :write,   1,
+  #       :execute, 1,
+  #       :unused,  5
+  #
+  #     def self.release(ptr)
+  #       # Custom memory cleanup code
+  #     end
+  #   end
   class ManagedBitStruct < ManagedStruct
     # [] is defined in FFI::Struct
     alias get_member_value []

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ffi-bitfield
 version: !ruby/object:Gem::Version
-  version: 0.0.6
+  version: 0.0.8
 platform: ruby
 authors:
 - kojix2
-autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-07-17 00:00:00.000000000 Z
+date: 2025-03-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ffi
@@ -24,76 +23,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-- !ruby/object:Gem::Dependency
-  name: bundler
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: irb
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: minitest
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: rake
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: rubocop
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
 description: bit fields for Ruby-FFI
 email:
 - 2xijok@gmail.com
@@ -113,7 +42,6 @@ homepage: https://github.com/kojix2/ffi-bitfield
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -128,8 +56,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.15
-signing_key: 
+rubygems_version: 3.6.2
 specification_version: 4
 summary: bit fields for Ruby-FFI
 test_files: []