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).

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



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

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

Instance Attribute Details

#static_length ⇒ Integer? (readonly)

Static length, if any

Returns:

  • (Integer, nil) 


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

def static_length
  @static_length
end

#string ⇒ ::String (readonly)

Underlying Ruby String

Returns:

  • (::String) 


72
73
74
 
# File 'lib/bin_struct/cstring.rb', line 72

def string
  @string
end

Instance Method Details

#<<(str) ⇒ self

Append the given string to CString

Parameters:

Returns:

  • (self) 


110
111
112
113
114
 
# File 'lib/bin_struct/cstring.rb', line 110

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

#== ⇒ Boolean

Check equality with underlying Ruby String

Returns:

  • (Boolean) 


66
67
68
 
# File 'lib/bin_struct/cstring.rb', line 66

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) 


66
67
68
 
# File 'lib/bin_struct/cstring.rb', line 66

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) 


66
67
68
 
# File 'lib/bin_struct/cstring.rb', line 66

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


66
67
68
 
# File 'lib/bin_struct/cstring.rb', line 66

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

#encoding ⇒ Encoding

Returns:

  • (Encoding)

See Also:

  • String#encoding


66
67
68
 
# File 'lib/bin_struct/cstring.rb', line 66

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

#force_encoding ⇒ Object

See Also:

  • String#force_encoding


66
67
68
 
# File 'lib/bin_struct/cstring.rb', line 66

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) 


135
136
137
 
# File 'lib/bin_struct/cstring.rb', line 135

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) 


66
67
68
 
# File 'lib/bin_struct/cstring.rb', line 66

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) 


66
67
68
 
# File 'lib/bin_struct/cstring.rb', line 66

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

#read(str) ⇒ self

Populate self from binary string

Parameters:

  • str (::String)

Returns:

  • (self) 


87
88
89
90
91
92
93
 
# File 'lib/bin_struct/cstring.rb', line 87

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:



66
67
68
 
# File 'lib/bin_struct/cstring.rb', line 66

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


66
67
68
 
# File 'lib/bin_struct/cstring.rb', line 66

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!


66
67
68
 
# File 'lib/bin_struct/cstring.rb', line 66

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) 


128
129
130
 
# File 'lib/bin_struct/cstring.rb', line 128

def static_length?
  !static_length.nil?
end

#sz ⇒ Integer

Get C String size in bytes

Returns:

  • (Integer) 


118
119
120
121
122
123
124
 
# File 'lib/bin_struct/cstring.rb', line 118

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

#to_human ⇒ ::String

Get human-readable string

Returns:

  • (::String) 


141
142
143
 
# File 'lib/bin_struct/cstring.rb', line 141

def to_human
  string
end

#to_s ⇒ ::String

Get null-terminated string

Returns:

  • (::String) 


97
98
99
100
101
102
103
104
105
 
# File 'lib/bin_struct/cstring.rb', line 97

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

#unpack ⇒ ::Array

Apply unpack on underlying Ruby String

Returns:

  • (::Array)

See Also:

  • String#unpack


66
67
68
 
# File 'lib/bin_struct/cstring.rb', line 66

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