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
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
Initializes the C string.
@param [String, ByteSlice
, nil] value
The contents of the C string.
# 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
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.
# 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
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
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
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
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
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
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
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
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
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