This file details how to use the function 'clone_unique()' which
is located in in the file '/lib/unique.c'.  This file is meant
to be inherited into objects that needs it's special item handling.

Read the file header or the sman file for the function (if available)
to get a basic understanding for the function and it's arguments.

To begin with, the function returns either an object pointer to
a successfully cloned object, or a null object reference '0'.

Secondly, the code does _no_ error checking.  This was done purposefully
to streamline it and make it efficient.  It's purely up to the coding
wizard to specify correct paths and loading/clonable objects.  If they
don't.  You'll get the standard runtime errors.

Arguments
---------

string file - This is the filepath to the unique item. Nothing more.
	      (must specify)

int    num  - This is the max number of available copies allowed at
	      the time of cloning.  If we are below this number, we
	      try to clone the unique item, otherwise we try the rest.
	      (defaults to 1)

mixed alt   - This is the 'alternates' argument.  It is very flexible
	      in what you can specify.  You may specify a single string
	      path, and that will always try to be cloned.  Otherwise
	      it looks for an array.  The array may contain either
	      string filepointer elements, array elements consisting
	      of a string filepointer and an int value, or a mixture
	      of the two. (defaults to 0)

int always  - This gets checked if the alt is an array.  If, after parsing
	      through the array and no object is found and this variable
	      is set, it will just randomly pull one of the array
	      elements and try to clone it. (defaults to 1)

int chance  - Sets the chance at which the main item will be checked
	      to see if it should try to be cloned.  If this check fails,
	      then it skips parsing the main item and goes directly to
	      parsing the alternates (if specified). (defaults to 50)

Examples
--------

object ob = clone_unique("/item/path", 2, "/alt/path");

- This will clone up to '2' instances of 'item'.  Otherwise will
  always try to clone 'alt'.

object ob = clone_unique("/item/path", 1, ({ "/alt1/path", "/alt2/path" }));

- This allows only one instance of 'item' and will randomly pick one
  of the two alternates.

object ob = clone_unique("/item/path", 1, ({ {( "/alt1/path", 40 }),
					  ({ ({ "/alt2/path", 80 }), 0);

- This will only attemp to clone '1' of 'item'.  Otherwise it parses
  through the array of arrays.  There is a 40/100 chance that alt1 will
  clone, if not, then it will see if it should try alt2 which has an
  80/100 chance.  If both fail, and since the 'always' variable is '0',
  a null object reference will be returned.  Meaning nothing gets clones.

- In order to work correctly, the % chance values specifed in the arrays
  should be sequentially incremented, meaning each one higher then the
  last.  I.e.: 20, 40, 60, 80, 100  will ensure the something gets
  chosen.  They are all tried in the order specified.  If you specify
  something like: 20, 5, 5, 10.  Then your chances are slim that it
  chooses anything through normal parsing.

- The 3rd argument 'alt' may contain a mixture of string elements and
  array elements.  Like so: ({ "/alt1/path", ({ "/alt2/path", 50 }) }).

NOTES
-----

The alternates are processed in the order specifed.  The only
deviation away from this is if an object wasn't selected after parsing
and the 'always' flag is set, then it simply pulls one at random.