ffi-bitfield 0.0.7 → 0.0.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6e82e912397a405df792824503984be18325c6c22b76307a0fc9d7fe65c5a95f
-  data.tar.gz: a3bbf7a5ecdcba6e4627c80e9a108788e281fc18f9d4abededf5d47833b0783d
+  metadata.gz: 50775cc156bce79d4d20153303484ba80d19d23707d5413ea2557676260e8b38
+  data.tar.gz: 941e057d7cd548da1fd133f81143e573d7795c060d7678334c74cd1ed7cdaa31
 SHA512:
-  metadata.gz: 76c80c9d0444042ad7ca1b8c28b084562c84b9ac843f0f23a3253444fefee3f4a959da752395d4fa43fc663aab4b1854bb5bd3e21b2550fca2b5c4cc8560ad4a
-  data.tar.gz: 33b72012820da5d15fcf1f753cd2a1203c3bd467b0d4596b429e7c46ba485bee91d45424142c4411996545054eb8f3bd368d53fa477cf7bde330c680689a9276
+  metadata.gz: 7329ad0a6bf66f580af0fdbbc3219774a53e7624a78e8e3891562150444282c0b2aae26b5eb4382edf8f67e27e66224aaf32592757f6e813105ab432a5e646a5
+  data.tar.gz: 3e4bb498d57114b6f9ccaf140d5789239609ff402f3be888d419fefa66957547659f1d5ab8577439f9fb98ad89fa6d56869f30a985b04486bc9bc90799c9b82a

data/README.md

@@ -99,7 +99,7 @@ bundle exec rake test
 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?

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 ArgumentError, "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.7'
+    # 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.7
+  version: 0.0.8
 platform: ruby
 authors:
 - kojix2
-autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-05-16 00:00:00.000000000 Z
+date: 2025-03-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ffi
@@ -43,7 +42,6 @@ homepage: https://github.com/kojix2/ffi-bitfield
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -58,8 +56,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.7
-signing_key: 
+rubygems_version: 3.6.2
 specification_version: 4
 summary: bit fields for Ruby-FFI
 test_files: []