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
- ENCODED_BLANKS
Public Instance Methods
Enables more predictable duck-typing on String-like classes. See
Object#acts_like?
.
# File lib/active_support/core_ext/string/behavior.rb, line 5 def acts_like_string? true end
If you pass a single integer, 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 29 def at(position) self[position] end
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 122 def blank? # The regexp that matches blank strings is expensive. For the case of empty # strings we can speed up this method (~3.5x) with an empty? call. The # penalty for the rest of strings is marginal. empty? || begin BLANK_RE.match?(self) rescue Encoding::CompatibilityError ENCODED_BLANKS[self.encoding].match?(self) end end
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 91 def camelize(first_letter = :upper) case first_letter when :upper ActiveSupport::Inflector.camelize(self, true) when :lower ActiveSupport::Inflector.camelize(self, false) else raise ArgumentError, "Invalid option, use either :upper or :lower." end end
Creates 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
.)
'ham_and_eggs'.classify # => "HamAndEgg" 'posts'.classify # => "Post"
# File lib/active_support/core_ext/string/inflections.rb, line 210 def classify ActiveSupport::Inflector.classify(self) end
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 67 def constantize ActiveSupport::Inflector.constantize(self) end
Replaces underscores with dashes in the string.
'puni_puni'.dasherize # => "puni-puni"
# File lib/active_support/core_ext/string/inflections.rb, line 134 def dasherize ActiveSupport::Inflector.dasherize(self) end
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 159 def deconstantize ActiveSupport::Inflector.deconstantize(self) end
Removes the module part from the constant expression in the string.
'ActiveSupport::Inflector::Inflections'.demodulize # => "Inflections" 'Inflections'.demodulize # => "Inflections" '::Inflections'.demodulize # => "Inflections" ''.demodulize # => ''
See also deconstantize
.
# File lib/active_support/core_ext/string/inflections.rb, line 146 def demodulize ActiveSupport::Inflector.demodulize(self) end
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 10 def exclude?(string) !include?(string) end
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 77 def first(limit = 1) if limit == 0 "" elsif limit >= size dup else to(limit - 1) end end
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 251 def foreign_key(separate_class_name_and_id_with_underscore = true) ActiveSupport::Inflector.foreign_key(self, separate_class_name_and_id_with_underscore) end
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 46 def from(position) self[position..-1] end
Marks a string as trusted safe. It will be inserted into HTML with no
additional escaping performed. It is your responsibility 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 255 def html_safe ActiveSupport::SafeBuffer.new(self) end
Capitalizes the first word, turns underscores into spaces, and (by
default)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.
The trailing '_id' can be kept and capitalized by setting the
optional parameter keep_id_suffix
to true. By default, this
parameter is false.
'employee_salary'.humanize # => "Employee salary" 'author_id'.humanize # => "Author" 'author_id'.humanize(capitalize: false) # => "author" '_id'.humanize # => "Id" 'author_id'.humanize(keep_id_suffix: true) # => "Author Id"
# File lib/active_support/core_ext/string/inflections.rb, line 231 def humanize(capitalize: true, keep_id_suffix: false) ActiveSupport::Inflector.humanize(self, capitalize: capitalize, keep_id_suffix: keep_id_suffix) end
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 9 def in_time_zone(zone = ::Time.zone) if zone ::Time.find_zone!(zone).parse(self) else to_time end end
Indents the lines in the receiver:
<<EOS.indent(2) def some_method some_code end EOS # => 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 42 def indent(amount, indent_string = nil, indent_empty_lines = false) dup.tap { |_| _.indent!(amount, indent_string, indent_empty_lines) } end
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 7 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
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 12 def inquiry ActiveSupport::StringInquirer.new(self) end
Returns true
if string has utf_8 encoding.
utf_8_str = "some string".encode "UTF-8" iso_str = "some string".encode "ISO-8859-1" utf_8_str.is_utf8? # => true iso_str.is_utf8? # => false
# File lib/active_support/core_ext/string/multibyte.rb, line 47 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
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 97 def last(limit = 1) if limit == 0 "" elsif limit >= size dup else from(-limit) end end
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.
>> "lj".upcase => "lj" >> "lj".mb_chars.upcase.to_s => "LJ"
NOTE: An above example is useful for pre Ruby 2.4. Ruby 2.4 supports Unicode case mappings.
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 36 def mb_chars ActiveSupport::Multibyte.proxy_class.new(self) end
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>
To preserve the case of the characters in a string, use the
preserve_case
argument.
class Person def to_param "#{id}-#{name.parameterize(preserve_case: true)}" 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 190 def parameterize(separator: "-", preserve_case: false) ActiveSupport::Inflector.parameterize(self, separator: separator, preserve_case: preserve_case) end
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 33 def pluralize(count = nil, locale = :en) locale = count if count.is_a?(Symbol) if count == 1 dup else ActiveSupport::Inflector.pluralize(self, locale) end end
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 32 def remove(*patterns) dup.remove!(*patterns) end
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 40 def remove!(*patterns) patterns.each do |pattern| gsub! pattern, "" end self end
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 78 def safe_constantize ActiveSupport::Inflector.safe_constantize(self) end
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 56 def singularize(locale = :en) ActiveSupport::Inflector.singularize(self, locale) end
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.
%{ 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 13 def squish dup.squish! end
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 21 def squish! gsub!(/[[:space:]]+/, " ") strip! self end
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 non-empty 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 gsub(/^#{scan(/^[ \t]*(?=\S)/).min}/, "".freeze) end
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" 'ham_and_egg'.tableize # => "ham_and_eggs" 'fancyCategory'.tableize # => "fancy_categories"
# File lib/active_support/core_ext/string/inflections.rb, line 200 def tableize ActiveSupport::Inflector.tableize(self) end
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.
The trailing '_id','Id'.. can be kept and capitalized by
setting the optional parameter keep_id_suffix
to true. By
default, this parameter is false.
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" 'string_ending_with_id'.titleize(keep_id_suffix: true) # => "String Ending With Id"
# File lib/active_support/core_ext/string/inflections.rb, line 116 def titleize(keep_id_suffix: false) ActiveSupport::Inflector.titleize(self, keep_id_suffix: keep_id_suffix) end
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 63 def to(position) self[0..position] end
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 46 def to_date ::Date.parse(self, false) unless blank? end
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 56 def to_datetime ::DateTime.parse(self, false) unless blank? end
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 06:12:00 UTC "12/13/2012".to_time # => ArgumentError: argument out of range
# File lib/active_support/core_ext/string/conversions.rb, line 21 def to_time(form = :local) parts = Date._parse(self, false) used_keys = %i(year mon mday hour min sec sec_fraction offset) return if (parts.keys & used_keys).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.to_time end
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 66 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
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 95 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
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 127 def underscore ActiveSupport::Inflector.underscore(self) end
Converts just the first character to uppercase.
'what a Lovely Day'.upcase_first # => "What a Lovely Day" 'w'.upcase_first # => "W" ''.upcase_first # => ""
# File lib/active_support/core_ext/string/inflections.rb, line 240 def upcase_first ActiveSupport::Inflector.upcase_first(self) end