Class: String

Inherits:
Object show all
Defined in:
motion/core_ext/string/inflections.rb,
motion/core_ext/string/strip.rb,
motion/core_ext/object/blank.rb,
motion/core_ext/string/indent.rb,
motion/core_ext/string/access.rb,
motion/core_ext/string/filters.rb,
motion/core_ext/string/exclude.rb,
motion/core_ext/string/behavior.rb,
motion/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 table from the name of a class.

'ScaleScore'.tableize # => "scale_scores"

Instance Method Summary collapse

Instance Method Details

#acts_like_string?Boolean

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


3
4
5
# File 'motion/core_ext/string/behavior.rb', line 3

def acts_like_string?
  true
end

#at(position) ⇒ Object

If you pass a single Fixnum, 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

27
28
29
# File 'motion/core_ext/string/access.rb', line 27

def at(position)
  self[position]
end

#blank?Boolean

A string is blank if it's empty or contains whitespaces only:

''.blank?                 # => true
'   '.blank?              # => true
' '.blank?               # => true
' something here '.blank? # => false

92
93
94
# File 'motion/core_ext/object/blank.rb', line 92

def blank?
  self !~ /[^[:space:]]/
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"

72
73
74
75
76
77
78
79
# File 'motion/core_ext/string/inflections.rb', line 72

def camelize(first_letter = :upper)
  case first_letter
  when :upper
    MotionSupport::Inflector.camelize(self, true)
  when :lower
    MotionSupport::Inflector.camelize(self, false)
  end
end

#classifyObject

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"

155
156
157
# File 'motion/core_ext/string/inflections.rb', line 155

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

#constantizeObject

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 MotionSupport::Inflector.constantize

'Module'.constantize  # => Module
'Class'.constantize   # => Class
'blargle'.constantize # => NameError: wrong constant name blargle

48
49
50
# File 'motion/core_ext/string/inflections.rb', line 48

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

#dasherizeObject

Replaces underscores with dashes in the string.

'puni_puni'.dasherize # => "puni-puni"

108
109
110
# File 'motion/core_ext/string/inflections.rb', line 108

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

#deconstantizeObject

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.


131
132
133
# File 'motion/core_ext/string/inflections.rb', line 131

def deconstantize
  MotionSupport::Inflector.deconstantize(self)
end

#demodulizeObject

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

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

See also deconstantize.


118
119
120
# File 'motion/core_ext/string/inflections.rb', line 118

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

#exclude?(string) ⇒ Boolean

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

8
9
10
# File 'motion/core_ext/string/exclude.rb', line 8

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

#first(limit = 1) ⇒ Object

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

str = "hello"
str.first    #=> "h"
str.first(1) #=> "h"
str.first(2) #=> "he"
str.first(0) #=> ""
str.first(6) #=> "hello"

75
76
77
78
79
80
81
82
83
# File 'motion/core_ext/string/access.rb', line 75

def first(limit = 1)
  if limit == 0
    ''
  elsif limit >= size
    self
  else
    to(limit - 1)
  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'.

'Message'.foreign_key        # => "message_id"
'Message'.foreign_key(false) # => "messageid"
'Admin::Post'.foreign_key    # => "post_id"

175
176
177
# File 'motion/core_ext/string/inflections.rb', line 175

def foreign_key(separate_class_name_and_id_with_underscore = true)
  MotionSupport::Inflector.foreign_key(self, separate_class_name_and_id_with_underscore)
end

#from(position) ⇒ Object

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"

44
45
46
# File 'motion/core_ext/string/access.rb', line 44

def from(position)
  self[position..-1]
end

#humanizeObject

Capitalizes the first word, turns underscores into spaces, and strips '_id'. Like titleize, this is meant for creating pretty output.

'employee_salary'.humanize # => "Employee salary"
'author_id'.humanize       # => "Author"

164
165
166
# File 'motion/core_ext/string/inflections.rb', line 164

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

#indent(amount, indent_string = nil, indent_empty_lines = false) ⇒ Object

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"

40
41
42
# File 'motion/core_ext/string/indent.rb', line 40

def indent(amount, indent_string=nil, indent_empty_lines=false)
  dup.tap {|_| _.indent!(amount, indent_string, indent_empty_lines)}
end

#indent!(amount, indent_string = nil, indent_empty_lines = false) ⇒ Object

Same as indent, except it indents the receiver in-place.

Returns the indented string, or nil if there was nothing to indent.


5
6
7
8
9
# File 'motion/core_ext/string/indent.rb', line 5

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

#last(limit = 1) ⇒ Object

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

str = "hello"
str.last    #=> "o"
str.last(1) #=> "o"
str.last(2) #=> "lo"
str.last(0) #=> ""
str.last(6) #=> "hello"

95
96
97
98
99
100
101
102
103
# File 'motion/core_ext/string/access.rb', line 95

def last(limit = 1)
  if limit == 0
    ''
  elsif limit >= size
    self
  else
    from(-limit)
  end
end

#pluralize(count = nil) ⇒ Object

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"

21
22
23
24
25
26
27
# File 'motion/core_ext/string/inflections.rb', line 21

def pluralize(count = nil)
  if count == 1
    self
  else
    MotionSupport::Inflector.pluralize(self)
  end
end

#safe_constantizeObject

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 MotionSupport::Inflector.safe_constantize

'Module'.safe_constantize  # => Module
'Class'.safe_constantize   # => Class
'blargle'.safe_constantize # => nil

59
60
61
# File 'motion/core_ext/string/inflections.rb', line 59

def safe_constantize
  MotionSupport::Inflector.safe_constantize(self)
end

#singularizeObject

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"

37
38
39
# File 'motion/core_ext/string/inflections.rb', line 37

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

#squishObject

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 like mongolian vowel separator (U+180E).

%{ Multi-line
   string }.squish                   # => "Multi-line string"
" foo   bar    \n   \t   boo".squish # => "foo bar boo"

11
12
13
# File 'motion/core_ext/string/filters.rb', line 11

def squish
  dup.squish!
end

#squish!Object

Performs a destructive squish. See String#squish.


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

def squish!
  gsub!(/\A[[:space:]]+/, '')
  gsub!(/[[:space:]]+\z/, '')
  gsub!(/[[:space:]]+/, ' ')
  self
end

#strip_heredocObject

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.


20
21
22
23
# File 'motion/core_ext/string/strip.rb', line 20

def strip_heredoc
  indent = scan(/^[ \t]*(?=\S)/).min.try(:size) || 0
  gsub(/^[ \t]{#{indent}}/, '')
end

#tableizeObject

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"

141
142
143
# File 'motion/core_ext/string/inflections.rb', line 141

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

#titleizeObject 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"

90
91
92
# File 'motion/core_ext/string/inflections.rb', line 90

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

#to(position) ⇒ Object

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"

61
62
63
# File 'motion/core_ext/string/access.rb', line 61

def to(position)
  self[0..position]
end

#truncate(truncate_at, 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..."

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

41
42
43
44
45
46
47
48
49
50
51
52
53
54
# File 'motion/core_ext/string/filters.rb', line 41

def truncate(truncate_at, options = {})
  return dup unless length > truncate_at

  options[:omission] ||= '...'
  length_with_room_for_omission = truncate_at - options[: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] + options[:omission]
end

#underscoreObject

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"

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

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