tree-optimization/122589 - imm use iterator checking fallout

tree-optimization/122589 - imm use iterator checking fallout

The following addresses the latent issue that gsi_replace_with_seq
causes debug info to unnecessarily degrade and in this process
break the new immediate use iterator sanity checking.  In particular
gsi_remove has side-effects on debug stmts even when operating
in non-permanent operation.  But as we are operating on a sequence
not in the IL here this should be avoided.  Re-factoring
gsi_replace_with_seq to not rely on gsi_remove fulfills this.

I've noticed gsi_split_seq_before has misleading documentation.
Fixed thereby as well.

	PR tree-optimization/122589
	PR middle-end/122594
	* gimple-iterator.cc (gsi_replace_with_seq): Instead of
	removing the last stmt from the sequence with gsi_remove,
	split it using gsi_split_seq_before.
	(gsi_split_seq_before): Fix bogus documentation.

	* g++.dg/torture/pr122589.C: New testcase.