class String - activesupport-4.2.4 Documentation

# class String

String inflections define new methods on the String class to transform names for different purposes. For instance, you can figure out the name of a table from the name of a class.

    'ScaleScore'.tableize # => "scale_scores"

### Constants

BLANK_RE

### Public Instance Methods

acts_like_string?() click to toggle source

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

    # File lib/active_support/core_ext/string/behavior.rb, line 3
    def acts_like_string?
      true
    end

at(position) click to toggle source

If you pass a single Fixnum, returns a substring of one character at that position. The first character of the string is at position 0, the next at position 1, and so on. If a range is supplied, a substring containing characters at offsets given by the range is returned. In both cases, if an offset is negative, it is counted from the end of the string. Returns nil if the initial offset falls outside the string. Returns an empty string if the beginning of the range is greater than the end of the string.

    str = "hello"
    str.at(0)      # => "h"
    str.at(1..3)   # => "ell"
    str.at(-2)     # => "l"
    str.at(-2..-1) # => "lo"
    str.at(5)      # => nil
    str.at(5..-1)  # => ""

If a Regexp is given, the matching portion of the string is returned. If a String is given, that given string is returned if it occurs in the string. In both cases, nil is returned if there is no match.

    str = "hello"
    str.at(/lo/) # => "lo"
    str.at(/ol/) # => nil
    str.at("lo") # => "lo"
    str.at("ol") # => nil

    # File lib/active_support/core_ext/string/access.rb, line 27
    def at(position)
      self[position]
    end

blank?() click to toggle source

A string is blank if it's empty or contains whitespaces only:

    ''.blank?       # => true
    '   '.blank?    # => true
    "\t\n\r".blank? # => true
    ' blah '.blank? # => false

Unicode whitespace is supported:

    "\u00a0".blank? # => true

@return [true, false]

    # File lib/active_support/core_ext/object/blank.rb, line 115
    def blank?
      BLANK_RE === self
    end

camelcase(first_letter = :upper)
Alias for: camelize
camelize(first_letter = :upper) click to toggle source

By default, `camelize` converts strings to UpperCamelCase. If the argument to camelize is set to `:lower` then camelize produces lowerCamelCase.

`camelize` will also convert '/' to '::' which is useful for converting paths to namespaces.

    'active_record'.camelize                # => "ActiveRecord"
    'active_record'.camelize(:lower)        # => "activeRecord"
    'active_record/errors'.camelize         # => "ActiveRecord::Errors"
    'active_record/errors'.camelize(:lower) # => "activeRecord::Errors"

    # File lib/active_support/core_ext/string/inflections.rb, line 89
    def camelize(first_letter = :upper)
      case first_letter
      when :upper
        ActiveSupport::Inflector.camelize(self, true)
      when :lower
        ActiveSupport::Inflector.camelize(self, false)
      end
    end

Also aliased as: camelcase
classify() click to toggle source

Create a class name from a plural table name like Rails does for table names to models. Note that this returns a string and not a class. (To convert to an actual class follow `classify` with `constantize`.)

    'egg_and_hams'.classify # => "EggAndHam"
    'posts'.classify        # => "Post"

    # File lib/active_support/core_ext/string/inflections.rb, line 187
    def classify
      ActiveSupport::Inflector.classify(self)
    end

constantize() click to toggle source

`constantize` tries to find a declared constant with the name specified in the string. It raises a NameError when the name is not in CamelCase or is not initialized. See ActiveSupport::Inflector#constantize

    'Module'.constantize  # => Module
    'Class'.constantize   # => Class
    'blargle'.constantize # => NameError: wrong constant name blargle

    # File lib/active_support/core_ext/string/inflections.rb, line 65
    def constantize
      ActiveSupport::Inflector.constantize(self)
    end

dasherize() click to toggle source

Replaces underscores with dashes in the string.

    'puni_puni'.dasherize # => "puni-puni"

    # File lib/active_support/core_ext/string/inflections.rb, line 125
    def dasherize
      ActiveSupport::Inflector.dasherize(self)
    end

deconstantize() click to toggle source

Removes the rightmost segment from the constant expression in the string.

    'Net::HTTP'.deconstantize   # => "Net"
    '::Net::HTTP'.deconstantize # => "::Net"
    'String'.deconstantize      # => ""
    '::String'.deconstantize    # => ""
    ''.deconstantize            # => ""

See also `demodulize`.

    # File lib/active_support/core_ext/string/inflections.rb, line 150
    def deconstantize
      ActiveSupport::Inflector.deconstantize(self)
    end

demodulize() click to toggle source

Removes the module part from the constant expression in the string.

    'ActiveRecord::CoreExtensions::String::Inflections'.demodulize # => "Inflections"
    'Inflections'.demodulize                                       # => "Inflections"
    '::Inflections'.demodulize                                     # => "Inflections"
    ''.demodulize                                                  # => ''

See also `deconstantize`.

    # File lib/active_support/core_ext/string/inflections.rb, line 137
    def demodulize
      ActiveSupport::Inflector.demodulize(self)
    end

exclude?(string) click to toggle source

The inverse of `String#include?`. Returns true if the string does not include the other string.

    "hello".exclude? "lo" # => false
    "hello".exclude? "ol" # => true
    "hello".exclude? ?h   # => false

    # File lib/active_support/core_ext/string/exclude.rb, line 8
    def exclude?(string)
      !include?(string)
    end

first(limit = 1) click to toggle source

Returns the first character. If a limit is supplied, returns a substring from the beginning of the string until it reaches the limit value. If the given limit is greater than or equal to the string length, returns a copy of self.

    str = "hello"
    str.first    # => "h"
    str.first(1) # => "h"
    str.first(2) # => "he"
    str.first(0) # => ""
    str.first(6) # => "hello"

    # File lib/active_support/core_ext/string/access.rb, line 75
    def first(limit = 1)
      if limit == 0
        ''
      elsif limit >= size
        self.dup
      else
        to(limit - 1)
      end
    end

foreign_key(separate_class_name_and_id_with_underscore = true) click to toggle source

Creates a foreign key name from a class name. `separate_class_name_and_id_with_underscore` sets whether the method should put '_' between the name and 'id'.

    'Message'.foreign_key        # => "message_id"
    'Message'.foreign_key(false) # => "messageid"
    'Admin::Post'.foreign_key    # => "post_id"

    # File lib/active_support/core_ext/string/inflections.rb, line 214
    def foreign_key(separate_class_name_and_id_with_underscore = true)
      ActiveSupport::Inflector.foreign_key(self, separate_class_name_and_id_with_underscore)
    end

from(position) click to toggle source

Returns a substring from the given position to the end of the string. If the position is negative, it is counted from the end of the string.

    str = "hello"
    str.from(0)  # => "hello"
    str.from(3)  # => "lo"
    str.from(-2) # => "lo"

You can mix it with `to` method and do fun things like:

    str = "hello"
    str.from(0).to(-1) # => "hello"
    str.from(1).to(-2) # => "ell"

    # File lib/active_support/core_ext/string/access.rb, line 44
    def from(position)
      self[position..-1]
    end

html_safe() click to toggle source

Marks a string as trusted safe. It will be inserted into HTML with no additional escaping performed. It is your responsibilty to ensure that the string contains no malicious content. This method is equivalent to the `raw` helper in views. It is recommended that you use `sanitize` instead of this method. It should never be called on user input.

    # File lib/active_support/core_ext/string/output_safety.rb, line 259
    def html_safe
      ActiveSupport::SafeBuffer.new(self)
    end

humanize(options = {}) click to toggle source

Capitalizes the first word, turns underscores into spaces, and strips a trailing '_id' if present. Like `titleize`, this is meant for creating pretty output.

The capitalization of the first word can be turned off by setting the optional parameter `capitalize` to false. By default, this parameter is true.

    'employee_salary'.humanize              # => "Employee salary"
    'author_id'.humanize                    # => "Author"
    'author_id'.humanize(capitalize: false) # => "author"
    '_id'.humanize                          # => "Id"

    # File lib/active_support/core_ext/string/inflections.rb, line 203
    def humanize(options = {})
      ActiveSupport::Inflector.humanize(self, options)
    end

in_time_zone(zone = ::Time.zone) click to toggle source

Converts String to a TimeWithZone in the current zone if Time.zone or Time.zone_default is set, otherwise converts String to a Time via #to_time

    # File lib/active_support/core_ext/string/zones.rb, line 7
    def in_time_zone(zone = ::Time.zone)
      if zone
        ::Time.find_zone!(zone).parse(self)
      else
        to_time
      end
    end

indent(amount, indent_string=nil, indent_empty_lines=false) click to toggle source

Indents the lines in the receiver:

    "def some_method
      some_code
    end
    ".indent(2)
    # =>
      def some_method
        some_code
      end

The second argument, `indent_string`, specifies which indent string to use. The default is `nil`, which tells the method to make a guess by peeking at the first indented line, and fallback to a space if there is none.

    "  foo".indent(2)        # => "    foo"
    "foo\n\t\tbar".indent(2) # => "\t\tfoo\n\t\t\t\tbar"
    "foo".indent(2, "\t")    # => "\t\tfoo"

While `indent_string` is typically one space or tab, it may be any string.

The third argument, `indent_empty_lines`, is a flag that says whether empty lines should be indented. Default is false.

    "foo\n\nbar".indent(2)            # => "  foo\n\n  bar"
    "foo\n\nbar".indent(2, nil, true) # => "  foo\n  \n  bar"

    # File lib/active_support/core_ext/string/indent.rb, line 40
    def indent(amount, indent_string=nil, indent_empty_lines=false)
      dup.tap {|_| _.indent!(amount, indent_string, indent_empty_lines)}
    end

indent!(amount, indent_string=nil, indent_empty_lines=false) click to toggle source

Same as `indent`, except it indents the receiver in-place.

Returns the indented string, or `nil` if there was nothing to indent.

    # File lib/active_support/core_ext/string/indent.rb, line 5
    def indent!(amount, indent_string=nil, indent_empty_lines=false)
      indent_string = indent_string || self[/^[ \t]/] || ' '
      re = indent_empty_lines ? /^/ : /^(?!$)/
      gsub!(re, indent_string * amount)
    end

inquiry() click to toggle source

Wraps the current string in the `ActiveSupport::StringInquirer` class, which gives you a prettier way to test for equality.

    env = 'production'.inquiry
    env.production?  # => true
    env.development? # => false

    # File lib/active_support/core_ext/string/inquiry.rb, line 10
    def inquiry
      ActiveSupport::StringInquirer.new(self)
    end

is_utf8?() click to toggle source

    # File lib/active_support/core_ext/string/multibyte.rb, line 38
    def is_utf8?
      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. If a limit is supplied, returns a substring from the end of the string until it reaches the limit value (counting backwards). If the given limit is greater than or equal to the string length, returns a copy of self.

    str = "hello"
    str.last    # => "o"
    str.last(1) # => "o"
    str.last(2) # => "lo"
    str.last(0) # => ""
    str.last(6) # => "hello"

    # File lib/active_support/core_ext/string/access.rb, line 95
    def last(limit = 1)
      if limit == 0
        ''
      elsif limit >= size
        self.dup
      else
        from(-limit)
      end
    end

mb_chars() click to toggle source

## Multibyte proxy¶ ↑

`mb_chars` is a multibyte safe proxy for string methods.

It creates and returns an instance of the ActiveSupport::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 encapsulated 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

## 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 ActiveSupport::Multibyte::Chars. For information about how to change the default Multibyte behavior see ActiveSupport::Multibyte.

    # File lib/active_support/core_ext/string/multibyte.rb, line 34
    def mb_chars
      ActiveSupport::Multibyte.proxy_class.new(self)
    end

parameterize(sep = '-') click to toggle source

Replaces special characters in a string so that it may be used as part of a 'pretty' URL.

    class Person
      def to_param
        "#{id}-#{name.parameterize}"
      end
    end

    @person = Person.find(1)
    # => #<Person id: 1, name: "Donald E. Knuth">

    <%= link_to(@person.name, person_path) %>
    # => <a href="/person/1-donald-e-knuth">Donald E. Knuth</a>

    # File lib/active_support/core_ext/string/inflections.rb, line 167
    def parameterize(sep = '-')
      ActiveSupport::Inflector.parameterize(self, sep)
    end

pluralize(count = nil, locale = :en) click to toggle source

Returns the plural form of the word in the string.

If the optional parameter `count` is specified, the singular form will be returned if `count == 1`. For any other value of `count` the plural will be returned.

If the optional parameter `locale` is specified, the word will be pluralized as a word of that language. By default, this parameter is set to `:en`. You must define your own inflection rules for languages other than English.

    'post'.pluralize             # => "posts"
    'octopus'.pluralize          # => "octopi"
    'sheep'.pluralize            # => "sheep"
    'words'.pluralize            # => "words"
    'the blue mailman'.pluralize # => "the blue mailmen"
    'CamelOctopus'.pluralize     # => "CamelOctopi"
    'apple'.pluralize(1)         # => "apple"
    'apple'.pluralize(2)         # => "apples"
    'ley'.pluralize(:es)         # => "leyes"
    'ley'.pluralize(1, :es)      # => "ley"

    # File lib/active_support/core_ext/string/inflections.rb, line 31
    def pluralize(count = nil, locale = :en)
      locale = count if count.is_a?(Symbol)
      if count == 1
        self.dup
      else
        ActiveSupport::Inflector.pluralize(self, locale)
      end
    end

remove(*patterns) click to toggle source

Returns a new string with all occurrences of the patterns removed.

    str = "foo bar test"
    str.remove(" test")                 # => "foo bar"
    str.remove(" test", /bar/)          # => "foo "
    str                                 # => "foo bar test"

    # File lib/active_support/core_ext/string/filters.rb, line 31
    def remove(*patterns)
      dup.remove!(*patterns)
    end

remove!(*patterns) click to toggle source

Alters the string by removing all occurrences of the patterns.

    str = "foo bar test"
    str.remove!(" test", /bar/)         # => "foo "
    str                                 # => "foo "

    # File lib/active_support/core_ext/string/filters.rb, line 39
    def remove!(*patterns)
      patterns.each do |pattern|
        gsub! pattern, ""
      end

      self
    end

safe_constantize() click to toggle source

`safe_constantize` tries to find a declared constant with the name specified in the string. It returns nil when the name is not in CamelCase or is not initialized. See ActiveSupport::Inflector#safe_constantize

    'Module'.safe_constantize  # => Module
    'Class'.safe_constantize   # => Class
    'blargle'.safe_constantize # => nil

    # File lib/active_support/core_ext/string/inflections.rb, line 76
    def safe_constantize
      ActiveSupport::Inflector.safe_constantize(self)
    end

singularize(locale = :en) click to toggle source

The reverse of `pluralize`, returns the singular form of a word in a string.

If the optional parameter `locale` is specified, the word will be singularized as a word of that language. By default, this parameter is set to `:en`. You must define your own inflection rules for languages other than English.

    'posts'.singularize            # => "post"
    'octopi'.singularize           # => "octopus"
    'sheep'.singularize            # => "sheep"
    'word'.singularize             # => "word"
    'the blue mailmen'.singularize # => "the blue mailman"
    'CamelOctopi'.singularize      # => "CamelOctopus"
    'leyes'.singularize(:es)       # => "ley"

    # File lib/active_support/core_ext/string/inflections.rb, line 54
    def singularize(locale = :en)
      ActiveSupport::Inflector.singularize(self, locale)
    end

squish() click to toggle source

Returns the string, first removing all whitespace on both ends of the string, and then changing remaining consecutive whitespace groups into one space each.

Note that it handles both ASCII and Unicode whitespace.

    %Q{ Multi-line
       string }.squish                   # => "Multi-line string"
    " foo   bar    \n   \t   boo".squish # => "foo bar boo"

    # File lib/active_support/core_ext/string/filters.rb, line 11
    def squish
      dup.squish!
    end

squish!() click to toggle source

Performs a destructive squish. See #squish.

    str = " foo   bar    \n   \t   boo"
    str.squish!                         # => "foo bar boo"
    str                                 # => "foo bar boo"

    # File lib/active_support/core_ext/string/filters.rb, line 19
    def squish!
      gsub!(/\A[[:space:]]+/, '')
      gsub!(/[[:space:]]+\z/, '')
      gsub!(/[[:space:]]+/, ' ')
      self
    end

strip_heredoc() click to toggle source

Strips indentation in heredocs.

For example in

    if options[:usage]
      puts "    This command does such and such.

        Supported options are:
          -h         This message
          ...
    ".strip_heredoc
    end

the user would see the usage message aligned against the left margin.

Technically, it looks for the least indented line in the whole string, and removes that amount of leading whitespace.

    # File lib/active_support/core_ext/string/strip.rb, line 22
    def strip_heredoc
      indent = scan(/^[ \t]*(?=\S)/).min.try(:size) || 0
      gsub(/^[ \t]{#{indent}}/, '')
    end

tableize() click to toggle source

Creates the name of a table like Rails does for models to table names. This method uses the `pluralize` method on the last word in the string.

    'RawScaledScorer'.tableize # => "raw_scaled_scorers"
    'egg_and_ham'.tableize     # => "egg_and_hams"
    'fancyCategory'.tableize   # => "fancy_categories"

    # File lib/active_support/core_ext/string/inflections.rb, line 177
    def tableize
      ActiveSupport::Inflector.tableize(self)
    end

titlecase()
Alias for: titleize
titleize() click to toggle source

Capitalizes all the words and replaces some characters in the string to create a nicer looking title. `titleize` is meant for creating pretty output. It is not used in the Rails internals.

`titleize` is also aliased as `titlecase`.

    'man from the boondocks'.titleize # => "Man From The Boondocks"
    'x-men: the last stand'.titleize  # => "X Men: The Last Stand"

    # File lib/active_support/core_ext/string/inflections.rb, line 107
    def titleize
      ActiveSupport::Inflector.titleize(self)
    end

Also aliased as: titlecase
to(position) click to toggle source

Returns a substring from the beginning of the string to the given position. If the position is negative, it is counted from the end of the string.

    str = "hello"
    str.to(0)  # => "h"
    str.to(3)  # => "hell"
    str.to(-2) # => "hell"

You can mix it with `from` method and do fun things like:

    str = "hello"
    str.from(0).to(-1) # => "hello"
    str.from(1).to(-2) # => "ell"

    # File lib/active_support/core_ext/string/access.rb, line 61
    def to(position)
      self[0..position]
    end

to_date() click to toggle source

Converts a string to a Date value.

    "1-1-2012".to_date   # => Sun, 01 Jan 2012
    "01/01/2012".to_date # => Sun, 01 Jan 2012
    "2012-12-13".to_date # => Thu, 13 Dec 2012
    "12/13/2012".to_date # => ArgumentError: invalid date

    # File lib/active_support/core_ext/string/conversions.rb, line 43
    def to_date
      ::Date.parse(self, false) unless blank?
    end

to_datetime() click to toggle source

Converts a string to a DateTime value.

    "1-1-2012".to_datetime            # => Sun, 01 Jan 2012 00:00:00 +0000
    "01/01/2012 23:59:59".to_datetime # => Sun, 01 Jan 2012 23:59:59 +0000
    "2012-12-13 12:50".to_datetime    # => Thu, 13 Dec 2012 12:50:00 +0000
    "12/13/2012".to_datetime          # => ArgumentError: invalid date

    # File lib/active_support/core_ext/string/conversions.rb, line 53
    def to_datetime
      ::DateTime.parse(self, false) unless blank?
    end

to_time(form = :local) click to toggle source

Converts a string to a Time value. The `form` can be either :utc or :local (default :local).

The time is parsed using Time.parse method. If `form` is :local, then the time is in the system timezone. If the date part is missing then the current date is used and if the time part is missing then it is assumed to be 00:00:00.

    "13-12-2012".to_time               # => 2012-12-13 00:00:00 +0100
    "06:12".to_time                    # => 2012-12-13 06:12:00 +0100
    "2012-12-13 06:12".to_time         # => 2012-12-13 06:12:00 +0100
    "2012-12-13T06:12".to_time         # => 2012-12-13 06:12:00 +0100
    "2012-12-13T06:12".to_time(:utc)   # => 2012-12-13 05:12:00 UTC
    "12/13/2012".to_time               # => ArgumentError: argument out of range

    # File lib/active_support/core_ext/string/conversions.rb, line 19
    def to_time(form = :local)
      parts = Date._parse(self, false)
      return if parts.empty?

      now = Time.now
      time = Time.new(
        parts.fetch(:year, now.year),
        parts.fetch(:mon, now.month),
        parts.fetch(:mday, now.day),
        parts.fetch(:hour, 0),
        parts.fetch(:min, 0),
        parts.fetch(:sec, 0) + parts.fetch(:sec_fraction, 0),
        parts.fetch(:offset, form == :utc ? 0 : nil)
      )

      form == :utc ? time.utc : time.getlocal
    end

truncate(truncate_at, options = {}) click to toggle source

Truncates a given `text` after a given `length` if `text` is longer than `length`:

    'Once upon a time in a world far far away'.truncate(27)
    # => "Once upon a time in a wo..."

Pass a string or regexp `:separator` to truncate `text` at a natural break:

    'Once upon a time in a world far far away'.truncate(27, separator: ' ')
    # => "Once upon a time in a..."

    'Once upon a time in a world far far away'.truncate(27, separator: /\s/)
    # => "Once upon a time in a..."

The last characters will be replaced with the `:omission` string (defaults to “…”) for a total length not exceeding `length`:

    'And they found that many people were sleeping better.'.truncate(25, omission: '... (continued)')
    # => "And they f... (continued)"

    # File lib/active_support/core_ext/string/filters.rb, line 65
    def truncate(truncate_at, options = {})
      return dup unless length > truncate_at

      omission = options[:omission] || '...'
      length_with_room_for_omission = truncate_at - omission.length
      stop =        if options[:separator]
          rindex(options[:separator], length_with_room_for_omission) || length_with_room_for_omission
        else
          length_with_room_for_omission
        end

      "#{self[0, stop]}#{omission}"
    end

truncate_words(words_count, options = {}) click to toggle source

Truncates a given `text` after a given number of words (`words_count`):

    'Once upon a time in a world far far away'.truncate_words(4)
    # => "Once upon a time..."

Pass a string or regexp `:separator` to specify a different separator of words:

    'Once<br>upon<br>a<br>time<br>in<br>a<br>world'.truncate_words(5, separator: '<br>')
    # => "Once<br>upon<br>a<br>time<br>in..."

The last characters will be replaced with the `:omission` string (defaults to “…”):

    'And they found that many people were sleeping better.'.truncate_words(5, omission: '... (continued)')
    # => "And they found that many... (continued)"

    # File lib/active_support/core_ext/string/filters.rb, line 94
    def truncate_words(words_count, options = {})
      sep = options[:separator] || /\s+/
      sep = Regexp.escape(sep.to_s) unless Regexp === sep
      if self =~ /\A((?>.+?#{sep}){#{words_count - 1}}.+?)#{sep}.*/m
        $1 + (options[:omission] || '...')
      else
        dup
      end
    end

underscore() click to toggle source

The reverse of `camelize`. Makes an underscored, lowercase form from the expression in the string.

`underscore` will also change '::' to '/' to convert namespaces to paths.

    'ActiveModel'.underscore         # => "active_model"
    'ActiveModel::Errors'.underscore # => "active_model/errors"

    # File lib/active_support/core_ext/string/inflections.rb, line 118
    def underscore
      ActiveSupport::Inflector.underscore(self)
    end