com.starteam.util
Class TimeSpanFormatter

java.lang.Object
  com.starteam.util.TimeSpanFormatter

public final class TimeSpanFormatter
extends java.lang.Object

Properties of type eTimeSpan can specify a DisplayPreference in the form of a string that describes how the value should be formatted for display. The syntax of the format string is described below.

     format: format-term [format-term ...]
     format-term: optional-term | required-term
     optional-term: '[' format ']'
 
         A sequence of format terms can be enclosed in [] to indicate that it is optional. An optional
         format term is included in the formatted string if and only if it contains at least one
         field-name whose value is non-zero.
 
     required-term: field-specifier | literal
     field-specifier: [width-specifier] field-name[unit-specifier][fraction][label-specifier]
 
         A parameterized term that contains a field-name that gets replaced by a value derived from the
         TimeSpan. Other components of the field-specifier are optional, and influence the formatting
         of field-name.
 
     width-specifier: positive-integer
 
         Specifies the field width. For example, '2s' shows the number of seconds padded with leading zeros
         if necessary to obtain a width of 2 digits.
 
     field-name: 'y' | 'n' | 'w' | 'd' | 'h' | 'm' | 's' | 'f' | 'u'
 
         Inserts a number derived from the TimeSpan. The different field names are interpreted as follows:
 
             y: Years. Defined as 365-day intervals. If you want to use a different definition of years,
                    then use unit-specifier. For example 'y=365.25d' might be used to display the number
                    of 365 1/4 -day years.
 
             n: Months. Defined as 30-day intervals. If you want to use a different definition of months,
                    then use unit-specifier.
 
             w: Weeks. Defined as 7-day intervals. If you want to use a different definition of weeks,
                    then use unit-specifier.
 
             d: Days.
             h: Hours.
             m: Minutes.
             s: Seconds.
             f: Milliseconds.
             u: An alias for the native units that are used in the repository to represent property values
                    for this property. The native units may be days, hours, minutes, etc. May also be a
                    custom value that doesn't correspond to one of the recognized named units. In this latter
                    case, the label-specifier, if provided, is ignored. You can add your own label as a
                    literal string, but it won't be localized.
 
 The algorithm used to fill field-names with numeric values is described below.
 
     unit-specifier: '='double field-name
 
         Supports custom units. For example, 'd=8h' might be used to display the TimeSpan in 8-hour man-days.
 
     fraction: '.' min-digits [':'max-digits]
 
         Used to format the remainder of the TimeSpan as a fraction. The value is padded to the right with zeros,
         if necessary, to get at least min-digits fractional digits. The value is rounded if necessary to get no
         more than max-digits fractional digits. If max-digits is not specified, min-digits is assumed. If
         min-digits is 0 and the fractional component for a given value is zero, then the decimal point is omitted.
 
     label-specifier: '+' | '-'
 
         Adds a label to the given field by formatting it using a pattern that is specific to both the cardinality
         of the term and the current locale. Use + to use a long label, or ' to use a short label (abbreviation).
         For example, 'h+' might display as '6 hours' in English; 'f.2-' might display as '1432.65 msec.' in English.
 
     literal: '"' text ' '"' | ''' text ' ''' | text '
 
         Literal text, optionally enclosed in double or single quotes. Any character that cannot be parsed as a
         valid part of a field-specifier in context is automatically interpreted as part of a literal. Use
         double-quotes or single-quotes to force any character sequence to be interpreted literally. White space
         is always significant, whether it appears inside or outside quotes.
 
 To determine the value for each field-name, we find the most-significant field-name referenced in the format (T0)
 and the least-significant term referenced in the format (TN). All defined field-names from T0 through TN
 participate in the calculation, even if they are not referenced in the format, with the exception of w (weeks),
 which participates only if it is explicitly referenced.
 
 T0 is assigned the integer value obtained when dividing the initial TimeSpan by the appropriate units; T1 through
 TN are assigned values based on the time that remains after assigning a value to the previous term. TN is then
 rounded to the nearest integer value, unless its field-specifier includes a fraction.
 
 For example, consider the following meaningless format string: '4m/d'. In this case, T0 is d (days) and TN
 is m (minutes). Thus, the days, hours and minutes fields all participate in value calculation.
 
 Now, suppose we were to use this format on a TimeSpan whose value was 26.505556 hours. The fields would be
 calculated as follows:
 
     (26.505556 hours) / (24.0 hours-per-day) = (1.104606 days)
     Thus, d = 1.
 
     2.505556 hours remain;
     Thus, h = 2; remainder = 0.505556 hours.
 
     (0.505556 hours) * (60 minutes-per-hours) = (30.633333 minutes)
     Thus, m = 30; remainder = 0.633333 minutes.
 
     This is the least significant participating field, and no fractional component was specified in the format
     string, so we round m = 31.
 
 The resulting display string is therefore '0031/1'.
 
 Some more meaningful examples are shown below.
 
 Format       Comment
 'u.0:2'       If no DisplayPreference is specified for a given TimeSpan property, this is the default. The
              examples below assume the storage unit in the repository is 1.0 hours.
 
         Value (hours)   Display String
         26.505556         '26.51'
          4.500000         '4.5'
          2.000000         '2'
          0.250000         '0.25'
 
 Format               Comment
 '[d.]2h:2m:2s.0:7'    The format used by System.TimeSpan.ToString() under .NET. Oracle uses a similar format
                      for their time spans (except that the period after the optional day component is replaced by a space).
 
         Value (hours)         Display String
         26.505556          '1.02:30:20.0016'
          4.500000          '04:30:00'
          2.000000          '02:00:00'
          0.250000          '00:15:00'
 
 Format                       Comment
 '[[d+, ]h+, ]m+[, s.0:2+]'     A verbose display format, with minutes always displayed, and each component labeled.
 
         Value (hours)          Display String
         26.505556           '1 day, 2 hours, 30 minutes, 20.002 seconds'
          4.500000           '4 hours, 30 minutes'
          2.000000           '2 hours, 0 minutes'
          0.250000           '15 minutes'
 
 Format       Comment
 'd=8h+'        Displays 8-hour man-days.
 
         Value (hours)         Display String
         26.505556           '3 days'
          4.500000           '1 day'
          2.000000           '0 days'
          0.250000           '0 days'
 

Constructor Summary

TimeSpanFormatter(java.lang.String format)
Construct a TimeSpanFormatter.

TimeSpanFormatter(java.lang.String format, TimeSpan nativeUnits)
Construct a TimeSpanFormatter.

Method Summary

java.lang.String

format(TimeSpan t) Return a string representing the value of TimeSpan t, formatted as specified by the format string used to create this TimeSpanFormatter.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

TimeSpanFormatter

public TimeSpanFormatter(java.lang.String format)

Construct a TimeSpanFormatter.

Parameters:

format - String that specifies the desired TimeSpan format, assuming 1 hour as the native storage unit.

TimeSpanFormatter

public TimeSpanFormatter(java.lang.String format,
                         TimeSpan nativeUnits)

Construct a TimeSpanFormatter.

Parameters:

format - String that specifies the desired TimeSpan format.

nativeUnits - TimeSpan that specifies the native storage unit. Used with the "u" format field.

Method Detail

format

public java.lang.String format(TimeSpan t)

Return a string representing the value of TimeSpan t, formatted as specified by the format string used to create this TimeSpanFormatter.

Parameters:

t - TimeSpan to format.

Returns:

String representing TimeSpan t in the specified format.