#substr EXPR,OFFSET,LENGTH,REPLACEMENT

#substr EXPR,OFFSET,LENGTH

#substr EXPR,OFFSET

Extracts a substring out of EXPR and returns it. First character is at offset 0, or whatever you've set $[ to (but don't do that). If OFFSET is negative (or more precisely, less than $[), starts that far from the end of the string. If LENGTH is omitted, returns everything to the end of the string. If LENGTH is negative, leaves that many characters off the end of the string.

You can use the substr() function as an lvalue, in which case EXPR must itself be an lvalue. If you assign something shorter than LENGTH, the string will shrink, and if you assign something longer than LENGTH, the string will grow to accommodate it. To keep the string the same length you may need to pad or chop your value using sprintf.

If OFFSET and LENGTH specify a substring that is partly outside the string, only the part within the string is returned. If the substring is beyond either end of the string, substr() returns the undefined value and produces a warning. When used as an lvalue, specifying a substring that is entirely outside the string is a fatal error. Here's an example showing the behavior for boundary cases:

my $name = 'fred';
substr($name, 4) = 'dy';		# $name is now 'freddy'
my $null = substr $name, 6, 2;	# returns '' (no warning)
my $oops = substr $name, 7;		# returns undef, with warning
substr($name, 7) = 'gap';		# fatal error

An alternative to using substr() as an lvalue is to specify the replacement string as the 4th argument. This allows you to replace parts of the EXPR and return what was there before in one operation, just as you can with splice().

If the lvalue returned by substr is used after the EXPR is changed in any way, the behaviour may not be as expected and is subject to change. This caveat includes code such as print(substr($foo,$a,$b)=$bar) or (substr($foo,$a,$b)=$bar)=$fud (where $foo is changed via the substring assignment, and then the substr is used again), or where a substr() is aliased via a foreach loop or passed as a parameter or a reference to it is taken and then the alias, parameter, or deref'd reference either is used after the original EXPR has been changed or is assigned to and then used a second time.

Perldoc Browser is maintained by Dan Book (DBOOK). Please contact him via the GitHub issue tracker or email regarding any issues with the site itself, search, or rendering of documentation.

The Perl documentation is maintained by the Perl 5 Porters in the development of Perl. Please contact them via the Perl issue tracker, the mailing list, or IRC to report any issues with the contents or format of the documentation.