Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Fetching contributors…

Cannot retrieve contributors at this time

428 lines (279 sloc) 12.93 kB
=begin pod
=TITLE class Str
class Str is Cool does Stringy { }
Built-in class for strings. Objects of type C<Str> 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<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)
=head2 lcfirst
Perl 6 does not have a C<lcfirst> function.
=head2 ucfirst
Perl 6 does not have a C<ucfirst> function. See L<tc>.
=head2 length
Perl 6 does not have a C<length> function. See L<chars> or L<elems>.
=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<Buf> 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<utf8> object,
C<$str.encode('ISO-8859-1')> a C<buf8>.
=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<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
=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<Str> by default, or as L<Match> 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 { '%': <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 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 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<succ>). 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 ~ '>'; # <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>
=head2 trim-trailing
Remove the white-space charecters from the end of a string. See also L<trim>.
=head2 trim-leading
Remove the white-space charecters from the beginning of a string. See also L<trim>.
=end pod
Jump to Line
Something went wrong with that request. Please try again.