class Ronin::Support::Binary::CString

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"

@api public

@since 1.0.0

Constants

NULL

Null byte

Public Class Methods

[](*values) click to toggle source

Creates a C string.

@param [Array<Integer>, Array<String>] values

The bytes or characters for the new C string.

@return [CString]

The newly created C string.

@example Create a C string from a series of bytes:

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

@example Create a C string from a series of chars:

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

@example Create a C string from a String:

Binary::CString["AAA"]

@see initialize

# 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
new(value=nil) click to toggle source

Initializes the C string.

@param [String, ByteSlice, nil] value

The contents of the C string.
Calls superclass method
# 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

Public Instance Methods

+(other) click to toggle source

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

@param [#to_s, Integer] other

The other String or an offset.

@return [CString, ByteSlice]

The new combined C string, or a {ByteSlice} if an offset Integer
was given.
Calls superclass method
# 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
<<(value)
Alias for: concat
bytes() click to toggle source

The bytes within the C string.

@return [Array<Integer>]

The Array of bytes within the C string.
# File lib/ronin/support/binary/cstring.rb, line 244
def bytes
  each_byte.to_a
end
chars() click to toggle source

The characters within the C string.

@return [Array<String>]

The Array of characters within the C string.
# File lib/ronin/support/binary/cstring.rb, line 211
def chars
  each_char.to_a
end
concat(value) click to toggle source

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

@param [String, Integer, to_s] value

The other String to concat to the C string.

@return [self]

# 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
Also aliased as: <<
each_byte() { |byte| ... } click to toggle source

Enumerates over each byte within the C string.

@yield [byte]

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

@yieldparam [Integer] byte

A byte within the C string.

@return [Enumerator]

If no block is given, an Enumerator will be returned.
# 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| ... } click to toggle source

Enumerates over each characters within the C string.

@yield [char]

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

@yieldparam [String] char

A character within the C string.

@return [Enumerator]

If no block is given, an Enumerator will be returned.
# 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) click to toggle source

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

@param [String, Integer, Regexp] key

The char, byte, substring, or Regexp to search for.

@return [Integer, nil]

The index of the char, byte, substring, or Regexp.
# 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
len()
Alias for: length
length() click to toggle source

The length of the C string.

@return [Integer]

The number of non-null characters in the String.
# File lib/ronin/support/binary/cstring.rb, line 271
def length
  null_index || size
end
Also aliased as: len
to_s() click to toggle source

Converts the C stirng into a regular String.

@return [String]

The C string without it's terminating null byte.
# 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

Private Instance Methods

null_index() click to toggle source

Finds the index of the first null byte (‘0`).

@return [Integer, nil]

# File lib/ronin/support/binary/cstring.rb, line 298
def null_index
  @string.index(NULL)
end