Class: BinData::String

Inherits:
BasePrimitive show all
Defined in:
lib/bindata/string.rb

Overview

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.

Instance Attribute Summary

Attributes inherited from Base

#parent

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from BasePrimitive

#<=>, bit_aligned, #clear?, #do_num_bytes, #do_read, #do_read_with_hook, #do_write, #eql?, #hash, #initialize_instance, #initialize_shared_instance, #method_missing, #respond_to?, #trace_value, turn_off_tracing, turn_on_tracing, #value

Methods inherited from Base

#==, #=~, arg_extractor, bindata_name, #clear, #debug_name, #eval_parameter, #get_parameter, #has_parameter?, #initialize_instance, #initialize_with_warning, #inspect, #lazy_evaluator, #new, #num_bytes, #offset, #pretty_print, #read, read, register_subclasses, #rel_offset, #safe_respond_to?, #to_binary_s, #to_s, unregister_self, #write

Methods included from AcceptedParametersPlugin

#accepted_parameters, #default_parameters, #mandatory_parameters, #mutually_exclusive_parameters, #optional_parameters

Methods included from RegisterNamePlugin

included, #initialize_shared_instance

Methods included from CheckOrAdjustOffsetPlugin

included, #initialize_shared_instance

Methods included from Framework

#clear?, #debug_name_of, included, #offset_of

Dynamic Method Handling

This class handles dynamic methods through the method_missing method in the class BinData::BasePrimitive

Class Method Details

.sanitize_parameters!(params) ⇒ Object

:nodoc:



60
61
62
63
64
65
66
67
68
69
70
71
72
73
 
# File 'lib/bindata/string.rb', line 60

def sanitize_parameters!(params) #:nodoc:
  params.warn_replacement_parameter(:initial_length, :read_length)

  params.warn_renamed_parameter(:pad_char, :pad_byte) # Remove this line in the future

  if params.has_parameter?(:pad_left)
    params[:pad_front] = params.delete(:pad_left)
  end

  if params.has_parameter?(:pad_byte)
    byte = params[:pad_byte]
    params[:pad_byte] = sanitized_pad_byte(byte)
  end
end

Instance Method Details

#assign(val) ⇒ Object 



88
89
90
 
# File 'lib/bindata/string.rb', line 88

def assign(val)
  super(binary_string(val))
end

#snapshot ⇒ Object 



92
93
94
95
96
97
98
99
100
101
 
# File 'lib/bindata/string.rb', line 92

def snapshot
  # override to trim padding
  result = super
  result = clamp_to_length(result)

  if get_parameter(:trim_padding)
    result = trim_padding(result)
  end
  result
end