class String - mail-2.5.4 Documentation

# class String

This is an almost cut and paste from ActiveSupport v3.0.6, copied in here so that Mail itself does not depend on ActiveSupport to avoid versioning conflicts

### Public Instance Methods

at(position) click to toggle source

Returns the character at the `position` treating the string as an array (where 0 is the first character).

Examples:

    "hello".at(0)  # => "h"
    "hello".at(4)  # => "o"
    "hello".at(10) # => ERROR if < 1.9, nil in 1.9

    # File lib/mail/core_extensions/string/access.rb, line 15
    def at(position)
      mb_chars[position, 1].to_s
    end

constantize() click to toggle source

Tries to find a constant with the name specified in the argument string:

    "Module".constantize     # => Module
    "Test::Unit".constantize # => Test::Unit

The name is assumed to be the one of a top-level constant, no matter whether it starts with “::” or not. No lexical context is taken into account:

    C = 'outside'
    module M
      C = 'inside'
      C               # => 'inside'
      "C".constantize # => 'outside', same as ::C
    end

NameError is raised when the name is not in CamelCase or the constant is unknown.

    # File lib/mail/core_extensions/string/access.rb, line 122
    def constantize
      names = self.split('::')
      names.shift if names.empty? || names.first.empty?

      constant = Object
      names.each do |name|
        constant = constant.const_defined?(name) ? constant.const_get(name) : constant.const_missing(name)
      end
      constant
    end

first(limit = 1) click to toggle source

Returns the first character of the string or the first `limit` characters.

Examples:

    "hello".first     # => "h"
    "hello".first(2)  # => "he"
    "hello".first(10) # => "hello"

    # File lib/mail/core_extensions/string/access.rb, line 45
    def first(limit = 1)
      if limit == 0
        ''
      elsif limit >= size
        self
      else
        mb_chars[0...limit].to_s
      end
    end

from(position) click to toggle source

Returns the remaining of the string from the `position` treating the string as an array (where 0 is the first character).

Examples:

    "hello".from(0)  # => "hello"
    "hello".from(2)  # => "llo"
    "hello".from(10) # => "" if < 1.9, nil in 1.9

    # File lib/mail/core_extensions/string/access.rb, line 25
    def from(position)
      mb_chars[position..-1].to_s
    end

is_utf8?() click to toggle source

    # File lib/mail/core_extensions/string/multibyte.rb, line 52
    def is_utf8? #:nodoc
      case encoding
      when Encoding::UTF_8
        valid_encoding?
      when Encoding::ASCII_8BIT, Encoding::US_ASCII
        dup.force_encoding(Encoding::UTF_8).valid_encoding?
      else
        false
      end
    end

last(limit = 1) click to toggle source

Returns the last character of the string or the last `limit` characters.

Examples:

    "hello".last     # => "o"
    "hello".last(2)  # => "lo"
    "hello".last(10) # => "hello"

    # File lib/mail/core_extensions/string/access.rb, line 61
    def last(limit = 1)
      if limit == 0
        ''
      elsif limit >= size
        self
      else
        mb_chars[(-limit)..-1].to_s
      end
    end

mb_chars() 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/core_extensions/string/multibyte.rb, line 44
    def mb_chars
      if Mail::Multibyte.proxy_class.consumes?(self)
        Mail::Multibyte.proxy_class.new(self)
      else
        self
      end
    end

to(position) click to toggle source

Returns the beginning of the string up to the `position` treating the string as an array (where 0 is the first character).

Examples:

    "hello".to(0)  # => "h"
    "hello".to(2)  # => "hel"
    "hello".to(10) # => "hello"

    # File lib/mail/core_extensions/string/access.rb, line 35
    def to(position)
      mb_chars[0..position].to_s
    end