class BinData::String

A String is a sequence of bytes. This is the same as strings in Ruby 1.8. The issue of character encoding is ignored by this class.

require 'bindata'

data = "abcdefghij"

obj = BinData::String.new(:read_length => 5)
obj.read(data)
obj #=> "abcde"

obj = BinData::String.new(:length => 6)
obj.read(data)
obj #=> "abcdef"
obj.assign("abcdefghij")
obj #=> "abcdef"
obj.assign("abcd")
obj #=> "abcd\000\000"

obj = BinData::String.new(:length => 6, :trim_padding => true)
obj.assign("abcd")
obj #=> "abcd"
obj.to_binary_s #=> "abcd\000\000"

obj = BinData::String.new(:length => 6, :pad_byte => 'A')
obj.assign("abcd")
obj #=> "abcdAA"
obj.to_binary_s #=> "abcdAA"

Parameters

String objects accept all the params that BinData::BasePrimitive does, as well as the following:

:read_length

The length in bytes to use when reading a value.

:length

The fixed length of the string. If a shorter string is set, it will be padded to this length.

:pad_byte

The byte to use when padding a string to a set length. Valid values are Integers and Strings of length 1. “0” is the default.

:pad_front

Signifies that the padding occurs at the front of the string rather than the end. Default is false.

:trim_padding

Boolean, default false. If set, value will return the value with all pad_bytes trimmed from the end of the string. The value will not be trimmed when writing.

Public Instance Methods

assign(val) click to toggle source
Calls superclass method BinData::BasePrimitive#assign
# File lib/bindata/string.rb, line 67
def assign(val)
  super(binary_string(val))
end
initialize_shared_instance() click to toggle source
# File lib/bindata/string.rb, line 59
def initialize_shared_instance
  if (has_parameter?(:value) || has_parameter?(:asserted_value)) &&
      ! has_parameter?(:read_length)
    extend WarnNoReadLengthPlugin
  end
  super
end
snapshot() click to toggle source
Calls superclass method BinData::BasePrimitive#snapshot
# File lib/bindata/string.rb, line 71
def snapshot
  # override to trim padding
  snap = super
  snap = clamp_to_length(snap)

  if get_parameter(:trim_padding)
    trim_padding(snap)
  else
    snap
  end
end

Private Instance Methods

clamp_to_length(str) click to toggle source
# File lib/bindata/string.rb, line 86
def clamp_to_length(str)
  str = binary_string(str)

  len = eval_parameter(:length) || str.length
  if str.length == len
    str
  elsif str.length > len
    str.slice(0, len)
  else
    padding = (eval_parameter(:pad_byte) * (len - str.length))
    if get_parameter(:pad_front)
      padding + str
    else
      str + padding
    end
  end
end
read_and_return_value(io) click to toggle source
# File lib/bindata/string.rb, line 116
def read_and_return_value(io)
  len = eval_parameter(:read_length) || eval_parameter(:length) || 0
  io.readbytes(len)
end
sensible_default() click to toggle source
# File lib/bindata/string.rb, line 121
def sensible_default
  ""
end
trim_padding(str) click to toggle source
# File lib/bindata/string.rb, line 104
def trim_padding(str)
  if get_parameter(:pad_front)
    str.sub(/\A#{eval_parameter(:pad_byte)}*/, "")
  else
    str.sub(/#{eval_parameter(:pad_byte)}*\z/, "")
  end
end
value_to_binary_string(val) click to toggle source
# File lib/bindata/string.rb, line 112
def value_to_binary_string(val)
  clamp_to_length(val)
end