{smcl}
{* 7feb2006}{...}
{hline}
help for {hi:stimeofday}{right:(SJ6-1: dm0018)}
{hline}

{title:Generate string time-of-day variables from numeric time-of-day variables}

{p 8 17 2} 
{cmd:stimeofday}
{it:numvarlist}
{ifin}
{cmd:,}
{cmdab:g:enerate(}{it:newvarlist}{cmd:)} 
{cmdab:n:umeric(}{it:units}{cmd:)} 
{cmdab:s:tring(}{it:specification}{cmd:)}{break} 
[{cmd:am(}{it:am_string}{cmd:)}
{cmd:pm(}{it:pm_string}{cmd:)}
{cmdab:time:only}{break}
{cmdab:df:ormat(}{it:format}{cmd:)}
{cmdab:hf:ormat(}{it:format}{cmd:)}
{cmdab:mf:ormat(}{it:format}{cmd:)}
{cmdab:sf:ormat(}{it:format}{cmd:)}{break}
{cmdab:ds:ymbol(}{it:symbol}{cmd:)}
{cmdab:hs:ymbol(}{it:symbol}{cmd:)}
{cmdab:ms:ymbol(}{it:symbol}{cmd:)}
{cmdab:ss:ymbol(}{it:symbol}{cmd:)}] 


{title:Description} 

{p 4 4 2} 
{cmd:stimeofday} takes one or more numeric variables indicating times of
day, or dates including times of day, or timings, and generates
corresponding string variables giving those times, date-times, or timings
in one of various specified forms.  All the numeric variables must share
the same units, one of days, hours, minutes, or seconds.  Either all
string variables requested will be generated or none will, whenever any
error arises in processing. The list of new variable names will be
returned in {cmd:r(varlist)}. 
 

{title:Options} 

{p 4 8 2}
{cmd:generate(}{it:newvarlist}{cmd:)} specifies a list of new names for the
new string variables. There must be as many new names as there are existing
numeric variables. {cmd:generate()} is required. 

{p 4 8 2}
{cmd:numeric(}{it:units}{cmd:)} indicates units for the numeric variables.
One of {cmd:days}, {cmd:hours} (or {cmd:hrs}), {cmd:minutes}, or {cmd:seconds}
must be specified but may be abbreviated in any way. {cmd:numeric()} is
required.  

{p 4 8 2} 
{cmd:string(}{it:specification}{cmd:)} specifies the sequence of time or date
elements followed in each of the string variables to be generated.   One of
the following specifications should be given. 

{space 8}{cmdab:d:ays} {cmdab:h:ours} {cmdab:m:inutes} {cmdab:s:econds} {col 40}(a) 
{space 8}{cmdab:d:ays} {cmdab:h:ours} {cmdab:m:inutes} {col 40}(b)
{space 8}{cmdab:d:ays} {cmdab:h:ours} {col 40}(c)
{space 8}{cmdab:h:ours} {cmdab:m:inutes} {cmdab:s:econds} {col 40}(d)
{space 8}{cmdab:h:ours} {cmdab:m:inutes} {col 40}(e)
{space 8}{cmdab:m:inutes} {cmdab:s:econds} {col 40}(f) 

{p 8 8 2}
{cmdab:h:rs} is allowed as an alternative to {cmdab:h:ours}. 

{p 8 8 2}
{cmd:string()} is required. 

{p 4 8 2}
{cmd:am(}{it:am_string}{cmd:)} and {cmd:pm(}{it:pm_string}{cmd:)} specify text
used in the string variables to indicate whether times are a.m. or p.m.  Thus
{cmd:am(am)} specifies that times a.m. are to be flagged with the text
``am''.  Times a.m. are naturally not adjusted.  Similarly,
{cmd:pm(" p.m.")} specifies that times p.m. are to be flagged with that text,
including the leading space.  Times p.m. are adjusted by subtracting 12 from
hours from 13 to 23. By default, no such text is used.  One of {cmd:am()} and
{cmd:pm()} may be specified without the other. {cmd:am()} and {cmd:pm()} are
deemed incompatible with (c) and (f).  Assigning am or pm text when the number
of hours is 24 or more will cause an error. 

{p 4 8 2}
{cmd:timeonly} specifies that only the time-of-day part of a date with a time
of day be used. Thus given 1453466096 with specified unit seconds, which is
21 Jan 2006 12:34, then only the time-of-day part would be used: i.e.,
{cmd:mod(1453466096, 86400)} would be used to produce a representation of the
time of day.

{p 4 8 2}
{cmd:dformat()}, {cmd:hformat()}, {cmd:mformat()}, and {cmd:sformat()}
specify formats for day, hour, minute, and second elements.  Commonly,
but not necessarily, the day format will be specified by using a date
format; see {help dfmt}. This choice is at the user's discretion. The default
format is the default numeric format, given that the number of days
could be (part of) a timing. The default formats for hours, minutes, and
seconds are {cmd:%02.0f}, {cmd:%02.Of}, and {cmd:%05.2f}, respectively,
so that leading zeros apply by default with numbers less than 10; see
{helpb format}. Using default formats may lead to considerable loss of
information, so you should exercise due care. 

{p 4 8 2} 
{cmd:dsymbol()}, {cmd:hsymbol()}, {cmd:msymbol()}, and {cmd:ssymbol()}
specify "symbols" for day, hour, minute, and second elements. Each symbol
occurs after the associated element. The defaults are {cmd:" "} (space),
{cmd::} (colon), {cmd::} (colon), and {cmd:""} (empty string),
respectively, except that the default symbol is always an empty string
for the last element specified (namely, hours given (c) above and
minutes given (b) or (e) above). 


{title:Remarks} 

{p 4 4 2}
A numeric time of day might look like 45296, which is
12:34:56 expressed in seconds after midnight. A numeric date with
time of day might look like 1453466096, which is 
21 January 2006 12:34:56 expressed in seconds after midnight on 31
December 1959/1 January 1960.  A timing could look like 45296,
indicating that some task or state lasted 12h 34m 56s, converted to
seconds. Fractional parts are allowed in every case. Negative parts are
also allowed, but the processing of negative hours, minutes, or seconds
may not match your expectation. Thus as far as Stata is concerned there
is no difference between times of day and other numeric
variables; the distinction is in the user's knowledge.  The user must
therefore specify units, which {cmd:stimeofday} cannot determine by
itself. 

{p 4 4 2} 
{cmd:stimeofday} does not indicate time zones (e.g., CET) or days
of the week (e.g., Mon). If desired, these should be added.

{p 4 4 2}
{cmd:stimeofday} makes no adjustments for leap seconds or other
astronomical subtleties. Every day in every year is presumed to have 24
hours, each being 60 minutes, and each minute in turn being 60 seconds. 


{title:Examples} 

{p 4 4 2}
Suppose that you want a typical date-time to look like 
21 Jan 2006 12:34:56. Then specify 
{cmd:string(d h m s) dformat(%dd_m_CY) sformat(%02.0f)}.  
By default, without these format statements, exactly the same date-time would
appear as 16822 12:34:56.00.

{p 8 12 2}{cmd:. stimeofday ntime, gen(stime) n(s) s(d h m s) dformat(%dd_m_CY) sformat(%02.0f)}

{p 4 4 2}
Suppose that you want just the time-of-day from such a date and an indication
of both a.m. and p.m.  Then specify 
{cmd:string(h m s) timeonly am(" am") pm(" pm")}. 
 
{p 8 12 2}{cmd:. stimeofday ntime, gen(stime) n(s) s(h m s) timeonly am(" am") pm(" pm")}


{title:Author}

{p 4 4 2}Nicholas J. Cox, Durham University, UK{break}
         n.j.cox@durham.ac.uk


{title:Acknowledgments}

{p 4 4 2}
Kit Baum, William Gould, and Vince Wiggins produced programs or comments that 
were very helpful in identifying user needs and possible solutions. 


{title:Also see}

{p 4 13 2}Online:  {helpb ntimeofday}, {help dfmt}, 
{helpb format} 
{p_end}