String inflections define new methods on theString 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"- A
- B
- C
- D
- E
- F
- H
- I
- L
- M
- P
- R
- S
- T
- U
Constants
| BLANK_RE | = | /\A[[:space:]]*\z/ |
| ENCODED_BLANKS | = | Concurrent::Map.new do |h, enc|h[enc] = Regexp.new(BLANK_RE.source.encode(enc), BLANK_RE.options | Regexp::FIXEDENCODING)end |
Instance Public methods
acts_like_string?()Link
Enables more predictable duck-typing on String-like classes. SeeObject#acts_like?.
at(position)Link
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. Returnsnil 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) # => nilstr.at(5..-1) # => ""If aRegexp is given, the matching portion of the string is returned. If aString 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/) # => nilstr.at("lo") # => "lo"str.at("ol") # => nilblank?()Link
A string is blank if it’s empty or contains whitespaces only:
''.blank? # => true' '.blank? # => true"\t\n\r".blank? # => true' blah '.blank? # => falseUnicode whitespace is supported:
"\u00a0".blank? # => true@return [true, false]
# File activesupport/lib/active_support/core_ext/object/blank.rb, line 153defblank?# 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?||beginBLANK_RE.match?(self)rescueEncoding::CompatibilityErrorENCODED_BLANKS[self.encoding].match?(self)endend
camelize(first_letter = :upper)Link
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 activesupport/lib/active_support/core_ext/string/inflections.rb, line 101defcamelize(first_letter =:upper)casefirst_letterwhen:upperActiveSupport::Inflector.camelize(self,true)when:lowerActiveSupport::Inflector.camelize(self,false)elseraiseArgumentError,"Invalid option, use either :upper or :lower."endend
classify()Link
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 followclassify withconstantize.)
'ham_and_eggs'.classify # => "HamAndEgg"'posts'.classify # => "Post"constantize()Link
constantize tries to find a declared constant with the name specified in the string. It raises aNameError when the name is not in CamelCase or is not initialized.
'Module'.constantize # => Module'Class'.constantize # => Class'blargle'.constantize # => NameError: wrong constant name blargledasherize()Link
Replaces underscores with dashes in the string.
'puni_puni'.dasherize # => "puni-puni"deconstantize()Link
Removes the rightmost segment from the constant expression in the string.
'Net::HTTP'.deconstantize # => "Net"'::Net::HTTP'.deconstantize # => "::Net"'String'.deconstantize # => ""'::String'.deconstantize # => ""''.deconstantize # => ""SeeActiveSupport::Inflector.deconstantize.
See alsodemodulize.
demodulize()Link
Removes the module part from the constant expression in the string.
'ActiveSupport::Inflector::Inflections'.demodulize # => "Inflections"'Inflections'.demodulize # => "Inflections"'::Inflections'.demodulize # => "Inflections"''.demodulize # => ''SeeActiveSupport::Inflector.demodulize.
See alsodeconstantize.
downcase_first()Link
Converts the first character to lowercase.
'If they enjoyed The Matrix'.downcase_first # => "if they enjoyed The Matrix"'I'.downcase_first # => "i"''.downcase_first # => ""exclude?(string)Link
The inverse ofString#include?. Returns true if the string does not include the other string.
"hello".exclude? "lo" # => false"hello".exclude? "ol" # => true"hello".exclude? ?h # => falsefirst(limit = 1)Link
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"foreign_key(separate_class_name_and_id_with_underscore = true)Link
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"from(position)Link
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 withto method and do fun things like:
str = "hello"str.from(0).to(-1) # => "hello"str.from(1).to(-2) # => "ell"html_safe()Link
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 theraw helper in views. It is recommended that you usesanitize instead of this method. It should never be called on user input.
humanize(capitalize: true, keep_id_suffix: false)Link
Capitalizes the first word, turns underscores into spaces, and (by default) strips a trailing ‘_id’ if present. Liketitleize, this is meant for creating pretty output.
The capitalization of the first word can be turned off by setting the optional parametercapitalize to false. By default, this parameter is true.
The trailing ‘_id’ can be kept and capitalized by setting the optional parameterkeep_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"in_time_zone(zone = ::Time.zone)Link
ConvertsString to a TimeWithZone in the current zone ifTime.zone orTime.zone_default is set, otherwise convertsString to aTime viaString#to_time
indent(amount, indent_string = nil, indent_empty_lines = false)Link
Indents the lines in the receiver:
<<EOS.indent(2)def some_method some_codeendEOS# => def some_method some_code endThe second argument,indent_string, specifies which indent string to use. The default isnil, which tells the method to make a guess by peeking at the first indented line, and fall back 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"Whileindent_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"indent!(amount, indent_string = nil, indent_empty_lines = false)Link
Same asindent, except it indents the receiver in-place.
Returns the indented string, ornil if there was nothing to indent.
inquiry()Link
Wraps the current string in theActiveSupport::StringInquirer class, which gives you a prettier way to test for equality.
env = 'production'.inquiryenv.production? # => trueenv.development? # => falseis_utf8?()Link
Returnstrue 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? # => trueiso_str.is_utf8? # => falselast(limit = 1)Link
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"mb_chars()Link
Multibyte proxy
mb_chars is a multibyte safe proxy for string methods.
It creates and returns an instance of theActiveSupport::Multibyte::Chars class which encapsulates the original string. A Unicode safe version of all theString 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".mb_chars.upcase.to_s=> "LJ"NOTE: Ruby 2.4 and later support native Unicode case mappings:
>> "lj".upcase=> "LJ"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 # => 12Interoperability and configuration
The Chars object tries to be as interchangeable withString objects as possible: sorting and comparing betweenString and Char work like expected. The bang! methods change the internal string representation in the Chars object. Interoperability problems can be resolved easily with ato_s call.
For more information about the methods defined on the Chars proxy seeActiveSupport::Multibyte::Chars. For information about how to change the default Multibyte behavior seeActiveSupport::Multibyte.
parameterize(separator: "-", preserve_case: false, locale: nil)Link
Replaces special characters in a string so that it may be used as part of a ‘pretty’ URL.
If the optional parameterlocale is specified, the word will be parameterized as a word of that language. By default, this parameter is set tonil and it will use the configuredI18n.locale.
class Person def to_param "#{id}-#{name.parameterize}" endend@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 thepreserve_case argument.
class Person def to_param "#{id}-#{name.parameterize(preserve_case: true)}" endend@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>pluralize(count = nil, locale = :en)Link
Returns the plural form of the word in the string.
If the optional parametercount is specified, the singular form will be returned ifcount == 1. For any other value ofcount the plural will be returned.
If the optional parameterlocale 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"remove(*patterns)Link
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"remove!(*patterns)Link
Alters the string by removing all occurrences of the patterns.
str = "foo bar test"str.remove!(" test", /bar/) # => "foo "str # => "foo "safe_constantize()Link
safe_constantize tries to find a declared constant with the name specified in the string. It returnsnil when the name is not in CamelCase or is not initialized.
'Module'.safe_constantize # => Module'Class'.safe_constantize # => Class'blargle'.safe_constantize # => nilsingularize(locale = :en)Link
The reverse ofpluralize, returns the singular form of a word in a string.
If the optional parameterlocale 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"squish()Link
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"squish!()Link
Performs a destructive squish. SeeString#squish.
str = " foo bar \n \t boo"str.squish! # => "foo bar boo"str # => "foo bar boo"strip_heredoc()Link
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 ... USAGEendthe 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.
tableize()Link
Creates the name of a table like Rails does for models to table names. This method uses thepluralize method on the last word in the string.
'RawScaledScorer'.tableize # => "raw_scaled_scorers"'ham_and_egg'.tableize # => "ham_and_eggs"'fancyCategory'.tableize # => "fancy_categories"titleize(keep_id_suffix: false)Link
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 parameterkeep_id_suffix to true. By default, this parameter is false.
'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"to(position)Link
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 withfrom method and do fun things like:
str = "hello"str.from(0).to(-1) # => "hello"str.from(1).to(-2) # => "ell"to_date()Link
Converts a string to aDate 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 dateto_datetime()Link
Converts a string to aDateTime 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 dateto_time(form = :local)Link
Converts a string to aTime value. Theform can be either:utc or:local (default:local).
The time is parsed using Time.parse method. Ifform 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"1604326192".to_time # => ArgumentError: argument out of range# File activesupport/lib/active_support/core_ext/string/conversions.rb, line 22defto_time(form =:local)parts =Date._parse(self,false)used_keys =%i(year mon mday hour min sec sec_fraction offset)returnif!parts.keys.intersect?(used_keys)now =Time.nowtime =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_timeend
truncate(truncate_to, options = {})Link
Truncates a giventext to lengthtruncate_to iftext is longer thantruncate_to:
'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 truncatetext 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 “…”). The total length will not exceedtruncate_to unless bothtext and:omission are longer thantruncate_to:
'And they found that many people were sleeping better.'.truncate(25, omission: '... (continued)')# => "And they f... (continued)"'And they found that many people were sleeping better.'.truncate(4, omission: '... (continued)')# => "... (continued)"# File activesupport/lib/active_support/core_ext/string/filters.rb, line 70deftruncate(truncate_to,options = {})returndupunlesslength>truncate_toomission =options[:omission]||"..."length_with_room_for_omission =truncate_to-omission.lengthstop = \ifoptions[:separator]rindex(options[:separator],length_with_room_for_omission)||length_with_room_for_omissionelselength_with_room_for_omissionend+"#{self[0, stop]}#{omission}"end
truncate_bytes(truncate_to, omission: "…")Link
Truncatestext to at mosttruncate_to bytes in length without breaking string encoding by splitting multibyte characters or breaking grapheme clusters (“perceptual characters”) by truncating at combining characters.
>> "🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪".size=> 20>> "🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪".bytesize=> 80>> "🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪".truncate_bytes(20)=> "🔪🔪🔪🔪…"The truncated text ends with the:omission string, defaulting to “…”, for a total length not exceedingtruncate_to.
RaisesArgumentError when the bytesize of:omission exceedstruncate_to.
# File activesupport/lib/active_support/core_ext/string/filters.rb, line 101deftruncate_bytes(truncate_to,omission:"…")omission||=""casewhenbytesize<=truncate_todupwhenomission.bytesize>truncate_toraiseArgumentError,"Omission #{omission.inspect} is #{omission.bytesize}, larger than the truncation length of #{truncate_to} bytes"whenomission.bytesize==truncate_toomission.dupelseself.class.new.force_encoding(encoding).tapdo|cut|cut_at =truncate_to-omission.bytesizeeach_grapheme_clusterdo|grapheme|ifcut.bytesize+grapheme.bytesize<=cut_atcut<<graphemeelsebreakendendcut<<omissionendendend
truncate_words(words_count, options = {})Link
Truncates a giventext 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 activesupport/lib/active_support/core_ext/string/filters.rb, line 142deftruncate_words(words_count,options = {})sep =options[:separator]||/\s+/sep =Regexp.escape(sep.to_s)unlessRegexp===sepifself=~/\A((?>.+?#{sep}){#{words_count - 1}}.+?)#{sep}.*/m$1+ (options[:omission]||"...")elsedupendend
underscore()Link
The reverse ofcamelize. 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"upcase_first()Link
Converts the first character to uppercase.
'what a Lovely Day'.upcase_first # => "What a Lovely Day"'w'.upcase_first # => "W"''.upcase_first # => ""