Perl substr() function

In the Perl programming language has a built-in function substr(). You can use this function when working with strings. Using this function, you can obtain part of a string, or to replace part of a string with another string.

Here is an example of receiving part of a string:

▶ Run
#!/usr/bin/perl

my $str = 'Hello, world!';

print "'" . substr($str, 7, 5) . "'";

This program displays the text 'world'. Call function substr($str, 7, 5) says you need to get from line $str five characters, starting from the seventh position. In this use the value $str does not change.

When using substr() with four arguments changes the value of a variable. Here is an example using substr() to replace:

▶ Run
#!/usr/bin/perl

my $str = 'Hello, world!';

print "'" . substr($str, 7, 5, 'you') . "'\n";
print $str;

The output of the program:

'world'
Hello, you!

The return value when you call substr($str, 7, 5, 'you') is exactly the same as when you call substr($str, 7, 5), but the call with four arguments and even changed the value of the variable. The word world was replaced by you. Please note that the replacement was correct despite the fact that in the original word and the new word a different number letters.

Arguments

my $str1 = substr($str, $offset);
my $str2 = substr($str, $offset, $length);
my $str3 = substr($str, $offset, $replacement);

Function substr() , you must specify two, three, or four arguments.

In the case if you try to use the function substr() with no arguments, or with one argument, it will error:

Not enough arguments for substr at script.pl line 3, near "substr()"
Execution of script.pl aborted due to compilation errors.

When using two arguments substr($str, $offset) the function returns all characters from the string $str starting with the character at position $offset to the end of the row.

When using three arguments substr($str, $offset, $length) the function returns $length characters from a string $str starting with the character at position $offset.

When using substr() with two or three arguments, the original string value does not change.

If you use four arguments substr($str, $offset, $replacement)function returns the same as in the case of three arguments, but additionally replace in the original string, the value obtained by $replacement.

Return value

Function substr() may return either undef, or a string.

undef is returned if you try to get element from string index which is greater than the length of the string. Here is a sample program that returns undef:

▶ Run
#!/usr/bin/perl

use Data::Dumper;

my $str = 'Hello, world!';
my $str1 = substr($str, 10000);

warn Dumper $str1;

In the event if in the program code would be use warnings;, the program would still additionally put on the warning screen:

substr outside of string at script.pl line 8.

Negative values $offset

Function substr() allows you to specify negative values for the second argument. Example program:

▶ Run
#!/usr/bin/perl

my $str = 'Hello, world!';
print substr($str, -3);

The screen will display the text ld! is the last three characters from string Hello, world!.

A negative second argument suggests that the position is counted from the end of the row.

Entry substr($str, -3) is quite similar substr($str, -3, 3).

Negative values $length

The value of the third argument can be negative. Here is example of:

▶ Run
#!/usr/bin/perl

use feature qw(say);

my $str = 'Hello, world!';

say substr($str, 7, -1); # world
say substr($str, 7, -2); # worl
say substr($str, 7, -3); # wor

Official documentation

Here is the output of the command perldoc -f substr:

    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 zero. If OFFSET is negative, starts that far back
            from the end of the string. If LENGTH is omitted, returns
            everything through 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 raises an exception. 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';        # raises an exception

            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 three-argument 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:

                my $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
                }

            With negative offsets, it remembers its position from the end of
            the string when the target string is modified:

                my $x = '1234';
                for (substr($x, -3, 2)) {
                    $_ = 'a';   print $x,"\n";    # prints 1a4, as above
                    $x = 'abcdefg';
                    print $_,"\n";                # prints f
                }

            Prior to Perl version 5.10, the result of using an lvalue
            multiple times was unspecified. Prior to 5.16, the result with
            negative offsets was unspecified.

Related topics

Other articles