class Str

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

length

Perl 6 does not have a length function. See chars or 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 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 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 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:

Compatibility:

Perl 5 (non-)compatibility:

Modifiers change the meaning of format directives, but are largely no-ops (the semantics are still being determined).

Examples:

sprintf "%ld a big number, %lld a bigger number\n", 4294967295, 4294967296;

Special case: sprintf("<b>%s</b>\n", "Perl 6") will not work use either of the following:

sprintf Q:b "<b>%s</b>\n",  "Perl 6";
sprintf     "<b>\%s</b>\n", "Perl 6";
sprintf     "<b>%s\</b>\n", "Perl 6";

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 Regex, or a literal Str. Non-Str matcher arguments of type 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

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 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 trim-trailing and trim-leading

trim-trailing

Remove the white-space charecters from the end of a string. See also trim.

trim-leading

Remove the white-space charecters from the beginning of a string. See also trim.

Methods supplied by class Any

Str inherits from class Any, which provides the following methods:

ACCEPTS

multi method ACCEPTS(Any:D: Mu $other)

Returns True if $other === self (ie it checks object identity).

any

Interprets the invocant as a list and creates an any-Junction from it.

all

Interprets the invocant as a list and creates an all-Junction from it.

one

Interprets the invocant as a list and creates an one-Junction from it.

none

Interprets the invocant as a list and creates an none-Junction from it.

Methods supplied by class Mu

Str inherits from class Mu, which provides the following methods:

defined

multi sub    defined(Mu) returns Bool:D
multi method defined()   returns Bool:D

Returns False on the type object, and True otherwise.

Bool

multi sub    Bool(Mu) returns Bool:D
multi method Bool()   returns Bool:D

Returns False on the type object, and True otherwise.

Str

multi method Str()   returns Str

Returns a string representation of the invocant, intended to be machine readable.

gist

multi sub    gist(Mu) returns Str
multi method gist()   returns Str

Returns a string representation of the invocant, optimized for fast recognition by humans.

The default gist method in Mu re-dispatches to the perl method, but many built-in classes override it to something more specific.

perl

multi sub    perl(Mu) returns Str
multi method perl()   returns Str

Returns a Perlish representation of the object (i.e., can usually be reparsed to regenerate the object).

clone

method clone(*%twiddles)

Creates a shallow clone of the invocant. If named arguments are passed to it, their values are used in every place where an attribute name matches the name of a named argument.

new

multi method new(*%attrinit)

Default method for constructing (create + initialize) new objects of a class. This method expects only named arguments which are then used to initialize attributes with accessors of the same name.

Classes may provide their own new method to override this default.

bless

method bless(Mu $candidate, *%attrinit) returns Mu:D

Lower-level object construction method than new.

If you pass a Whatever as a candidate, it creates a new object of the same type as the invocant, and then uses the named arguments to initialize attributes.

If you pass something other than a Whatever object as a candidate, it simply does the attribute initialization on the $candidate.

In both cases, the object with the attributes initialized is returned.

You can use this method when writing custom constructors:

class Point {
    has $.x;
    has $.y;
    multi method new($x, $y) {
        self.bless(:$x, :$y);
    }
}
my $p = Point.new(-1, 1);

(Though each time you write a custom constructor, remember that it makes subclassing harder).

CREATE

method CREATE() returns Mu:D

Allocates a new object of the same type as the invocant, without initializating any attributes.

print

multi method print() returns Bool:D

Prints value to $*OUT after stringification using .Str method without newline at end.

say

multi method say() returns Bool:D

Prints value to $*OUT after stringification using .gist method with newline at end.

ACCEPTS

multi method ACCEPTS(Mu:U: $other)

Performs a type check. Returns True if $other conforms to the invocant (which is always a type object or failure).

This is the method that is triggered on smart-matching against type objects, for example in if $var ~~ Int { ... }.

WHICH

multi method WHICH() returns ObjAt:D

Returns an object of type ObjAt which uniquely identifies the object. Value types override this method which makes sure that two equivalent objects return the same return value from WHICH.