🕒 timelib

A C++17 library for parsing and handling time-related queries, made mainly for rnux. This is pretty straightforward right now. The regex might not catch every possible query, and the location database isn't exactly the best, but it tries its best :(

Right now, it's fairly simple, but it does have a few neat features:

• It can... tell time.
• It can parse natural language queries to convert time between locations ("5pm in new york to tokyo").
• It can calculate the time difference between two locations.
• It knows a bunch of aliases for cities and timezones (nyc, ist, pacific time, etc.).
• Fuzzy-ish parsing of time-related questions (aka hard-coded common misspellings).

This project uses AI-generated code frequently! Please read this section to learn more!

Usage

Here's how you can use timelib in your project.

#include <iostream>
#include "time.hpp"

int main() {
    timelib::TimeConverter converter;

    // current time at location
    auto parsed_time = converter.parseInput("what is the time in london");
    if (auto res = timelib::TimeConverter::processQuery(parsed_time); res.code == timelib::ErrorCode::Success) {
        std::cout << res.result << std::endl;
        // expected output: The current time in london is Jul 10, 02:30 PM (BST)
    }

    // convert time between two locations
    auto parsed_conversion = converter.parseInput("convert 9:30pm in delhi to nyc");
    if (auto conv_res = timelib::TimeConverter::processQuery(parsed_conversion); conv_res.code == timelib::ErrorCode::Success) {
        std::cout << conv_res.result << std::endl;
        // expected output: Jul 10, 09:30 PM in delhi is Jul 10, 12:00 PM in nyc
    }

    // calculate time difference
    auto parsed_diff = converter.parseInput("time difference between tokyo and la");
    if (auto diff_res = timelib::TimeConverter::processQuery(parsed_diff); diff_res.code == timelib::ErrorCode::Success) {
        std::cout << diff_res.result << std::endl;
        // expected output: Tokyo (JST) is 16h ahead of La (PDT).
    }

    return 0;
}

Installation

The project uses CMake, so building it is fairly standard.

git clone https://github.com/TheUnium/timelib.git
cd timelib
git submodule update --init --recursive

mkdir build && cd build
cmake ..
make

sudo make install

Afterwards, if you are using CMake in your project, you'll need to add this to your CMakeLists.txt:

find_package(timelib REQUIRED)
target_link_libraries(YOUR_PROJECT PRIVATE timelib::timelib)

Structure

All the code is in src/ and include/.

• include/: Contains all the public headers for the library (time.hpp, location.hpp, zones.hpp).
• src/: The main C++ source code (time.cpp).
• extern/: Contains the date library by Howard Hinnant the 🐐.

Stuff used

• C++17
• CMake
• Howard Hinnant's date library
• CURL

Extra stuff

Raycast has this cool thing where you can ask what time it is in a different location, and I wanted to implement that in my app launcher, rnux. I pretty quickly realized timezones are VERY complicated, and are NOT just offsets. This made it really annoying to work with, so I decided to make a separate library that uses Howard Hinnant's date library. This library only handles the parsing of language (like "whats 5pm in berlin" would convert 5 PM in your machines timezone to UTC+2/CEST)
TLDR; it's a time library. it works. sometimes 😔

Oh yeah also....

• The location and timezone aliases in location.hpp and zones.hpp were mostly generated by an AI.
• In general, a LOT of AI (specifically Gemini 2.5 Pro and Claude Sonnet 4) was used to make this. I have never really worked with timezones, or made libraries like this before. I know it's frowned upon (I know, because I frown upon AI usage in projects like these as well), and I don't like AI being used like it either... but it was helpful. I'll try not to use AI (or at the very least keep it's usage minimal) for future projects like this.
• If you use this project, you don't need to credit this. Since like 65% of this was made using AI, this uses the Unlicense as I don't feel as if I should take credit for it. However, you can still link to this repository if needed/wanted.