Method: OpenC3::BinaryAccessor.read_array

Defined in:

lib/openc3/accessors/binary_accessor.rb

.read_array(bit_offset, bit_size, data_type, array_size, buffer, endianness) ⇒ Array

Reads an array of binary data of any data type from a buffer

Parameters:

• Bit offset to the start of the array. A negative number means to offset from the end of the buffer.

• Size of each item in the array in bits

• DATA_TYPES

• Size in bits of the array. 0 or negative means fill the array with as many bit_size number of items that exist (negative means excluding the final X number of bits).

• Binary string buffer to read from

• ENDIANNESS

Returns:

• Array created from reading the buffer

Raises:

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

def self.read_array(bit_offset, bit_size, data_type, array_size, buffer, endianness)
  # Save given values of bit offset, bit size, and array_size
  given_bit_offset = bit_offset
  given_bit_size = bit_size
  given_array_size = array_size

  # Handle negative and zero bit sizes
  raise ArgumentError, "bit_size #{given_bit_size} must be positive for arrays" if bit_size <= 0

  # Handle negative bit offsets
  if bit_offset < 0
    bit_offset = ((buffer.length * 8) + bit_offset)
    raise_buffer_error(:read, buffer, data_type, given_bit_offset, given_bit_size) if bit_offset < 0
  end

  # Handle negative and zero array sizes
  if array_size <= 0
    if given_bit_offset < 0
      raise ArgumentError, "negative or zero array_size (#{given_array_size}) cannot be given with negative bit_offset (#{given_bit_offset})"
    else
      array_size = ((buffer.length * 8) - bit_offset + array_size)
      if array_size == 0
        return []
      elsif array_size < 0
        raise_buffer_error(:read, buffer, data_type, given_bit_offset, given_bit_size)
      end
    end
  end

  # Calculate number of items in the array
  # If there is a remainder then we have a problem
  raise ArgumentError, "array_size #{given_array_size} not a multiple of bit_size #{given_bit_size}" if array_size % bit_size != 0

  num_items = array_size / bit_size

  # Define bounds of string to access this item
  lower_bound = bit_offset / 8
  upper_bound = (bit_offset + array_size - 1) / 8

  # Check for byte alignment
  byte_aligned = ((bit_offset % 8) == 0)

  case data_type
  when :STRING, :BLOCK
    #######################################
    # Handle :STRING and :BLOCK data types
    #######################################

    if byte_aligned
      value = []
      num_items.times do
        value << self.read(bit_offset, bit_size, data_type, buffer, endianness)
        bit_offset += bit_size
      end
    else
      raise ArgumentError, "bit_offset #{given_bit_offset} is not byte aligned for data_type #{data_type}"
    end

  when :INT, :UINT
    ###################################
    # Handle :INT and :UINT data types
    ###################################

    if byte_aligned and (bit_size == 8 or bit_size == 16 or bit_size == 32 or bit_size == 64)
      ###########################################################
      # Handle byte-aligned 8, 16, 32, and 64 bit :INT and :UINT
      ###########################################################

      case bit_size
      when 8
        if data_type == :INT
          value = buffer[lower_bound..upper_bound].unpack(PACK_8_BIT_INT_ARRAY)
        else # data_type == :UINT
          value = buffer[lower_bound..upper_bound].unpack(PACK_8_BIT_UINT_ARRAY)
        end

      when 16
        if data_type == :INT
          if endianness == HOST_ENDIANNESS
            value = buffer[lower_bound..upper_bound].unpack(PACK_NATIVE_16_BIT_INT_ARRAY)
          else # endianness != HOST_ENDIANNESS
            temp = self.byte_swap_buffer(buffer[lower_bound..upper_bound], 2)
            value = temp.to_s.unpack(PACK_NATIVE_16_BIT_INT_ARRAY)
          end
        else # data_type == :UINT
          if endianness == :BIG_ENDIAN
            value = buffer[lower_bound..upper_bound].unpack(PACK_BIG_ENDIAN_16_BIT_UINT_ARRAY)
          else # endianness == :LITTLE_ENDIAN
            value = buffer[lower_bound..upper_bound].unpack(PACK_LITTLE_ENDIAN_16_BIT_UINT_ARRAY)
          end
        end

      when 32
        if data_type == :INT
          if endianness == HOST_ENDIANNESS
            value = buffer[lower_bound..upper_bound].unpack(PACK_NATIVE_32_BIT_INT_ARRAY)
          else # endianness != HOST_ENDIANNESS
            temp = self.byte_swap_buffer(buffer[lower_bound..upper_bound], 4)
            value = temp.to_s.unpack(PACK_NATIVE_32_BIT_INT_ARRAY)
          end
        else # data_type == :UINT
          if endianness == :BIG_ENDIAN
            value = buffer[lower_bound..upper_bound].unpack(PACK_BIG_ENDIAN_32_BIT_UINT_ARRAY)
          else # endianness == :LITTLE_ENDIAN
            value = buffer[lower_bound..upper_bound].unpack(PACK_LITTLE_ENDIAN_32_BIT_UINT_ARRAY)
          end
        end

      when 64
        if data_type == :INT
          if endianness == HOST_ENDIANNESS
            value = buffer[lower_bound..upper_bound].unpack(PACK_NATIVE_64_BIT_INT_ARRAY)
          else # endianness != HOST_ENDIANNESS
            temp = self.byte_swap_buffer(buffer[lower_bound..upper_bound], 8)
            value = temp.to_s.unpack(PACK_NATIVE_64_BIT_INT_ARRAY)
          end
        else # data_type == :UINT
          if endianness == HOST_ENDIANNESS
            value = buffer[lower_bound..upper_bound].unpack(PACK_NATIVE_64_BIT_UINT_ARRAY)
          else # endianness != HOST_ENDIANNESS
            temp = self.byte_swap_buffer(buffer[lower_bound..upper_bound], 8)
            value = temp.to_s.unpack(PACK_NATIVE_64_BIT_UINT_ARRAY)
          end
        end
      end

    else
      ##################################
      # Handle :INT and :UINT Bitfields
      ##################################
      raise ArgumentError, "read_array does not support little endian bit fields with bit_size greater than 1-bit" if endianness == :LITTLE_ENDIAN and bit_size > 1

      value = []
      num_items.times do
        value << self.read(bit_offset, bit_size, data_type, buffer, endianness)
        bit_offset += bit_size
      end
    end

  when :FLOAT
    ##########################
    # Handle :FLOAT data type
    ##########################

    if byte_aligned
      case bit_size
      when 32
        if endianness == :BIG_ENDIAN
          value = buffer[lower_bound..upper_bound].unpack(PACK_BIG_ENDIAN_32_BIT_FLOAT_ARRAY)
        else # endianness == :LITTLE_ENDIAN
          value = buffer[lower_bound..upper_bound].unpack(PACK_LITTLE_ENDIAN_32_BIT_FLOAT_ARRAY)
        end

      when 64
        if endianness == :BIG_ENDIAN
          value = buffer[lower_bound..upper_bound].unpack(PACK_BIG_ENDIAN_64_BIT_FLOAT_ARRAY)
        else # endianness == :LITTLE_ENDIAN
          value = buffer[lower_bound..upper_bound].unpack(PACK_LITTLE_ENDIAN_64_BIT_FLOAT_ARRAY)
        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

  value
end