Method: OpenC3::BinaryAccessor.read

Defined in:: lib/openc3/accessors/binary_accessor.rb,
ext/openc3/ext/structure/structure.c

.read(param_bit_offset, param_bit_size, param_data_type, param_buffer, param_endianness) ⇒ `Integer`

Reads binary data of any data type from a buffer

Parameters:

bit_offset (Integer) —

Bit offset to the start of the item. A negative number means to offset from the end of the buffer.
bit_size (Integer) —

Size of the item in bits
data_type (Symbol) —

DATA_TYPES
buffer (String) —

Binary string buffer to read from
endianness (Symbol) —

ENDIANNESS

Returns:

(Integer) —

value read from the buffer

# File 'lib/openc3/accessors/binary_accessor.rb', line 146

def self.read(bit_offset, bit_size, data_type, buffer, endianness)
  given_bit_offset = bit_offset
  given_bit_size = bit_size

  bit_offset = check_bit_offset_and_size(:read, given_bit_offset, given_bit_size, data_type, buffer)

  # If passed a negative bit size with strings or blocks
  # recalculate based on the buffer length
  if (bit_size <= 0) && ((data_type == :STRING) || (data_type == :BLOCK))
    bit_size = (buffer.length * 8) - bit_offset + bit_size
    if bit_size == 0
      return ""
    elsif bit_size < 0
      raise_buffer_error(:read, buffer, data_type, given_bit_offset, given_bit_size)
    end
  end

  result, lower_bound, upper_bound = check_bounds_and_buffer_size(bit_offset, bit_size, buffer.length, endianness, data_type)
  raise_buffer_error(:read, buffer, data_type, given_bit_offset, given_bit_size) unless result

  if (data_type == :STRING) || (data_type == :BLOCK)
    #######################################
    # Handle :STRING and :BLOCK data types
    #######################################

    if byte_aligned(bit_offset)
      if data_type == :STRING
        return buffer[lower_bound..upper_bound].unpack('Z*')[0]
      else
        return buffer[lower_bound..upper_bound].unpack('a*')[0]
      end
    else
      raise(ArgumentError, "bit_offset #{given_bit_offset} is not byte aligned for data_type #{data_type}")
    end

  elsif (data_type == :INT) || (data_type == :UINT)
    ###################################
    # Handle :INT and :UINT data types
    ###################################

    if byte_aligned(bit_offset) && even_bit_size(bit_size)

      if data_type == :INT
        ###########################################################
        # Handle byte-aligned 8, 16, 32, and 64 bit :INT
        ###########################################################

        case bit_size
        when 8
          return buffer[lower_bound].unpack(PACK_8_BIT_INT)[0]
        when 16
          if endianness == HOST_ENDIANNESS
            return buffer[lower_bound..upper_bound].unpack(PACK_NATIVE_16_BIT_INT)[0]
          else # endianness != HOST_ENDIANNESS
            temp = buffer[lower_bound..upper_bound].reverse
            return temp.unpack(PACK_NATIVE_16_BIT_INT)[0]
          end
        when 32
          if endianness == HOST_ENDIANNESS
            return buffer[lower_bound..upper_bound].unpack(PACK_NATIVE_32_BIT_INT)[0]
          else # endianness != HOST_ENDIANNESS
            temp = buffer[lower_bound..upper_bound].reverse
            return temp.unpack(PACK_NATIVE_32_BIT_INT)[0]
          end
        when 64
          if endianness == HOST_ENDIANNESS
            return buffer[lower_bound..upper_bound].unpack(PACK_NATIVE_64_BIT_INT)[0]
          else # endianness != HOST_ENDIANNESS
            temp = buffer[lower_bound..upper_bound].reverse
            return temp.unpack(PACK_NATIVE_64_BIT_INT)[0]
          end
        end
      else # data_type == :UINT
        ###########################################################
        # Handle byte-aligned 8, 16, 32, and 64 bit :UINT
        ###########################################################

        case bit_size
        when 8
          return buffer.getbyte(lower_bound)
        when 16
          if endianness == :BIG_ENDIAN
            return buffer[lower_bound..upper_bound].unpack(PACK_BIG_ENDIAN_16_BIT_UINT)[0]
          else # endianness == :LITTLE_ENDIAN
            return buffer[lower_bound..upper_bound].unpack(PACK_LITTLE_ENDIAN_16_BIT_UINT)[0]
          end
        when 32
          if endianness == :BIG_ENDIAN
            return buffer[lower_bound..upper_bound].unpack(PACK_BIG_ENDIAN_32_BIT_UINT)[0]
          else # endianness == :LITTLE_ENDIAN
            return buffer[lower_bound..upper_bound].unpack(PACK_LITTLE_ENDIAN_32_BIT_UINT)[0]
          end
        when 64
          if endianness == HOST_ENDIANNESS
            return buffer[lower_bound..upper_bound].unpack(PACK_NATIVE_64_BIT_UINT)[0]
          else # endianness != HOST_ENDIANNESS
            temp = buffer[lower_bound..upper_bound].reverse
            return temp.unpack(PACK_NATIVE_64_BIT_UINT)[0]
          end
        end
      end

    else
      ##########################
      # Handle :INT and :UINT Bitfields
      ##########################

      # Extract Data for Bitfield
      if endianness == :LITTLE_ENDIAN
        # Bitoffset always refers to the most significant bit of a bitfield
        num_bytes = (((bit_offset % 8) + bit_size - 1) / 8) + 1
        upper_bound = bit_offset / 8
        lower_bound = upper_bound - num_bytes + 1

        if lower_bound < 0
          raise(ArgumentError, "LITTLE_ENDIAN bitfield with bit_offset #{given_bit_offset} and bit_size #{given_bit_size} is invalid")
        end

        temp_data = buffer[lower_bound..upper_bound].reverse
      else
        temp_data = buffer[lower_bound..upper_bound]
      end

      # Determine temp upper bound
      temp_upper = upper_bound - lower_bound

      # Handle Bitfield
      start_bits = bit_offset % 8
      start_mask = ~(0xFF << (8 - start_bits))
      total_bits = (temp_upper + 1) * 8
      right_shift = total_bits - start_bits - bit_size

      # Mask off unwanted bits at beginning
      temp = temp_data.getbyte(0) & start_mask

      if upper_bound > lower_bound
        # Combine bytes into a FixNum
        temp_data[1..temp_upper].each_byte { |temp_value| temp = temp << 8; temp = temp + temp_value }
      end

      # Shift off unwanted bits at end
      temp = temp >> right_shift

      if data_type == :INT
        # Convert to negative if necessary
        if (bit_size > 1) && (temp[bit_size - 1] == 1)
          temp = -((1 << bit_size) - temp)
        end
      end

      return temp
    end

  elsif data_type == :FLOAT
    ##########################
    # Handle :FLOAT data type
    ##########################

    if byte_aligned(bit_offset)
      case bit_size
      when 32
        if endianness == :BIG_ENDIAN
          return buffer[lower_bound..upper_bound].unpack(PACK_BIG_ENDIAN_32_BIT_FLOAT)[0]
        else # endianness == :LITTLE_ENDIAN
          return buffer[lower_bound..upper_bound].unpack(PACK_LITTLE_ENDIAN_32_BIT_FLOAT)[0]
        end
      when 64
        if endianness == :BIG_ENDIAN
          return buffer[lower_bound..upper_bound].unpack(PACK_BIG_ENDIAN_64_BIT_FLOAT)[0]
        else # endianness == :LITTLE_ENDIAN
          return buffer[lower_bound..upper_bound].unpack(PACK_LITTLE_ENDIAN_64_BIT_FLOAT)[0]
        end
      else
        raise(ArgumentError, "bit_size is #{given_bit_size} but must be 32 or 64 for data_type #{data_type}")
      end
    else
      raise(ArgumentError, "bit_offset #{given_bit_offset} is not byte aligned for data_type #{data_type}")
    end

  else
    ############################
    # Handle Unknown data types
    ############################

    raise(ArgumentError, "data_type #{data_type} is not recognized")
  end

  return return_value
end

Method: OpenC3::BinaryAccessor.read

.read(param_bit_offset, param_bit_size, param_data_type, param_buffer, param_endianness) ⇒ Integer

.read(param_bit_offset, param_bit_size, param_data_type, param_buffer, param_endianness) ⇒ `Integer`