class Str
src
class Str is Cool does Stringy { }
Built-in class for strings. Objects of type Str are immutable.
Methods
chop
multi sub chop(Str:D) returns Str:D
multi method chop(Str:D:) returns Str:D
Returns the string with one character removed from the end.
chomp
multi sub chomp(Str:D ) returns Str:D
multi method chomp(Str:D:) returns Str:D
Returns the string with a logical newline removed from the end.
lc
multi sub lc(Str:D ) returns Str:D
multi method lc(Str:D:) returns Str:D
Returns a lower-case version of the string.
uc
multi sub uc(Str:D ) returns Str:D
multi method uc(Str:D:) returns Str:D
Returns an uppercase version of the string.
fc
multi sub fc(Str:D ) returns Str:D
multi method fc(Str:D:) returns Str:D
Does a Unicode "fold case" operation suitable for doing caseless
string comparisons. (In general, the returned string is unlikely to
be useful for any purpose other than comparison.)
(Not implemented in Rakudo and Niecza)
tc
multi sub tc(Str:D ) returns Str:D
multi method tc(Str:D:) returns Str:D
Does a Unicode "titlecase" operation, that is changes the first character in
the string to title case, or to upper case if the character has no title case
mapping
(Not implemented in Rakudo and Niecza)
tclc
multi sub tclc(Str:D ) returns Str:D
multi method tclc(Str:D:) returns Str:D
Turns the first character to title case, and all other characters to lower
case
(not implemented in Niecza)
tcuc
multi sub tcuc(Str:D ) returns Str:D
multi method tcuc(Str:D:) returns Str:D
Turns the first character to title case, and all other characters to upper
case
(Not implemented in Rakudo and Niecza)
wordcase
multi sub wordcase(Str:D :&filter = &lc, :%exceptions = set()) returns Str
multi method wordcase(Str:D: :&filter = &lc, :%exceptions = set()) returns Str
Performs a Unicode titlecase operation on the first character of
each word of the string (as defined by a regex « boundary),
and forces the rest of the letters through a filter that defaults
to L<lc>. After this operation, if any exceptions are supplied and
if the word is found in the set of exceptions, the first character is also
forced through the filter. Note that the exceptions must be spelled with
an initial titlecase, such as "By" or "And", to produce "by" or "and".
(Not implemented in Rakudo and Niecza)
lcfirst
Perl 6 does not have a lcfirst function.
ucfirst
Perl 6 does not have a ucfirst function. See L<tc>.
length
Perl 6 does not have a length function. See L<chars> or L<elems>.
chars
multi sub chars(Str:D ) returns Int:D
multi method chars(Str:D:) returns Int:D
Returns the number of characters in the string in the current
(lexically scoped) idea of what a normal character is, usually graphemes.
encode
multi method encode(Str:D: $encoding = $?ENC, $nf = $?NF) returns Buf
Returns a L<Buf> which represents the original string in the given encoding
and normal form. The actual return type is as specific as possible, so
$str.encode('UTF-8') returns a utf8 object,
$str.encode('ISO-8859-1') a buf8 .
index
multi sub index(Str:D, Str:D $needle, Int $startpos = 0) returns StrPos
multi method index(Str:D: Str:D $needle, Int $startpos = 0) returns StrPos
Searches for $needle in the string starting from $startpos . It returns
the offset into the string where $needle was found, and an undefined value
if it was not found.
Examples:
say index "Camelia is a butterfly", "a"; # 1
say index "Camelia is a butterfly", "a", 2; #6
say index "Camelia is a butterfly", "er"; # 17
say index "Camelia is a butterfly", "Camel"; # 0
say index "Camelia is a butterfly", "Onion"; # Int()
say index("Camelia is a butterfly", "Onion").defined ?? 'OK' !! 'NOT'; # NOT
rindex
multi sub rindex(Str:D $haystack, Str:D $needle, Int $startpos = $haystack.chars) returns StrPos
multi method rindex(Str:D $haystack: Str:D $needle, Int $startpos = $haystack.chars) returns StrPos
Returns the last position of $needle in $haystack not after $startpos .
Returns an undefined value if $needle wasn't found.
Examples:
say rindex "Camelia is a butterfly", "a"; # 11
say rindex "Camelia is a butterfly", "a", 10; # 6
split
multi sub split( Str:D $delimiter, Str:D $input, $limit = Inf, :$all) returns Positional
multi sub split(Regex:D $delimiter, Str:D $input, $limit = Inf, :$all) returns Positional
multi method split(Str:D $input: Str:D $delimiter, $limit = Inf, :$all) returns Positional
multi method split(Str:D $input: Regex:D $delimiter, $limit = Inf, :$all) returns Positional
Splits a string up into pieces based on delimiters found in the string.
If $delimiter is a string, it is searched for literally and not treated
as a regex.
If the named parameter :all is passed, the matches from $delimiter
are included in the result list.
Note that unlike in Perl 5, empty chunks are not removed from the result list.
If you want that behavior, consider using L<comb> instead.
Examples:
say split(';', "a;b;c").perl; # ("a", "b", "c").list
say split(';', "a;b;c", :all).perl; # ("a", ";", "b", ";", "c").list
say split(';', "a;b;c", 2).perl; # ("a", "b;c").list
say split(';', "a;b;c", 2, :all).perl; #("a", ";", "b;c").list
say split(';', "a;b;c,d").perl; # ("a", "b", "c,d").list
say split(/\;/, "a;b;c,d").perl; # ("a", "b", "c,d").list
say split(/<[;,]>/, "a;b;c,d").perl; # ("a", "b", "c", "d").list
comb
multi sub comb(Str:D $matcher, Str:D $input, $limit = Inf, Bool :$match)
multi sub comb(Regex:D $matcher, Str:D $input, $limit = Inf, Bool :$match)
multi method comb(Str:D $input:)
multi method comb(Str:D $input: Str:D $matcher, $limit = Inf, Bool :$match)
multi method comb(Str:D $input: Regex:D $matcher, $limit = Inf, Bool :$match)
Searches for $matcher in $input and returns a list of all matches
(as Str by default, or as L<Match> if $match is True), limited to at most
$limit matches.
If no matcher is supplied, a list of characters in the string
(ie $delimiter = rx/./ ) is returned.
Examples:
comb(/\w/, "a;b;c").perl; # ("a", "b", "c").list
comb(/\N/, "a;b;c").perl; # ("a", ";", "b", ";", "c").list
comb(/\w/, "a;b;c", 2).perl; # ("a", "b").list
comb(/\w\;\w/, "a;b;c", 2).perl; # ("a;b",).list
lines
multi sub lines(Str:D $input, $limit = Inf) returns Positional
multi method lines(Str:D $input: $limit = Inf) returns Positional
Returns a list of lines (without trailing newline characters), i.e. the
same as a call to $input.comb( / ^^ \N* /, $limit ) would.
Examples:
lines("a\nb").perl; # ("a", "b").list
lines("a\nb").elems; # 2
"a\nb".lines.elems; # 2
"a\n".lines.elems; # 1
words
multi sub words(Str:D $input, $limit = Inf) returns Positional
multi method words(Str:D $input: $limit = Inf) returns Positional
Returns a list of non-whitespace bits, i.e. the same as a call to
$input.comb( / \S+ /, $limit ) would.
Examples:
"a\nb\n".words.perl; # ("a", "b").list
"hello world".words.perl; # ("hello", "world").list
"foo:bar".words.perl; # ("foo:bar",).list
"foo:bar\tbaz".words.perl; # ("foo:bar", "baz").list
flip
multi sub flip(Str:D ) returns Str:D
multi method flip(Str:D:) returns Str:D
Returns the string reversed character by character.
Examples:
"Perl".flip; # lreP
"ABBA".flip; # ABBA
sprintf
multi sub sprintf ( Str:D $format, *@args) returns Str:D
This function is mostly identical to the C library sprintf function.
The $format is scanned for % characters. Any % introduces a
format token. Format tokens have the following grammar:
grammar Str::SprintfFormat {
regex format_token { '%': <index>? <precision>? <modifier>? <directive> }
token index { \d+ '$' }
token precision { <flags>? <vector>? <precision_count> }
token flags { <[ \x20 + 0 \# \- ]>+ }
token precision_count { [ <[1..9]>\d* | '*' ]? [ '.' [ \d* | '*' ] ]? }
token vector { '*'? v }
token modifier { < ll l h V q L > }
token directive { < % c s d u o x e f g X E G b p n i D U O F > }
}
Directives guide the use (if any) of the arguments. When a directive
(other than % ) is used, it indicates how the next argument
passed is to be formatted into the string.
The directives are:
% a literal percent sign
c a character with the given codepoint
s a string
d a signed integer, in decimal
u an unsigned integer, in decimal
o an unsigned integer, in octal
x an unsigned integer, in hexadecimal
e a floating-point number, in scientific notation
f a floating-point number, in fixed decimal notation
g a floating-point number, in %e or %f notation
X like x, but using uppercase letters
E like e, but using an uppercase "E"
G like g, but with an uppercase "E" (if applicable)
b an unsigned integer, in binary
Compatibility:
i a synonym for %d
D a synonym for %ld
U a synonym for %lu
O a synonym for %lo
F a synonym for %f
Perl 5 (non-)compatibility:
n produces a runtime exception
p produces a runtime exception
Modifiers change the meaning of format directives, but are largely
no-ops (the semantics are still being determined).
h interpret integer as native "short" (typically int16)
l interpret integer as native "long" (typically int32 or int64)
ll interpret integer as native "long long" (typically int64)
L interpret integer as native "long long" (typically uint64)
q interpret integer as native "quads" (typically int64 or larger)
Examples:
sprintf "%ld a big number, %lld a bigger number\n", 4294967295, 4294967296;
subst
multi method subst(Str:D: $matcher, $replacement, *%opts)
Returns the invocant string where $matcher is replaced by $replacement
(or the original string, if no match was found).
There is an in-place syntactic variant of subst spelled
s/matcher/replacement .
$matcher an be a L<Regex>, or a literal Str . Non-Str matcher arguments
of type L<Cool> are coereced to to Str for literal matching.
my $some-string = "Some foo";
my $another-string = $some-string.subst(/foo/, "string"); # gives 'Some string'
$some-string.=subst(/foo/, "string); # in-place substitution. $some-string is now 'Some string'
The replacement can be a closure:
my $i = 41;
my $str = "The answer is secret.";
my $real-answer = $str.subst(/secret/, {++$i}); # The answer to everything
Here are other examples of usage:
my $str = "Hey foo foo foo";
$str.subst(/foo/, "bar", :g); # global substitution - returns Hey bar bar bar
$str.subst(/foo/, "no subst", :x(0)); # targeted substitution. Number of times to substitute. Returns back unmodified.
$str.subst(/foo/, "bar", :x(1)); #replace just the first occurrence.
$str.subst(/foo/, "bar", :nth(3)); # replace nth match alone. Replaces the third foo. Returns Hey foo foo bar
The following adverbs are supported
short long meaning
===== ==== =======
:g :global tries to match as often as possible
:nth(Int) only substitute the nth's match
:ss :samespace preserves whitespace on subsitution
:ii :samecase preserives case on substitution
:x(Int) substitute exactly $x matches
Note that only in the s/// form :ii implies :i and :ss implies
:s . In the method form, the :s and :i modifiers must be added to the
regex, not the subst method call.
substr
multi sub substr(Str:D $s, Int:D $from, Int:D $chars = $s.chars - $from) returns Str:D
multi method substr(Str:D $s: Int:D $from, Int:D $chars = $s.chars - $from) returns Str:D
Returns a part of the string, starting from the character with index $from
(where the first character has index 0) and with length $chars .
Examples:
substr("Long string", 6, 3); # tri
substr("Long string", 6); # tring
substr("Long string", 6, *-1); # trin
substr("Long string", *-3, *-1); # in
succ
method succ(Str:D) returns Str:D
Returns the string incremented by one.
String increment is "magical". It searches for the last alphanumeric
sequence that is not preceeded by a dot, and increments it.
'12.34'.succ # 13.34
'img001.png'.succ # img002.png
The actual incrementation step works by mapping the last alphanumeric
character to a character range it belongs to, and chosing the next
character in that range, carrying to the previous letter on overflow.
'aa'.succ # ab
'az'.succ # ba
'109'.succ # 110
'α'.succ # β
'a9'.succ # b0
String increment is Unicode-aware, and generally works for scripts where a
character can be uniquely classified as belonging to one range of characters.
pred
method pred(Str:D:) returns Str:D
Returns the string decremented by one.
String decrementing is "magical" just like string increment (see
L<succ>). It fails on underflow
'b0'.pred # a9
'a0'.pred # Failure
'img002.png'.pred # img001.png
ord
multi sub ord (Str:D) returns Int:D
multi method ord(Str:D:) returns Int:D
Returns the codepoint number of the first character of the string
ords
multi method ords(Str:D:) returns Positional
Returns a list of codepoint numbers, one for each character in the string.
trim
method trim(Str:D:) returns Str
Remove leading and trailing white-spces. It can be use both as a method
on strings and as a function. When used as a method it will return
the trimmed string. In order to do in-place trimming, once needs to write
.=trim
my $line = ' hello world ';
say '<' ~ $line.trim ~ '>'; # <hello world>
say '<' ~ trim($line) ~ '>'; # <hello world>
$line.trim;
say '<' ~ $line ~ '>'; # < hello world >
$line.=trim;
say '<' ~ $line ~ '>'; # <hello world>
See also L<trim-trailing> and L<trim-leading>
trim-trailing
Remove the white-space charecters from the end of a string. See also L<trim>.
trim-leading
Remove the white-space charecters from the beginning of a string. See also L<trim>.
