module Mail::Multibyte

Constants

VALID_CHARACTER

Regular expressions that describe valid byte sequences for a character

Attributes

proxy_class[RW]

The proxy class returned when calling mb_chars. You can use this accessor to configure your own proxy class so you can support other encodings. See the Mail::Multibyte::Chars implementation for an example how to do this.

Example:

Mail::Multibyte.proxy_class = CharsForUTF32

Public Class Methods

mb_chars(str) click to toggle source

Multibyte proxy

mb_chars is a multibyte safe proxy for string methods.

In Ruby 1.8 and older it creates and returns an instance of the Mail::Multibyte::Chars class which encapsulates the original string. A Unicode safe version of all the String methods are defined on this proxy class. If the proxy class doesn’t respond to a certain method, it’s forwarded to the encapsuled string.

name = 'Claus Müller'
name.reverse # => "rell??M sualC"
name.length  # => 13

name.mb_chars.reverse.to_s # => "rellüM sualC"
name.mb_chars.length       # => 12

In Ruby 1.9 and newer mb_chars returns self because String is (mostly) encoding aware. This means that it becomes easy to run one version of your code on multiple Ruby versions.

Method chaining

All the methods on the Chars proxy which normally return a string will return a Chars object. This allows method chaining on the result of any of these methods.

name.mb_chars.reverse.length # => 12

Interoperability and configuration

The Chars object tries to be as interchangeable with String objects as possible: sorting and comparing between String and Char work like expected. The bang! methods change the internal string representation in the Chars object. Interoperability problems can be resolved easily with a to_s call.

For more information about the methods defined on the Chars proxy see Mail::Multibyte::Chars. For information about how to change the default Multibyte behaviour see Mail::Multibyte.

# File lib/mail/multibyte.rb, line 55
def self.mb_chars(str)
  if is_utf8?(str)
    proxy_class.new(str)
  else
    str
  end
end