Class: Ronin::Support::Binary::CString

Inherits:
Memory
  • Object
show all
Defined in:
lib/ronin/support/binary/cstring.rb

Overview

Represents a null terminated C string.

Examples

Initializing C Strings

From a String:

str = Binary::CString.new("hello ")
# => #<Ronin::Support::Binary::CString:0x00007fc94ba577f8 @string="hello \u0000">

From a binary C string:

str = Binary::CString.new("world\0".b)
# => #<Ronin::Support::Binary::CString:0x00007fc94ba06f88 @string="world\u0000">

From characters:

str = Binary::CString['A', 'B', 'C']
# => #<Ronin::Support::Binary::CString:0x00007fc94ba6f268 @string="ABC\x00">

Modifying C Strings

Concating Strings to a C String:

str = Binary::CString.new("hello ")
str.concat("world")
# => #<Ronin::Support::Binary::CString:0x00007fc94b978df0 @string="hello world\u0000">
str.to_s
# => "hello world"

Appending two C Strings:

str1 = Binary::CString.new("hello ")
str2 = Binary::CString.new("world\0")
str = str1 + str2
# => #<Ronin::Support::Binary::CString:0x00007fc94b9523f8 @string="hello world\u0000">

Setting characters:

str = Binary::CString.new("hello")
str[0] = 'X'
str.to_s
# => "Xello"

Since:

  • 1.0.0

Constant Summary collapse

NULL =

Null byte

Since:

  • 1.0.0

"\0".encode(Encoding::ASCII_8BIT).freeze

Instance Attribute Summary

Attributes inherited from Memory

#string

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from Memory

#[], #[]=, #byteslice, #clear, #copy_from, #copy_to, #pack, #read_from, #size

Constructor Details

#initialize(value = nil) ⇒ CString

Initializes the C string.

Parameters:

  • value (String, ByteSlice, nil) (defaults to: nil) —

    The contents of the C string.

Since:

  • 1.0.0



85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
 
# File 'lib/ronin/support/binary/cstring.rb', line 85

def initialize(value=nil)
  case value
  when String
    if value.include?(NULL)
      super(value)
    else
      # ensure the C String ends in or contains a NULL byte.
      super("#{value}#{NULL}")
    end
  when nil
    # initialize with a single \0 byte
    super(1)
  else
    super(value)
  end
end

Class Method Details

.[](*values) ⇒ CString

Creates a C string.

Examples:

Create a C string from a series of bytes:

Binary::CString[0x41, 0x41, 0x41, 0x00, 0x00, 0x00]

Create a C string from a series of chars:

Binary::CString['A', 'A', 'A']

Create a C string from a String:

Binary::CString["AAA"]

Parameters:

Returns:

  • (CString) —

    The newly created C string.

See Also:

Since:

  • 1.0.0



122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
 
# File 'lib/ronin/support/binary/cstring.rb', line 122

def self.[](*values)
  buffer = String.new

  values.each do |element|
    buffer << case element
              when Integer then element.chr
              else              element.to_s
              end
  end

  # ensure the C String ends in or contains a NULL byte.
  buffer << NULL unless buffer.include?(NULL)

  return new(buffer)
end

Instance Method Details

#+(other) ⇒ CString, ByteSlice

Creates a new C string by adding two C strings together.

Parameters:

  • other (#to_s, Integer) —

    The other String or an offset.

Returns:

Since:

  • 1.0.0



175
176
177
178
179
180
 
# File 'lib/ronin/support/binary/cstring.rb', line 175

def +(other)
  case other
  when Integer then super(other)
  else              CString.new(to_s + other.to_s)
  end
end

#bytes ⇒ Array<Integer>

The bytes within the C string.

Returns:

  • (Array<Integer>) —

    The Array of bytes within the C string.

Since:

  • 1.0.0



244
245
246
 
# File 'lib/ronin/support/binary/cstring.rb', line 244

def bytes
  each_byte.to_a
end

#chars ⇒ Array<String>

The characters within the C string.

Returns:

  • (Array<String>) —

    The Array of characters within the C string.

Since:

  • 1.0.0



211
212
213
 
# File 'lib/ronin/support/binary/cstring.rb', line 211

def chars
  each_char.to_a
end

#concat(value) ⇒ self Also known as: <<

Concatinates a character, byte, or String to the C string.

Parameters:

Returns:

  • (self)

Since:

  • 1.0.0



146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
 
# File 'lib/ronin/support/binary/cstring.rb', line 146

def concat(value)
  value      = case value
               when Integer then value.chr
               else              value.to_s
               end
  value_size = value.bytesize

  unless value.include?(NULL)
    value = "#{value}#{NULL}"

    value_size += 1
  end

  self[null_index,value_size] = value
  return self
end

#each_byte {|byte| ... } ⇒ Enumerator

Enumerates over each byte within the C string.

Yields:

  • (byte) —

    If a block is given, it will be passed each character within the C string.

Yield Parameters:

  • byte (Integer) —

    A byte within the C string.

Returns:

  • (Enumerator) —

    If no block is given, an Enumerator will be returned.

Since:

  • 1.0.0



228
229
230
231
232
233
234
235
236
 
# File 'lib/ronin/support/binary/cstring.rb', line 228

def each_byte(&block)
  return enum_for(__method__) unless block_given?

  @string.each_byte do |byte|
    break if byte == 0x00

    yield byte
  end
end

#each_char {|char| ... } ⇒ Enumerator

Enumerates over each characters within the C string.

Yields:

  • (char) —

    If a block is given, it will be passed each character within the C string.

Yield Parameters:

  • char (String) —

    A character within the C string.

Returns:

  • (Enumerator) —

    If no block is given, an Enumerator will be returned.

Since:

  • 1.0.0



195
196
197
198
199
200
201
202
203
 
# File 'lib/ronin/support/binary/cstring.rb', line 195

def each_char
  return enum_for(__method__) unless block_given?

  @string.each_char do |char|
    break if char == NULL

    yield char
  end
end

#index(key) ⇒ Integer?

Searches for the char, byte, substring, or regexp within the C string.

Parameters:

Returns:

  • (Integer, nil) —

    The index of the char, byte, substring, or Regexp.

Since:

  • 1.0.0



257
258
259
260
261
262
263
 
# File 'lib/ronin/support/binary/cstring.rb', line 257

def index(key)
  if (index = @string.index(key))
    if index < null_index
      return index
    end
  end
end

#length ⇒ Integer Also known as: len

The length of the C string.

Returns:

  • (Integer) —

    The number of non-null characters in the String.

Since:

  • 1.0.0



271
272
273
 
# File 'lib/ronin/support/binary/cstring.rb', line 271

def length
  null_index || size
end

#to_s ⇒ String

Converts the C stirng into a regular String.

Returns:

  • (String) —

    The C string without it's terminating null byte.

Since:

  • 1.0.0



283
284
285
286
287
288
289
 
# File 'lib/ronin/support/binary/cstring.rb', line 283

def to_s
  if (length = null_index)
    @string[0,length]
  else
    @string.to_s
  end
end