
PARSE_TIME(3)              UNIX Programmer's Manual              PARSE_TIME(3)

NNAAMMEE
     ppaarrssee__ttiimmee, pprriinntt__ttiimmee__ttaabbllee, uunnppaarrssee__ttiimmee, uunnppaarrssee__ttiimmee__aapppprrooxx, - parse
     and unparse time intervals

LLIIBBRRAARRYY
     The roken library (libroken, -lroken)

SSYYNNOOPPSSIISS
     ##iinncclluuddee <<ppaarrssee__ttiimmee..hh>>

     _i_n_t
     ppaarrssee__ttiimmee(_c_o_n_s_t _c_h_a_r _*_t_i_m_e_s_p_e_c, _c_o_n_s_t _c_h_a_r _*_d_e_f___u_n_i_t)

     _v_o_i_d
     pprriinntt__ttiimmee__ttaabbllee(_F_I_L_E _*_f)

     _s_i_z_e___t
     uunnppaarrssee__ttiimmee(_i_n_t _s_e_c_o_n_d_s, _c_h_a_r _*_b_u_f, _s_i_z_e___t _l_e_n)

     _s_i_z_e___t
     uunnppaarrssee__ttiimmee__aapppprrooxx(_i_n_t _s_e_c_o_n_d_s, _c_h_a_r _*_b_u_f, _s_i_z_e___t _l_e_n)

DDEESSCCRRIIPPTTIIOONN
     The ppaarrssee__ttiimmee() function converts a the period of time specified in into
     a number of seconds.  The _t_i_m_e_s_p_e_c can be any number of <number unit>
     pairs separated by comma and whitespace. The number can be negative. Num-
     ber without explicit units are taken as being _d_e_f___u_n_i_t.

     The uunnppaarrssee__ttiimmee() and uunnppaarrssee__ttiimmee__aapppprrooxx() does the opposite of
     ppaarrssee__ttiimmee(), that is they take a number of seconds and express that as
     human readable string.  _u_n_p_a_r_s_e___t_i_m_e produces an exact time, while
     _u_n_p_a_r_s_e___t_i_m_e___a_p_p_r_o_x restricts the result to only include one units.

     pprriinntt__ttiimmee__ttaabbllee() prints a descriptive list of available units on the
     passed file descriptor.

     The possible units include:
           second, s
           minute, m
           hour, h
           day
           week   seven days
           month  30 days
           year   365 days

     Units names can be arbitrarily abbreviated (as long as they are unique).

RREETTUURRNN VVAALLUUEESS
     ppaarrssee__ttiimmee() returns the number of seconds that represents the expression
     in _t_i_m_e_s_p_e_c or -1 on error.  uunnppaarrssee__ttiimmee() and uunnppaarrssee__ttiimmee__aapppprrooxx() re-
     turn the number of characters written to _b_u_f. if the return value is
     greater than or equal to the _l_e_n argument, the string was too short and
     some of the printed characters were discarded.

EEXXAAMMPPLLEESS
     #include <stdio.h>
     #include <parse_time.h>

     int
     main(int argc, char **argv)
     {
         int i;
         int result;
         char buf[128];
         print_time_table(stdout);
         for (i = 1; i < argc; i++) {
             result = parse_time(argv[i], "second");
             if(result == -1) {
                 fprintf(stderr, "%s: parse error\n", argv[i]);
                 continue;
             }
             printf("--\n");
             printf("parse_time = %d\n", result);
             unparse_time(result, buf, sizeof(buf));
             printf("unparse_time = %s\n", buf);
             unparse_time_approx(result, buf, sizeof(buf));
             printf("unparse_time_approx = %s\n", buf);
         }
         return 0;
     }

     $ ./a.out "1 minute 30 seconds" "90 s" "1 y -1 s"
     1   year = 365 days
     1  month = 30 days
     1   week = 7 days
     1    day = 24 hours
     1   hour = 60 minutes
     1 minute = 60 seconds
     1 second
     --
     parse_time = 90
     unparse_time = 1 minute 30 seconds
     unparse_time_approx = 1 minute
     --
     parse_time = 90
     unparse_time = 1 minute 30 seconds
     unparse_time_approx = 1 minute
     --
     parse_time = 31535999
     unparse_time = 12 months 4 days 23 hours 59 minutes 59 seconds
     unparse_time_approx = 12 months

BBUUGGSS
     Since ppaarrssee__ttiimmee() returns -1 on error there is no way to parse "minus
     one second".  Currently "s" at the end of units is ignored. This is a
     hack for English plural forms. If these functions are ever localised,
     this scheme will have to change.

 HEIMDAL                       October 31, 2004                              2
