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
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 !~ /[^[:space:]]/
  else
    self !~ NON_WHITESPACE_REGEXP
  end
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 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
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.

"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 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 183
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!(/\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(/^[ \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 164
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 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

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

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