#=========================================================================================== # # FileName: TimeStrings.var # #=========================================================================================== # DBD2 uses the strftime system-call to print time values using the 'timestring' as a format-string. # # This allows for a user-defined expression of time. # However, there are a few fields that strftime gives no control over and some that do not work correctly (meaning that I've not yet been able to ascertain why they do not work for me). # # For those instances, DBD2 provides some additional field-specifications. # # - The standard format options for the strftime command are all single-character alpha-numeric values. # - DBD2 is therefore able to use non-alpabetic characters (punctuation and numceric values) to define additional # variables intended to supplement those provided by the operating system calls or those not supported by the operating system. # # -- All DBD2 field specifications are strings that start and end with a percent-sign ('%'). # # --- Strings (vs single characters) are required to specify multiple formatting and conversion options) # # -- Unlike the default strftime alphabetic values, DBD2 values both start and end with a percent sign to allow multiple characters # to define a given value (much like the system-variable 'recipes'). # # -- Inside the '%' delimiters, a mix of numeric values and punctuation characters are used with the following meanings. Note that # symbols may be in any order and any alpha values encountered will be non-case-senstive. All calculations use integer math. # For example: 30 / 60 = 0 (no remaining fractions). To get the fractional part, a 'modulo' (using '%') is calculated so 30 % 60 = 30. # Likewise, 90 % 60 = 30, and 90 / 60 = 1. # # -- Numeric parameter values (base-values or 'main ingredients') are identified with an exclamation point ('!'). # # --- 1: Current Time-zone offset. This value is defined in the system's time-zone files in units of seconds. Positive values are East of GMT, negative values are West. # This value is calculated by DBD2 from the information in the system's timeszone files and current timezone setting. It will change as dst (Daylight Savings Time) status changes. # # --- 2: Daylight Savings Time. This numeric value may be followed by an optional, single-character modifier ('s', 'n', or 'b'). # ---- The default value is a (s)tring such as 'CST' or 'CDT'. # ---- For the (n)umeric version of this value, the base value is in seconds. # ---- For the (b)oolean version of this value, the return value is zero (0) if dst is not currently active or one (1) if dst is active. # # -- Punctuation-character sequences (formatting): # --- '!' (exclamation point): The exclamation point identifies the base-value ('primary ingredient') parameter (see numeric values above). # # --- '<', '>' (angle brackets): These symbols act on 'expression-units' to shift the 'unit-values' 'up' (<) or 'down' (>). An 'expression unit' # is the unit in which the value will displayed. For example, time-zone values default to seconds. "<" converts the value to # be displayed in minutes while '<<' converts the value to be displayed in hours. # # ---- All unit conversions are done using integer division (no fractions). # # ---- '<' and '>' are not valid for use with non-numeric values # # --- '|' (pipe symbol) Causes the value to assume a 'modulo' of the current 'expression-level'. For example: To get the number of hours in 23400 seconds, # use "<<" to convert to hours. Since this is integer division, this is 6 hours (no fractional component). To get the number of addtional # minutes, use '<|'. This converts the number of seconds to minutes (by division), then takes the modulo of 60 minutes/hour. (Divisions is always done before modulo). # ---- (The answer is 30: [(23400 seconds / 60 seconds/minute) = 390 minutes. 390 minutes - (6 hours * 60 minutes/hour) = 390 - 360 = 30 minutes)]. # For a hypothetical timezone offset of 23400 seconds, using the string '%!1#02<<%:%!1#02<|%' would yield: 06:30 (remember the formatting sequences can be in any order). # # --- '#' (hashtag): Defines fixed-field parameters. The following sub-symbols are recognized for use within the hashtag sequence: # ---- '+': Forces a '+' character for positive values (as in +01:00 timezone-offsets in rfc3339 time-formats). # ----- Negative values will always show a '-' sign, but positive values (by default) will not. # ---- : The overall width of the field not including the sign character (if any). # ---- pad-character: This is the 1st non-positive-numeric, non-'+' character found after the hashtag. #=========================================================================================== # # T i m e S t r i n g - V a r i a b l e F o r m a t # #=========================================================================================== # TimeString [=] [=] # timestring = 100 = %w %b %e %H:%M:%S %Y # timestring = 200 = %Y-%b-%d %H:%M:%SZ (%!2%) # timestring 300 %Y-%b-%d %H:%M:%S%#+02!1<<%:%#02!1<|% (%!1% %!2% %!2b% %!2n% %#02!2n<<%) # timestring 400 %Y-%b-%dT%H:%M:%S%z # timestring 500 %Y%m%d%H%M%S #