substr()

Description

This function returns a substring from a source string. The starting position within the source string and the maximum length of the substring may be specified.

Syntax


string substr( string $str, int $start [, int $length] )

Parameters

$str
Source string from which substring is to be extracted. The passed string must be at least one character in length.
$start
Position to begin the substring. If positive, the starting position will be calculated from the beginnig of the string (position 0). If negative, the starting position will be calculated from the last character in the string (position strlen()-1).
$length
Length of substring.

Return Value

string
The substr() function will return one of the following values:

  • string if the substring is successfully extracted
  • null string if there is an error

Examples

1. Starting from the Left

Each of these examples pass a zero or positive $start value so the substring will begin at a position calculated from the start of the string. Different $length values >= 0 are tried.

<?php
$str = "To whom it may concern";
echo 'Length of string: ' . strlen($str) . "\n";;

echo 'substr( $str, 0 )    : ' . substr( $str, 0 )     . "\n";
echo 'substr( $str, 3 )    : ' . substr( $str, 3 )     . "\n";
echo 'substr( $str, 11 )   : ' . substr( $str, 11 )    . "\n";
echo 'substr( $str, 3, 11 ): ' . substr( $str, 3, 11 ) . "\n";
echo 'substr( $str, 3, 20 ): ' . substr( $str, 3, 20 ) . "\n";
echo 'substr( $str, 3, 0 ) : ' . substr( $str, 3, 0 )  . "\n";
echo 'substr( $str, 25 )   : ' . substr( $str, 25 )    . "\n";
?>

The output below shows the results of extracting substrings based on various starting locations calculated from the beginning of the string. Several $length values are also examined.

  • Starting at position 0, the whole string is returned, while starting at position 3 skips the first word and starting at position 11 skips three words. Since no $length is provided, each of these examples return substrings to the end of the source string.
  • The output on line 5 shows a positive $length argument of 11 restricts the substring to 11 characters. On line 6, a $length value of 20 returns the rest of the source string. Line 7 shows that passing a $length of 0 results in a null substring return value.
  • On line 8 we see the effect of starting beyond the end of the string. Again, the returned substring is null.
Length of string: 22
substr( $str, 0 )    : To whom it may concern
substr( $str, 3 )    : whom it may concern
substr( $str, 11 )   : may concern
substr( $str, 3, 11 ): whom it may
substr( $str, 3, 20 ): whom it may concern
substr( $str, 3, 0 ) : 
substr( $str, 25 )   : 

2. Starting from the Right

In this example, negative $start arguments cause substrings to start at positions counted from the end of the string. Several positive $length arguments are passed.

<?php
$str = "To whom it may concern";
echo 'Length of string: ' . strlen($str) . "\n";;

echo 'substr( $str, -11 )    : ' . substr( $str, -11 )     . "\n";
echo 'substr( $str, -22 )    : ' . substr( $str, -22 )     . "\n";
echo 'substr( $str, -11, 3)  : ' . substr( $str, -11, 3 )  . "\n";
echo 'substr( $str, -11, 11) : ' . substr( $str, -11, 11 ) . "\n";
?>

The output below shows that negative $start arguments cause the starting position of the extracted substrings to be calculated from the end of the string. The $start value of -11 starts the substring at “may” since it is 11 characters from the last character of the source string. Similarly, a $start value of -22 starts at the beginning of the string.

By omitting the $length parameter, the substrings run to the end of the source string. Positive $length values determine the maximum length of the returned substring as in the last example.

Length of string: 22
substr( $str, -11 )    : may concern
substr( $str, -22 )    : To whom it may concern
substr( $str, -11, 3)  : may
substr( $str, -11, 11) : may concern

3. The Effect of Negative $length

In this example, the effect of a negative $length is examined. If $length is negative, the source string will be effectively truncated (from the right) by the magnitude of the $length prior to extracting the substring. This “truncation” occurs after the starting position is calculated.

<?php
$str = "To whom it may concern";
echo 'Length of string: ' . strlen($str) . "\n";;

echo 'substr( $str, 3, -8 )    : ' . substr( $str, 3, -8 )    . "\n";
echo 'substr( $str, 11, -8 )   : ' . substr( $str, 11, -8 )   . "\n";
echo 'substr( $str, -19, -12 ) : ' . substr( $str, -19, -12 ) . "\n";
echo 'substr( $str, -11, -11 ) : ' . substr( $str, -11, -11 ) . "\n";
?>

Lines 2-3 of the output below show the effect of negative $length arguments when the $start position is positive. In both cases the source string is trimmed from the right by 8 characters (up to the word “may”) prior to the substring extraction. In Line 4 the source string is trimmed from the right by 12 characters (up to the word “it”), but the source argument of -19 starts the substring at a position 19 characters from the right prior to the $length truncation. Finally, Line 5 shows the effect of $start and $length limiting the substring to 0 characters. In this case an empty string is returned.

Length of string: 22
substr( $str, 3, -8 )    : whom it may
substr( $str, 11, -8 )   : may
substr( $str, -19, -12 ) : whom it
substr( $str, -11, -11 ) : 

See Also

References