Comment for future documentation of String#[] (etc.)

Hi!

I tested some minutes ago the access to individual characters
in a string object. I did this with an ascii and an utf-8 encoded
string. Here is the variant that adds one character to a pure
ascii string, in one case a "x", in the other a "竄ャ", but did
access the character before this one...

require 'benchmark'
include Benchmark

utf8 =     'abcdefgh' * 1000000 + '竄ャ'
ascii =    'abcdefgh' * 1000000 + 'x'

puts "Zeichen in 'utf8':          #{utf8.length}"
puts "Bytes in 'utf8':            #{utf8.bytesize}"
puts "Encoding von 'utf8':        #{utf8.encoding}"
puts "Zeichen 8000001 in 'utf8':  #{utf8[8000000]}"
puts ""
puts "Zeichen in 'ascii':         #{ascii.length}"
puts "Bytes in 'ascii':           #{ascii.bytesize}"
puts "Encoding von 'ascii':       #{ascii.encoding}"
puts "Zeichen 8000001 in 'ascii': #{ascii[8000000]}"
puts ""

bm(10) do |t|
   t.report('utf8'){100.times{utf8[7999999]}}
   t.report('ascii'){100.times{ascii[7999999]}}
end

...which gave the result (Ruby 1.9.0-0, MinGW/MSYS, Windows2000)...

Zeichen in 'utf8':          8000001
Bytes in 'utf8':            8000003
Encoding von 'utf8':        UTF-8
Zeichen 8000001 in 'utf8':  竄ャ

Zeichen in 'ascii':         8000001
Bytes in 'ascii':           8000001
Encoding von 'ascii':       ASCII-8BIT
Zeichen 8000001 in 'ascii': x

                 user     system      total        real
utf8      117.229000   0.030000 117.259000 (140.752000)
ascii       0.000000   0.000000   0.000000 (  0.000000)

The reason is clear, but there should be a remark in the future
documentation for the methods of class String, that will access
individual characters, that these methods can be very inefficient
when the string is utf-8 encoded and contains somewhere a character
that needs more than one byte.

Wolfgang Nテ。dasi-Donner