Class: BinStruct::CString

Inherits:
Object
  • Object
show all
Extended by:
Forwardable
Includes:
Structable
Defined in:
lib/bin_struct/cstring.rb

Overview

This class handles null-terminated strings (aka C strings). # @example

cstr = BinStruct::CString.new(value: 'abcd')
cstr.to_s #=> "abcd\x00".b

Author:

  • Sylvain Daubert (2016-2024)

  • LemonTree55

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Structable

#format_inspect, #type_name

Constructor Details

#initialize(options = {}) ⇒ CString

Returns a new instance of CString.

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :static_length (Integer) —

    set a static length for this string

  • :value (::String) —

    string value (default to “”)



83
84
85
86
 
# File 'lib/bin_struct/cstring.rb', line 83

def initialize(options = {})
  register_internal_string(options[:value] || +'')
  @static_length = options[:static_length]
end

Instance Attribute Details

#static_length ⇒ Integer? (readonly)

Static length, if any

Returns:

  • (Integer, nil) 


78
79
80
 
# File 'lib/bin_struct/cstring.rb', line 78

def static_length
  @static_length
end

#string ⇒ ::String (readonly)

Underlying Ruby String

Returns:

  • (::String) 


75
76
77
 
# File 'lib/bin_struct/cstring.rb', line 75

def string
  @string
end

Instance Method Details

#<<(str) ⇒ self

Append the given string to CString

Parameters:

Returns:

  • (self) 


114
115
116
117
118
 
# File 'lib/bin_struct/cstring.rb', line 114

def <<(str)
  @string << str.to_s
  remove_null_character
  self
end

#== ⇒ Boolean

Check equality with underlying Ruby String

Returns:

  • (Boolean) 


69
70
71
 
# File 'lib/bin_struct/cstring.rb', line 69

def_delegators :@string, :[], :length, :size, :inspect, :==,
:unpack, :force_encoding, :encoding, :index, :empty?,
:encode, :slice, :slice!

#[](index) ⇒ ::String? #[](start, length) ⇒ ::String?

Overloads:

  • #[](index) ⇒ ::String?

    Return the character at index.

    Parameters:

    • index (Integer)
  • #[](start, length) ⇒ ::String?

    Return the substring starting at start with length length.

    Parameters:

    • start (Integer)
    • length (Integer)

Returns:

  • (::String, nil) 


69
70
71
 
# File 'lib/bin_struct/cstring.rb', line 69

def_delegators :@string, :[], :length, :size, :inspect, :==,
:unpack, :force_encoding, :encoding, :index, :empty?,
:encode, :slice, :slice!

#empty? ⇒ Boolean

Return true is string is empty.

Returns:

  • (Boolean) 


69
70
71
 
# File 'lib/bin_struct/cstring.rb', line 69

def_delegators :@string, :[], :length, :size, :inspect, :==,
:unpack, :force_encoding, :encoding, :index, :empty?,
:encode, :slice, :slice!

#encode(encoding, **options) ⇒ ::String

Returns:

  • (::String)

See Also:

  • String#encode


69
70
71
 
# File 'lib/bin_struct/cstring.rb', line 69

def_delegators :@string, :[], :length, :size, :inspect, :==,
:unpack, :force_encoding, :encoding, :index, :empty?,
:encode, :slice, :slice!

#encoding ⇒ Encoding

Returns:

  • (Encoding)

See Also:

  • String#encoding


69
70
71
 
# File 'lib/bin_struct/cstring.rb', line 69

def_delegators :@string, :[], :length, :size, :inspect, :==,
:unpack, :force_encoding, :encoding, :index, :empty?,
:encode, :slice, :slice!

#force_encoding ⇒ Object

See Also:

  • String#force_encoding


69
70
71
 
# File 'lib/bin_struct/cstring.rb', line 69

def_delegators :@string, :[], :length, :size, :inspect, :==,
:unpack, :force_encoding, :encoding, :index, :empty?,
:encode, :slice, :slice!

#from_human(str) ⇒ self

Populate CString from a human readable string

Parameters:

  • str (::String)

Returns:

  • (self) 


139
140
141
 
# File 'lib/bin_struct/cstring.rb', line 139

def from_human(str)
  read(str)
end

#index(substring, offset = 0) ⇒ Integer?

Returns the Integer index of the first occurrence of the given substring, or nil if none found.

Parameters:

  • substring (::String)
  • offset (Integer) (defaults to: 0)

Returns:

  • (Integer, nil) 


69
70
71
 
# File 'lib/bin_struct/cstring.rb', line 69

def_delegators :@string, :[], :length, :size, :inspect, :==,
:unpack, :force_encoding, :encoding, :index, :empty?,
:encode, :slice, :slice!

#length ⇒ Integer

Return string length (without null-terminator)

Returns:

  • (Integer) 


69
70
71
 
# File 'lib/bin_struct/cstring.rb', line 69

def_delegators :@string, :[], :length, :size, :inspect, :==,
:unpack, :force_encoding, :encoding, :index, :empty?,
:encode, :slice, :slice!

#read(str) ⇒ self

Populate self from binary string

Parameters:

Returns:

  • (self) 


91
92
93
94
95
96
97
 
# File 'lib/bin_struct/cstring.rb', line 91

def read(str)
  s = str.to_s
  s = s[0, static_length] if static_length?
  register_internal_string s
  remove_null_character
  self
end

#size ⇒ Integer

Return string length (without null-terminator)

Returns:

  • (Integer)

See Also:



69
70
71
 
# File 'lib/bin_struct/cstring.rb', line 69

def_delegators :@string, :[], :length, :size, :inspect, :==,
:unpack, :force_encoding, :encoding, :index, :empty?,
:encode, :slice, :slice!

#slice(*args) ⇒ String?

Returns the substring of self specified by the arguments.

Returns:

See Also:

  • String#slice


69
70
71
 
# File 'lib/bin_struct/cstring.rb', line 69

def_delegators :@string, :[], :length, :size, :inspect, :==,
:unpack, :force_encoding, :encoding, :index, :empty?,
:encode, :slice, :slice!

#slice!(*args) ⇒ String?

Removes the substring of self specified by the arguments; returns the removed substring.

Returns:

See Also:

  • String#slice!


69
70
71
 
# File 'lib/bin_struct/cstring.rb', line 69

def_delegators :@string, :[], :length, :size, :inspect, :==,
:unpack, :force_encoding, :encoding, :index, :empty?,
:encode, :slice, :slice!

#static_length? ⇒ Boolean

Say if a static length is defined

Returns:

  • (Boolean) 


132
133
134
 
# File 'lib/bin_struct/cstring.rb', line 132

def static_length?
  !static_length.nil?
end

#sz ⇒ Integer

Get C String size in bytes

Returns:

  • (Integer) 


122
123
124
125
126
127
128
 
# File 'lib/bin_struct/cstring.rb', line 122

def sz
  if static_length?
    static_length
  else
    to_s.size
  end
end

#to_human ⇒ ::String

Get human-readable string

Returns:

  • (::String) 


145
146
147
 
# File 'lib/bin_struct/cstring.rb', line 145

def to_human
  string
end

#to_s ⇒ ::String

Get null-terminated string

Returns:

  • (::String) 


101
102
103
104
105
106
107
108
109
 
# File 'lib/bin_struct/cstring.rb', line 101

def to_s
  if static_length?
    s = string[0, static_length - 1]
    s << ("\x00" * (static_length - s.length))
  else
    s = "#{string}\x00"
  end
  s.b
end

#unpack ⇒ ::Array

Apply unpack on underlying Ruby String

Returns:

  • (::Array)

See Also:

  • String#unpack


69
70
71
 
# File 'lib/bin_struct/cstring.rb', line 69

def_delegators :@string, :[], :length, :size, :inspect, :==,
:unpack, :force_encoding, :encoding, :index, :empty?,
:encode, :slice, :slice!