Combined from primary sources listed below.
See primary docmentation in context for routine substr.
multi substr(Str:D $s, $from, $chars? --> Str:D)
multi substr(Str:D $s, Range $from-to --> Str:D)
multi method substr(Str:D $s: $from, $chars? --> Str:D)
multi method substr(Str:D $s: Range $from-to --> Str:D)
Returns a substring of the original string, between the indices specified by $from-to's endpoints (coerced to Int) or from index $from and of length $chars.
Both $from and $chars can be specified as Callable, which will be invoked with the length of the original string and the returned value will be used as the value for the argument. If $from or $chars are not Callable, they'll be coerced to Int.
If $chars is omitted or is larger than the available characters, the string from $from until the end of the string is returned. If $from-to's starting index or $from is less than zero, X::OutOfRange exception is thrown. The $from-to's ending index is permitted to extend past the end of string, in which case it will be equivalent to the index of the last character.
say substr("Long string", 3..6); # OUTPUT: «g st»
say substr("Long string", 6, 3); # OUTPUT: «tri»
say substr("Long string", 6); # OUTPUT: «tring»
say substr("Long string", 6, *-1); # OUTPUT: «trin»
say substr("Long string", *-3, *-1); # OUTPUT: «in»
See primary docmentation in context for method substr.
method substr-rw($from, $length = *)
A version of substr that returns a Proxy functioning as a writable reference to a part of a string variable. Its first argument, $from specifies the index in the string from which a substitution should occur, and its last argument, $length specifies how many characters are to be replaced. If not specified, $length defaults to the length of the string.
For example, in its method form, if one wants to take the string "abc" and replace the second character (at index 1) with the letter "z", then one does this:
my $string = "abc";
$string.substr-rw(1, 1) = "z";
$string.say; # OUTPUT: «azc»
Note that new characters can be inserted as well:
my $string = 'azc';
$string.substr-rw(2, 0) = "-Zorro-"; # insert new characters BEFORE the character at index 2
$string.say; # OUTPUT: «az-Zorro-c»
substr-rw also has a function form, so the above examples can also be written like so:
my $string = "abc";
substr-rw($string, 1, 1) = "z";
$string.say; # OUTPUT: «azc»
substr-rw($string, 2, 0) = "-Zorro-";
$string.say; # OUTPUT: «az-Zorro-c»
It is also possible to alias the writable reference returned by substr-rw for repeated operations:
my $string = "A character in the 'Flintstones' is: barney";
$string ~~ /(barney)/;
my $ref := substr-rw($string, $0.from, $0.to-$0.from);
$string.say;
# OUTPUT: «A character in the 'Flintstones' is: barney»
$ref = "fred";
$string.say;
# OUTPUT: «A character in the 'Flintstones' is: fred»
$ref = "wilma";
$string.say;
# OUTPUT: «A character in the 'Flintstones' is: wilma»
See primary docmentation in context for method substr.
multi method substr-eq(Str:D: Str(Cool) $test-string, Int(Cool) $from, :i(:$ignorecase), :m(:$ignoremark) --> Bool)
multi method substr-eq(Cool:D: Str(Cool) $test-string, Int(Cool) $from, :i(:$ignorecase), :m(:$ignoremark) --> Bool)
Returns True if the $test-string exactly matches the String object, starting from the given initial index $from. For example, beginning with the string "foobar", the substring "bar" will match from index 3:
my $string = "foobar";
say $string.substr-eq("bar", 3); # OUTPUT: «True»
However, the substring "barz" starting from index 3 won't match even though the first three letters of the substring do match:
my $string = "foobar";
say $string.substr-eq("barz", 3); # OUTPUT: «False»
Naturally, to match the entire string, one merely matches from index 0:
my $string = "foobar";
say $string.substr-eq("foobar", 0); # OUTPUT: «True»
Since Rakudo version 2020.02, if the optional named parameter :ignorecase, or :i, is specified, the comparison of the invocant and $test-string ignores the distinction between uppercase, lowercase and titlecase letters.
say "foobar".substr-eq("Bar", 3); # OUTPUT: «False»
say "foobar".substr-eq("Bar", 3, :ignorecase); # OUTPUT: «True»
Since Rakudo version 2020.02, if the optional named parameter :ignoremark, or :m, is specified, the comparison of the invocant and $test-string only considers base characters, and ignores additional marks such as combining accents.
say "cliché".substr-eq("che", 3); # OUTPUT: «False»
say "cliché".substr-eq("che", 3, :ignoremark); # OUTPUT: «True»
Since this method is inherited from the Cool type, it also works on integers. Thus the integer 42 will match the value 342 starting from index 1:
my $integer = 342;
say $integer.substr-eq(42, 1); # OUTPUT: «True»
As expected, one can match the entire value by starting at index 0:
my $integer = 342;
say $integer.substr-eq(342, 0); # OUTPUT: «True»
Also using a different value or an incorrect starting index won't match:
my $integer = 342;
say $integer.substr-eq(42, 3); # OUTPUT: «False»
say $integer.substr-eq(7342, 0); # OUTPUT: «False»
See primary docmentation in context for routine substr.
sub substr(Str(Cool) $str, |c)
method substr(|c)
Coerces the invocant (or in the sub form, the first argument) to Str, and calls Str.substr with the arguments.
See primary docmentation in context for routine substr.
multi method substr-rw(|) is rw
multi substr-rw(|) is rw
Coerces the invocant (or in the sub form, the first argument) to Str, and calls Str.substr-rw with the arguments.
See primary docmentation in context for method substr.
method substr-rw(Allomorph:D \SELF: $start = 0, $want = Whatever)
Calls Str.substr-rw on the invocant's Str value.
See primary docmentation in context for method substr.