Recipe 5.11 Generating a Unique Number

5.11.1 Problem

You want to generate a unique number to append to a URL to prevent the browser from retrieving the asset from the local cache.

5.11.2 Solution

Use the number of milliseconds elapsed since January 1, 1970, as returned by Date( ).getTime( ).

5.11.3 Discussion

Unique numbers are most commonly used to generate a unique URL (to prevent an asset from being retrieved from the local cache). That is, by appending a unique number to the end of a URL, it is unlike any previous URL; therefore, the browser obtains the data from the remote server instead of the local cache.

Assuming you need a unique number less frequently than once per millisecond, the number of milliseconds returned by Date( ).getTime( ) is essentially unique (at least during the execution of your movie).

Note that you do not want to use the milliseconds of an existing Date object because its time value doesn't automatically increase as your movie runs. Instead, generate a new Date object representing "now" each time you need to extract a unique number.

Here, we define our custom Math.getUniqueID( ) method to encapsulate the code to generate the unique number. By default, the method automatically generates a new value each time it is called. However, if you pass it a useCached parameter of true, the method returns the same ID that it generated the last time it was called. This can be useful if you want to create a single ID for a movie and access it multiple times.

Math.getUniqueID = function (useCached) {

  // If the unique ID has already been created and if useCached is true, return the 
  // previously generated value.
  if (this.uniqueID != undefined && useCached) {
    return this.uniqueID;
  }

  var now = new Date(  );          // Generate a Date object that represents "now."
  this.uniqueID = now.getTime(  ); // Get the elapsed milliseconds since Jan 1, 1970.
  return this.uniqueID;  
};

Note that you shouldn't use the Date.getMilliseconds( ) method to generate unique numbers because it returns the milliseconds of a Date object (i.e., the fractional remainder of the number of seconds), which is always in the range of 0 to 999.

As already noted, the getUniqueID( ) method generates a unique value only if at least one millisecond elapses between invocations. If you call it more frequently, it returns the same value twice.

// Each of these calls returns the same value because they are all called within one
// millisecond of each other.
timeOne   = Math.getUniqueID(  );
timeTwo   = Math.getUniqueID(  );
timeThree = Math.getUniqueID(  );
trace(timeOne);
trace(timeTwo);
trace(timeThree);