Simul efun: valid_id - check if we are meant by an ID 
 
Synopsis:
	string valid_id(string id)
		or
	string valid_id(string id, mixed where)
		or
	string valid_id(string id, mixed where, string func, mixed value)

Description:
	'valid_id' is an enhanced check in an object e.g. in an add_action
	function to check if we are meant - with numbering ('see help
	numbering') in continuing inventories: Starting in the player's
	inventory and continuing in the environment of the player (the
	inventory of room) incl. room items. This is is done via the lfun
	'find_id' in obj/living - see 'man living/find_id'. 

	Or for checking if this objects matches a special condition -
	see below.

	First argument 'string id' is the ID we are checking. 'id' could
	be in the form "item #" like "torch 3" or "sword 2".
	The 'string id' is lowercased before checking and searching (see
	'man efun/lower_case').
	This numbering only works without a third argument - again see
	below.

	Second argument 'mixed where' (optional) - where the given ID is
	should be - is this object there (in most cases 0, therefore not
	really needed):
	- 0 means all inventories, starting in the inventory of the player
	and continuing in the environment of the player, the room where
	he/she/it is. In the environment, we start with objects there and
	for room items is checked at the end.
	- 1 means that only the inventory of the player is checked.
	- 2 searches the environment of the player, for objects first and
	finally for room items.
	- 3 is like 0, but without room items: The player's inventory and
	the inventory of the room - only "real" objects.
	- an pointer of object that is to search for the ID. Mainly this is
	to get the ID of the searched object without any given numbering.
	Especially for this variation I don't see any use but it would
	work ;-)

	The third argument "string func" is also optional: It's the name
	of a function to be called within us to check a specific
	condition of the "item", e.g. if "torch" is lit. In this case (with
	third argument) numbering is NOT supported. This is (or will be)
	used in obj/torch for 'light torch': the first not lit torch will
	be lit, no matter if carried or lying in the room - even if the
	player is carrying a lit torch. But 'light torch 2' will try to
	light the second torch (carried or lying around), no matter if it
	is lit or not.

	The fourth argument is the expected return value of the function
	specified by the third argument. If this fits for for us (and we
	have the correct ID), we are the object that was looked for. If
	there is no fourth argument given, 0 is assumed to be expected. 

Return value:
	0: this object does not meet the expected conditions: wrong ID or
	right ID but wrong number or right ID but the requirement via the
	third and fourth argument are not fulfilled.
		or
	mixed string id;
	'id': The given 'id' (first argument of 'valid_id') but without any
	numbering, except for room items! With room items the numbering is
	not removed if the room has numbered room items as it is needed in
	(almost) all cases but corrected by "re-counting".

Examples:
	read(str) {
		if (valid_id(str) == "label") {
			...
			return 1;
		}
	}

	read(str) {
		str = valid_id(str);
		if (str == "red label")
		  return write("A red label - nothing written on it.\n");
		if (str == "black label")
		  return write("A black label - nothing written on it.\n");
		if (str == "label" || str == "labels")
		  write("Which label? The black label or the red one?\n");
	}

See also: object/id, living/find_id, helpdir/numbering, efun/lower_case