com.avian.util
Class NanoTimeString

java.lang.Object
  extended by com.avian.util.NanoTimeString

public class NanoTimeString
extends java.lang.Object

Some events that we want to track happen too quickly for Java's millisecond resolution that was available previously. Using the System.nanoTime allows us to capture these super fast events.

Unfortunately, nanoTime is way too many digits for the human brain to comprehend easily or manage conveniently. This utility object provides several convenience methods to display nanoTime, including one unformatted String and two formatted Strings. Formatting reduces the number of digits and inserts punctuation to separate the digits into smaller groups that are easier to understand.

System.nanoTime doesn't seem to be connected to System time. I expected to see the nano's roll up into the milliTime, but I couldn't see a place where the nano's matched the millis. In fact, there were times when the nanoTime had a bunch of leading zeros, which were silently removed by Java, when the long value is coverted into a String. So we have to be aware that the length of the nanoTime String may be very short while we are formatting it.

It is common to have these types of utilities provided as static methods to improve system efficiency. However, using statics would require that all of the methods be synchronized so that two birds don't access the same method at the same time and corrput each other's results.


Constructor Summary
NanoTimeString()
           
 
Method Summary
 java.lang.String getNanoTimeString()
          Gets the current system nanoTime and returns the whole thing as a String.
 java.lang.String toShortNanoTimeString()
          Gets the current system nanoTIme and returns the whole thing as a formatted String.
 java.lang.String toShortNanoTimeString(long nt)
          Converts a long number parameter into a formatted nanoTime String so it will be easier for humans to understand the nanoTime.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

NanoTimeString

public NanoTimeString()
Method Detail

getNanoTimeString

public java.lang.String getNanoTimeString()
Gets the current system nanoTime and returns the whole thing as a String. This is good for quick snapshots of the nanoTime but is difficult to use if you are comparing two or more nanoTimes because you have to find the highest digit that was changed in the nanoTime interval. It is usually easier to spot the highest digit that changed if a formatted nanoTime is displayed.

Returns:
String that represents the current nanoTime, unformatted and full length.

toShortNanoTimeString

public java.lang.String toShortNanoTimeString()
Gets the current system nanoTIme and returns the whole thing as a formatted String. The default formatting is to break the nanoTime String into groups of 3 and separating them with different punctuation marks. Angle brackets go around front and rear of the formatted String.

Because nanoTimes can easily have leading zeros, the length of the nanoTime can be short when converted into a String. Therefore, this method checks the length of the nanoTime String before trying to insert formatting punctuation.

Returns:
String that is formatted with punctuation to separate the nanoTime into bite-sized pieces that are easier for humans to understand.

toShortNanoTimeString

public java.lang.String toShortNanoTimeString(long nt)
Converts a long number parameter into a formatted nanoTime String so it will be easier for humans to understand the nanoTime. This number does not verify or validate that the long number that is passed in is a valid nanoTime or make any assumptions about the "timeliness" of the long, it formats any long the same way. It is the user's responsibility to provide valid long nanoTimes .

The digits of the nanoTime String are separated into groups of 3 by punctuation marks. Angle brackets are added to front and back of the formatted nanoTime String to help it stand out.

Because nanoTimes can easily have leading zeros, the length of the nanoTime can be short when converted into a String. Therefore, this method checks the length of the nanoTime String before trying to insert formatting punctuation.

Parameters:
nt - is the long number that should be turned into a String and formatted. The assumption is that it came from System.nanoTime method, but it will format any long that is passed in the same way.
Returns:
String formatted with angle brackets front and back, with the numbers separated into groups of 3 for easier reading.