A
          / \      _             Play Now                         Nemesis on 
          | |     | |  _______   _        _   _______    _______   _    _______
          | |\    | | |   ____| |  \    /  | |   ____|  /   ____| | |  /   ____|
 /-------/-------------------------------------------------------------------,
O= Home <=XX|  About  News  Pics  Adventurers  Wizards  Download  Connect     >
 \-------\-------------------------------------------------------------------'
          | |   \   | |  |____  | |      | | |  |____   ___ \  \  | |  ___ \  \
          | |     \_| |_______| |_|      |_| |_______| |_______/  |_| |_______/
          \ /
           V  

Documentation Area

Document Path: /doc/living/find_id

Name: find_id - find an object by its ID in continuing inventories etc.

Synopsis:
	mixed *find_id(string id);
		or
	mixed *find_id(string id, mixed where);
		or
	mixed *find_id(string id, mixed where, string func, mixed value);

Description:
	'find_id' is more than an "enhanced" 'present':
	Searching for IDs (not pointers of object as in 'present') in
	continuing inventories, also with numbered items - see 'help
	numbering'. Search continuing inventories is searching e.g. for 
	"torch 3" starting in the inventory of the player and continuing
	the search in the environment of the player (the inventory of
	the room) incl. room items if the player has no "torch 3".

	Or searching for the first item with a special condition - see
	below.

	'find_id' is some kind of back-end for 'valid_id' (see 'man
	lib/valid_id') which is more relevant for "normal" coding.
	'find_id' is used in obj/player.
	
	First argument 'string id' is the ID we are searching for. '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
	searched:
	- 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 searched.
	- 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.

	The third argument "string func" is also optional: It's the name
	of a function to be called in the found object to check a specific
	condition of the "item", e.g. if "torch" is lit. In this case (with
	third argument) numbering is NOT supported.

	The fourth argument is the expected return value of the function
	specified by the third argument. If this fits for an object of the
	correct ID, the search is complete.

Return value:
	0: no matching object found.
		or
	mixed ({ string id, object obj, int where });
	'id': The given 'id' (first argument of 'find_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.
	The removal of the number sounds trivial, but you can't do it with
	a simple 'sscanf' in LPC ;-)
	'obj' is the found pointer of the object.
	'where' the required ID was found:
	- 1 says it is in the inventory of the player.
	- 2 means its in the inventory of the room, a "real" object.
	- 3 is a room item.

Examples:
	found = find_id("candle 3", 0);
	printf("%O", found);
	({ "candle", obj/torch#1234 ["a lighted candle"], 2 });
		After searching the player and the room the "candle 3" is
		'obj/torch ["a lighted candle"]' and it is in the inventory
		of the room - the environment of the player.

	found = find_id("ring 2", 2);
	printf("%O", found);
	({ "ring", room/mine/tunnel3 ["a tunnel with an hole"], 3 });
		Only the room is searched - including room items. "ring 2"
		is a room item.

	found = find_id("torch", 3, "query_lit", 0);
	printf("%O", found);
	({ "torch", obj/torch#2345 ["a torch"], 2 });
		The player and the room (without room items) are searched
		for "torch" that is not lit.

See also:
lib/valid_id
efun/present
helpdir/numbering
efun/lower_case