Class: String

Inherits:
Object show all
Includes:
CSD::Extensions::Core::String, Term::ANSIColor
Defined in:
lib/csd/extensions/core/string.rb,
lib/active_support/json/encoding.rb,
lib/active_support/core_ext/object/blank.rb,
lib/active_support/core_ext/string/access.rb,
lib/active_support/core_ext/string/exclude.rb,
lib/active_support/core_ext/string/filters.rb,
lib/active_support/core_ext/string/behavior.rb,
lib/active_support/core_ext/string/encoding.rb,
lib/active_support/core_ext/string/multibyte.rb,
lib/active_support/core_ext/string/conversions.rb,
lib/active_support/core_ext/string/inflections.rb,
lib/active_support/core_ext/string/output_safety.rb,
lib/active_support/core_ext/string/starts_ends_with.rb

Overview

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 database from the name of a class.

"ScaleScore".tableize # => "scale_scores"

Constant Summary

Constants included from Term::ANSIColor

Term::ANSIColor::ATTRIBUTES, Term::ANSIColor::ATTRIBUTE_NAMES, Term::ANSIColor::COLORED_REGEXP, Term::ANSIColor::VERSION, Term::ANSIColor::VERSION_ARRAY, Term::ANSIColor::VERSION_BUILD, Term::ANSIColor::VERSION_MAJOR, Term::ANSIColor::VERSION_MINOR

Instance Method Summary collapse

Methods included from CSD::Extensions::Core::String

#enquote

Methods included from Term::ANSIColor

attributes, coloring=, coloring?, #uncolored

Instance Method Details

#acts_like_string? ⇒ Boolean

Enable more predictable duck-typing on String-like classes. See Object#acts_like?.



4
5
6
 
# File 'lib/active_support/core_ext/string/behavior.rb', line 4

def acts_like_string?
  true
end

#as_json(options = nil) ⇒ Object

:nodoc:



168
 
# File 'lib/active_support/json/encoding.rb', line 168

def as_json(options = nil) self end

#at(position) ⇒ Object

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



11
12
13
 
# File 'lib/active_support/core_ext/string/access.rb', line 11

def at(position)
  mb_chars[position, 1].to_s
end

#blank? ⇒ Boolean 



67
68
69
 
# File 'lib/active_support/core_ext/object/blank.rb', line 67

def blank?
  self !~ /\S/
end

#camelize(first_letter = :upper) ⇒ Object Also known as: camelcase

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"



40
41
42
43
44
45
 
# File 'lib/active_support/core_ext/string/inflections.rb', line 40

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

#classify ⇒ Object

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"



125
126
127
 
# File 'lib/active_support/core_ext/string/inflections.rb', line 125

def classify
  ActiveSupport::Inflector.classify(self)
end

#constantize ⇒ Object

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.

Examples

"Module".constantize # => Module
"Class".constantize  # => Class



58
59
60
 
# File 'lib/active_support/core_ext/string/conversions.rb', line 58

def constantize
  ActiveSupport::Inflector.constantize(self)
end

#dasherize ⇒ Object

Replaces underscores with dashes in the string.

"puni_puni" # => "puni-puni"



74
75
76
 
# File 'lib/active_support/core_ext/string/inflections.rb', line 74

def dasherize
  ActiveSupport::Inflector.dasherize(self)
end

#demodulize ⇒ Object

Removes the module part from the constant expression in the string.

"ActiveRecord::CoreExtensions::String::Inflections".demodulize # => "Inflections"
"Inflections".demodulize                                       # => "Inflections"



82
83
84
 
# File 'lib/active_support/core_ext/string/inflections.rb', line 82

def demodulize
  ActiveSupport::Inflector.demodulize(self)
end

#encode_json(encoder) ⇒ Object

:nodoc:



169
 
# File 'lib/active_support/json/encoding.rb', line 169

def encode_json(encoder) encoder.escape(self) end

#encoding_aware? ⇒ Boolean 



3
4
5
 
# File 'lib/active_support/core_ext/string/encoding.rb', line 3

def encoding_aware?
  true
end

#exclude?(string) ⇒ Boolean

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



3
4
5
 
# File 'lib/active_support/core_ext/string/exclude.rb', line 3

def exclude?(string)
  !include?(string)
end

#first(limit = 1) ⇒ Object

Returns the first character of the string or the first limit characters.

Examples:

"hello".first     # => "h"
"hello".first(2)  # => "he"
"hello".first(10) # => "hello"



41
42
43
44
45
46
47
48
49
 
# 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) ⇒ Object

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"



146
147
148
 
# File 'lib/active_support/core_ext/string/inflections.rb', line 146

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) ⇒ Object

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



21
22
23
 
# File 'lib/active_support/core_ext/string/access.rb', line 21

def from(position)
  mb_chars[position..-1].to_s
end

#html_safe ⇒ Object 



106
107
108
 
# File 'lib/active_support/core_ext/string/output_safety.rb', line 106

def html_safe
  ActiveSupport::SafeBuffer.new(self)
end

#html_safe! ⇒ Object 



102
103
104
 
# File 'lib/active_support/core_ext/string/output_safety.rb', line 102

def html_safe!
  raise "You can't call html_safe! on a String"
end

#humanize ⇒ Object

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"



134
135
136
 
# File 'lib/active_support/core_ext/string/inflections.rb', line 134

def humanize
  ActiveSupport::Inflector.humanize(self)
end

#is_utf8? ⇒ Boolean

Returns true if the string has UTF-8 semantics (a String used for purely byte resources is unlikely to have them), returns false otherwise.



47
48
49
50
51
52
53
54
55
56
 
# File 'lib/active_support/core_ext/string/multibyte.rb', line 47

def is_utf8? #:nodoc
  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) ⇒ Object

Returns the last character of the string or the last limit characters.

Examples:

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



57
58
59
60
61
62
63
64
65
 
# 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 ⇒ Object

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 encapsuled 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 behaviour see ActiveSupport::Multibyte.



39
40
41
42
43
44
45
 
# File 'lib/active_support/core_ext/string/multibyte.rb', line 39

def mb_chars
  if ActiveSupport::Multibyte.proxy_class.consumes?(self)
    ActiveSupport::Multibyte.proxy_class.new(self)
  else
    self
  end
end

#ord ⇒ Object

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.



27
28
29
 
# File 'lib/active_support/core_ext/string/conversions.rb', line 27

def ord
  self[0]
end

#parameterize(sep = '-') ⇒ Object

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>



101
102
103
 
# File 'lib/active_support/core_ext/string/inflections.rb', line 101

def parameterize(sep = '-')
  ActiveSupport::Inflector.parameterize(self, sep)
end

#pluralize ⇒ Object

Returns the plural form of the word in the string.

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



15
16
17
 
# File 'lib/active_support/core_ext/string/inflections.rb', line 15

def pluralize
  ActiveSupport::Inflector.pluralize(self)
end

#singularize ⇒ Object

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"



27
28
29
 
# File 'lib/active_support/core_ext/string/inflections.rb', line 27

def singularize
  ActiveSupport::Inflector.singularize(self)
end

#squish ⇒ Object

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"



12
13
14
 
# File 'lib/active_support/core_ext/string/filters.rb', line 12

def squish
  dup.squish!
end

#squish! ⇒ Object

Performs a destructive squish. See String#squish.



17
18
19
20
21
 
# File 'lib/active_support/core_ext/string/filters.rb', line 17

def squish!
  strip!
  gsub!(/\s+/, ' ')
  self
end

#tableize ⇒ Object

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"



111
112
113
 
# File 'lib/active_support/core_ext/string/inflections.rb', line 111

def tableize
  ActiveSupport::Inflector.tableize(self)
end

#titleize ⇒ Object Also known as: titlecase

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"



56
57
58
 
# File 'lib/active_support/core_ext/string/inflections.rb', line 56

def titleize
  ActiveSupport::Inflector.titleize(self)
end

#to(position) ⇒ Object

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"



31
32
33
 
# File 'lib/active_support/core_ext/string/access.rb', line 31

def to(position)
  mb_chars[0..position].to_s
end

#to_date ⇒ Object 



39
40
41
42
 
# File 'lib/active_support/core_ext/string/conversions.rb', line 39

def to_date
  return nil if self.blank?
  ::Date.new(*::Date._parse(self, false).values_at(:year, :mon, :mday))
end

#to_datetime ⇒ Object 



44
45
46
47
48
49
 
# File 'lib/active_support/core_ext/string/conversions.rb', line 44

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) ⇒ Object

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



32
33
34
35
36
37
 
# File 'lib/active_support/core_ext/string/conversions.rb', line 32

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).map { |arg| arg || 0 }
  d[6] *= 1000000
  ::Time.send("#{form}_time", *d)
end

#truncate(length, options = {}) ⇒ Object

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

The last characters will be replaced with the :omission string (defaults to “…”) for a total length not exceeding :length:

"Once upon a time in a world far far away".truncate(27, :separator => ' ')
# => "Once upon a time in a..."

Pass a :separator to truncate text at a natural break:

"And they found that many people were sleeping better.".truncate(25, :omission => "... (continued)")
# => "And they f... (continued)"



38
39
40
41
42
43
44
45
46
47
48
 
# 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 ⇒ Object

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.

"ActiveRecord".underscore         # => "active_record"
"ActiveRecord::Errors".underscore # => active_record/errors



67
68
69
 
# File 'lib/active_support/core_ext/string/inflections.rb', line 67

def underscore
  ActiveSupport::Inflector.underscore(self)
end