# :markup: ruby

class String
  # call-seq:
  #   String.new(string = '') -> new_string
  #   String.new(string = '', encoding: encoding) -> new_string
  #   String.new(string = '', capacity: size) -> new_string
  #
  # Returns a new \String that is a copy of +string+.
  #
  # With no arguments, returns the empty string with the Encoding <tt>ASCII-8BIT</tt>:
  #   s = String.new
  #   s # => ""
  #   s.encoding # => #<Encoding:ASCII-8BIT>
  #
  # With the single \String argument +string+, returns a copy of +string+
  # with the same encoding as +string+:
  #   s = String.new('Que veut dire ça?')
  #   s # => "Que veut dire ça?"
  #   s.encoding # => #<Encoding:UTF-8>
  #
  # Literal strings like <tt>""</tt> or here-documents always use
  # Encoding@Script+encoding, unlike String.new.
  #
  # With keyword +encoding+, returns a copy of +str+
  # with the specified encoding:
  #   s = String.new(encoding: 'ASCII')
  #   s.encoding # => #<Encoding:US-ASCII>
  #   s = String.new('foo', encoding: 'ASCII')
  #   s.encoding # => #<Encoding:US-ASCII>
  #
  # Note that these are equivalent:
  #   s0 = String.new('foo', encoding: 'ASCII')
  #   s1 = 'foo'.force_encoding('ASCII')
  #   s0.encoding == s1.encoding # => true
  #
  # With keyword +capacity+, returns a copy of +str+;
  # the given +capacity+ may set the size of the internal buffer,
  # which may affect performance:
  #   String.new(capacity: 1) # => ""
  #   String.new(capacity: 4096) # => ""
  #
  # The +string+, +encoding+, and +capacity+ arguments may all be used together:
  #
  #   String.new('hello', encoding: 'UTF-8', capacity: 25)
  #
  def initialize(str = '', encoding: nil, capacity: nil)
    Primitive.rb_str_init(str, encoding, capacity)
  end

  #  call-seq:
  #    bytes -> array_of_bytes
  #
  #  Returns an array of the bytes in +self+:
  #
  #    'hello'.bytes # => [104, 101, 108, 108, 111]
  #    'тест'.bytes  # => [209, 130, 208, 181, 209, 129, 209, 130]
  #    'こんにちは'.bytes
  #    # => [227, 129, 147, 227, 130, 147, 227, 129, 171, 227, 129, 161, 227, 129, 175]
  #
  def bytes; end

  #  call-seq:
  #    each_byte {|byte| ... } -> self
  #    each_byte               -> enumerator
  #
  #  Calls the given block with each successive byte from +self+;
  #  returns +self+:
  #
  #    'hello'.each_byte {|byte| print byte, ' ' }
  #    print "\n"
  #    'тест'.each_byte {|byte| print byte, ' ' }
  #    print "\n"
  #    'こんにちは'.each_byte {|byte| print byte, ' ' }
  #    print "\n"
  #
  #  Output:
  #
  #    104 101 108 108 111
  #    209 130 208 181 209 129 209 130
  #    227 129 147 227 130 147 227 129 171 227 129 161 227 129 175
  #
  #  Returns an enumerator if no block is given.
  def each_byte; end


  #  call-seq:
  #    each_line(line_sep = $/, chomp: false) {|substring| ... } -> self
  #    each_line(line_sep = $/, chomp: false)                    -> enumerator
  #
  #  With a block given, forms the substrings ("lines")
  #  that are the result of splitting +self+
  #  at each occurrence of the given line separator +line_sep+;
  #  passes each line to the block;
  #  returns +self+:
  #
  #    s = <<~EOT
  #    This is the first line.
  #    This is line two.
  #
  #    This is line four.
  #    This is line five.
  #    EOT
  #
  #    s.each_line {|line| p line }
  #
  #  Output:
  #
  #    "This is the first line.\n"
  #    "This is line two.\n"
  #    "\n"
  #    "This is line four.\n"
  #    "This is line five.\n"
  #
  #  With a different +line_sep+:
  #
  #    s.each_line(' is ') {|line| p line }
  #
  #  Output:
  #
  #    "This is "
  #    "the first line.\nThis is "
  #    "line two.\n\nThis is "
  #    "line four.\nThis is "
  #    "line five.\n"
  #
  #  With +chomp+ as +true+, removes the trailing +line_sep+ from each line:
  #
  #    s.each_line(chomp: true) {|line| p line }
  #
  #  Output:
  #
  #    "This is the first line."
  #    "This is line two."
  #    ""
  #    "This is line four."
  #    "This is line five."
  #
  #  With an empty string as +line_sep+,
  #  forms and passes "paragraphs" by splitting at each occurrence
  #  of two or more newlines:
  #
  #    s.each_line('') {|line| p line }
  #
  #  Output:
  #
  #    "This is the first line.\nThis is line two.\n\n"
  #    "This is line four.\nThis is line five.\n"
  #
  #  With no block given, returns an enumerator.
  #
  def each_line; end

  #  call-seq:
  #    split(field_sep = $;, limit = nil) -> array
  #    split(field_sep = $;, limit = nil) {|substring| ... } -> self
  #
  #  Returns an array of substrings of +self+
  #  that are the result of splitting +self+
  #  at each occurrence of the given field separator +field_sep+.
  #
  #  When +field_sep+ is <tt>$;</tt>:
  #
  #  - If <tt>$;</tt> is +nil+ (its default value),
  #    the split occurs just as if +field_sep+ were given as a space character
  #    (see below).
  #
  #  - If <tt>$;</tt> is a string,
  #    the split ocurs just as if +field_sep+ were given as that string
  #    (see below).
  #
  #  When +field_sep+ is <tt>' '</tt> and +limit+ is +nil+,
  #  the split occurs at each sequence of whitespace:
  #
  #    'abc def ghi'.split(' ')          # => ["abc", "def", "ghi"]
  #    "abc \n\tdef\t\n  ghi".split(' ') # => ["abc", "def", "ghi"]
  #    'abc  def   ghi'.split(' ')       # => ["abc", "def", "ghi"]
  #    ''.split(' ')                     # => []
  #
  #  When +field_sep+ is a string different from <tt>' '</tt>
  #  and +limit+ is +nil+,
  #  the split occurs at each occurrence of +field_sep+;
  #  trailing empty substrings are not returned:
  #
  #    'abracadabra'.split('ab')   # => ["", "racad", "ra"]
  #    'aaabcdaaa'.split('a')      # => ["", "", "", "bcd"]
  #    ''.split('a')               # => []
  #    '3.14159'.split('1')        # => ["3.", "4", "59"]
  #    '!@#$%^$&*($)_+'.split('$') # => ["!@#", "%^", "&*(", ")_+"]
  #    'тест'.split('т')           # => ["", "ес"]
  #    'こんにちは'.split('に')      # => ["こん", "ちは"]
  #
  #  When +field_sep+ is a Regexp and +limit+ is +nil+,
  #  the split occurs at each occurrence of a match;
  #  trailing empty substrings are not returned:
  #
  #    'abracadabra'.split(/ab/) # => ["", "racad", "ra"]
  #    'aaabcdaaa'.split(/a/)    # => ["", "", "", "bcd"]
  #    'aaabcdaaa'.split(//)     # => ["a", "a", "a", "b", "c", "d", "a", "a", "a"]
  #    '1 + 1 == 2'.split(/\W+/) # => ["1", "1", "2"]
  #
  #  If the \Regexp contains groups, their matches are also included
  #  in the returned array:
  #
  #    '1:2:3'.split(/(:)()()/, 2) # => ["1", ":", "", "", "2:3"]
  #
  #  As seen above, if +limit+ is +nil+,
  #  trailing empty substrings are not returned;
  #  the same is true if +limit+ is zero:
  #
  #    'aaabcdaaa'.split('a')    # => ["", "", "", "bcd"]
  #    'aaabcdaaa'.split('a', 0) # => ["", "", "", "bcd"]
  #
  #  If +limit+ is positive integer +n+, no more than <tt>n - 1-</tt>
  #  splits occur, so that at most +n+ substrings are returned,
  #  and trailing empty substrings are included:
  #
  #    'aaabcdaaa'.split('a', 1) # => ["aaabcdaaa"]
  #    'aaabcdaaa'.split('a', 2) # => ["", "aabcdaaa"]
  #    'aaabcdaaa'.split('a', 5) # => ["", "", "", "bcd", "aa"]
  #    'aaabcdaaa'.split('a', 7) # => ["", "", "", "bcd", "", "", ""]
  #    'aaabcdaaa'.split('a', 8) # => ["", "", "", "bcd", "", "", ""]
  #
  #  Note that if +field_sep+ is a \Regexp containing groups,
  #  their matches are in the returned array, but do not count toward the limit.
  #
  #  If +limit+ is negative, it behaves the same as if +limit+ was +nil+,
  #  meaning that there is no limit,
  #  and trailing empty substrings are included:
  #
  #    'aaabcdaaa'.split('a', -1) # => ["", "", "", "bcd", "", "", ""]
  #
  #  If a block is given, it is called with each substring:
  #
  #    'abc def ghi'.split(' ') {|substring| p substring }
  #
  #  Output:
  #
  #    "abc"
  #    "def"
  #    "ghi"
  #
  def split; end

end