Contents
Top- SYNOPSIS
- DESCRIPTION
- CONSTRUCTOR METHODS
- new()
- copy()
- INSPECTOR METHODS
- text()
- length()
- search($pattern)
- split($pattern, $limit)
- MUTATOR METHODS
- push($suffix, ...) / append($suffix, ...)
- pop($suffix)
- unshift($prefix, ...) / prepend($prefix, ...)
- shift($prefix)
- left($pad)
- right($pad)
- center($pad) / centre($pad)
- format($format)
- upper()
- lower()
- capital()
- chop()
- chomp()
- trim()
- collapse()
- truncate($length, $suffix)
- replace($search, $replace)
- remove($search)
- repeat($count)
- AUTHOR
- COPYRIGHT
- SEE ALSO
SYNOPSIS
Top# create String objects via USE directive [% USE String %] [% USE String 'initial text' %] [% USE String text => 'initial text' %] # or from an existing String via new() [% newstring = String.new %] [% newstring = String.new('newstring text') %] [% newstring = String.new( text => 'newstring text' ) %] # or from an existing String via copy() [% newstring = String.copy %] # append text to string [% String.append('text to append') %] # format left, right or center/centre padded [% String.left(20) %] [% String.right(20) %] [% String.center(20) %] # American spelling [% String.centre(20) %] # European spelling # and various other methods...
DESCRIPTION
Top
                      This module implements a String class for doing stringy
                      things to text in an object-oriented way.
                    
                      You can create a String object via the USE
                      directive, adding any initial text value as an argument or as the named
                      parameter text.
                    
[% USE String %] [% USE String 'initial text' %] [% USE String text='initial text' %]
                      The object created will be referenced as String by default,
                      but you can provide a different variable name for the object to be
                      assigned to:
                    
[% USE greeting = String 'Hello World' %]
                    
                      Once you've got a String object, you can use it as a
                      prototype to create other String objects with the
                      new() method.
                    
[% USE String %] [% greeting = String.new('Hello World') %]
                      The new() method also accepts an initial text string as an
                      argument or the named parameter text.
                    
[% greeting = String.new( text => 'Hello World' ) %]
                    
                      You can also call copy() to create a new String
                      as a copy of the original.
                    
[% greet2 = greeting.copy %]
                    
                      The String object has a text() method to return
                      the content of the string.
                    
[% greeting.text %]
                    
                      However, it is sufficient to simply print the string and let the
                      overloaded stringification operator call the text() method
                      automatically for you.
                    
[% greeting %]
                    
                      Thus, you can treat String objects pretty much like any
                      regular piece of text, interpolating it into other strings, for example:
                    
[% msg = "It printed '$greeting' and then dumped core\n" %]
                    You also have the benefit of numerous other methods for manipulating the string.
[% msg.append("PS  Don't eat the yellow snow") %]
                    Note that all methods operate on and mutate the contents of the string itself. If you want to operate on a copy of the string then simply take a copy first:
[% msg.copy.append("PS  Don't eat the yellow snow") %]
                    
                      These methods return a reference to the String object
                      itself. This allows you to chain multiple methods together.
                    
[% msg.copy.append('foo').right(72) %]
                    
                      It also means that in the above examples, the String is
                      returned which causes the text() method to be called, which
                      results in the new value of the string being printed. To suppress
                      printing of the string, you can use the CALL directive.
                    
[% foo = String.new('foo') %] [% foo.append('bar') %] # prints "foobar" [% CALL foo.append('bar') %] # nothing
CONSTRUCTOR METHODS
Top
                      These methods are used to create new String objects.
                    
new()
Top
                          Creates a new string using an initial value passed as a positional
                          argument or the named parameter text.
                        
[% USE String %] [% msg = String.new('Hello World') %] [% msg = String.new( text => 'Hello World' ) %]
copy()
Top
                          Creates a new String object which contains a copy of the
                          original string.
                        
[% msg2 = msg.copy %]
                  INSPECTOR METHODS
TopThese methods are used to examine the string.
text()
TopReturns the internal text value of the string. The stringification operator is overloaded to call this method. Thus the following are equivalent:
[% msg.text %] [% msg %]
length()
TopReturns the length of the string.
[% USE String("foo") %] [% String.length %] # => 3
search($pattern)
Top
                          Searches the string for the regular expression specified in
                          $pattern returning true if found or false otherwise.
                        
[% item = String.new('foo bar baz wiz waz woz') %] [% item.search('wiz') ? 'WIZZY! :-)' : 'not wizzy :-(' %]
split($pattern, $limit)
Top
                          Splits the string based on the delimiter $pattern and
                          optional $limit. Delegates to Perl's internal
                          split() so the parameters are exactly the same.
                        
[% FOREACH item.split %] ... [% END %] [% FOREACH item.split('baz|waz') %] ... [% END %]
MUTATOR METHODS
TopThese methods modify the internal value of the string. For example:
[% USE str=String('foobar') %] [% str.append('.html') %] # str => 'foobar.html'
                      The value of str is now 'foobar.html'. If you
                      don't want to modify the string then simply take a copy first.
                    
[% str.copy.append('.html') %]
                    
                      These methods all return a reference to the String object
                      itself. This has two important benefits. The first is that when used as
                      above, the String object 'str' returned by the
                      append() method will be stringified with a call to its
                      text() method. This will return the newly modified string
                      content. In other words, a directive like:
                    
[% str.append('.html') %]
                    
                      will update the string and also print the new value. If you just want to
                      update the string but not print the new value then use CALL.
                    
[% CALL str.append('.html') %]
                    
                      The other benefit of these methods returning a reference to the
                      String is that you can chain as many different method calls
                      together as you like. For example:
                    
[% String.append('.html').trim.format(href) %]
                    Here are the methods:
push($suffix, ...) / append($suffix, ...)
Top
                          Appends all arguments to the end of the string. The append()
                          method is provided as an alias for push().
                        
[% msg.push('foo', 'bar') %] [% msg.append('foo', 'bar') %]
pop($suffix)
TopRemoves the suffix passed as an argument from the end of the String.
[% USE String 'foo bar' %] [% String.pop(' bar') %] # => 'foo'
unshift($prefix, ...) / prepend($prefix, ...)
Top
                          Prepends all arguments to the beginning of the string. The
                          prepend() method is provided as an alias for
                          unshift().
                        
[% msg.unshift('foo ', 'bar ') %] [% msg.prepend('foo ', 'bar ') %]
shift($prefix)
TopRemoves the prefix passed as an argument from the start of the String.
[% USE String 'foo bar' %] [% String.shift('foo ') %] # => 'bar'
left($pad)
Top
                          If the length of the string is less than $pad then the
                          string is left formatted and padded with spaces to $pad
                          length.
                        
[% msg.left(20) %]
                  center($pad) / centre($pad)
Topformat($format)
Top
                          Apply a format in the style of sprintf() to the string.
                        
[% USE String("world") %] [% String.format("Hello %s\n") %] # => "Hello World\n"
upper()
TopConverts the string to upper case.
[% USE String("foo") %] [% String.upper %] # => 'FOO'
lower()
TopConverts the string to lower case
[% USE String("FOO") %] [% String.lower %] # => 'foo'
capital()
TopConverts the first character of the string to upper case.
[% USE String("foo") %] [% String.capital %] # => 'Foo'
The remainder of the string is left untouched. To force the string to be all lower case with only the first letter capitalised, you can do something like this:
[% USE String("FOO") %] [% String.lower.capital %] # => 'Foo'
chop()
TopRemoves the last character from the string.
[% USE String("foop") %] [% String.chop %] # => 'foo'
chomp()
TopRemoves the trailing newline from the string.
[% USE String("foo\n") %] [% String.chomp %] # => 'foo'
trim()
TopRemoves all leading and trailing whitespace from the string
[% USE String(" foo \n\n ") %] [% String.trim %] # => 'foo'
collapse()
TopRemoves all leading and trailing whitespace and collapses any sequences of multiple whitespace to a single space.
[% USE String(" \n\r \t foo \n \n bar \n") %] [% String.collapse %] # => "foo bar"
truncate($length, $suffix)
Top
                          Truncates the string to $length characters.
                        
[% USE String('long string') %] [% String.truncate(4) %] # => 'long'
                          If $suffix is specified then it will be appended to the
                          truncated string. In this case, the string will be further shortened by
                          the length of the suffix to ensure that the newly constructed string
                          complete with suffix is exactly $length characters long.
                        
[% USE msg = String('Hello World') %] [% msg.truncate(8, '...') %] # => 'Hello...'
replace($search, $replace)
Top
                          Replaces all occurences of $search in the string with
                          $replace.
                        
[% USE String('foo bar foo baz') %] [% String.replace('foo', 'wiz') %] # => 'wiz bar wiz baz'
remove($search)
Top
                          Remove all occurences of $search in the string.
                        
[% USE String('foo bar foo baz') %] [% String.remove('foo ') %] # => 'bar baz'
repeat($count)
Top
                          Repeats the string $count times.
                        
[% USE String('foo ') %] [% String.repeat(3) %] # => 'foo foo foo '
AUTHOR
TopAndy Wardley <abw@wardley.org> http://wardley.org/
COPYRIGHT
TopCopyright (C) 1996-2007 Andy Wardley. All Rights Reserved.
This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.