123456789_123456789_123456789_123456789_123456789_

Class: FFI::Struct

Relationships & Source Files
Namespace Children
Classes:
InlineArray, ManagedStructConverter
Extension / Inclusion / Inheritance Descendants
Subclasses:
ManagedStruct, Union
Inherits: Object
Defined in: ext/ffi_c/Struct.c,
lib/ffi/struct.rb

Overview

A Struct means to mirror a C struct.

A Struct is defined as:

class MyStruct < FFI::Struct
  layout :value1, :int,
         :value2, :double
end

and is used as:

my_struct = MyStruct.new
my_struct[:value1] = 12

For more information, see github.com/ffi/ffi/wiki/Structs

Class Attribute Summary

Class Method Summary

Instance Method Summary

Class Attribute Details

.size ⇒ Integer (rw)

Get struct size

[ GitHub ] 

  


# File 'lib/ffi/struct.rb', line 91



def self.size
  defined?(@layout) ? @layout.size : defined?(@size) ? @size : 0
end


  








  

    .size=(size)  ⇒ size  (rw)
  



  

    

set struct size


  





  
Parameters:


    
  
  • 
    size
    (Integer)
  
    • 



Raises:


    
  
  • 
    (ArgumentError)
  
    • 





  [ GitHub ]


  

  


# File 'lib/ffi/struct.rb', line 98



def self.size=(size)
  raise ArgumentError, "Size already set" if defined?(@size) || defined?(@layout)
  @size = size
end


  







Class Method Details



  

    .alignment  
  

  [ GitHub ]


  

  


# File 'lib/ffi/struct.rb', line 104



def self.alignment
  @layout.alignment
end


  








  

    .array_layout(builder, spec)  ⇒ builder  (private)
  



  

    

Add array spec to builder.


  





  
Parameters:





  [ GitHub ]


  

  


# File 'lib/ffi/struct.rb', line 298



def array_layout(builder, spec)
  i = 0
  while i < spec.size
    name, type = spec[i, 2]
    i += 2

    # If the next param is a Integer, it specifies the offset
    if spec[i].kind_of?(Integer)
      offset = spec[i]
      i += 1
    else
      offset = nil
    end

    builder.add name, find_field_type(type), offset
  end
end


  








  

    .auto_ptr  
  

  [ GitHub ]


  

  


# File 'lib/ffi/struct.rb', line 165



def self.auto_ptr
  @managed_type ||= Type::Mapped.new(ManagedStructConverter.new(self))
end


  








  

    .by_ref(flags = :inout)  
  

  [ GitHub ]


  

  


# File 'lib/ffi/struct.rb', line 143



def self.by_ref(flags = :inout)
  self.ptr(flags)
end


  








  

    .by_value  
  

  [ GitHub ]


  

  


# File 'lib/ffi/struct.rb', line 139



def self.by_value
  self.val
end


  








  

    .hash_layout(builder, spec)  ⇒ builder  (private)
  



  

    

Add hash spec to builder.


  





  
Parameters:





  [ GitHub ]


  

  


# File 'lib/ffi/struct.rb', line 288



def hash_layout(builder, spec)
  spec[0].each do |name, type|
    builder.add name, find_field_type(type), nil
  end
end


  








  

    .in  
  

  [ GitHub ]


  

  


# File 'lib/ffi/struct.rb', line 123



def self.in
  ptr(:in)
end


  








  

    

      .layout  ⇒ StructLayout 
      .layout(*spec)  ⇒ StructLayout 
    

  



  

    
  





  


  [ GitHub ]


  

  


# File 'lib/ffi/struct.rb', line 205



def layout(*spec)
  return @layout if spec.size == 0

  warn "[DEPRECATION] Struct layout is already defined for class #{self.inspect}. Redefinition as in #{caller[0]} will be disallowed in ffi-2.0." if defined?(@layout)

  builder = StructLayoutBuilder.new
  builder.union = self < Union
  builder.packed = @packed if defined?(@packed)
  builder.alignment = @min_alignment if defined?(@min_alignment)

  if spec[0].kind_of?(Hash)
    hash_layout(builder, spec)
  else
    array_layout(builder, spec)
  end
  builder.size = @size if defined?(@size) && @size > builder.size
  cspec = builder.build
  @layout = cspec unless self == Struct
  @size = cspec.size
  return cspec
end


  








  

    .members  
  

  [ GitHub ]


  

  


# File 'lib/ffi/struct.rb', line 109



def self.members
  @layout.members
end


  








  

    .offset_of(name)  ⇒ Integer 
  



  

    

Get the offset of a field.


  





  


  [ GitHub ]


  

  


# File 'lib/ffi/struct.rb', line 119



def self.offset_of(name)
  @layout.offset_of(name)
end


  








  

    .offsets  ⇒ Array<Array(Symbol, Integer)> 
  



  

    

Get an array of tuples (field name, offset of the field).


  





  
Returns:


    
  
  • 
    (Array<Array(Symbol, Integer)>)
—    
    

    Array<Array(Symbol, Integer)>
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/ffi/struct.rb', line 114



def self.offsets
  @layout.offsets
end


  








  

    .out  
  

  [ GitHub ]


  

  


# File 'lib/ffi/struct.rb', line 127



def self.out
  ptr(:out)
end


  








  

    .ptr(flags = :inout)  
  

  [ GitHub ]


  

  


# File 'lib/ffi/struct.rb', line 131



def self.ptr(flags = :inout)
  @ref_data_type ||= Type::Mapped.new(StructByReference.new(self))
end


  








  

    .val  
  

  [ GitHub ]


  

  


# File 'lib/ffi/struct.rb', line 135



def self.val
  @val_data_type ||= StructByValue.new(self)
end


  







Instance Method Details



  

    #align  
  



  

    

Alias for #alignment.


  



  [ GitHub ]


  

  


# File 'lib/ffi/struct.rb', line 53



alias_method :align, :alignment


  








  

    #alignment  ⇒ Integer 
    Also known as: #align
  



  

    
  





  
Returns:


    
  
  • 
    (Integer)
—    
    

    Struct alignment
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/ffi/struct.rb', line 50



def alignment
  self.class.alignment
end


  








  

    #clear  ⇒ self 
  



  

    

Clear the struct content.


  





  


  [ GitHub ]


  

  


# File 'lib/ffi/struct.rb', line 78



def clear
  pointer.clear
  self
end


  








  

    

      #members  
      #list(of)  
    

  



  

    
  





  


  [ GitHub ]


  

  


# File 'lib/ffi/struct.rb', line 61



def members
  self.class.members
end


  








  

    #offset_of(name)  ⇒ Integer 
  



  

    

Get the offset of a field.


  





  


  [ GitHub ]


  

  


# File 'lib/ffi/struct.rb', line 56



def offset_of(name)
  self.class.offset_of(name)
end


  








  

    #offsets  ⇒ Array<Array(Symbol, Integer)> 
  



  

    

Get an array of tuples (field name, offset of the field).


  





  
Returns:


    
  
  • 
    (Array<Array(Symbol, Integer)>)
—    
    

    Array<Array(Symbol, Integer)>
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/ffi/struct.rb', line 72



def offsets
  self.class.offsets
end


  








  

    #size  ⇒ Integer 
  



  

    

Get struct size


  





  


  [ GitHub ]


  

  


# File 'lib/ffi/struct.rb', line 45



def size
  self.class.size
end


  








  

    #to_ptr  ⇒ AbstractMemory 
  



  

    

Get Pointer to struct content.


  





  


  [ GitHub ]


  

  


# File 'lib/ffi/struct.rb', line 85



def to_ptr
  pointer
end


  








  

    #values  ⇒ Array 
  



  

    

Get array of values from Struct fields.


  





  


  [ GitHub ]


  

  


# File 'lib/ffi/struct.rb', line 67



def values
  members.map { |m| self[m] }
end