I see this as a problem throughout the documentation, but I experienced it
with ereg_replace() :

The return values of ereg_replace() are NOT clearly described. In the case
of success, its evident that the return value is the new string.  However, in
the case of failure to match the pattern, its not specified what the return 
value is (null, empty string, or the original string).

Empirical testing has shown that the original string is returned.

Below is an exmaple that can be used to insert group separators into a number.
The loop termination relies on the fact that, when no further matches are found
the return value is the same as the supplied string parameter.

function groupseparator($num, $delim) {
	for ( ; ; $num = $t) {
		$t = ereg_replace("(.*[0-9])([0-9]{3})", "\\1$delim\\2", $num);
		if ($t == $num)
			break;
	}

	return $num;
}

On a more general note - the documention of functions should be clear to always
indicate what all the possible return values are.  ( I used to edit and read POSIX.1 
and .2 standards, so I kind of got use too more detailed descriptions. )