Manual

- Overview
- Tutorials
- FAQs
- History / Changes
- License

Reference

- Language
- Functions
- Operators
- Special Variables
- Pragmas
- Utilities
- Internals
- Platform Specific

Modules

- A • B • C • D • E
- F • G • H • I • L
- M • N • O • P • S
- T • U • X

News / Blogs

- Perl Buzz
- Perl Iron Man
- Perlsphere
- Planet Perl
- TPF news
- Use Perl

See also

- CPAN
- Perl.org
- Perl.com
- Perl 5 Wiki
- Perl Jobs
- Perl Mongers
- Perl Monks

Contact

- Site designed and maintained by Jon Allen (JJ)
- http://perl.jonallen.info

- View the project page and FAQs

# substr

Perl 5 version 10.1 documentation
Go to top

# substr

Perl functions A-Z | Perl functions by category | The 'perlfunc' manpage

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

          my $s = "The black cat climbed the green tree";    my $color  = substr $s, 4, 5;	# black    my $middle = substr $s, 4, -11;	# black cat climbed the    my $end    = substr $s, 14;		# climbed the green tree    my $tail   = substr $s, -4;		# tree    my $z      = substr $s, -4, 2;	# tr

  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().

          my $s = "The black cat climbed the green tree";    my $z = substr $s, 14, 7, "jumped from";	# climbed    # $s is now "The black cat jumped from the green tree"

  Note that the lvalue returned by the 3-arg version of substr() acts as a 'magic bullet'; each time it is assigned to, it remembers which part of the original string is being modified; for example:

          $x = '1234';    for (substr($x,1,2)) {        $_ = 'a';   print $x,"\n";	# prints 1a4        $_ = 'xyz'; print $x,"\n";	# prints 1xyz4        $x = '56789';        $_ = 'pq';  print $x,"\n";	# prints 5pq9    }

  Prior to Perl version 5.9.1, the result of using an lvalue multiple times was unspecified.

Recently read

Tools

- Preferences