# UTILS

`FoX_utils` is a collection of general utility functions that the rest of FoX depends on, but which may be of independent use. They are documented here.

All functions are accessible from the `FoX_utils` module. 

NB Unlike the APIs of WXML, WCML, and SAX, the UTILS APIs may not remain constant between FoX versions. While some effort will be expended to ensure they don't change unnecessarily, no guarantees are made.

For any end-users interested in the code who are worried about interface changes, it is recommended that the  relevant code (all found in the `utils/` directory be lifted directly and imported into other projects, rather than accessed through the FoX interfaces.

Currently only one utility function is provided, `generate_UUID`.

<a name="UUID"/>

## UUID

UUIDs (see [RFC 4122](http://www.ietf.org/rfc/rfc4122.txt)) are  Universally Unique IDentifiers. They are a 128-bit number, represented as a 36-character string. For example:

     f81d4fae-7dec-11d0-a765-00a0c91e6bf6

The intention of UUIDs is to enable distributed systems to uniquely identify information without significant central coordination. Thus, anyone can create a UUID and use it to identify something with reasonable confidence that the identifier will never be unintentionally used by anyone for anything else.

This property also makes them useful as Uniform Resource Names, to refer to a given document without requiring a position in a particular URI scheme. Thus the above UUID could be referred to as

    urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6

UUIDs are used by WCML to ensure that every document generated has a unique ID. This enables users to go back later on and have confidence that they are examining the same document, regardless of where it might have ended up in file-system hierarchies or databases.

In addition, UUIDs come in several flavours, one of which stores the time of creation to 100-nanosecond accuracy. This can later be extracted (see, for example [this service](http://www.famkruithof.net/uuid/uuidgen?typeReq=-1)) to verify creation time.

This may well be useful for other XML document types, or indeed in non-XML applications. Thus, UUIDs may be generated by the following function, with one optional argument.

* `generate_UUID`  
**version**: *integer*

This function returns a 36-character string containing the UUID.

**version** identifies the version of UUID to be used (see section 4.1.3 of the RFC). Only versions 0, 1, and 4 are supported. Version 0 generates a nil UUID; version 1 a time-based UUID, and version 4 a pseudo-randomly-generated UUID.

Version 1 is the default, and is recommended.

(Note: all pseudo-random-numbers are generated using the high-quality Mersenne Twister algorithm, using the Fortran implementation of [Scott Robert Ladd](http://www.coyotegulch.com).)
