Class String
In: lib/core/facets/blank.rb
lib/core/facets/boolean.rb
lib/core/facets/comparable/cmp.rb
lib/core/facets/kernel/object_state.rb
lib/core/facets/string/align.rb
lib/core/facets/string/bracket.rb
lib/core/facets/string/bytes.rb
lib/core/facets/string/camelcase.rb
lib/core/facets/string/capitalized.rb
lib/core/facets/string/chars.rb
lib/core/facets/string/chomp.rb
lib/core/facets/string/cleanlines.rb
lib/core/facets/string/cleave.rb
lib/core/facets/string/compress_lines.rb
lib/core/facets/string/divide.rb
lib/core/facets/string/each_char.rb
lib/core/facets/string/each_word.rb
lib/core/facets/string/edit_distance.rb
lib/core/facets/string/expand_tab.rb
lib/core/facets/string/file.rb
lib/core/facets/string/fold.rb
lib/core/facets/string/indent.rb
lib/core/facets/string/index_all.rb
lib/core/facets/string/interpolate.rb
lib/core/facets/string/line_wrap.rb
lib/core/facets/string/lines.rb
lib/core/facets/string/margin.rb
lib/core/facets/string/methodize.rb
lib/core/facets/string/modulize.rb
lib/core/facets/string/mscan.rb
lib/core/facets/string/natcmp.rb
lib/core/facets/string/nchar.rb
lib/core/facets/string/newlines.rb
lib/core/facets/string/op_div.rb
lib/core/facets/string/op_sub.rb
lib/core/facets/string/pathize.rb
lib/core/facets/string/range.rb
lib/core/facets/string/rewrite.rb
lib/core/facets/string/shatter.rb
lib/core/facets/string/similarity.rb
lib/core/facets/string/snakecase.rb
lib/core/facets/string/splice.rb
lib/core/facets/string/start_with.rb
lib/core/facets/string/tab.rb
lib/core/facets/string/tabto.rb
lib/core/facets/string/titlecase.rb
lib/core/facets/string/to_re.rb
lib/core/facets/string/underscore.rb
lib/core/facets/string/unfold.rb
lib/core/facets/string/uppercase.rb
lib/core/facets/string/variablize.rb
lib/core/facets/string/word_wrap.rb
lib/core/facets/string/words.rb
lib/core/facets/string/xor.rb
lib/more/facets/date.rb
lib/more/facets/random.rb
lib/more/facets/roman.rb
lib/more/facets/succ.rb
lib/more/facets/tuple.rb
Parent: Object

Conveniently turn a string into a tuple.

Methods

Included Modules

Random

Constants

BRA2KET = { '['=>']', '('=>')', '{'=>'}', '<'=>'>' }

External Aliases

[]= -> store
  Alias for []=.
succ -> succ1

Public Class methods

Interpolate. Provides a means of extenally using Ruby string interpolation mechinism.

  try = "hello"
  str = "\#{try}!!!"
  String.interpolate{ str }    #=> "hello!!!"

  NOTE: The block neccessary in order to get
        then binding of the caller.

CREDIT: Trans

Public Instance methods

Removes occurances of a string or regexp.

  "HELLO HELLO" - "LL"    #=> "HEO HEO"

CREDIT: Benjamin David Oakes

Treats self and path as representations of pathnames, joining thme together as a single path.

  'home'/'trans' #=> 'home/trans'

Binary XOR of two strings.

  puts "\000\000\001\001" ^ "\000\001\000\001"
  puts  "\003\003\003" ^ "\000\001\002"

produces

  "\000\001\001\000"
  "\003\002\001"

Centers each line of a string.

The default alignment separation is a new line ("\n"). This can be changed as can be the padding string which defaults to a single space (’ ’).

  s = <<-EOS
    This is a test
    and
    so on
  EOS

  puts s.align_center(14)

produces

  This is a test
       and
      so on

CREDIT: Trans

Align a string to the left.

The default alignment separation is a new line ("\n"). This can be changed as can be the padding string which defaults to a single space (’ ’).

  s = <<-EOS
  This is a test
    and
    so on
  EOS

  puts s.align_left(20, "\n", '.')

produces

  This is a test......
  and.................
  so on...............

CREDIT: Trans

Align a string to the right.

The default alignment separation is a new line ("\n"). This can be changed as can be the padding string which defaults to a single space (’ ’).

  s = <<-EOS
  This is a test
    and
    so on
  EOS

  puts s.align_right(14)

produces

  This is a test
             and
           so on

CREDIT: Trans

Is this string just whitespace?

  "abc".blank?  #=> false
  "   ".blank?  #=> true

Return a new string embraced by given brakets. If only one bracket char is given it will be placed on either side.

  "wrap me".bracket('{')        #=> "{wrap me}"
  "wrap me".bracket('--','!')   #=> "--wrap me!"

CREDIT: Trans

Inplace version of braket.

CREDIT: Trans

Upacks string into bytes.

Note, this is not 100% compatible with 1.8.7+ which returns an enumerator instead of an array.

Return true if the string is capitalized, otherwise false.

  "THIS".capitalized?  #=> true
  "This".capitalized?  #=> true
  "this".capitalized?  #=> false

CREDIT: Phil Tomson

Returns an array of characters.

  "abc".chars  #=> ["a","b","c"]

Returns an Enumerator for iterating over each line of the string, stripped of whitespace on either side.

Cleave a string. Break a string in two parts at the nearest whitespace.

CREDIT: Trans

Compare method that takes length into account. Unlike #<=>, this is compatible with succ.

  "abc".cmp("abc")   #=>  0
  "abcd".cmp("abc")  #=>  1
  "abc".cmp("abcd")  #=> -1
  "xyz".cmp("abc")   #=>  1

CREDIT: Peter Vanbroekhoven

Matches any whitespace (including newline) and replaces with a single space

@example

  <<-QUERY.compress_lines
    SELECT name
    FROM users
  QUERY
  => "SELECT name FROM users"

Remove quotes from string.

  "'hi'".dequite    #=> "hi"

CREDIT: Trans

Breaks a string up into an array based on a regular expression. Similar to scan, but includes the matches.

  s = "<p>This<b>is</b>a test.</p>"
  s.divide( /\<.*?\>/ )

produces

  ["<p>This", "<b>is", "</b>a test.", "</p>"]

CREDIT: Trans

Return true if the string is lowercase (downcase), otherwise false.

  "THIS".downcase?  #=> false
  "This".downcase?  #=> false
  "this".downcase?  #=> true

CREDIT: Phil Tomson

Yields a single-character string for each character in the string. When $KCODE = ‘UTF8’, multi-byte characters are yielded appropriately.

Iterate through each word of a string.

  "a string".each_word { |word| ... }

Levenshtein distance algorithm implementation for Ruby, with UTF-8 support.

The Levenshtein distance is a measure of how similar two strings s and t are, calculated as the number of deletions/insertions/substitutions needed to transform s into t. The greater the distance, the more the strings differ.

The Levenshtein distance is also sometimes referred to as the easier-to-pronounce-and-spell ‘edit distance’.

Calculate the Levenshtein distance between two strings self and +str2+. self and +str2+ should be ASCII, UTF-8, or a one-byte-per character encoding such as ISO-8859-*.

The strings will be treated as UTF-8 if $KCODE is set appropriately (i.e. ‘u’). Otherwise, the comparison will be performed byte-by-byte. There is no specific support for Shift-JIS or EUC strings.

When using Unicode text, be aware that this algorithm does not perform normalisation. If there is a possibility of different normalised forms being used, normalisation should be performed beforehand.

CREDIT: Paul Battley

Does a string end with the given suffix?

  "hello".end_with?("lo")    #=> true
  "hello".end_with?("to")    #=> false

CREDIT: Lucas Carlson, Blaine Cook

ends_with?(suffix)

Alias for end_with?

Expands tabs to n spaces. Non-destructive. If n is 0, then tabs are simply removed. Raises an exception if n is negative.

  "\t\tHey".expand_tab(2)  #=> "    Hey"

Thanks to GGaramuno for a more efficient algorithm. Very nice.

CREDIT: Gavin Sinclair, Noah Gibbs, GGaramuno

expand_tabs(n=8)

Alias for expand_tab

Use fluent notation for making file directives.

   '~/trans/Desktop/notes.txt'.file.mtime

Returns a new string with all new lines removed from adjacent lines of text.

  s = "This is\na test.\n\nIt clumps\nlines of text."
  s.fold

produces

  "This is a test.\n\nIt clumps lines of text. "

One arguable flaw with this, that might need a fix: if the given string ends in a newline, it is replaced with a single space.

CREDIT: Trans

Indent left or right by n spaces. (This used to be called tab and aliased as indent.)

CREDIT: Gavin Sinclair, Trans, Tyler Rick

Like index but returns an array of all index locations. The reuse flag allows the trailing portion of a match to be reused for subsquent matches.

  "abcabcabc".index_all('a')  #=> [0,3,6]

  "bbb".index_all('bb', false)  #=> [0]
  "bbb".index_all('bb', true)   #=> [0,1]

TODO: Culd probably be defined for Indexable in general too.

Returns true iif the subject is a roman numeral.

Left chomp.

  "help".lchomp("h")  #=> "elp"
  "help".lchomp("k")  #=> "help"

CREDIT: Trans

In-place left chomp.

  "help".lchomp("h")  #=> "elp"
  "help".lchomp("k")  #=> "help"

CREDIT: Trans

Line wrap at width.

  puts "1234567890".line_wrap(5)

produces

  12345
  67890

CREDIT: Trans

Returns an array of characters.

  "abc\n123".lines  #=> ["abc\n","123"]

Downcase first letter.

Provides a margin controlled string.

  x = %Q{
        | This
        |   is
        |     margin controlled!
        }.margin

NOTE: This may still need a bit of tweaking.

TODO: describe its limits and caveats and edge cases

CREDIT: Trans

Translate a (class or module) name to a suitable method name.

  My::CoolClass.name.methodize => "my__cool_class"

Converts a string to module name representation.

This is essentially camelcase. It also converts ’/’ to ’::’ which is useful for converting paths to namespaces.

Examples

  "method_name".modulize    #=> "MethodName"
  "method/name".modulize    #=> "Method::Name"

Like scan but returns MatchData ($~) rather then matched string ($&).

CREDIT: Trans

‘Natural order’ comparison of strings, e.g.

  "my_prog_v1.1.0" < "my_prog_v1.2.0" < "my_prog_v1.10.0"

which does not follow alphabetically. A secondary parameter, if set to true, makes the comparison case insensitive.

  "Hello.10".natcmp("Hello.1")  #=> -1

  TODO: Invert case flag?

CREDIT: Alan Davies, Martin Pool

Returns n characters of the string. If n is positive the characters are from the beginning of the string. If n is negative from the end of the string.

Alternatively a replacement string can be given, which will replace the n characters.

   str = "this is text"
   str.nchar(4)            #=> "this"
   str.nchar(4, 'that')    #=> "that"
   str                     #=> "that is text"

Returns an Enumerator for iterating over each line of the string, void of the termining newline character, in contrast to lines which retains it.

Outdent just indents a negative number of spaces.

CREDIT: Noah Gibbs

Converts a (class or module) name to a unix path.

  My::CoolClass.name.pathize  #=> "my/cool_class"

Return a new string embraced by given quotes. If no quotes are specified, then assumes single quotes.

  "quote me".quote     #=> "'quote me'"
  "quote me".quote(2)  #=> "\"quote me\""

CREDIT: Trans

Like index but returns a Range.

  "This is a test!".range('test')  #=> 10..13

CREDIT: Trans

Like index_all but returns an array of Ranges.

  "abc123abc123".range_all('abc')  #=> [0..2, 6..8]

  TODO: Add offset, perhaps ?

CREDIT: Trans

Returns an array of ranges mapping the characters per line.

  "this\nis\na\ntest".range_of_line
  #=> [0..4, 5..7, 8..9, 10..13]

CREDIT: Trans

Apply a set of rules (regular expression matches) to the string.

Requirements:

The rules must be applied in order! So we cannot use a hash because the ordering is not guaranteed! we use an array instead.

Input:

The array containing rule-pairs (match, write).

Output:

The rewritten string.

CREDIT: George Moschovitis

Breaks a string up into an array based on a regular expression. Similar to scan, but includes the matches.

  s = "<p>This<b>is</b>a test.</p>"
  s.shatter( /\<.*?\>/ )

produces

  ["<p>", "This", "<b>", "is", "</b>", "a test.", "</p>"]

CREDIT: Trans

A fuzzy matching mechanism. Returns a score from 0-1, based on the number of shared edges. To be effective, the strings must be of length 2 or greater.

  "Alexsander".fuzzy_match( "Aleksander" )  #=> 0.9

The way it works:

  • Converts each string into a "graph like" object, with edges
      "alexsander" -> [ alexsander, alexsand, alexsan ... lexsand ... san ... an, etc ]
      "aleksander" -> [ aleksander, aleksand ... etc. ]
    
  • Perform match, then remove any subsets from this matched set (i.e. a hit on "san" is a subset of a hit on "sander")
      Above example, once reduced -> [ ale, sander ]
    
  • See‘s how many of the matches remain, and calculates a score based on how many matches, their length, and compare to the length of the larger of the two words.

Still a bit rough. Any suggestions for improvement are welcome.

CREDIT: Derek Lewis.

The reverse of camelcase. Makes an underscored of a camelcase string.

Changes ’::’ to ’/’ to convert namespaces to paths.

Examples

  "SnakeCase".snakecase           #=> "snake_case"
  "Snake-Case".snakecase          #=> "snake_case"
  "SnakeCase::Errors".snakecase   #=> "snake_case/errors"

This is basically the same as store, but it acts like slice! when given only one argument.

Essentlay slice, but writes rather than reads.

  a = "HELLO"
  a.splice("X", 1)
  a                #=> "HXLLO"

  a = "HELLO"
  a.splice(1)    #=> "E"
  a              #=> "HLLO"

CREDIT: Trans

Does a string start with the given prefix?

  "hello".start_with?("he")    #=> true
  "hello".start_with?("to")    #=> false

CREDIT: Lucas Carlson, Blaine Cook

starts_with?(prefix)

Alias for start_with?

Allows succ to take n step increments.

  "abc".succ      #=> "abd"
  "abc".succ(4)   #=> "abg"
  "abc".succ(24)  #=> "aca"

CREDIT: Trans

Aligns each line n spaces.

CREDIT: Gavin Sinclair

Preserves relative tabbing. The first non-empty line ends up with n spaces before nonspace.

CREDIT: Gavin Sinclair

Title case.

  "this is a string".titlecase
  => "This Is A String"

CREDIT: Eliazar Parra

Interpret common affirmative string meanings as true, otherwise false. Balnk sapce and case are ignored. The following strings that will return true:

  <tt>true</tt>,<tt>yes</tt>,<tt>on</tt>,<tt>t</tt>,<tt>1</tt>,<tt>y</tt>,<tt>==</tt>

Examples:

  "true".to_b   #=> true
  "yes".to_b    #=> true
  "no".to_b     #=> false
  "123".to_b    #=> false

Parse data from string.

Convert string to DateTime.

Considers string a roman numeral numeral, and converts it to the corresponding integer.

Turns a string into a regular expression.

  "a?".to_re  #=> /a?/

CREDIT: Trans

Turns a string into a regular expression. By default it will escape all characters. Use false argument to turn off escaping.

  "[".to_rx  #=> /\[/

CREDIT: Trans

Translates a string in the form on a set of numerical and/or alphanumerical characters separated by non-word characters (eg \W+) into a Tuple. The values of the tuple will be converted to integers if they are purely numerical.

  '1.2.3a'.to_t  #=> [1,2,"3a"]

It you would like to control the interpretation of each value as it is added to the tuple you can supply a block.

  '1.2.3a'.to_t { |v| v.upcase }  #=> ["1","2","3A"]

This method calls Tuple.cast_from_string.

Return a new string embraced by given brakets. If only one bracket char is given it will be placed on either side.

  "{unwrap me}".debracket('{')        #=> "unwrap me"
  "--unwrap me!".debracket('--','!')  #=> "unwrap me!"

CREDIT: Trans

Inplace version of debraket.

CREDIT: Trans

The reverse of camelcase. Makes an underscored of a camelcase string.

Changes ’::’ to ’/’ to convert namespaces to paths.

Examples

  "SnakeCase".underscore           #=> "snake_case"
  "Snake-Case".underscore          #=> "snake_case"
  "SnakeCase::Errors".underscore   #=> "snake_case/errors"

Unfold paragrpahs.

FIXME: Sometimes adds one too many blank lines. TEST!!!

Is the string upcase/uppercase?

  "THIS".upcase?  #=> true
  "This".upcase?  #=> false
  "this".upcase?  #=> false

CREDIT: Phil Tomson

Upcase first letter.

NOTE: One might argue that this method should behave the same as +upcase+ and rather this behavior should be in place of +captialize+. Probably so, but since Matz has already defined +captialize+ the way it is, this name seems most fitting to the missing behavior.

Prepend an "@" to the beginning of a string to make a instance variable name. This also replaces non-valid characters with underscores.

Word wrap a string not exceeding max width.

  puts "this is a test".word_wrap(4)

produces

  this
  is a
  test

This is basic implementation of word wrap, but smart enough to suffice for most use cases.

CREDIT: Gavin Kistner, Dayne Broderson

As with word_wrap, but modifies the string in place.

CREDIT: Gavin Kistner, Dayne Broderson

Returns an array of characters.

  "abc 123".words  #=> ["abc","123"]

[Validate]