Parent

Included Modules

Class Index [+]

Quicksearch

Mail::Multibyte::Chars

Chars enables you to work transparently with UTF-8 encoding in the Ruby String class without having extensive knowledge about the encoding. A Chars object accepts a string upon initialization and proxies String methods in an encoding safe manner. All the normal String methods are also implemented on the proxy.

String methods are proxied through the Chars object, and can be accessed through the mb_chars method. Methods which would normally return a String object now return a Chars object so methods can be chained.

  "The Perfect String  ".mb_chars.downcase.strip.normalize # => "the perfect string"

Chars objects are perfectly interchangeable with String objects as long as no explicit class checks are made. If certain methods do explicitly check the class, call to_s before you pass chars objects to them.

  bad.explicit_checking_method "T".mb_chars.downcase.to_s

The default Chars implementation assumes that the encoding of the string is UTF-8, if you want to handle different encodings you can write your own multibyte string handler and configure it through Mail::Multibyte.proxy_class.

  class CharsForUTF32
    def size
      @wrapped_string.size / 4
    end

    def self.accepts?(string)
      string.length % 4 == 0
    end
  end

  Mail::Multibyte.proxy_class = CharsForUTF32

Attributes

wrapped_string[R]

Public Class Methods

consumes?(string) click to toggle source

Returns true when the proxy class can handle the string. Returns false otherwise.

    # File lib/mail/multibyte/chars.rb, line 74
74:       def self.consumes?(string)
75:         # Unpack is a little bit faster than regular expressions.
76:         string.unpack('U*')
77:         true
78:       rescue ArgumentError
79:         false
80:       end
new(string) click to toggle source

Creates a new Chars instance by wrapping string.

    # File lib/mail/multibyte/chars.rb, line 41
41:         def initialize(string)
42:           @wrapped_string = string
43:           @wrapped_string.force_encoding(Encoding::UTF_8) unless @wrapped_string.frozen?
44:         end
wants?(string) click to toggle source

Returns true if the Chars class can and should act as a proxy for the string string. Returns false otherwise.

     # File lib/mail/multibyte/chars.rb, line 98
 98:         def self.wants?(string)
 99:           $KCODE == 'UTF8' && consumes?(string)
100:         end

Public Instance Methods

+(other) click to toggle source

Returns a new Chars object containing the other object concatenated to the string.

Example:

  ('Café'.mb_chars + ' périferôl').to_s # => "Café périferôl"
     # File lib/mail/multibyte/chars.rb, line 106
106:         def +(other)
107:           chars(@wrapped_string + other)
108:         end
<=>(other) click to toggle source

Returns -1, 0, or 1, depending on whether the Chars object is to be sorted before, equal or after the object on the right side of the operation. It accepts any object that implements to_s:

  'é'.mb_chars <=> 'ü'.mb_chars # => -1

See String#<=> for more details.

    # File lib/mail/multibyte/chars.rb, line 91
91:       def <=>(other)
92:         @wrapped_string <=> other.to_s
93:       end
=~(other) click to toggle source

Like String#=~ only it returns the character offset (in codepoints) instead of the byte offset.

Example:

  'Café périferôl'.mb_chars =~ /ô/ # => 12
     # File lib/mail/multibyte/chars.rb, line 114
114:         def =~(other)
115:           translate_offset(@wrapped_string =~ other)
116:         end
=~(other) click to toggle source
     # File lib/mail/multibyte/chars.rb, line 237
237:         def =~(other)
238:           @wrapped_string =~ other
239:         end
[](*args) click to toggle source
Alias for: slice
[]=(*args) click to toggle source

Like String#[]=, except instead of byte offsets you specify character offsets.

Example:

  s = "Müller"
  s.mb_chars[2] = "e" # Replace character with offset 2
  s
  # => "Müeler"

  s = "Müller"
  s.mb_chars[1, 2] = "ö" # Replace 2 characters at character offset 1
  s
  # => "Möler"
     # File lib/mail/multibyte/chars.rb, line 264
264:       def []=(*args)
265:         replace_by = args.pop
266:         # Indexed replace with regular expressions already works
267:         if args.first.is_a?(Regexp)
268:           @wrapped_string[*args] = replace_by
269:         else
270:           result = Unicode.u_unpack(@wrapped_string)
271:           if args[0].is_a?(Fixnum)
272:             raise IndexError, "index #{args[0]} out of string" if args[0] >= result.length
273:             min = args[0]
274:             max = args[1].nil? ? min : (min + args[1] - 1)
275:             range = Range.new(min, max)
276:             replace_by = [replace_by].pack('U') if replace_by.is_a?(Fixnum)
277:           elsif args.first.is_a?(Range)
278:             raise RangeError, "#{args[0]} out of range" if args[0].min >= result.length
279:             range = args[0]
280:           else
281:             needle = args[0].to_s
282:             min = index(needle)
283:             max = min + Unicode.u_unpack(needle).length - 1
284:             range = Range.new(min, max)
285:           end
286:           result[range] = Unicode.u_unpack(replace_by)
287:           @wrapped_string.replace(result.pack('U*'))
288:         end
289:       end
acts_like_string?() click to toggle source

Enable more predictable duck-typing on String-like classes. See Object#acts_like?.

    # File lib/mail/multibyte/chars.rb, line 69
69:       def acts_like_string?
70:         true
71:       end
capitalize() click to toggle source

Converts the first character to uppercase and the remainder to lowercase.

Example:

 'über'.mb_chars.capitalize.to_s # => "Über"
     # File lib/mail/multibyte/chars.rb, line 357
357:       def capitalize
358:         (slice(0) || chars('')).upcase + (slice(1..1) || chars('')).downcase
359:       end
center(integer, padstr=' ') click to toggle source

Works just like String#center, only integer specifies characters instead of bytes.

Example:

  "¾ cup".mb_chars.center(8).to_s
  # => " ¾ cup  "

  "¾ cup".mb_chars.center(8, " ").to_s # Use non-breaking whitespace
  # => " ¾ cup  "
     # File lib/mail/multibyte/chars.rb, line 232
232:         def center(integer, padstr=' ')
233:           justify(integer, :center, padstr)
234:         end
compose() click to toggle source

Performs composition on all the characters.

Example:

  'é'.length                       # => 3
  'é'.mb_chars.compose.to_s.length # => 2
     # File lib/mail/multibyte/chars.rb, line 395
395:       def compose
396:         chars(Unicode.compose_codepoints(Unicode.u_unpack(@wrapped_string)).pack('U*'))
397:       end
decompose() click to toggle source

Performs canonical decomposition on all the characters.

Example:

  'é'.length                         # => 2
  'é'.mb_chars.decompose.to_s.length # => 3
     # File lib/mail/multibyte/chars.rb, line 386
386:       def decompose
387:         chars(Unicode.decompose_codepoints(:canonical, Unicode.u_unpack(@wrapped_string)).pack('U*'))
388:       end
downcase() click to toggle source

Convert characters in the string to lowercase.

Example:

  'VĚDA A VÝZKUM'.mb_chars.downcase.to_s # => "věda a výzkum"
     # File lib/mail/multibyte/chars.rb, line 349
349:       def downcase
350:         chars(Unicode.apply_mapping(@wrapped_string), :lowercase_mapping)
351:       end
g_length() click to toggle source

Returns the number of grapheme clusters in the string.

Example:

  'क्षि'.mb_chars.length   # => 4
  'क्षि'.mb_chars.g_length # => 3
     # File lib/mail/multibyte/chars.rb, line 404
404:       def g_length
405:         Unicode.g_unpack(@wrapped_string).length
406:       end
include?(other) click to toggle source

Returns true if contained string contains other. Returns false otherwise.

Example:

  'Café'.mb_chars.include?('é') # => true
     # File lib/mail/multibyte/chars.rb, line 138
138:         def include?(other)
139:           # We have to redefine this method because Enumerable defines it.
140:           @wrapped_string.include?(other)
141:         end
index(needle, offset=0) click to toggle source

Returns the position needle in the string, counting in codepoints. Returns nil if needle isn’t found.

Example:

  'Café périferôl'.mb_chars.index('ô')   # => 12
  'Café périferôl'.mb_chars.index(/\w/u) # => 0
     # File lib/mail/multibyte/chars.rb, line 148
148:         def index(needle, offset=0)
149:           wrapped_offset = first(offset).wrapped_string.length
150:           index = @wrapped_string.index(needle, wrapped_offset)
151:           index ? (Unicode.u_unpack(@wrapped_string.slice(0...index)).size) : nil
152:         end
insert(offset, fragment) click to toggle source

Inserts the passed string at specified codepoint offsets.

Example:

  'Café'.mb_chars.insert(4, ' périferôl').to_s # => "Café périferôl"
     # File lib/mail/multibyte/chars.rb, line 122
122:         def insert(offset, fragment)
123:           unpacked = Unicode.u_unpack(@wrapped_string)
124:           unless offset > unpacked.length
125:             @wrapped_string.replace(
126:               Unicode.u_unpack(@wrapped_string).insert(offset, *Unicode.u_unpack(fragment)).pack('U*')
127:             )
128:           else
129:             raise IndexError, "index #{offset} out of string"
130:           end
131:           self
132:         end
limit(limit) click to toggle source

Limit the byte size of the string to a number of bytes without breaking characters. Usable when the storage for a string is limited for some reason.

Example:

  s = 'こんにちは'
  s.mb_chars.limit(7) # => "こに"
     # File lib/mail/multibyte/chars.rb, line 333
333:       def limit(limit)
334:         slice(0...translate_offset(limit))
335:       end
ljust(integer, padstr=' ') click to toggle source

Works just like String#ljust, only integer specifies characters instead of bytes.

Example:

  "¾ cup".mb_chars.rjust(8).to_s
  # => "¾ cup   "

  "¾ cup".mb_chars.rjust(8, " ").to_s # Use non-breaking whitespace
  # => "¾ cup   "
     # File lib/mail/multibyte/chars.rb, line 219
219:         def ljust(integer, padstr=' ')
220:           justify(integer, :left, padstr)
221:         end
lstrip() click to toggle source

Strips entire range of Unicode whitespace from the left of the string.

     # File lib/mail/multibyte/chars.rb, line 180
180:         def lstrip
181:           chars(@wrapped_string.gsub(Unicode::LEADERS_PAT, ''))
182:         end
method_missing(method, *args, &block) click to toggle source

Forward all undefined methods to the wrapped string.

    # File lib/mail/multibyte/chars.rb, line 52
52:       def method_missing(method, *args, &block)
53:         if method.to_s =~ /!$/
54:           @wrapped_string.__send__(method, *args, &block)
55:           self
56:         else
57:           result = @wrapped_string.__send__(method, *args, &block)
58:           result.kind_of?(String) ? chars(result) : result
59:         end
60:       end
normalize(form = nil) click to toggle source

Returns the KC normalization of the string by default. NFKC is considered the best normalization form for passing strings to databases and validations.

  • form - The form you want to normalize in. Should be one of the following: :c, :kc, :d, or :kd. Default is Mail::Multibyte::Unicode.default_normalization_form

     # File lib/mail/multibyte/chars.rb, line 377
377:       def normalize(form = nil)
378:         chars(Unicode.normalize(@wrapped_string, form))
379:       end
ord() click to toggle source

Returns the codepoint of the first character in the string.

Example:

  'こんにちは'.mb_chars.ord # => 12371
     # File lib/mail/multibyte/chars.rb, line 193
193:         def ord
194:           Unicode.u_unpack(@wrapped_string)[0]
195:         end
respond_to?(method, include_private=false) click to toggle source

Returns true if obj responds to the given method. Private methods are included in the search only if the optional second parameter evaluates to true.

    # File lib/mail/multibyte/chars.rb, line 64
64:       def respond_to?(method, include_private=false)
65:         super || @wrapped_string.respond_to?(method, include_private) || false
66:       end
reverse() click to toggle source

Reverses all characters in the string.

Example:

  'Café'.mb_chars.reverse.to_s # => 'éfaC'
     # File lib/mail/multibyte/chars.rb, line 295
295:       def reverse
296:         chars(Unicode.g_unpack(@wrapped_string).reverse.flatten.pack('U*'))
297:       end
rindex(needle, offset=nil) click to toggle source

Returns the position needle in the string, counting in codepoints, searching backward from offset or the end of the string. Returns nil if needle isn’t found.

Example:

  'Café périferôl'.mb_chars.rindex('é')   # => 6
  'Café périferôl'.mb_chars.rindex(/\w/u) # => 13
     # File lib/mail/multibyte/chars.rb, line 161
161:         def rindex(needle, offset=nil)
162:           offset ||= length
163:           wrapped_offset = first(offset).wrapped_string.length
164:           index = @wrapped_string.rindex(needle, wrapped_offset)
165:           index ? (Unicode.u_unpack(@wrapped_string.slice(0...index)).size) : nil
166:         end
rjust(integer, padstr=' ') click to toggle source

Works just like String#rjust, only integer specifies characters instead of bytes.

Example:

  "¾ cup".mb_chars.rjust(8).to_s
  # => "   ¾ cup"

  "¾ cup".mb_chars.rjust(8, " ").to_s # Use non-breaking whitespace
  # => "   ¾ cup"
     # File lib/mail/multibyte/chars.rb, line 206
206:         def rjust(integer, padstr=' ')
207:           justify(integer, :right, padstr)
208:         end
rstrip() click to toggle source

Strips entire range of Unicode whitespace from the right of the string.

     # File lib/mail/multibyte/chars.rb, line 175
175:         def rstrip
176:           chars(@wrapped_string.gsub(Unicode::TRAILERS_PAT, ''))
177:         end
size() click to toggle source

Returns the number of codepoints in the string

     # File lib/mail/multibyte/chars.rb, line 169
169:         def size
170:           Unicode.u_unpack(@wrapped_string).size
171:         end
slice(*args) click to toggle source

Implements Unicode-aware slice with codepoints. Slicing on one point returns the codepoints for that character.

Example:

  'こんにちは'.mb_chars.slice(2..3).to_s # => "にち"
     # File lib/mail/multibyte/chars.rb, line 304
304:       def slice(*args)
305:         if args.size > 2
306:           raise ArgumentError, "wrong number of arguments (#{args.size} for 1)" # Do as if we were native
307:         elsif (args.size == 2 && !(args.first.is_a?(Numeric) || args.first.is_a?(Regexp)))
308:           raise TypeError, "cannot convert #{args.first.class} into Integer" # Do as if we were native
309:         elsif (args.size == 2 && !args[1].is_a?(Numeric))
310:           raise TypeError, "cannot convert #{args[1].class} into Integer" # Do as if we were native
311:         elsif args[0].kind_of? Range
312:           cps = Unicode.u_unpack(@wrapped_string).slice(*args)
313:           result = cps.nil? ? nil : cps.pack('U*')
314:         elsif args[0].kind_of? Regexp
315:           result = @wrapped_string.slice(*args)
316:         elsif args.size == 1 && args[0].kind_of?(Numeric)
317:           character = Unicode.u_unpack(@wrapped_string)[args[0]]
318:           result = character && [character].pack('U')
319:         else
320:           cps = Unicode.u_unpack(@wrapped_string).slice(*args)
321:           result = cps && cps.pack('U*')
322:         end
323:         result && chars(result)
324:       end
Also aliased as: []
split(*args) click to toggle source

Works just like String#split, with the exception that the items in the resulting list are Chars instances instead of String. This makes chaining methods easier.

Example:

  'Café périferôl'.mb_chars.split(/é/).map { |part| part.upcase.to_s } # => ["CAF", " P", "RIFERÔL"]
     # File lib/mail/multibyte/chars.rb, line 247
247:       def split(*args)
248:         @wrapped_string.split(*args).map { |i| i.mb_chars }
249:       end
strip() click to toggle source

Strips entire range of Unicode whitespace from the right and left of the string.

     # File lib/mail/multibyte/chars.rb, line 185
185:         def strip
186:           rstrip.lstrip
187:         end
tidy_bytes(force = false) click to toggle source

Replaces all ISO-8859-1 or CP1252 characters by their UTF-8 equivalent resulting in a valid UTF-8 string.

Passing true will forcibly tidy all bytes, assuming that the string’s encoding is entirely CP1252 or ISO-8859-1.

     # File lib/mail/multibyte/chars.rb, line 411
411:       def tidy_bytes(force = false)
412:         chars(Unicode.tidy_bytes(@wrapped_string, force))
413:       end
titlecase() click to toggle source
Alias for: titleize
titleize() click to toggle source

Capitalizes the first letter of every word, when possible.

Example:

  "ÉL QUE SE ENTERÓ".mb_chars.titleize    # => "Él Que Se Enteró"
  "日本語".mb_chars.titleize                 # => "日本語"
     # File lib/mail/multibyte/chars.rb, line 366
366:       def titleize
367:         chars(downcase.to_s.gsub(/\b('?[\S])/) { Unicode.apply_mapping $1, :uppercase_mapping })
368:       end
Also aliased as: titlecase
upcase() click to toggle source

Convert characters in the string to uppercase.

Example:

  'Laurent, où sont les tests ?'.mb_chars.upcase.to_s # => "LAURENT, OÙ SONT LES TESTS ?"
     # File lib/mail/multibyte/chars.rb, line 341
341:       def upcase
342:         chars(Unicode.apply_mapping(@wrapped_string), :uppercase_mapping)
343:       end

Disabled; run with --debug to generate this.

[Validate]

Generated with the Darkfish Rdoc Generator 1.1.6.