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"
0x3000: fullwidth whitespace
Enable more predictable duck-typing on String-like classes. See Object#acts_like?.
# File lib/active_support/core_ext/string/behavior.rb, line 3 3: def acts_like_string? 4: true 5: end
# File lib/active_support/json/encoding.rb, line 176 176: def as_json(options = nil) self end
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 11: def at(position) 12: mb_chars[position, 1].to_s 13: end
# File lib/active_support/core_ext/string/access.rb, line 67 67: def at(position) 68: self[position] 69: end
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 102 102: def blank? 103: # 1.8 does not takes [:space:] properly 104: if encoding_aware? 105: self !~ /[^[:space:]]/ 106: else 107: self !~ NON_WHITESPACE_REGEXP 108: end 109: 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 78 78: def camelize(first_letter = :upper) 79: case first_letter 80: when :upper then ActiveSupport::Inflector.camelize(self, true) 81: when :lower then ActiveSupport::Inflector.camelize(self, false) 82: end 83: end
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 178: def classify 179: ActiveSupport::Inflector.classify(self) 180: 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
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 53: def constantize 54: ActiveSupport::Inflector.constantize(self) 55: end
Replaces underscores with dashes in the string.
"puni_puni" # => "puni-puni"
# File lib/active_support/core_ext/string/inflections.rb, line 112 112: def dasherize 113: ActiveSupport::Inflector.dasherize(self) 114: 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 135 135: def deconstantize 136: ActiveSupport::Inflector.deconstantize(self) 137: end
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 122: def demodulize 123: ActiveSupport::Inflector.demodulize(self) 124: end
# File lib/active_support/json/encoding.rb, line 177 177: def encode_json(encoder) encoder.escape(self) end
# File lib/active_support/core_ext/string/encoding.rb, line 7 7: def encoding_aware? 8: false 9: end
# File lib/active_support/core_ext/string/encoding.rb, line 3 3: def encoding_aware? 4: true 5: 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 8 8: def exclude?(string) 9: !include?(string) 10: end
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 41: def first(limit = 1) 42: if limit == 0 43: '' 44: elsif limit >= size 45: self 46: else 47: mb_chars[0...limit].to_s 48: end 49: end
# File lib/active_support/core_ext/string/access.rb, line 79 79: def first(limit = 1) 80: if limit == 0 81: '' 82: elsif limit >= size 83: self 84: else 85: to(limit - 1) 86: end 87: 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’.
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 199: def foreign_key(separate_class_name_and_id_with_underscore = true) 200: ActiveSupport::Inflector.foreign_key(self, separate_class_name_and_id_with_underscore) 201: end
# File lib/active_support/core_ext/string/access.rb, line 71 71: def from(position) 72: self[position..1] 73: end
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 21: def from(position) 22: mb_chars[position..1].to_s 23: end
# File lib/active_support/core_ext/string/output_safety.rb, line 183 183: def html_safe 184: ActiveSupport::SafeBuffer.new(self) 185: end
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 187: def humanize 188: ActiveSupport::Inflector.humanize(self) 189: end
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 10: def inquiry 11: ActiveSupport::StringInquirer.new(self) 12: end
Returns true if the string has UTF-8 semantics (a String used for purely byte resources is unlikely to have them), returns false otherwise.
# File lib/active_support/core_ext/string/multibyte.rb, line 68 68: def is_utf8? 69: ActiveSupport::Multibyte::Chars.consumes?(self) 70: end
# File lib/active_support/core_ext/string/multibyte.rb, line 47 47: def is_utf8? 48: case encoding 49: when Encoding::UTF_8 50: valid_encoding? 51: when Encoding::ASCII_8BIT, Encoding::US_ASCII 52: dup.force_encoding(Encoding::UTF_8).valid_encoding? 53: else 54: false 55: end 56: end
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 57: def last(limit = 1) 58: if limit == 0 59: '' 60: elsif limit >= size 61: self 62: else 63: mb_chars[(-limit)..1].to_s 64: end 65: end
# File lib/active_support/core_ext/string/access.rb, line 89 89: def last(limit = 1) 90: if limit == 0 91: '' 92: elsif limit >= size 93: self 94: else 95: from(-limit) 96: end 97: end
# File lib/active_support/core_ext/string/multibyte.rb, line 58 58: def mb_chars 59: if ActiveSupport::Multibyte.proxy_class.wants?(self) 60: ActiveSupport::Multibyte.proxy_class.new(self) 61: else 62: self 63: end 64: end
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.
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
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 39 39: def mb_chars 40: if ActiveSupport::Multibyte.proxy_class.consumes?(self) 41: ActiveSupport::Multibyte.proxy_class.new(self) 42: else 43: self 44: end 45: end
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 28 28: def ord 29: self[0] 30: 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>
# File lib/active_support/core_ext/string/inflections.rb, line 154 154: def parameterize(sep = '-') 155: ActiveSupport::Inflector.parameterize(self, sep) 156: 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.
"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 25: def pluralize(count = nil) 26: if count == 1 27: self 28: else 29: ActiveSupport::Inflector.pluralize(self) 30: end 31: 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
Examples
"Module".safe_constantize # => Module "Class".safe_constantize # => Class "blargle".safe_constantize # => nil
# File lib/active_support/core_ext/string/inflections.rb, line 65 65: def safe_constantize 66: ActiveSupport::Inflector.safe_constantize(self) 67: end
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 41: def singularize 42: ActiveSupport::Inflector.singularize(self) 43: 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.
Examples:
%{ 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 12: def squish 13: dup.squish! 14: end
Performs a destructive squish. See String#squish.
# File lib/active_support/core_ext/string/filters.rb, line 17 17: def squish! 18: strip! 19: gsub!(/\s+/, ' ') 20: self 21: 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 line in the whole string, and removes that amount of leading whitespace.
# File lib/active_support/core_ext/string/strip.rb, line 22 22: def strip_heredoc 23: indent = scan(/^[ \t]*(?=\S)/).min.try(:size) || 0 24: gsub(/^[ \t]{#{indent}}/, '') 25: 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" "egg_and_ham".tableize # => "egg_and_hams" "fancyCategory".tableize # => "fancy_categories"
# File lib/active_support/core_ext/string/inflections.rb, line 164 164: def tableize 165: ActiveSupport::Inflector.tableize(self) 166: 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.
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 94: def titleize 95: ActiveSupport::Inflector.titleize(self) 96: end
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 31: def to(position) 32: mb_chars[0..position].to_s 33: end
# File lib/active_support/core_ext/string/access.rb, line 75 75: def to(position) 76: self[0..position] 77: 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 49 49: def to_date 50: return nil if self.blank? 51: ::Date.new(*::Date._parse(self, false).values_at(:year, :mon, :mday)) 52: 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 60 60: def to_datetime 61: return nil if self.blank? 62: d = ::Date._parse(self, false).values_at(:year, :mon, :mday, :hour, :min, :sec, :zone, :sec_fraction).map { |arg| arg || 0 } 63: d[5] += d.pop 64: ::DateTime.civil(*d) 65: end
Form can be either :utc (default) or :local.
# File lib/active_support/core_ext/string/conversions.rb, line 36 36: def to_time(form = :utc) 37: return nil if self.blank? 38: d = ::Date._parse(self, false).values_at(:year, :mon, :mday, :hour, :min, :sec, :sec_fraction, :offset).map { |arg| arg || 0 } 39: d[6] *= 1000000 40: ::Time.send("#{form}_time", *d[0..6]) - d[7] 41: 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 :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 38: def truncate(length, options = {}) 39: text = self.dup 40: options[:omission] ||= "..." 41: 42: length_with_room_for_omission = length - options[:omission].mb_chars.length 43: chars = text.mb_chars 44: stop = options[:separator] ? 45: (chars.rindex(options[:separator].mb_chars, length_with_room_for_omission) || length_with_room_for_omission) : length_with_room_for_omission 46: 47: (chars.length > length ? chars[0...stop] + options[:omission] : text).to_s 48: 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 105 105: def underscore 106: ActiveSupport::Inflector.underscore(self) 107: end
Disabled; run with --debug to generate this.
Generated with the Darkfish Rdoc Generator 1.1.6.