The sub function is similar to gsub, except that this function attempts only one match and substitution of string that matches the regular expression regexpr and replaces the substring with the string repl. The resulting string is assigned to lvalue, which must be a variable name or an array element. If string is omitted, then the value of lvalue is used as the source string. When copying the string to lvalue, the part that was matched by regexpr is replaced according to the string repl.

If repl contains a & or \0, then it is replaced with the substring that matched regexpr. If repl contains a \ n, where n is a digit between 1 and 9, then it is replaced in the substitution with that part of the string that matched the n th parenthesized subexpression of regexpr. n must not be greater than the number of parenthesized expressions in regexpr.

sub returns 1 (True) if the substring was replaced, or 0 if no match occurred. The lvalue is not changed if 0 is returned. Note that because the expression parser interprets backslash sequences in double quoted strings, you must use two backslashes to get a single \ character in regexp or repl or use single quotes to delimit strings.