commit bash-20120525 snapshot

doc/bashref.texi

@@ -1781,15 +1781,16 @@ embedded arithmetic expansion, command substitution, or parameter
 expansion.
 
 The basic form of parameter expansion is $@{@var{parameter}@}.
-The value of @var{parameter} is substituted.  The braces are required
-when @var{parameter}
+The value of @var{parameter} is substituted.
+The @var{parameter} is a shell parameter as described above
+(@pxref{Shell Parameters}) or an array reference (@pxref{Arrays}).
+The braces are required when @var{parameter}
 is a positional parameter with more than one digit,
-or when @var{parameter}
-is followed by a character that is not to be
+or when @var{parameter} is followed by a character that is not to be
 interpreted as part of its name.
 
 If the first character of @var{parameter} is an exclamation point (!),
-a level of variable indirection is introduced.
+it introduces a level of variable indirection.
 Bash uses the value of the variable formed from the rest of
 @var{parameter} as the name of the variable; this variable is then
 expanded and that value is used in the rest of the substitution, rather
@@ -1805,7 +1806,7 @@ In each of the cases below, @var{word} is subject to tilde expansion,
 parameter expansion, command substitution, and arithmetic expansion.
 
 When not performing substring expansion, using the form described
-below, Bash tests for a parameter that is unset or null.
+below (e.g., @samp{:-}), Bash tests for a parameter that is unset or null.
 Omitting the colon results in a test only for a parameter that is unset.
 Put another way, if the colon is included,
 the operator tests for both @var{parameter}'s existence and that its value
@@ -1841,33 +1842,147 @@ is null or unset, nothing is substituted, otherwise the expansion of
 
 @item $@{@var{parameter}:@var{offset}@}
 @itemx $@{@var{parameter}:@var{offset}:@var{length}@}
-Expands to up to @var{length} characters of @var{parameter}
+This is referred to as Substring Expansion.
+It expands to up to @var{length} characters of the value of @var{parameter}
 starting at the character specified by @var{offset}.
-If @var{length} is omitted, expands to the substring of
-@var{parameter} starting at the character specified by @var{offset}.
+If @var{parameter} is @samp{@@}, an indexed array subscripted by
+@samp{@@} or @samp{*}, or an associative array name, the results differ as
+described below.
+If @var{length} is omitted, it expands to the substring of the value of
+@var{parameter} starting at the character specified by @var{offset}
+and extending to the end of the value.
 @var{length} and @var{offset} are arithmetic expressions
 (@pxref{Shell Arithmetic}).
-This is referred to as Substring Expansion.
 
 If @var{offset} evaluates to a number less than zero, the value
-is used as an offset from the end of the value of @var{parameter}.
-If @var{length} evaluates to a number less than zero, and @var{parameter}
-is not @samp{@@} and not an indexed or associative array, it is interpreted
-as an offset from the end of the value of @var{parameter} rather than
-a number of characters, and the expansion is the characters between the
-two offsets.
+is used as an offset in characters
+from the end of the value of @var{parameter}.
+If @var{length} evaluates to a number less than zero,
+it is interpreted as an offset in characters
+from the end of the value of @var{parameter} rather than
+a number of characters, and the expansion is the characters between
+@var{offset} and that result.
+Note that a negative offset must be separated from the colon by at least
+one space to avoid being confused with the @samp{:-} expansion.
+
+Here are some examples illustrating substring expansion on parameters and
+subscripted arrays:
+
+@verbatim
+$ string=01234567890abcdefgh
+$ echo ${string:7}
+7890abcdefgh
+$ echo ${string:7:0}
+
+$ echo ${string:7:2}
+78
+$ echo ${string:7:-2}
+7890abcdef
+$ echo ${string: -7}
+bcdefgh
+$ echo ${string: -7:0}
+
+$ echo ${string: -7:2}
+bc
+$ echo ${string: -7:-2}
+bcdef
+$ set -- 01234567890abcdefgh
+$ echo ${1:7}
+7890abcdefgh
+$ echo ${1:7:0}
+
+$ echo ${1:7:2}
+78
+$ echo ${1:7:-2}
+7890abcdef
+$ echo ${1: -7}
+bcdefgh
+$ echo ${1: -7:0}
+
+$ echo ${1: -7:2}
+bc
+$ echo ${1: -7:-2}
+bcdef
+$ array[0]=01234567890abcdefgh
+$ echo ${array[0]:7}
+7890abcdefgh
+$ echo ${array[0]:7:0}
+
+$ echo ${array[0]:7:2}
+78
+$ echo ${array[0]:7:-2}
+7890abcdef
+$ echo ${array[0]: -7}
+bcdefgh
+$ echo ${array[0]: -7:0}
+
+$ echo ${array[0]: -7:2}
+bc
+$ echo ${array[0]: -7:-2}
+bcdef
+@end verbatim
+
 If @var{parameter} is @samp{@@}, the result is @var{length} positional
 parameters beginning at @var{offset}.
+A negative @var{offset} is taken relative to one greater than the greatest
+positional parameter, so an offset of -1 evaluates to the last positional
+parameter.
+It is an expansion error if @var{length} evaluates to a number less than zero.
+
+The following examples illustrate substring expansion using positional
+parameters:
+
+@verbatim
+$ set -- 1 2 3 4 5 6 7 8 9 0 a b c d e f g h
+$ echo ${@:7}
+7 8 9 0 a b c d e f g h
+$ echo ${@:7:0}
+
+$ echo ${@:7:2}
+7 8
+$ echo ${@:7:-2}
+bash: -2: substring expression < 0
+$ echo ${@: -7:2}
+b c
+$ echo ${@:0}
+./bash 1 2 3 4 5 6 7 8 9 0 a b c d e f g h
+$ echo ${@:0:2}
+./bash 1
+$ echo ${@: -7:0}
+
+@end verbatim
+
 If @var{parameter} is an indexed array name subscripted
 by @samp{@@} or @samp{*}, the result is the @var{length}
 members of the array beginning with @code{$@{@var{parameter}[@var{offset}]@}}.
 A negative @var{offset} is taken relative to one greater than the maximum
 index of the specified array.
+It is an expansion error if @var{length} evaluates to a number less than zero.
+
+These examples show how you can use substring expansion with indexed
+arrays:
+
+@verbatim
+$ array=(0 1 2 3 4 5 6 7 8 9 0 a b c d e f g h)
+$ echo ${array[@]:7}
+7 8 9 0 a b c d e f g h
+$ echo ${array[@]:7:2}
+7 8
+$ echo ${array[@]: -7:2}
+b c
+$ echo ${array[@]: -7:-2}
+bash: -2: substring expression < 0
+$ echo ${array[@]:0}
+0 1 2 3 4 5 6 7 8 9 0 a b c d e f g h
+$ echo ${array[@]:0:2}
+0 1
+$ echo ${array[@]: -7:0}
+
+@end verbatim
+
 Substring expansion applied to an associative array produces undefined
 results.
 
-Note that a negative offset must be separated from the colon by at least
-one space to avoid being confused with the @samp{:-} expansion.
 Substring indexing is zero-based unless the positional parameters
 are used, in which case the indexing starts at 1 by default.
 If @var{offset} is 0, and the positional parameters are used, @code{$@@} is