Name: deep_inventory - get the inventory of an object

Syntax:
	object *deep_inventory(object ob)

Description:
	The deep_inventory efun gets the (recursive) inventory of an object
	in form of an array.

	Unlike all_inventory, deep_inventory even finds items in bags or
	chests too.

	To make a for-loop to step through the inventory of an object it
	is still faster using first_inventory() and next_inventory()
	instead of deep_inventory(), but not much.

Return value:
	It returns an array of objects which are in the (deep) inventory of
	the given object.

Examples:
	Search the inventory of a player for a ring:

	int i, len;
	object *ob=deep_inventory(this_player());
	for (i=0, len=sizeof(ob); i<len; i++)
		if (ob[i]->id("ring")) write("Ring found!\n");

See also: efun/first_inventory, efun/next_inventory, efun/all_inventory