# 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

NON_WHITESPACE_REGEXP

  0x3000: fullwidth whitespace

### 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

as_json(options = nil) click to toggle source

    # File lib/active_support/json/encoding.rb, line 176
    def as_json(options = nil) self end

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/active_support/core_ext/string/access.rb, line 11
    def at(position)
      mb_chars[position, 1].to_s
    end

blank?() click to toggle source

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

    "".blank?                 # => true
    "   ".blank?              # => true
    "　".blank?               # => true
    " something here ".blank? # => false

    # File lib/active_support/core_ext/object/blank.rb, line 101
    def blank?
      # 1.8 does not takes [:space:] properly
      if encoding_aware?
        self !~ %r[^[:space:]]/
      else
        self !~ NON_WHITESPACE_REGEXP
      end
    end

camelcase(first_letter = :upper) click to toggle source
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 78
    def camelize(first_letter = :upper)
      case first_letter
        when :upper then ActiveSupport::Inflector.camelize(self, true)
        when :lower then 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"

Singular names are not handled correctly.

    "business".classify # => "Busines"

    # File lib/active_support/core_ext/string/inflections.rb, line 178
    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

Examples

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

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

dasherize() click to toggle source

Replaces underscores with dashes in the string.

    "puni_puni" # => "puni-puni"

    # File lib/active_support/core_ext/string/inflections.rb, line 112
    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 135
    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"

See also `deconstantize`.

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

encode_json(encoder) click to toggle source

    # File lib/active_support/json/encoding.rb, line 177
    def encode_json(encoder) encoder.escape(self) end

encoding_aware?() click to toggle source

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

exclude?(string) click to toggle source

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

    # File lib/active_support/core_ext/string/exclude.rb, line 3
    def exclude?(string)
      !include?(string)
    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/active_support/core_ext/string/access.rb, line 41
    def first(limit = 1)
      if limit == 0
        ''
      elsif limit >= size
        self
      else
        mb_chars[0...limit].to_s
      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’.

Examples

    "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 199
    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 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/active_support/core_ext/string/access.rb, line 21
    def from(position)
      mb_chars[position..-1].to_s
    end

html_safe() click to toggle source

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

humanize() click to toggle source

Capitalizes the first word, turns underscores into spaces, and strips ‘_id’. Like `titleize`, this is meant for creating pretty output.

    "employee_salary" # => "Employee salary"
    "author_id"       # => "Author"

    # File lib/active_support/core_ext/string/inflections.rb, line 187
    def humanize
      ActiveSupport::Inflector.humanize(self)
    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. Example:

    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 46
    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 or the last `limit` characters.

Examples:

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

    # File lib/active_support/core_ext/string/access.rb, line 57
    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 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

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 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 38
    def mb_chars
      if ActiveSupport::Multibyte.proxy_class.consumes?(self)
        ActiveSupport::Multibyte.proxy_class.new(self)
      else
        self
      end
    end

ord() click to toggle source

Returns the codepoint of the first character of the string, assuming a single-byte character encoding:

    "a".ord # => 97
    "à".ord # => 224, in ISO-8859-1

This method is defined in Ruby 1.8 for Ruby 1.9 forward compatibility on these character encodings.

`ActiveSupport::Multibyte::Chars#ord` is forward compatible with Ruby 1.9 on UTF8 strings:

    "a".mb_chars.ord # => 97
    "à".mb_chars.ord # => 224, in UTF8

Note that the 224 is different in both examples. In ISO-8859-1 “à” is represented as a single byte, 224. In UTF8 it is represented with two bytes, namely 195 and 160, but its Unicode codepoint is 224. If we call `ord` on the UTF8 string “à” the return value will be 195. That is not an error, because UTF8 is unsupported, the call itself would be bogus.

    # File lib/active_support/core_ext/string/conversions.rb, line 27
    def ord
      self[0]
    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.

#### Examples

    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 154
    def parameterize(sep = '-')
      ActiveSupport::Inflector.parameterize(self, sep)
    end

pluralize(count = nil) 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.

#### Examples

    "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"

    # File lib/active_support/core_ext/string/inflections.rb, line 25
    def pluralize(count = nil)
      if count == 1
        self
      else
        ActiveSupport::Inflector.pluralize(self)
      end
    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

Examples

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

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

singularize() click to toggle source

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

    "posts".singularize            # => "post"
    "octopi".singularize           # => "octopus"
    "sheep".singularize            # => "sheep"
    "word".singularize             # => "word"
    "the blue mailmen".singularize # => "the blue mailman"
    "CamelOctopi".singularize      # => "CamelOctopus"

    # File lib/active_support/core_ext/string/inflections.rb, line 41
    def singularize
      ActiveSupport::Inflector.singularize(self)
    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.

Examples:

    %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 12
    def squish
      dup.squish!
    end

squish!() click to toggle source

Performs a destructive squish. See #squish.

    # File lib/active_support/core_ext/string/filters.rb, line 17
    def squish!
      strip!
      gsub!(%r\s+/, ' ')
      self
    end

strip_heredoc() click to toggle source

Strips indentation in heredocs.

For example in

    if options[:usage]
      puts <<-USAGE.strip_heredoc
        This command does such and such.

        Supported options are:
          -h         This message
          ...
      USAGE
    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(%r^[ \t]*(?=\S)/).min.try(:size) || 0
      gsub(%r^[ \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 164
    def tableize
      ActiveSupport::Inflector.tableize(self)
    end

titlecase() click to toggle source
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 94
    def titleize
      ActiveSupport::Inflector.titleize(self)
    end

Also aliased as: titlecase
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/active_support/core_ext/string/access.rb, line 31
    def to(position)
      mb_chars[0..position].to_s
    end

to_date() click to toggle source

    # File lib/active_support/core_ext/string/conversions.rb, line 42
    def to_date
      return nil if self.blank?
      ::Date.new(*::Date._parse(self, false).values_at(:year, :mon, :mday))
    end

to_datetime() click to toggle source

    # File lib/active_support/core_ext/string/conversions.rb, line 47
    def to_datetime
      return nil if self.blank?
      d = ::Date._parse(self, false).values_at(:year, :mon, :mday, :hour, :min, :sec, :zone, :sec_fraction).map { |arg| arg || 0 }
      d[5] += d.pop
      ::DateTime.civil(*d)
    end

to_time(form = :utc) click to toggle source

Form can be either :utc (default) or :local.

    # File lib/active_support/core_ext/string/conversions.rb, line 35
    def to_time(form = :utc)
      return nil if self.blank?
      d = ::Date._parse(self, false).values_at(:year, :mon, :mday, :hour, :min, :sec, :sec_fraction, :offset).map { |arg| arg || 0 }
      d[6] *= 1000000
      ::Time.send("#{form}_time", *d[0..6]) - d[7]
    end

truncate(length, 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 `: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..."

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 38
    def truncate(length, options = {})
      text = self.dup
      options[:omission] ||= "..."

      length_with_room_for_omission = length - options[:omission].mb_chars.length
      chars = text.mb_chars
      stop = options[:separator] ?
        (chars.rindex(options[:separator].mb_chars, length_with_room_for_omission) || length_with_room_for_omission) : length_with_room_for_omission

      (chars.length > length ? chars[0...stop] + options[:omission] : text).to_s
    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 105
    def underscore
      ActiveSupport::Inflector.underscore(self)
    end