mail 2.6.5 → 2.7.0.rc1

data/lib/mail/elements/mime_version_element.rb

@@ -1,23 +1,15 @@
 # encoding: utf-8
 # frozen_string_literal: true
+require 'mail/parsers/mime_version_parser'
+
 module Mail
   class MimeVersionElement
-    
-    include Mail::Utilities
-    
-    def initialize( string )
-      mime_version = Mail::Parsers::MimeVersionParser.new.parse(string)
+    attr_reader :major, :minor
+
+    def initialize(string)
+      mime_version = Mail::Parsers::MimeVersionParser.parse(string)
       @major = mime_version.major
       @minor = mime_version.minor
     end
-    
-    def major
-      @major
-    end
-    
-    def minor
-      @minor
-    end
-    
   end
 end

data/lib/mail/elements/phrase_list.rb

@@ -1,17 +1,14 @@
 # encoding: utf-8
 # frozen_string_literal: true
+require 'mail/parsers/phrase_lists_parser'
+require 'mail/utilities'
+
 module Mail
   class PhraseList
-    
-    include Mail::Utilities
-    
+    attr_reader :phrases
+
     def initialize(string)
-      @phrase_lists = Mail::Parsers::PhraseListsParser.new.parse(string)
+      @phrases = Mail::Parsers::PhraseListsParser.parse(string).phrases.map { |p| Mail::Utilities.unquote(p) }
     end
-    
-    def phrases
-      @phrase_lists.phrases.map { |p| unquote(p) }
-    end
-
   end
 end

data/lib/mail/elements/received_element.rb

@@ -1,27 +1,21 @@
 # encoding: utf-8
 # frozen_string_literal: true
+require 'mail/parsers/received_parser'
+require 'date'
+
 module Mail
   class ReceivedElement
-    
     include Mail::Utilities
-    
-    def initialize( string )
-      received = Mail::Parsers::ReceivedParser.new.parse(string)
+    attr_reader :date_time, :info
+
+    def initialize(string)
+      received = Mail::Parsers::ReceivedParser.parse(string)
       @date_time = ::DateTime.parse("#{received.date} #{received.time}")
       @info = received.info
     end
-    
-    def date_time
-      @date_time
-    end
-    
-    def info
-      @info
-    end
-    
+
     def to_s(*args)
-      "#{@info}; #{@date_time.to_s(*args)}"
+      "#{info}; #{date_time.to_s(*args)}"
     end
-    
   end
 end

data/lib/mail/encodings.rb

@@ -178,9 +178,8 @@ module Mail
 
     def Encodings.encode_non_usascii(address, charset)
       return address if address.ascii_only? or charset.nil?
-      us_ascii = %Q{\x00-\x7f}
-      # Encode any non usascii strings embedded inside of quotes
-      address = address.gsub(/(".*?[^#{us_ascii}].*?")/) { |s| Encodings.b_value_encode(unquote(s), charset) }
+      # Encode all strings embedded inside of quotes
+      address = address.gsub(/("[^"]*")/) { |s| Encodings.b_value_encode(unquote(s), charset) }
       # Then loop through all remaining items and encode as needed
       tokens = address.split(/\s/)
       map_with_index(tokens) do |word, i|
@@ -258,24 +257,23 @@ module Mail
       str[ENCODED_VALUE, 1]
     end
 
-    # When the encoded string consists of multiple lines, lines with the same
-    # encoding (Q or B) can be joined together.
+    # Split header line into proper encoded and unencoded parts.
     #
     # String has to be of the format =?<encoding>?[QB]?<string>?=
+    #
+    # Omit unencoded space after an encoded-word.
     def Encodings.collapse_adjacent_encodings(str)
       results = []
-      previous_encoding = nil
+      last_encoded = nil  # Track whether to preserve or drop whitespace
+
       lines = str.split(FULL_ENCODED_VALUE)
       lines.each_slice(2) do |unencoded, encoded|
-        if encoded
-          encoding = value_encoding_from_string(encoded)
-          if encoding == previous_encoding && Utilities.blank?(unencoded)
-            results.last << encoded
-          else
-            results << unencoded unless unencoded == EMPTY
-            results << encoded
+        if last_encoded = encoded
+          if !Utilities.blank?(unencoded) || (!last_encoded && unencoded != EMPTY)
+            results << unencoded
           end
-          previous_encoding = encoding
+
+          results << encoded
         else
           results << unencoded
         end

data/lib/mail/field.rb

@@ -218,10 +218,13 @@ module Mail
     private
 
     def split(raw_field)
-      match_data = raw_field.mb_chars.match(FIELD_SPLIT)
-      [match_data[1].to_s.mb_chars.strip, match_data[2].to_s.mb_chars.strip.to_s]
+      match_data = Mail::Multibyte.mb_chars(raw_field).match(FIELD_SPLIT)
+      [
+        Mail::Multibyte.mb_chars(match_data[1].to_s).strip,
+        Mail::Multibyte.mb_chars(match_data[2].to_s).strip.to_s
+      ]
     rescue
-      STDERR.puts "WARNING: Could not parse (and so ignoring) '#{raw_field}'"
+      $stderr.puts "WARNING: Could not parse (and so ignoring) '#{raw_field}'"
     end
 
     # 2.2.3. Long Header Fields
@@ -233,7 +236,7 @@ module Mail
     #  treated in its unfolded form for further syntactic and semantic
     #  evaluation.
     def unfold(string)
-      string.gsub(/[\r\n \t]+/m, ' ')
+      string.gsub(/#{CRLF}(#{WSP})/m, '\1')
     end
 
     def create_field(name, value, charset)

data/lib/mail/fields/common/parameter_hash.rb

@@ -30,7 +30,7 @@ module Mail
         super(exact || key_name)
       else # Dealing with a multiple value pair or a single encoded value pair
         string = pairs.sort { |a,b| a.first.to_s <=> b.first.to_s }.map { |v| v.last }.join('')
-        if mt = string.match(/([\w\-]+)'(\w\w)'(.*)/)
+        if mt = string.match(/([\w\-]+)?'(\w\w)?'(.*)/)
           string = mt[3]
           encoding = mt[1]
         else

data/lib/mail/fields/content_type_field.rb

@@ -145,9 +145,7 @@ module Mail
       # TODO: check if there are cases where whitespace is not a separator
       val = val.
         gsub(/\s*=\s*/,'='). # remove whitespaces around equal sign
-        tr(' ',';').
-        squeeze(';').
-        gsub(';', '; '). #use '; ' as a separator (or EOL)
+        gsub(/[; ]+/, '; '). #use '; ' as a separator (or EOL)
         gsub(/;\s*$/,'') #remove trailing to keep examples below
 
       if val =~ /(boundary=(\S*))/i
@@ -157,9 +155,6 @@ module Mail
       end
 
       case
-      when val.chomp =~ /^\s*([\w\-]+)\/([\w\-]+)\s*;;+(.*)$/i
-        # Handles 'text/plain;; format="flowed"' (double semi colon)
-        "#{$1}/#{$2}; #{$3}"
       when val.chomp =~ /^\s*([\w\-]+)\/([\w\-]+)\s*;\s?(ISO[\w\-]+)$/i
         # Microsoft helper:
         # Handles 'type/subtype;ISO-8559-1'
@@ -186,7 +181,7 @@ module Mail
       when val =~ /^\s*$/
         'text/plain'
       else
-        ''
+        val
       end
     end
 

data/lib/mail/fields/unstructured_field.rb

@@ -121,7 +121,7 @@ module Mail
     def fold(prepend = 0) # :nodoc:
       encoding       = normalized_encoding
       decoded_string = decoded.to_s
-      should_encode  = decoded_string.not_ascii_only?
+      should_encode  = !decoded_string.ascii_only?
       if should_encode
         first = true
         words = decoded_string.split(/[ \t]/).map do |word|
@@ -130,7 +130,7 @@ module Mail
           else
             word = " #{word}"
           end
-          if word.not_ascii_only?
+          if !word.ascii_only?
             word
           else
             word.scan(/.{7}|.+$/)

data/lib/mail/header.rb

@@ -57,6 +57,7 @@ module Mail
     def initialize_copy(original)
       super
       @fields = @fields.dup
+      @fields.map!(&:dup)
     end
     
     # The preserved raw source of the header as you passed it in, untouched

data/lib/mail/message.rb

@@ -213,7 +213,7 @@ module Mail
     self.default_charset = 'UTF-8'
 
     def register_for_delivery_notification(observer)
-      STDERR.puts("Message#register_for_delivery_notification is deprecated, please call Mail.register_observer instead")
+      $stderr.puts("Message#register_for_delivery_notification is deprecated, please call Mail.register_observer instead")
       Mail.register_observer(observer)
     end
 
@@ -360,13 +360,8 @@ module Mail
       if self.message_id && other.message_id
         self.encoded == other.encoded
       else
-        self_message_id, other_message_id = self.message_id, other.message_id
-        begin
-          self.message_id, other.message_id = '<temp@test>', '<temp@test>'
-          self.encoded == other.encoded
-        ensure
-          self.message_id, other.message_id = self_message_id, other_message_id
-        end
+        dup.tap { |m| m.message_id = '<temp@test>' }.encoded ==
+          other.dup.tap { |m| m.message_id = '<temp@test>' }.encoded
       end
     end
 
@@ -1420,7 +1415,7 @@ module Mail
     end
 
     def has_transfer_encoding? # :nodoc:
-      STDERR.puts(":has_transfer_encoding? is deprecated in Mail 1.4.3.  Please use has_content_transfer_encoding?\n#{caller}")
+      $stderr.puts(":has_transfer_encoding? is deprecated in Mail 1.4.3.  Please use has_content_transfer_encoding?\n#{caller}")
       has_content_transfer_encoding?
     end
 
@@ -1468,9 +1463,9 @@ module Mail
       if !body.empty?
         # Only give a warning if this isn't an attachment, has non US-ASCII and the user
         # has not specified an encoding explicitly.
-        if @defaulted_charset && body.raw_source.not_ascii_only? && !self.attachment?
+        if @defaulted_charset && !body.raw_source.ascii_only? && !self.attachment?
           warning = "Non US-ASCII detected and no charset defined.\nDefaulting to UTF-8, set your own if this is incorrect.\n"
-          STDERR.puts(warning)
+          $stderr.puts(warning)
         end
         header[:content_type].parameters['charset'] = @charset
       end
@@ -1484,18 +1479,18 @@ module Mail
         header[:content_transfer_encoding] = '7bit'
       else
         warning = "Non US-ASCII detected and no content-transfer-encoding defined.\nDefaulting to 8bit, set your own if this is incorrect.\n"
-        STDERR.puts(warning)
+        $stderr.puts(warning)
         header[:content_transfer_encoding] = '8bit'
       end
     end
 
     def add_transfer_encoding # :nodoc:
-      STDERR.puts(":add_transfer_encoding is deprecated in Mail 1.4.3.  Please use add_content_transfer_encoding\n#{caller}")
+      $stderr.puts(":add_transfer_encoding is deprecated in Mail 1.4.3.  Please use add_content_transfer_encoding\n#{caller}")
       add_content_transfer_encoding
     end
 
     def transfer_encoding # :nodoc:
-      STDERR.puts(":transfer_encoding is deprecated in Mail 1.4.3.  Please use content_transfer_encoding\n#{caller}")
+      $stderr.puts(":transfer_encoding is deprecated in Mail 1.4.3.  Please use content_transfer_encoding\n#{caller}")
       content_transfer_encoding
     end
 
@@ -1505,7 +1500,7 @@ module Mail
     end
 
     def message_content_type
-      STDERR.puts(":message_content_type is deprecated in Mail 1.4.3.  Please use mime_type\n#{caller}")
+      $stderr.puts(":message_content_type is deprecated in Mail 1.4.3.  Please use mime_type\n#{caller}")
       mime_type
     end
 
@@ -1537,7 +1532,7 @@ module Mail
 
     # Returns the content type parameters
     def mime_parameters
-      STDERR.puts(':mime_parameters is deprecated in Mail 1.4.3, please use :content_type_parameters instead')
+      $stderr.puts(':mime_parameters is deprecated in Mail 1.4.3, please use :content_type_parameters instead')
       content_type_parameters
     end
 
@@ -1563,7 +1558,14 @@ module Mail
 
     # returns the part in a multipart/report email that has the content-type delivery-status
     def delivery_status_part
-      @delivery_stats_part ||= parts.select { |p| p.delivery_status_report_part? }.first
+      unless defined? @delivery_status_part
+        @delivery_status_part =
+          if delivery_status_report?
+            parts.detect(&:delivery_status_report_part?)
+          end
+      end
+
+      @delivery_status_part
     end
 
     def bounced?
@@ -1798,7 +1800,6 @@ module Mail
     # ready to send
     def ready_to_send!
       identify_and_set_transfer_encoding
-      parts.sort!([ "text/plain", "text/enriched", "text/html", "multipart/alternative" ])
       parts.each do |part|
         part.transport_encoding = transport_encoding
         part.ready_to_send!
@@ -1807,7 +1808,7 @@ module Mail
     end
 
     def encode!
-      STDERR.puts("Deprecated in 1.1.0 in favour of :ready_to_send! as it is less confusing with encoding and decoding.")
+      $stderr.puts("Deprecated in 1.1.0 in favour of :ready_to_send! as it is less confusing with encoding and decoding.")
       ready_to_send!
     end
 
@@ -1975,7 +1976,7 @@ module Mail
 
   private
 
-    HEADER_SEPARATOR = /#{CRLF}#{CRLF}|#{CRLF}#{WSP}*#{CRLF}(?!#{WSP})/m
+    HEADER_SEPARATOR = /#{CRLF}#{CRLF}/
 
     #  2.1. General Description
     #   A message consists of header fields (collectively called "the header
@@ -1984,9 +1985,6 @@ module Mail
     #   this standard. The body is simply a sequence of characters that
     #   follows the header and is separated from the header by an empty line
     #   (i.e., a line with nothing preceding the CRLF).
-    #
-    # Additionally, I allow for the case where someone might have put whitespace
-    # on the "gap line"
     def parse_message
       header_part, body_part = raw_source.lstrip.split(HEADER_SEPARATOR, 2)
       self.header = header_part
@@ -2130,10 +2128,10 @@ module Mail
       content_disp_name = header[:content_disposition].filename rescue nil
       content_loc_name  = header[:content_location].location rescue nil
       case
-      when content_type && content_type_name
-        filename = content_type_name
       when content_disposition && content_disp_name
         filename = content_disp_name
+      when content_type && content_type_name
+        filename = content_type_name
       when content_location && content_loc_name
         filename = content_loc_name
       else

data/lib/mail/multibyte/chars.rb

@@ -103,7 +103,7 @@ module Mail #:nodoc:
         # 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"
+        #   (Mail::Multibyte.mb_chars('Café') + ' périferôl').to_s # => "Café périferôl"
         def +(other)
           chars(@wrapped_string + other)
         end
@@ -111,7 +111,7 @@ module Mail #:nodoc:
         # Like <tt>String#=~</tt> only it returns the character offset (in codepoints) instead of the byte offset.
         #
         # Example:
-        #   'Café périferôl'.mb_chars =~ /ô/ # => 12
+        #   Mail::Multibyte.mb_chars('Café périferôl') =~ /ô/ # => 12
         def =~(other)
           translate_offset(@wrapped_string =~ other)
         end
@@ -119,7 +119,7 @@ module Mail #:nodoc:
         # Inserts the passed string at specified codepoint offsets.
         #
         # Example:
-        #   'Café'.mb_chars.insert(4, ' périferôl').to_s # => "Café périferôl"
+        #   Mail::Multibyte.mb_chars('Café').insert(4, ' périferôl').to_s # => "Café périferôl"
         def insert(offset, fragment)
           unpacked = Unicode.u_unpack(@wrapped_string)
           unless offset > unpacked.length
@@ -135,7 +135,7 @@ module Mail #:nodoc:
         # Returns +true+ if contained string contains _other_. Returns +false+ otherwise.
         #
         # Example:
-        #   'Café'.mb_chars.include?('é') # => true
+        #   Mail::Multibyte.mb_chars('Café').include?('é') # => true
         def include?(other)
           # We have to redefine this method because Enumerable defines it.
           @wrapped_string.include?(other)
@@ -144,8 +144,8 @@ module Mail #:nodoc:
         # 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
+        #   Mail::Multibyte.mb_chars('Café périferôl').index('ô')   # => 12
+        #   Mail::Multibyte.mb_chars('Café périferôl').index(/\w/u) # => 0
         def index(needle, offset=0)
           wrapped_offset = first(offset).wrapped_string.length
           index = @wrapped_string.index(needle, wrapped_offset)
@@ -157,8 +157,8 @@ module Mail #:nodoc:
         # 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
+        #   Mail::Multibyte.mb_chars('Café périferôl').rindex('é')   # => 6
+        #   Mail::Multibyte.mb_chars('Café périferôl').rindex(/\w/u) # => 13
         def rindex(needle, offset=nil)
           offset ||= length
           wrapped_offset = first(offset).wrapped_string.length
@@ -190,7 +190,7 @@ module Mail #:nodoc:
         # Returns the codepoint of the first character in the string.
         #
         # Example:
-        #   'こんにちは'.mb_chars.ord # => 12371
+        #   Mail::Multibyte.mb_chars('こんにちは').ord # => 12371
         def ord
           Unicode.u_unpack(@wrapped_string)[0]
         end
@@ -199,10 +199,10 @@ module Mail #:nodoc:
         #
         # Example:
         #
-        #   "¾ cup".mb_chars.rjust(8).to_s
+        #   Mail::Multibyte.mb_chars("¾ cup").rjust(8).to_s
         #   # => "   ¾ cup"
         #
-        #   "¾ cup".mb_chars.rjust(8, " ").to_s # Use non-breaking whitespace
+        #   Mail::Multibyte.mb_chars("¾ cup").rjust(8, " ").to_s # Use non-breaking whitespace
         #   # => "   ¾ cup"
         def rjust(integer, padstr=' ')
           justify(integer, :right, padstr)
@@ -212,10 +212,10 @@ module Mail #:nodoc:
         #
         # Example:
         #
-        #   "¾ cup".mb_chars.rjust(8).to_s
+        #   Mail::Multibyte.mb_chars("¾ cup").rjust(8).to_s
         #   # => "¾ cup   "
         #
-        #   "¾ cup".mb_chars.rjust(8, " ").to_s # Use non-breaking whitespace
+        #   Mail::Multibyte.mb_chars("¾ cup").rjust(8, " ").to_s # Use non-breaking whitespace
         #   # => "¾ cup   "
         def ljust(integer, padstr=' ')
           justify(integer, :left, padstr)
@@ -225,10 +225,10 @@ module Mail #:nodoc:
         #
         # Example:
         #
-        #   "¾ cup".mb_chars.center(8).to_s
+        #   Mail::Multibyte.mb_chars("¾ cup").center(8).to_s
         #   # => " ¾ cup  "
         #
-        #   "¾ cup".mb_chars.center(8, " ").to_s # Use non-breaking whitespace
+        #   Mail::Multibyte.mb_chars("¾ cup").center(8, " ").to_s # Use non-breaking whitespace
         #   # => " ¾ cup  "
         def center(integer, padstr=' ')
           justify(integer, :center, padstr)
@@ -244,7 +244,7 @@ module Mail #:nodoc:
       # 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"]
+      #   Mail::Multibyte.mb_chars('Café périferôl').split(/é/).map { |part| part.upcase.to_s } # => ["CAF", " P", "RIFERÔL"]
       def split(*args)
         @wrapped_string.split(*args).map { |i| i.mb_chars }
       end
@@ -292,7 +292,7 @@ module Mail #:nodoc:
       # Reverses all characters in the string.
       #
       # Example:
-      #   'Café'.mb_chars.reverse.to_s # => 'éfaC'
+      #   Mail::Multibyte.mb_chars('Café').reverse.to_s # => 'éfaC'
       def reverse
         chars(Unicode.g_unpack(@wrapped_string).reverse.flatten.pack('U*'))
       end
@@ -301,7 +301,7 @@ module Mail #:nodoc:
       # character.
       #
       # Example:
-      #   'こんにちは'.mb_chars.slice(2..3).to_s # => "にち"
+      #   Mail::Multibyte.mb_chars('こんにちは').slice(2..3).to_s # => "にち"
       def slice(*args)
         if args.size > 2
           raise ArgumentError, "wrong number of arguments (#{args.size} for 1)" # Do as if we were native
@@ -338,7 +338,7 @@ module Mail #:nodoc:
       # Convert characters in the string to uppercase.
       #
       # Example:
-      #   'Laurent, où sont les tests ?'.mb_chars.upcase.to_s # => "LAURENT, OÙ SONT LES TESTS ?"
+      #   Mail::Multibyte.mb_chars('Laurent, où sont les tests ?').upcase.to_s # => "LAURENT, OÙ SONT LES TESTS ?"
       def upcase
         chars(Unicode.apply_mapping(@wrapped_string, :uppercase_mapping))
       end
@@ -346,7 +346,7 @@ module Mail #:nodoc:
       # Convert characters in the string to lowercase.
       #
       # Example:
-      #   'VĚDA A VÝZKUM'.mb_chars.downcase.to_s # => "věda a výzkum"
+      #   Mail::Multibyte.mb_chars('VĚDA A VÝZKUM').downcase.to_s # => "věda a výzkum"
       def downcase
         chars(Unicode.apply_mapping(@wrapped_string, :lowercase_mapping))
       end
@@ -354,7 +354,7 @@ module Mail #:nodoc:
       # Converts the first character to uppercase and the remainder to lowercase.
       #
       # Example:
-      #  'über'.mb_chars.capitalize.to_s # => "Über"
+      #  Mail::Multibyte.mb_chars('über').capitalize.to_s # => "Über"
       def capitalize
         (slice(0) || chars('')).upcase + (slice(1..-1) || chars('')).downcase
       end
@@ -362,8 +362,8 @@ module Mail #:nodoc:
       # Capitalizes the first letter of every word, when possible.
       #
       # Example:
-      #   "ÉL QUE SE ENTERÓ".mb_chars.titleize    # => "Él Que Se Enteró"
-      #   "日本語".mb_chars.titleize                 # => "日本語"
+      #   Mail::Multibyte.mb_chars("ÉL QUE SE ENTERÓ").titleize    # => "Él Que Se Enteró"
+      #   Mail::Multibyte.mb_chars("日本語").titleize                 # => "日本語"
       def titleize
         chars(downcase.to_s.gsub(/\b('?\S)/u) { Unicode.apply_mapping $1, :uppercase_mapping })
       end
@@ -383,7 +383,7 @@ module Mail #:nodoc:
       #
       # Example:
       #   'é'.length                         # => 2
-      #   'é'.mb_chars.decompose.to_s.length # => 3
+      #   Mail::Multibyte.mb_chars('é').decompose.to_s.length # => 3
       def decompose
         chars(Unicode.decompose_codepoints(:canonical, Unicode.u_unpack(@wrapped_string)).pack('U*'))
       end
@@ -392,7 +392,7 @@ module Mail #:nodoc:
       #
       # Example:
       #   'é'.length                       # => 3
-      #   'é'.mb_chars.compose.to_s.length # => 2
+      #   Mail::Multibyte.mb_chars('é').compose.to_s.length # => 2
       def compose
         chars(Unicode.compose_codepoints(Unicode.u_unpack(@wrapped_string)).pack('U*'))
       end
@@ -400,8 +400,8 @@ module Mail #:nodoc:
       # Returns the number of grapheme clusters in the string.
       #
       # Example:
-      #   'क्षि'.mb_chars.length   # => 4
-      #   'क्षि'.mb_chars.g_length # => 3
+      #   Mail::Multibyte.mb_chars('क्षि').length   # => 4
+      #   Mail::Multibyte.mb_chars('क्षि').g_length # => 3
       def g_length
         Unicode.g_unpack(@wrapped_string).length
       end

data/lib/mail/multibyte.rb

@@ -21,6 +21,57 @@ module Mail #:nodoc:
       @proxy_class ||= Mail::Multibyte::Chars
     end
 
+    if RUBY_VERSION >= "1.9"
+      # == 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.
+      def self.mb_chars(str)
+        if proxy_class.consumes?(str)
+          proxy_class.new(str)
+        else
+          str
+        end
+      end
+    else
+      def self.mb_chars(str)
+        if proxy_class.wants?(str)
+          proxy_class.new(str)
+        else
+          str
+        end
+      end
+    end
+
     # Regular expressions that describe valid byte sequences for a character
     VALID_CHARACTER = {
       # Borrowed from the Kconv library by Shinji KONO - (also as seen on the W3C site)