PARSE_TIME(3)

💖 PARSE_TIME(3) 💖

okay bestie, sit down, hydrate, because we're about to talk about parse_time — that's the library functions manual page for the whole parse_time, print_time_table, unparse_time, unparse_time_approx girl gang. time intervals, parsing them, unparsing them, the whole vibe. let's go ✨

🌸 NAME 🌸

parse_time, print_time_table, unparse_time, unparse_time_approx — the icons that parse and unparse time intervals 💅

📚 LIBRARY 📚

she lives in the roken library, aka libroken, and you link her with -lroken. no cap.

✨ SYNOPSIS ✨

#include <parse_time.h>

int
parse_time(const char *timespec, const char *def_unit);

void
print_time_table(FILE *f);

size_t
unparse_time(int seconds, char *buf, size_t len);

size_t
unparse_time_approx(int seconds, char *buf, size_t len);

🦋 DESCRIPTION 🦋

so parse_time() takes a period of time you wrote out and converts it into a number of seconds. the timespec can be literally any number of ⟨number unit⟩ pairs, separated by commas and whitespace — stack them up, go off. the number is allowed to be negative (yes queen, go backwards). and any number that doesn't have an explicit unit attached gets treated as def_unit. it's giving "we'll assume unless you tell us otherwise" 💅

unparse_time() and unparse_time_approx() do the exact opposite of parse_time() — they take a number of seconds and turn it back into a human readable string. the difference? unparse_time gives you an exact time, no rounding, no cutting corners. unparse_time_approx restricts the result to include only one unit, so it's the quick vibes-only version, the tl;dr, the main character summary.

print_time_table() prints a descriptive list of all the available units onto the file descriptor you hand it. like a little menu, a menu of time 🎀

the possible units include:

• second, s
• minute, m
• hour, h
• day
• week — seven days
• month — 30 days
• year — 365 days

and here's the cute part: unit names can be arbitrarily abbreviated, as long as they stay unique. abbreviate away, bestie, just don't cause a collision 🫶

🔥 RETURN VALUES 🔥

parse_time() returns the number of seconds that represents the expression in timespec, or -1 on error. (yes, -1 is the error code and a valid-looking number, we'll get to that in BUGS, hold on)

unparse_time() and unparse_time_approx() return the number of characters written to buf. and listen — if that return value is greater than or equal to the len argument, the string was too short and some of the printed characters got discarded. she got cut off mid-sentence 😭 size your buffers, babes.

🌈 EXAMPLES 🌈

here's a whole little program, she's iconic:

#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;
}

and when you run it like this:

$ ./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

look at that. 1 minute 30 seconds and 90 s both land on 90, the approximation trims it down to 1 minute, and 1 y -1 s gives you 31535999. math ate, honestly 👑

💀 BUGS 💀

okay so, real talk:

since parse_time() returns -1 on error, there is no way to parse "minus one second". the error code and the answer are the same value. it's giving identity crisis. 🙈

also, currently a "s" at the end of units gets ignored — it's a hack to handle English plural forms (second vs seconds, minute vs minutes, you get it). if these functions are ever localised, this scheme will have to change. noted, periodt.

and that's the whole page, bestie 💜 this was the HEIMDAL version, dated November 17, 2013. go parse something cute ✨🎀