Class | String

In:

lib/core/facets/boolean.rb
lib/core/facets/comparable/cmp.rb
lib/core/facets/kernel/blank.rb
lib/core/facets/object/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/characters.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/exclude.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/lchomp.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/quote.rb
lib/core/facets/string/random_binary.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/tab.rb
lib/core/facets/string/snakecase.rb
lib/core/facets/string/splice.rb
lib/core/facets/string/squish.rb
lib/core/facets/string/start_with.rb
lib/core/facets/string/store.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/core-uncommon/facets/integer/roman.rb
lib/core-uncommon/facets/string/acronym.rb
lib/core-uncommon/facets/string/crypt.rb
lib/standard/facets/date.rb
lib/standard/facets/random.rb
lib/supplemental/facets/tuple.rb

Parent: | Object

### Methods

- / ^ acronymize align align_center align_left align_right blank? bracket bracket! bytes camelcase capitalized? characters cleanlines cleave cmp compress_lines crypt divide downcase? each_char each_word edit_distance edit_distance end_with? ends_with? exclude? expand_tab expand_tabs file fold indent indent! index_all inter_camelcase interpolate lchomp lchomp! line_wrap lines lower_camelcase lowercase margin methodize modulize mscan natcmp nchar newlines object_state pathize quote random_binary range range_all range_of_line rewrite shatter similarity snakecase splice squish squish! start_with? starts_with? tab tabto titlecase to_b to_date to_datetime to_re to_rx to_t to_time unbracket unbracket! underscore unfold unindent unindent! unquote upcase? upper_camelcase uppercase variablize word_wrap word_wrap! words

### Included Modules

Random::StringExtensions

### Constants

BRA2KET | = | { '['=>']', '('=>')', '{'=>'}', '<'=>'>' }
ROMAN | = | /^M*(D?C{0,3}|C[DM])(L?X{0,3}|X[LC])(V?I{0,3}|I[VX])$/i unless const_defined?(:ROMAN) |  | Taken from O‘Reilly‘s Perl Cookbook 6.23. Regular Expression Grabbag.
ROMAN_VALUES | = | Integer::ROMAN_VALUES.inject({}) do |h,(r,a)| h[r] = a;

### External Aliases

[]= | -> | store
| Alias for []=.
crypt | -> | _crypt

### Public Class methods

interpolate(&str)

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

random_binary(n_bytes)

Generate a random binary string of `n_bytes` size.

CREDIT: Guido De Rosa

### Public Instance methods

-(pattern)

Removes occurances of a string or regexp.

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

CREDIT: Benjamin David Oakes

/(path)

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

      ('home' / 'trans')  #=> 'home/trans'

^(aString)

Binary XOR of two strings.

      a = "\000\000\001\001" ^ "\000\001\000\001"
      b = "\003\003\003" ^ "\000\001\002"

      a  #=> "\000\001\001\000"
      b  #=> "\003\002\001"

acronymize()

CREDIT: Robert Fey

align(direction, n, sep="\n", c=' ')

Alignment method dispatches to align_right, align_left or align_center, accorging to the first `direction` parameter.

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

      s.align(:right, 14)

produces …

      This is a test
                 and
               so on

Returns a String aligned right, left or center.

align_center(n, sep="\n", c=' ')

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

      s.align_center(14)

produces …

      This is a test
           and
          so on

CREDIT: Trans

align_left(n, sep="\n", c=' ')

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

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

produces …

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

CREDIT: Trans

align_right(n, sep="\n", c=' ')

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

      s.align_right(14)

produces …

      This is a test
                 and
               so on

CREDIT: Trans

blank?()

Is this string just whitespace?

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

bracket(bra, ket=nil)

Return a new string embraced by given brackets. 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

bracket!(bra, ket=nil)

Inplace version of bracket.

CREDIT: Trans

bytes(&blk)

Upacks string into bytes.

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

camelcase(first_letter=nil)
capitalized?()

Return true if the string is capitalized, otherwise false.

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

Note Ruby‘s strange concept of capitalized. See capitalcase for the more command conception.

CREDIT: Phil Tomson

characters()

Returns an array of characters.

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

TODO: Probably should make this an enumerator. With scan?

cleanlines(&block)

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

      "this\nthat\nother\n".cleanlines.to_a  #=> ['this', 'that', 'other']

cleave(threshold=nil, len=nil)

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

CREDIT: Trans

cmp(other)

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

TODO: Move String#cmp to string/ directory.

compress_lines(spaced = true)

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

      string = <<-QUERY.compress_lines
        SELECT name
        FROM users
      QUERY

      string  #=> "SELECT name FROM users"

crypt(salt=nil)

Common Unix cryptography method. This adds a default salt to the built-in crypt method.

NOTE: This is not (presently) a common core extension and is not loaded automatically when using `require ‘facets‘`.

divide( re )

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( /\<.*?\>/ )
      #=> ["<p>This", "<b>is", "</b>a test.", "</p>"]

CREDIT: Trans

downcase?()

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

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

CREDIT: Phil Tomson

each_char( {|| ...}

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

      a = ''
      "HELLO".each_char{ |c| a << "#{c.downcase}" }
      a  #=> 'hello'

each_word(&block)

Iterate through each word of a string.

      a = []

      "list of words".each_word { |word| a << word }

      a  #=> ['list', 'of', 'words']

edit_distance(str2)

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

edit_distance(str2)

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

end_with?(suffix)

Does a string end with the given suffix?

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

Note: This definition is better than standard Ruby‘s becuase it handles regular expressions.

CREDIT: Juris Galang

ends_with?(suffix)

Alias for end_with?

exclude?(str)

The inverse of include?.

expand_tab(n=8)

Alias for expand_tabs

expand_tabs(n=8)

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_tabs(2)  #=> "    Hey"

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

CREDIT: Gavin Sinclair, Noah Gibbs, GGaramuno

TODO: Don‘t much care for the name String#expand_tabs. What about a more concise name like detab?

file()

Use fluent notation for making file directives.

For instance, if we had a file ‘foo.txt’,

       'foo.txt'.file.mtime

fold(ignore_indented=false)

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(n, c=' ')

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

CREDIT: Gavin Sinclair, Trans, Tyler Rick

indent!(n, c=' ')

Equivalent to String#indent, but modifies the receiver in place.

index_all(s, reuse=false)

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.

inter_camelcase()
lchomp(match)

Left chomp.

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

CREDIT: Trans

lchomp!(match)

In-place left chomp.

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

CREDIT: Trans

line_wrap(width, tabs=4)

Line wrap at width.

      s = "1234567890".line_wrap(5)

      s  #=> "12345\n67890\n"

CREDIT: Trans

lines(&blk)

Returns an array of characters.

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

lower_camelcase()
lowercase()

Downcase first letter.

margin(n=0)

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

methodize()

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

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

modulize()

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"

mscan(re) {|| ...}

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

CREDIT: Trans

natcmp(str2, caseInsensitive=false)

‘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.1".natcmp("Hello.10")  #=> -1

TODO: Invert case flag?

CREDIT: Alan Davies, Martin Pool

nchar(n, replacement=nil)

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.

       str = "this is text"

       str.nchar(4)            #=> "this"
       str.nchar(-4)           #=> "text"

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

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

The original string remains unaffected.

       str  #=> "this is text"

newlines(&block)

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

      "a\nb\nc".newlines.class.assert == Enumerator
      "a\nb\nc".newlines.to_a.assert == %w{a b c}

      a = []
      "a\nb\nc".newlines{|nl| a << nl}
      a.assert == %w{a b c}

object_state(data=nil)
pathize()

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

      "ExamplePathize".pathize           #=> "example_pathize"
      "ExamplePathize::Example".pathize  #=> "example_pathize/example"

quote(type=:double, count=nil)

Return a new string embraced by given `type` and `count` of quotes. The arguments can be given in any order.

If no type is given, double quotes are assumed.

      "quote me".quote     #=> '"quote me"'

If no type but a count is given then :mixed is assumed.

      "quote me".quote(1)  #=> %q{'quote me'}
      "quote me".quote(2)  #=> %q{"quote me"}
      "quote me".quote(3)  #=> %q{'"quote me"'}

Symbols can be used to describe the type.

      "quote me".quote(:single)    #=> %q{'quote me'}
      "quote me".quote(:double)    #=> %q{"quote me"}
      "quote me".quote(:back)      #=> %q{`quote me`}
      "quote me".quote(:bracket)   #=> %q{`quote me'}

Or the character itself.

      "quote me".quote("'")     #=> %q{'quote me'}
      "quote me".quote('"')     #=> %q{"quote me"}
      "quote me".quote("`")     #=> %q{`quote me`}
      "quote me".quote("`'")    #=> %q{`quote me'}

CREDIT: Trans

range(pattern, offset=0)

Like index but returns a Range.

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

CREDIT: Trans

range_all(pattern, reuse=false)

Like index_all but returns an array of Ranges.

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

TODO: Add offset ?

CREDIT: Trans

range_of_line()

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

rewrite(rules)

Apply a set of rules in the form of regular expression matches to the string.

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

Keep in mind that the order of rules is significant.

Returns the rewritten String.

CREDIT: George Moschovitis

shatter( re )

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

similarity(str_in)

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".similarity("Aleksander")  #=> 0.9

The way it works:

1. Converts each string into a "graph like" object, with edges …

        "alexsander" -> [ alexsander, alexsand, alexsan ... lexsand ... san ... an, etc ]
        "aleksander" -> [ aleksander, aleksand ... etc. ]

2. 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 ]

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

snakecase()

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"

splice(idx, sub=nil)

String#slice is essentially the same as store.

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

But it acts like slice! when given a single argument.

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

CREDIT: Trans

squish()

Returns the string, first removing all whitespace on both ends of the string, and then changing remaining consecutive whitespace groups into one space each.

      %{ Multi-line
         string }.squish                   # => "Multi-line string"

      " foo   bar    \n   \t   boo".squish # => "foo bar boo"

squish!()

Performs a destructive squish. See String#squish.

start_with?(prefix)

Does a string start with the given prefix?

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

Note: This definition is better than standard Ruby‘s becuase it handles regular expressions.

CREDIT: Juris Galang

starts_with?(prefix)

Alias for start_with?

tab(n)

Aligns each line n spaces.

CREDIT: Gavin Sinclair

tabto(n)

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

CREDIT: Gavin Sinclair

titlecase()

Title case.

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

CREDIT: Eliazar Parra

to_b()

Interpret common affirmative string meanings as true, otherwise nil or false. Blank space and case are ignored. The following strings that will return true …

      true
      yes
      on
      t
      1
      y
      ==

The following strings will return nil …

      nil
      null

All other strings return false.

Here are some exmamples.

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

to_date()

Parse data from string.

to_datetime()

Convert string to DateTime.

to_re(esc=false)

Turns a string into a regular expression.

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

CREDIT: Trans

to_rx(esc=true)

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

to_t( &yld )

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.

to_time(form = :utc)
unbracket(bra=nil, ket=nil)

Return a new string with the given brackets removed. If only one bracket char is given it will be removed from either side.

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

CREDIT: Trans

unbracket!(bra=nil, ket=nil)

Inplace version of unbracket.

CREDIT: Trans

underscore()

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

Unfold paragrpahs.

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

unindent(size=nil)

Remove excessive indentation. Useful for multi-line strings embeded in already indented code.

      <<-END.unindent
          ohaie
            wurld
      END

Outputs …

      ohaie
        wurld

Instead of …

          ohaie
            wurld

CREDIT: Noah Gibbs, mynyml

unindent!()

Equivalent to String#unindent, but modifies the receiver in place.

CREDIT: mynyml

unquote()

Remove quotes from string.

      "'hi'".unquote    #=> "hi"

CREDIT: Trans

upcase?()

Is the string upcase/uppercase?

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

CREDIT: Phil Tomson

upper_camelcase()
uppercase()

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.

variablize()

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

word_wrap( col_width=80 )

Word wrap a string not exceeding max width.

      "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

word_wrap!( col_width=80 )

As with word_wrap, but modifies the string in place.

CREDIT: Gavin Kistner, Dayne Broderson

words()

Returns an array of characters.

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

[Validate]