.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Template::Plugin::String 3"
.TH Template::Plugin::String 3 2023-07-25 "perl v5.38.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Template::Plugin::String \- Object oriented interface for string manipulation
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 4
\&    # create String objects via USE directive
\&    [% USE String %]
\&    [% USE String \*(Aqinitial text\*(Aq %]
\&    [% USE String text => \*(Aqinitial text\*(Aq %]
\&
\&    # or from an existing String via new()
\&    [% newstring = String.new %]
\&    [% newstring = String.new(\*(Aqnewstring text\*(Aq) %]
\&    [% newstring = String.new( text => \*(Aqnewstring text\*(Aq ) %]
\&
\&    # or from an existing String via copy()
\&    [% newstring = String.copy %]
\&
\&    # append text to string
\&    [% String.append(\*(Aqtext to append\*(Aq) %]
\&
\&    # 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...
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
This module implements a \f(CW\*(C`String\*(C'\fR class for doing stringy things to
text in an object-oriented way.
.PP
You can create a \f(CW\*(C`String\*(C'\fR object via the \f(CW\*(C`USE\*(C'\fR directive, adding any
initial text value as an argument or as the named parameter \f(CW\*(C`text\*(C'\fR.
.PP
.Vb 3
\&    [% USE String %]
\&    [% USE String \*(Aqinitial text\*(Aq %]
\&    [% USE String text=\*(Aqinitial text\*(Aq %]
.Ve
.PP
The object created will be referenced as \f(CW\*(C`String\*(C'\fR by default, but you
can provide a different variable name for the object to be assigned
to:
.PP
.Vb 1
\&    [% USE greeting = String \*(AqHello World\*(Aq %]
.Ve
.PP
Once you've got a \f(CW\*(C`String\*(C'\fR object, you can use it as a prototype to
create other \f(CW\*(C`String\*(C'\fR objects with the \f(CWnew()\fR method.
.PP
.Vb 2
\&    [% USE String %]
\&    [% greeting = String.new(\*(AqHello World\*(Aq) %]
.Ve
.PP
The \f(CWnew()\fR method also accepts an initial text string as an argument
or the named parameter \f(CW\*(C`text\*(C'\fR.
.PP
.Vb 1
\&    [% greeting = String.new( text => \*(AqHello World\*(Aq ) %]
.Ve
.PP
You can also call \f(CWcopy()\fR to create a new \f(CW\*(C`String\*(C'\fR as a copy of the
original.
.PP
.Vb 1
\&    [% greet2 = greeting.copy %]
.Ve
.PP
The \f(CW\*(C`String\*(C'\fR object has a \f(CWtext()\fR method to return the content of the
string.
.PP
.Vb 1
\&    [% greeting.text %]
.Ve
.PP
However, it is sufficient to simply print the string and let the
overloaded stringification operator call the \f(CWtext()\fR method
automatically for you.
.PP
.Vb 1
\&    [% greeting %]
.Ve
.PP
Thus, you can treat \f(CW\*(C`String\*(C'\fR objects pretty much like any regular piece
of text, interpolating it into other strings, for example:
.PP
.Vb 1
\&    [% msg = "It printed \*(Aq$greeting\*(Aq and then dumped core\en" %]
.Ve
.PP
You also have the benefit of numerous other methods for manipulating
the string.
.PP
.Vb 1
\&    [% msg.append("PS  Don\*(Aqt eat the yellow snow") %]
.Ve
.PP
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:
.PP
.Vb 1
\&    [% msg.copy.append("PS  Don\*(Aqt eat the yellow snow") %]
.Ve
.PP
These methods return a reference to the \f(CW\*(C`String\*(C'\fR object itself.  This
allows you to chain multiple methods together.
.PP
.Vb 1
\&    [% msg.copy.append(\*(Aqfoo\*(Aq).right(72) %]
.Ve
.PP
It also means that in the above examples, the \f(CW\*(C`String\*(C'\fR is returned which
causes the \f(CWtext()\fR 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 \f(CW\*(C`CALL\*(C'\fR directive.
.PP
.Vb 1
\&    [% foo = String.new(\*(Aqfoo\*(Aq) %]
\&
\&    [% foo.append(\*(Aqbar\*(Aq) %]         # prints "foobar"
\&
\&    [% CALL foo.append(\*(Aqbar\*(Aq) %]    # nothing
.Ve
.SH "CONSTRUCTOR METHODS"
.IX Header "CONSTRUCTOR METHODS"
These methods are used to create new \f(CW\*(C`String\*(C'\fR objects.
.SS \fBnew()\fP
.IX Subsection "new()"
Creates a new string using an initial value passed as a positional
argument or the named parameter \f(CW\*(C`text\*(C'\fR.
.PP
.Vb 3
\&    [% USE String %]
\&    [% msg = String.new(\*(AqHello World\*(Aq) %]
\&    [% msg = String.new( text => \*(AqHello World\*(Aq ) %]
.Ve
.SS \fBcopy()\fP
.IX Subsection "copy()"
Creates a new \f(CW\*(C`String\*(C'\fR object which contains a copy of the original string.
.PP
.Vb 1
\&    [% msg2 = msg.copy %]
.Ve
.SH "INSPECTOR METHODS"
.IX Header "INSPECTOR METHODS"
These methods are used to examine the string.
.SS \fBtext()\fP
.IX Subsection "text()"
Returns the internal text value of the string.  The stringification
operator is overloaded to call this method.  Thus the following are
equivalent:
.PP
.Vb 2
\&    [% msg.text %]
\&    [% msg %]
.Ve
.SS \fBlength()\fP
.IX Subsection "length()"
Returns the length of the string.
.PP
.Vb 2
\&    [% USE String("foo") %]
\&    [% String.length %]   # => 3
.Ve
.SS search($pattern)
.IX Subsection "search($pattern)"
Searches the string for the regular expression specified in \f(CW$pattern\fR
returning true if found or false otherwise.
.PP
.Vb 2
\&    [% item = String.new(\*(Aqfoo bar baz wiz waz woz\*(Aq) %]
\&    [% item.search(\*(Aqwiz\*(Aq) ? \*(AqWIZZY! :\-)\*(Aq : \*(Aqnot wizzy :\-(\*(Aq %]
.Ve
.ie n .SS "split($pattern, $limit)"
.el .SS "split($pattern, \f(CW$limit\fP)"
.IX Subsection "split($pattern, $limit)"
Splits the string based on the delimiter \f(CW$pattern\fR and optional \f(CW$limit\fR.
Delegates to Perl's internal \f(CWsplit()\fR so the parameters are exactly the same.
.PP
.Vb 3
\&    [% FOREACH item.split %]
\&         ...
\&    [% END %]
\&
\&    [% FOREACH item.split(\*(Aqbaz|waz\*(Aq) %]
\&         ...
\&    [% END %]
.Ve
.SH "MUTATOR METHODS"
.IX Header "MUTATOR METHODS"
These methods modify the internal value of the string.  For example:
.PP
.Vb 2
\&    [% USE str=String(\*(Aqfoobar\*(Aq) %]
\&    [% str.append(\*(Aq.html\*(Aq) %]   # str => \*(Aqfoobar.html\*(Aq
.Ve
.PP
The value of \f(CW\*(C`str\*(C'\fR is now '\f(CW\*(C`foobar.html\*(C'\fR'.  If you don't want
to modify the string then simply take a copy first.
.PP
.Vb 1
\&    [% str.copy.append(\*(Aq.html\*(Aq) %]
.Ve
.PP
These methods all return a reference to the \f(CW\*(C`String\*(C'\fR object itself.  This
has two important benefits.  The first is that when used as above, the
\&\f(CW\*(C`String\*(C'\fR object '\f(CW\*(C`str\*(C'\fR' returned by the \f(CWappend()\fR method will be stringified
with a call to its \f(CWtext()\fR method.  This will return the newly modified
string content.  In other words, a directive like:
.PP
.Vb 1
\&    [% str.append(\*(Aq.html\*(Aq) %]
.Ve
.PP
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 \f(CW\*(C`CALL\*(C'\fR.
.PP
.Vb 1
\&    [% CALL str.append(\*(Aq.html\*(Aq) %]
.Ve
.PP
The other benefit of these methods returning a reference to the \f(CW\*(C`String\*(C'\fR
is that you can chain as many different method calls together as you
like.  For example:
.PP
.Vb 1
\&    [% String.append(\*(Aq.html\*(Aq).trim.format(href) %]
.Ve
.PP
Here are the methods:
.SS "push($suffix, ...) / append($suffix, ...)"
.IX Subsection "push($suffix, ...) / append($suffix, ...)"
Appends all arguments to the end of the string.  The
\&\f(CWappend()\fR method is provided as an alias for \f(CWpush()\fR.
.PP
.Vb 2
\&    [% msg.push(\*(Aqfoo\*(Aq, \*(Aqbar\*(Aq) %]
\&    [% msg.append(\*(Aqfoo\*(Aq, \*(Aqbar\*(Aq) %]
.Ve
.SS pop($suffix)
.IX Subsection "pop($suffix)"
Removes the suffix passed as an argument from the end of the String.
.PP
.Vb 2
\&    [% USE String \*(Aqfoo bar\*(Aq %]
\&    [% String.pop(\*(Aq bar\*(Aq)   %]   # => \*(Aqfoo\*(Aq
.Ve
.SS "unshift($prefix, ...) / prepend($prefix, ...)"
.IX Subsection "unshift($prefix, ...) / prepend($prefix, ...)"
Prepends all arguments to the beginning of the string.  The
\&\f(CWprepend()\fR method is provided as an alias for \f(CWunshift()\fR.
.PP
.Vb 2
\&    [% msg.unshift(\*(Aqfoo \*(Aq, \*(Aqbar \*(Aq) %]
\&    [% msg.prepend(\*(Aqfoo \*(Aq, \*(Aqbar \*(Aq) %]
.Ve
.SS shift($prefix)
.IX Subsection "shift($prefix)"
Removes the prefix passed as an argument from the start of the String.
.PP
.Vb 2
\&    [% USE String \*(Aqfoo bar\*(Aq %]
\&    [% String.shift(\*(Aqfoo \*(Aq) %]   # => \*(Aqbar\*(Aq
.Ve
.SS left($pad)
.IX Subsection "left($pad)"
If the length of the string is less than \f(CW$pad\fR then the string is left
formatted and padded with spaces to \f(CW$pad\fR length.
.PP
.Vb 1
\&    [% msg.left(20) %]
.Ve
.SS right($pad)
.IX Subsection "right($pad)"
As per \fBleft()\fR but right padding the \f(CW\*(C`String\*(C'\fR to a length of \f(CW$pad\fR.
.PP
.Vb 1
\&    [% msg.right(20) %]
.Ve
.SS "center($pad) / centre($pad)"
.IX Subsection "center($pad) / centre($pad)"
As per \fBleft()\fR and \fBright()\fR but formatting the \f(CW\*(C`String\*(C'\fR to be centered within
a space padded string of length \f(CW$pad\fR.  The \f(CWcentre()\fR method is provided as
an alias for \f(CWcenter()\fR.
.PP
.Vb 2
\&    [% msg.center(20) %]    # American spelling
\&    [% msg.centre(20) %]    # European spelling
.Ve
.SS format($format)
.IX Subsection "format($format)"
Apply a format in the style of \f(CWsprintf()\fR to the string.
.PP
.Vb 2
\&    [% USE String("world") %]
\&    [% String.format("Hello %s\en") %]  # => "Hello World\en"
.Ve
.SS \fBupper()\fP
.IX Subsection "upper()"
Converts the string to upper case.
.PP
.Vb 2
\&    [% USE String("foo") %]
\&    [% String.upper %]  # => \*(AqFOO\*(Aq
.Ve
.SS \fBlower()\fP
.IX Subsection "lower()"
Converts the string to lower case
.PP
.Vb 2
\&    [% USE String("FOO") %]
\&    [% String.lower %]  # => \*(Aqfoo\*(Aq
.Ve
.SS \fBcapital()\fP
.IX Subsection "capital()"
Converts the first character of the string to upper case.
.PP
.Vb 2
\&    [% USE String("foo") %]
\&    [% String.capital %]  # => \*(AqFoo\*(Aq
.Ve
.PP
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:
.PP
.Vb 2
\&    [% USE String("FOO") %]
\&    [% String.lower.capital %]  # => \*(AqFoo\*(Aq
.Ve
.SS \fBchop()\fP
.IX Subsection "chop()"
Removes the last character from the string.
.PP
.Vb 2
\&    [% USE String("foop") %]
\&    [% String.chop %]   # => \*(Aqfoo\*(Aq
.Ve
.SS \fBchomp()\fP
.IX Subsection "chomp()"
Removes the trailing newline from the string.
.PP
.Vb 2
\&    [% USE String("foo\en") %]
\&    [% String.chomp %]  # => \*(Aqfoo\*(Aq
.Ve
.SS \fBtrim()\fP
.IX Subsection "trim()"
Removes all leading and trailing whitespace from the string
.PP
.Vb 2
\&    [% USE String("   foo   \en\en ") %]
\&    [% String.trim %]   # => \*(Aqfoo\*(Aq
.Ve
.SS \fBcollapse()\fP
.IX Subsection "collapse()"
Removes all leading and trailing whitespace and collapses any sequences
of multiple whitespace to a single space.
.PP
.Vb 2
\&    [% USE String(" \en\er  \et  foo   \en \en bar  \en") %]
\&    [% String.collapse %]   # => "foo bar"
.Ve
.ie n .SS "truncate($length, $suffix)"
.el .SS "truncate($length, \f(CW$suffix\fP)"
.IX Subsection "truncate($length, $suffix)"
Truncates the string to \f(CW$length\fR characters.
.PP
.Vb 2
\&    [% USE String(\*(Aqlong string\*(Aq) %]
\&    [% String.truncate(4) %]  # => \*(Aqlong\*(Aq
.Ve
.PP
If \f(CW$suffix\fR 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 \f(CW$length\fR characters long.
.PP
.Vb 2
\&    [% USE msg = String(\*(AqHello World\*(Aq) %]
\&    [% msg.truncate(8, \*(Aq...\*(Aq) %]   # => \*(AqHello...\*(Aq
.Ve
.ie n .SS "replace($search, $replace)"
.el .SS "replace($search, \f(CW$replace\fP)"
.IX Subsection "replace($search, $replace)"
Replaces all occurrences of \f(CW$search\fR in the string with \f(CW$replace\fR.
.PP
.Vb 2
\&    [% USE String(\*(Aqfoo bar foo baz\*(Aq) %]
\&    [% String.replace(\*(Aqfoo\*(Aq, \*(Aqwiz\*(Aq)  %]  # => \*(Aqwiz bar wiz baz\*(Aq
.Ve
.SS remove($search)
.IX Subsection "remove($search)"
Remove all occurrences of \f(CW$search\fR in the string.
.PP
.Vb 2
\&    [% USE String(\*(Aqfoo bar foo baz\*(Aq) %]
\&    [% String.remove(\*(Aqfoo \*(Aq)  %]  # => \*(Aqbar baz\*(Aq
.Ve
.SS repeat($count)
.IX Subsection "repeat($count)"
Repeats the string \f(CW$count\fR times.
.PP
.Vb 2
\&    [% USE String(\*(Aqfoo \*(Aq) %]
\&    [% String.repeat(3)  %]  # => \*(Aqfoo foo foo \*(Aq
.Ve
.SH AUTHOR
.IX Header "AUTHOR"
Andy Wardley <abw@wardley.org> <http://wardley.org/>
.SH COPYRIGHT
.IX Header "COPYRIGHT"
Copyright (C) 1996\-2022 Andy Wardley.  All Rights Reserved.
.PP
This module is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Template::Plugin