=begin pod =TITLE class Str class Str is Cool does Stringy { } Built-in class for strings. Objects of type C are immutable. =head1 Methods =head2 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. =head2 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. =head2 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. =head2 uc multi sub uc(Str:D ) returns Str:D multi method uc(Str:D:) returns Str:D Returns an uppercase version of the string. =head2 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) =head2 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) =head2 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) =head2 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) =head2 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 C<«> boundary), and forces the rest of the letters through a filter that defaults to L. 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) =head2 lcfirst Perl 6 does not have a C function. =head2 ucfirst Perl 6 does not have a C function. See L. =head2 length Perl 6 does not have a C function. See L or L. =head2 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. =head2 encode multi method encode(Str:D: $encoding = $?ENC, $nf = $?NF) returns Buf Returns a L which represents the original string in the given encoding and normal form. The actual return type is as specific as possible, so C<$str.encode('UTF-8')> returns a C object, C<$str.encode('ISO-8859-1')> a C. =head2 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 C<$needle> in the string starting from C<$startpos>. It returns the offset into the string where C<$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 =head2 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 C<$needle> in C<$haystack> not after C<$startpos>. Returns an undefined value if C<$needle> wasn't found. Examples: say rindex "Camelia is a butterfly", "a"; # 11 say rindex "Camelia is a butterfly", "a", 10; # 6 =head2 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 C<$delimiter> is a string, it is searched for literally and not treated as a regex. If the named parameter C<:all> is passed, the matches from C<$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 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 =head2 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 C<$matcher> in C<$input> and returns a list of all matches (as C by default, or as L if C<$match> is True), limited to at most C<$limit> matches. If no matcher is supplied, a list of characters in the string (ie C<$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 =head2 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 C<$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 =head2 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 C<$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 =head2 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 =head2 sprintf multi sub sprintf ( Str:D $format, *@args) returns Str:D This function is mostly identical to the C library sprintf function. The C<$format> is scanned for C<%> characters. Any C<%> introduces a format token. Format tokens have the following grammar: grammar Str::SprintfFormat { regex format_token { '%': ? ? ? } token index { \d+ '$' } token precision { ? ? } 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 C<%>) is used, it indicates how the next argument passed is to be formatted into the string. The directives are: =begin table % 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 =end table Compatibility: =begin table 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 =end table Perl 5 (non-)compatibility: =begin table n produces a runtime exception p produces a runtime exception =end table Modifiers change the meaning of format directives, but are largely no-ops (the semantics are still being determined). =begin table 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) =end table Examples: sprintf "%ld a big number, %lld a bigger number\n", 4294967295, 4294967296; =head2 subst multi method subst(Str:D: $matcher, $replacement, *%opts) Returns the invocant string where C<$matcher> is replaced by C<$replacement> (or the original string, if no match was found). There is an in-place syntactic variant of C spelled C. C<$matcher> an be a L, or a literal C. Non-Str matcher arguments of type L are coereced to to C 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 =begin table 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 =end table Note that only in the C form C<:ii> implies C<:i> and C<:ss> implies C<:s>. In the method form, the C<:s> and C<:i> modifiers must be added to the regex, not the C method call. =head2 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 C<$from> (where the first character has index 0) and with length C<$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 =head2 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. =head2 pred method pred(Str:D:) returns Str:D Returns the string decremented by one. String decrementing is "magical" just like string increment (see L). It fails on underflow 'b0'.pred # a9 'a0'.pred # Failure 'img002.png'.pred # img001.png =head2 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 =head2 ords multi method ords(Str:D:) returns Positional Returns a list of codepoint numbers, one for each character in the string. =head2 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 C<.=trim> my $line = ' hello world '; say '<' ~ $line.trim ~ '>'; # say '<' ~ trim($line) ~ '>'; # $line.trim; say '<' ~ $line ~ '>'; # < hello world > $line.=trim; say '<' ~ $line ~ '>'; # See also L and L =head2 trim-trailing Remove the white-space charecters from the end of a string. See also L. =head2 trim-leading Remove the white-space charecters from the beginning of a string. See also L. =end pod