Update wording of IterableStorageMap docs

[xlc]

/// Enumerate all elements in the map in lexicographical order of the encoded key. If you
/// alter the map while doing this, you'll get undefined results.

The undefined results wording is very uncomfortable to me as someone with C++ background. There are no undefined behaviour here. There maybe unexpected result depends on the how the map is altered. Deleting item is perfectly fine, update value is also ok. Only add item means it may or may not be iterated later depends on the hash value of the key. Can we update the docs to make it more clear?

substrate/frame/support/src/storage/mod.rs

Lines 326 to 351 in ee8ac3a

	pub trait IterableStorageMap<K: FullEncode, V: FullCodec>: StorageMap<K, V> {
	/// The type that iterates over all `(key, value)`.
	type Iterator: Iterator<Item = (K, V)>;
	/// The type that itereates over all `key`s.
	type KeyIterator: Iterator<Item = K>;
	/// Enumerate all elements in the map in lexicographical order of the encoded key. If you
	/// alter the map while doing this, you'll get undefined results.
	fn iter() -> Self::Iterator;
	/// Enumerate all elements in the map after a specified `starting_raw_key` in lexicographical
	/// order of the encoded key. If you alter the map while doing this, you'll get undefined
	/// results.
	fn iter_from(starting_raw_key: Vec<u8>) -> Self::Iterator;
	/// Enumerate all keys in the map in lexicographical order of the encoded key, skipping over
	/// the elements. If you alter the map while doing this, you'll get undefined results.
	fn iter_keys() -> Self::KeyIterator;
	/// Enumerate all keys in the map after a specified `starting_raw_key` in lexicographical order
	/// of the encoded key. If you alter the map while doing this, you'll get undefined results.
	fn iter_keys_from(starting_raw_key: Vec<u8>) -> Self::KeyIterator;
	/// Remove all elements from the map and iterate through them in lexicographical order of the
	/// encoded key. If you add elements to the map while doing this, you'll get undefined results.
	fn drain() -> Self::Iterator;

[KiChjang]

I don't get how iterator invalidation is not undefined behaviour? The bit where you said "deleting/updating a value is also OK", it's actually not; if you had been iterating on a value whilst modifying it, then the iterator abstraction has been broken and it is undefined behaviour, because the iterator does not expect the item's value to be changed by something else while it exists.

Perhaps you meant that in Substrate, storage iterator invalidation is implementation-defined behaviour instead?

[xlc]

Yeah in general, it is undefined behaviour, but for this particular iterator, it is not. The iterator offers a mode to remove items after accessing it. We cannot have any undefined behaviour in warm runtime.