Date Library (v 4.4.0 up)

[SMcNeill]

QB64PE Date/Time Utility Library – Overview
-------------------------------------------

This library provides a comprehensive suite of date and time utilities designed
to extend and enhance the built‑in DATE$, TIME$, and TIMER functionality in
QB64PE. It offers consistent parsing, formatting, conversion, and timestamp
generation tools that make it easier to work with dates in multiple formats,
produce human‑readable or machine‑sortable output, and perform calendar‑related
calculations.

The library includes the following major capabilities:

1. Date Component Extraction
  --------------------------
  Functions such as Date.Day$, Date.Month$, and Date.Year$ allow you to extract
  individual components from a date string based on a user‑supplied format
  mask. This makes it possible to parse dates in virtually any layout, such as
  MM-DD-YYYY, DD/MM/YY, YYYY.MM.DD, and more.

  Time component extractors (Date.Hour$, Date.Minute$, Date.Second$) perform
  the same role for TIME$-formatted strings.

2. Timestamp Generation
  ---------------------
  Two different timestamp systems are provided:

  • Date.TimeStamp## 
    Produces a Unix‑style timestamp (seconds since Jan 1, 1970). Supports both
    pre‑1970 and post‑1970 dates, including leap‑year corrections and negative
    timestamps for historical dates.

  • Date.TimeStamp.HR$ 
    Generates a human‑readable, sortable timestamp in the form:
        YYYYMMDD.HHMMSS
    Ideal for filenames, logs, and chronological sorting.

  • ExtendedTimer## 
    A lightweight, high‑performance timer based on the current date and TIMER.
    Designed for real‑time measurement rather than historical accuracy.

3. Date Formatting and Conversion
  -------------------------------
  • Date.ToString$ 
    Converts numeric MM/DD/YYYY values into a formatted date string using
    tokens such as YYYY, YY, MM, and DD.

  • Date.ToUniDate$ 
    A powerful universal date formatter that supports:
        - Full month names (January)
        - Abbreviated month names (Jan)
        - Numeric months (01)
        - Ordinal days (01st, 02nd, 03rd)
        - Weekday names (Monday, Mon)
        - 2‑digit or 4‑digit years
    The format language is flexible and forgiving, allowing expressive output
    such as:
        "Tuesday, February 10th, 2026"
        "10.02.2026"
        "Mon 10 Feb 26"

4. Weekday Calculation
  --------------------
  • Date.WeekDay& 
    Returns the weekday number (1–7) using Zeller’s Congruence.

  • Date.WeekDay.Name$ 
    Returns the full weekday name (Sunday–Saturday).

  These functions work with any date format supported by the extraction
  routines.

5. Design Philosophy
  ------------------
  The library is built around flexibility, reliability, and compatibility with
  QB64PE’s native DATE$ and TIME$ formats. It provides:

  • Format‑aware parsing 
  • Consistent output across multiple date styles 
  • Human‑readable and machine‑readable timestamp options 
  • Leap‑year and calendar‑accurate calculations 
  • Tools suitable for logging, sorting, UI display, and timing

In short, this library transforms QB64PE’s basic date/time features into a
complete, modernized toolkit for parsing, formatting, converting, and analyzing
dates and times in any format you need.

---

NOTE:  This library uses my new *.QLB name extension, rather than *.BI or *.BM.

Since QB64PE v 4.4.0 now allows SUB and FUNCTION to go anywhere in your code, I'm converting all my old libraries into this new format so that all you need to do is include the single file up top in your own projects.  To distinguish between a *.BI (which just goes up top) and a *.BM (which just poops out the bottom), I've decided to go with a *.QLB for a library which holds both sections intact.

Place *.QLB files at the beginning of your program.  One $INCLUDE at the top of your code for one *.QLB library. It can't get much simpler than that. 

---

EDIT:  Updated to change extension to *.QLB, which is what QB45 used to use for Quick Libraries.  It's nostalgic and doesn't have the same connotations that .lib has with modern extensions.

[grymmjack]

What is .QLB? just something you made up or is it official?

[SMcNeill]

It's just what I decided to go with for myself, to help me keep things separate.

QB64 doesn't care about your extension.  In the end, it only works with TXT files, though you can name them however you want.  

The standard convention has always been:
*.BAS for a QB64 program.
*.BI for library code that goes at the beginning in a program.
*.BM for library code that goes at the end of a program.

Since v 4.4.0 makes those split libraries unnecessary, I've just decided to use *.QLB for my own personal libraries so I can tell at a glance -- "This is a combined, full library with both declares and subs/functions all included in the single file."

Honestly, it'd be nice if others adopted such a convention as well, but for now, I think this is just a "Steve Thing".  Though fingers are crossed that it might hopefully catch on with others as well, rather than them just making *.BI files with subs in them, which might confuse folks with older versions of QB64 who see them and make them think they'll work for them as well.

[Jack]

@SMcNeill
I would have chosen inc instead of lib

[SMcNeill]

@SMcNeill
I would have chosen inc instead of lib

@a740g suggested I swap to something else as well, and after a wee bit of back and forth, and some digging into old memories and documentation, I swapped over to *.QLB.

QB45 supported two different library file formats:
*.LIB -- this was the one I remembered, and an influence on my own use of *.LIB.  It, however, was the library which worked off the LINKER.
*.QLB -- this was the other format which QB45 supported, and it's basically the libraries which you could add via the IDE.

So QLB just makes more sense (Quick Library), and it doesn't have the same connections as *.lib has in modern extensions (MSVC and such).  So I've swapped these over to QLB extensions and will *hopefully* keep them that way forever more.  LOL!