Version API

Version parsing and comparison utilities.

Types

VersionRelation

Result of comparing two versions.

pub const VersionRelation = enum {
    local_newer,   // Local version is newer than remote
    remote_newer,  // Remote version is newer (update available)
    equal,         // Both versions are equal
    unknown,       // Cannot determine relationship

    /// Returns true if remote is newer (update available)
    pub fn hasUpdate(self: VersionRelation) bool;
};

VersionComparator

Version comparison strategy.

pub const VersionComparator = struct {
    /// Parse a raw version string into normalized form
    parse: *const fn (allocator: std.mem.Allocator, raw: []const u8) ParseError![]const u8,

    /// Compare two parsed version strings
    compare: *const fn (local: []const u8, remote: []const u8) VersionRelation,

    pub const ParseError = error{
        InvalidFormat,
        OutOfMemory,
    };
};

SemanticVersion

Parsed semantic version.

pub const SemanticVersion = struct {
    major: u32,
    minor: u32,
    patch: u32,
    prerelease: ?[]const u8 = null,
    build_metadata: ?[]const u8 = null,

    /// Parse a semantic version string
    pub fn parse(input: []const u8) !SemanticVersion;

    /// Compare two semantic versions
    pub fn compare(self: SemanticVersion, other: SemanticVersion) VersionRelation;

    /// Format the version as a string
    pub fn format(...) !void;
};

Built-in Comparators

semantic

Semantic versioning comparator (default).

pub const semantic: VersionComparator;

Supports:

• X.Y.Z format
• Optional v prefix
• Prerelease identifiers (-alpha.1)
• Build metadata (+build.123)

Examples:

• 1.0.0 < 1.0.1
• 1.0.0-alpha < 1.0.0
• v1.0.0 = 1.0.0

numeric

Numeric version comparator.

pub const numeric: VersionComparator;

Compares versions as sequences of numbers.

Examples:

• 1.2 < 1.10 (numeric, not lexical)
• 1.2.3.4 < 1.2.3.5

lexical

Lexical (string) comparator.

pub const lexical: VersionComparator;

Simple alphabetical string comparison.

Examples:

• alpha < beta
• release-1 < release-2

date_based

Calendar versioning comparator.

pub const date_based: VersionComparator;

Supports:

• YYYY.MM.DD format
• YYYYMMDD format

Examples:

• 2024.01.01 < 2024.06.15

Functions

compareVersions

Compare two version strings using a comparator.

pub fn compareVersions(
    allocator: std.mem.Allocator,
    comparator: VersionComparator,
    local: []const u8,
    remote: []const u8,
) !VersionRelation;

Parameters

• allocator: Memory allocator for parsing
• comparator: Version comparison strategy
• local: Current/local version string
• remote: Remote/latest version string

Returns

A VersionRelation indicating the comparison result.

Errors

• InvalidFormat: Version string could not be parsed
• OutOfMemory: Memory allocation failed

Example

const relation = try updater.version.compareVersions(
    allocator,
    updater.version.semantic,
    "1.0.0",
    "2.0.0",
);

if (relation.hasUpdate()) {
    std.debug.print("Update available!\n", .{});
}

Creating Custom Comparators

const myComparator = VersionComparator{
    .parse = myParseFn,
    .compare = myCompareFn,
};

fn myParseFn(allocator: std.mem.Allocator, raw: []const u8) ![]const u8 {
    // Parse and normalize the version string
    // Return allocated copy
    return allocator.dupe(u8, raw);
}

fn myCompareFn(local: []const u8, remote: []const u8) VersionRelation {
    // Compare the parsed versions
    return .equal;
}

SemanticVersion Methods

parse

pub fn parse(input: []const u8) !SemanticVersion;

Parse a semantic version string.

Example

const v = try SemanticVersion.parse("1.2.3-alpha+build");
// v.major = 1
// v.minor = 2
// v.patch = 3
// v.prerelease = "alpha"
// v.build_metadata = "build"

compare

pub fn compare(self: SemanticVersion, other: SemanticVersion) VersionRelation;

Compare this version with another.

Example

const v1 = try SemanticVersion.parse("1.0.0");
const v2 = try SemanticVersion.parse("2.0.0");
const relation = v1.compare(v2);  // .remote_newer