mail 2.6.3 → 2.7.1

data/lib/mail/message.rb

@@ -1,4 +1,5 @@
 # encoding: utf-8
+# frozen_string_literal: true
 require "yaml"
 
 module Mail
@@ -55,15 +56,23 @@ module Mail
     #
     # ===Making an email via a block
     #
-    #  mail = Mail.new do
-    #       from 'mikel@test.lindsaar.net'
-    #         to 'you@test.lindsaar.net'
-    #    subject 'This is a test email'
-    #       body File.read('body.txt')
+    #  mail = Mail.new do |m|
+    #    m.from 'mikel@test.lindsaar.net'
+    #    m.to 'you@test.lindsaar.net'
+    #    m.subject 'This is a test email'
+    #    m.body File.read('body.txt')
     #  end
     #
     #  mail.to_s #=> "From: mikel@test.lindsaar.net\r\nTo: you@...
     #
+    # If may also pass a block with no arguments, in which case it will
+    # be evaluated in the scope of the new message instance:
+    #
+    #  mail = Mail.new do
+    #    from 'mikel@test.lindsaar.net'
+    #    # …
+    #  end
+    #
     # ===Making an email via passing a string
     #
     #  mail = Mail.new("To: mikel@test.lindsaar.net\r\nSubject: Hello\r\n\r\nHi there!")
@@ -128,8 +137,23 @@ module Mail
         init_with_string(args.flatten[0].to_s)
       end
 
+      # Support both builder styles:
+      #
+      #   Mail.new do
+      #     to 'recipient@example.com'
+      #   end
+      #
+      # and
+      #
+      #   Mail.new do |m|
+      #     m.to 'recipient@example.com'
+      #   end
       if block_given?
-        instance_eval(&block)
+        if block.arity.zero? || (RUBY_VERSION < '1.9' && block.arity < 1)
+          instance_eval(&block)
+        else
+          yield self
+        end
       end
 
       self
@@ -212,7 +236,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")
+      warn("Message#register_for_delivery_notification is deprecated, please call Mail.register_observer instead")
       Mail.register_observer(observer)
     end
 
@@ -224,7 +248,7 @@ module Mail
       Mail.inform_interceptors(self)
     end
 
-    # Delivers an mail object.
+    # Delivers a mail object.
     #
     # Examples:
     #
@@ -359,13 +383,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
 
@@ -1192,8 +1211,8 @@ module Mail
     def default( sym, val = nil )
       if val
         header[sym] = val
-      else
-        header[sym].default if header[sym]
+      elsif field = header[sym]
+        field.default
       end
     end
 
@@ -1239,14 +1258,13 @@ module Mail
     def body(value = nil)
       if value
         self.body = value
-#        add_encoding_to_body
       else
         process_body_raw if @body_raw
         @body
       end
     end
 
-    def body_encoding(value)
+    def body_encoding(value = nil)
       if value.nil?
         body.encoding
       else
@@ -1255,7 +1273,7 @@ module Mail
     end
 
     def body_encoding=(value)
-        body.encoding = value
+      body.encoding = value
     end
 
     # Returns the list of addresses this message should be sent to by
@@ -1415,11 +1433,11 @@ module Mail
     end
 
     def has_content_transfer_encoding?
-      header[:content_transfer_encoding] && header[:content_transfer_encoding].errors.blank?
+      header[:content_transfer_encoding] && Utilities.blank?(header[:content_transfer_encoding].errors)
     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}")
+      warn(":has_transfer_encoding? is deprecated in Mail 1.4.3.  Please use has_content_transfer_encoding?\n#{caller}")
       has_content_transfer_encoding?
     end
 
@@ -1467,34 +1485,26 @@ 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)
+          warn(warning)
         end
         header[:content_type].parameters['charset'] = @charset
       end
     end
 
     # Adds a content transfer encoding
-    #
-    # Otherwise raises a warning
     def add_content_transfer_encoding
-      if body.only_us_ascii?
-        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)
-        header[:content_transfer_encoding] = '8bit'
-      end
+      header[:content_transfer_encoding] ||= body.default_encoding
     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}")
+      warn(":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}")
+      warn(":transfer_encoding is deprecated in Mail 1.4.3.  Please use content_transfer_encoding\n#{caller}")
       content_transfer_encoding
     end
 
@@ -1504,7 +1514,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}")
+      warn(":message_content_type is deprecated in Mail 1.4.3.  Please use mime_type\n#{caller}")
       mime_type
     end
 
@@ -1536,7 +1546,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')
+      warn(':mime_parameters is deprecated in Mail 1.4.3, please use :content_type_parameters instead')
       content_type_parameters
     end
 
@@ -1562,7 +1572,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?
@@ -1669,6 +1686,8 @@ module Mail
     def html_part=(msg)
       # Assign the html part and set multipart/alternative if there's a text part.
       if msg
+        msg = Mail::Part.new(:body => msg) unless msg.kind_of?(Mail::Message)
+
         @html_part = msg
         @html_part.content_type = 'text/html' unless @html_part.has_content_type?
         add_multipart_alternate_header if text_part
@@ -1691,6 +1710,8 @@ module Mail
     def text_part=(msg)
       # Assign the text part and set multipart/alternative if there's an html part.
       if msg
+        msg = Mail::Part.new(:body => msg) unless msg.kind_of?(Mail::Message)
+
         @text_part = msg
         @text_part.content_type = 'text/plain' unless @text_part.has_content_type?
         add_multipart_alternate_header if html_part
@@ -1709,7 +1730,7 @@ module Mail
 
     # Adds a part to the parts list or creates the part list
     def add_part(part)
-      if !body.multipart? && !self.body.decoded.blank?
+      if !body.multipart? && !Utilities.blank?(self.body.decoded)
         @text_part = Mail::Part.new('Content-Type: text/plain;')
         @text_part.body = body.decoded
         self.body << @text_part
@@ -1765,14 +1786,14 @@ module Mail
     #
     # See also #attachments
     def add_file(values)
-      convert_to_multipart unless self.multipart? || self.body.decoded.blank?
+      convert_to_multipart unless self.multipart? || Utilities.blank?(self.body.decoded)
       add_multipart_mixed_header
       if values.is_a?(String)
         basename = File.basename(values)
         filedata = File.open(values, 'rb') { |f| f.read }
       else
         basename = values[:filename]
-        filedata = values[:content] || File.open(values[:filename], 'rb') { |f| f.read }
+        filedata = values
       end
       self.attachments[basename] = filedata
     end
@@ -1790,7 +1811,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!
@@ -1799,7 +1819,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.")
+      warn("Deprecated in 1.1.0 in favour of :ready_to_send! as it is less confusing with encoding and decoding.")
       ready_to_send!
     end
 
@@ -1815,16 +1835,13 @@ module Mail
     end
 
     def without_attachments!
-      return self unless has_attachments?
-
-      parts.delete_if { |p| p.attachment? }
-      body_raw = if parts.empty?
-                   ''
-                 else
-                   body.encoded
-                 end
+      if has_attachments?
+        parts.delete_if { |p| p.attachment? }
 
-      @body = Mail::Body.new(body_raw)
+        reencoded = parts.empty? ? '' : body.encoded(content_transfer_encoding)
+        @body = nil # So the new parts won't be added to the existing body
+        self.body = reencoded
+      end
 
       self
     end
@@ -1857,7 +1874,7 @@ module Mail
         case
         when k == 'delivery_handler'
           begin
-            m.delivery_handler = Object.const_get(v) unless v.blank?
+            m.delivery_handler = Object.const_get(v) unless Utilities.blank?(v)
           rescue NameError
           end
         when k == 'transport_encoding'
@@ -1967,7 +1984,7 @@ module Mail
 
   private
 
-    HEADER_SEPARATOR = /#{CRLF}#{CRLF}|#{CRLF}#{WSP}*#{CRLF}(?!#{WSP})/m
+    HEADER_SEPARATOR = /#{Constants::CRLF}#{Constants::CRLF}/
 
     #  2.1. General Description
     #   A message consists of header fields (collectively called "the header
@@ -1976,9 +1993,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
@@ -1986,8 +2000,7 @@ module Mail
     end
 
     def raw_source=(value)
-      value = value.dup.force_encoding(Encoding::BINARY) if RUBY_VERSION >= "1.9.1"
-      @raw_source = value.to_crlf
+      @raw_source = value
     end
 
     # see comments to body=. We take data and process it lazily
@@ -1999,11 +2012,9 @@ module Mail
         @body_raw = nil
         add_encoding_to_body
       when @body && @body.multipart?
-        @body << Mail::Part.new(value)
-        add_encoding_to_body
+        self.text_part = value
       else
         @body_raw = value
-#        process_body_raw
       end
     end
 
@@ -2018,9 +2029,9 @@ module Mail
 
     def set_envelope_header
       raw_string = raw_source.to_s
-      if match_data = raw_source.to_s.match(/\AFrom\s(#{TEXT}+)#{CRLF}/m)
+      if match_data = raw_string.match(/\AFrom\s(#{TEXT}+)#{Constants::CRLF}/m)
         set_envelope(match_data[1])
-        self.raw_source = raw_string.sub(match_data[0], "") 
+        self.raw_source = raw_string.sub(match_data[0], "")
       end
     end
 
@@ -2028,6 +2039,13 @@ module Mail
       body.split!(boundary)
     end
 
+    def allowed_encodings
+      case mime_type
+      when 'message/rfc822'
+        [Encodings::SevenBit, Encodings::EightBit, Encodings::Binary]
+      end
+    end
+
     def add_encoding_to_body
       if has_content_transfer_encoding?
         @body.encoding = content_transfer_encoding
@@ -2035,18 +2053,18 @@ module Mail
     end
 
     def identify_and_set_transfer_encoding
-        if body && body.multipart?
-            self.content_transfer_encoding = @transport_encoding
-        else
-            self.content_transfer_encoding = body.get_best_encoding(@transport_encoding)
-        end
+      if body && body.multipart?
+        self.content_transfer_encoding = @transport_encoding
+      else
+        self.content_transfer_encoding = body.negotiate_best_encoding(@transport_encoding, allowed_encodings).to_s
+      end
     end
 
     def add_required_fields
       add_required_message_fields
       add_multipart_mixed_header    if body.multipart?
       add_content_type              unless has_content_type?
-      add_charset                   unless has_charset?
+      add_charset                   if text? && !has_charset?
       add_content_transfer_encoding unless has_content_transfer_encoding?
     end
 
@@ -2122,10 +2140,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
@@ -2146,20 +2164,7 @@ module Mail
     end
 
     def decode_body_as_text
-      body_text = decode_body
-      if charset
-        if RUBY_VERSION < '1.9'
-          require 'iconv'
-          return Iconv.conv("UTF-8//TRANSLIT//IGNORE", charset, body_text)
-        else
-          if encoding = Encoding.find(charset) rescue nil
-            body_text.force_encoding(encoding)
-            return body_text.encode(Encoding::UTF_8, :undef => :replace, :invalid => :replace, :replace => '')
-          end
-        end
-      end
-      body_text
+      Encodings.transcode_charset decode_body, charset, 'UTF-8'
     end
-
   end
 end

data/lib/mail/multibyte/chars.rb

@@ -1,4 +1,6 @@
 # encoding: utf-8
+# frozen_string_literal: true
+require 'mail/multibyte/unicode'
 
 module Mail #:nodoc:
   module Multibyte #:nodoc:
@@ -39,7 +41,7 @@ module Mail #:nodoc:
       if RUBY_VERSION >= "1.9"
         # Creates a new Chars instance by wrapping _string_.
         def initialize(string)
-          @wrapped_string = string
+          @wrapped_string = string.dup
           @wrapped_string.force_encoding(Encoding::UTF_8) unless @wrapped_string.frozen?
         end
       else
@@ -102,7 +104,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
@@ -110,7 +112,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
@@ -118,7 +120,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
@@ -134,7 +136,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)
@@ -143,8 +145,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)
@@ -156,8 +158,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
@@ -189,7 +191,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
@@ -198,10 +200,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)
@@ -211,10 +213,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)
@@ -224,10 +226,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)
@@ -243,7 +245,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
@@ -268,12 +270,12 @@ module Mail #:nodoc:
           @wrapped_string[*args] = replace_by
         else
           result = Unicode.u_unpack(@wrapped_string)
-          if args[0].is_a?(Fixnum)
+          if args[0].is_a?(Integer)
             raise IndexError, "index #{args[0]} out of string" if args[0] >= result.length
             min = args[0]
             max = args[1].nil? ? min : (min + args[1] - 1)
             range = Range.new(min, max)
-            replace_by = [replace_by].pack('U') if replace_by.is_a?(Fixnum)
+            replace_by = [replace_by].pack('U') if replace_by.is_a?(Integer)
           elsif args.first.is_a?(Range)
             raise RangeError, "#{args[0]} out of range" if args[0].min >= result.length
             range = args[0]
@@ -291,7 +293,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
@@ -300,7 +302,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
@@ -337,7 +339,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
@@ -345,7 +347,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
@@ -353,7 +355,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
@@ -361,8 +363,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
@@ -382,7 +384,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
@@ -391,7 +393,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
@@ -399,8 +401,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