Utils API

The Utils module provides consolidated utility functions for size parsing, duration parsing, time manipulation, and date formatting.

Overview

const logly = @import("logly");
const Utils = logly.Utils;

// Parse size strings
const bytes = Utils.parseSize("10MB"); // 10485760

// Parse duration strings
const ms = Utils.parseDuration("5m"); // 300000

// Time utilities
const tc = Utils.nowComponents();
std.debug.print("Year: {d}\n", .{tc.year});

// Date formatting
var buf: [32]u8 = undefined;
const date = try Utils.formatIsoDate(&buf, tc);

Quick Reference: Method Aliases

Full Method	Alias(es)	Description
formatDatePattern()	format()	Format date with pattern
formatDateToBuf()	formatToBuf()	Format date to buffer

Size Parsing

parseSize

Parses a size string into bytes.

pub fn parseSize(s: []const u8) ?u64

Supported units (case insensitive):

• B - Bytes
• K, KB - Kilobytes (×1024)
• M, MB - Megabytes (×1024²)
• G, GB - Gigabytes (×1024³)
• T, TB - Terabytes (×1024⁴)

Examples:

Utils.parseSize("1024")     // 1024
Utils.parseSize("10KB")     // 10240
Utils.parseSize("5 MB")     // 5242880 (whitespace allowed)
Utils.parseSize("1GB")      // 1073741824

formatSize

Formats a byte size into a human-readable string.

pub fn formatSize(allocator: std.mem.Allocator, bytes: u64) ![]u8

Example:

const str = try Utils.formatSize(allocator, 5242880);
defer allocator.free(str);
// str = "5.00 MB"

Duration Parsing

parseDuration

Parses a duration string into milliseconds.

pub fn parseDuration(s: []const u8) ?i64

Supported units (case insensitive):

• ms - Milliseconds
• s - Seconds (×1000)
• m - Minutes (×60000)
• h - Hours (×3600000)
• d - Days (×86400000)

Examples:

Utils.parseDuration("1000ms") // 1000
Utils.parseDuration("30s")    // 30000
Utils.parseDuration("5m")     // 300000
Utils.parseDuration("2h")     // 7200000
Utils.parseDuration("1d")     // 86400000

formatDuration

Formats milliseconds into a human-readable string.

pub fn formatDuration(allocator: std.mem.Allocator, ms: i64) ![]u8

Time Utilities

TimeComponents

Structure containing extracted time components.

pub const TimeComponents = struct {
    year: i32,
    month: u8,      // 1-12
    day: u8,        // 1-31
    hour: u64,      // 0-23
    minute: u64,    // 0-59
    second: u64,    // 0-59
};

fromEpochSeconds

Extracts time components from a Unix timestamp (seconds).

pub fn fromEpochSeconds(timestamp: i64) TimeComponents

fromMilliTimestamp

Extracts time components from a millisecond timestamp.

pub fn fromMilliTimestamp(timestamp: i64) TimeComponents

fromMilliTimestampLocal

Extracts local-time components from a millisecond timestamp.

pub fn fromMilliTimestampLocal(timestamp: i64) TimeComponents

localUtcOffsetMinutes

Returns local UTC offset (in minutes) for a millisecond timestamp. The result is bounded to Constants.TimeConstants.minUtcOffsetMinutes through Constants.TimeConstants.maxUtcOffsetMinutes.

pub fn localUtcOffsetMinutes(timestamp: i64) i16

writeUtcOffset

Writes a UTC offset in +HH:MM/-HH:MM form.

pub fn writeUtcOffset(writer: anytype, offsetMinutes: i16) !void

writeUtcOffsetCompact

Writes a compact UTC offset in +HHMM/-HHMM form.

pub fn writeUtcOffsetCompact(writer: anytype, offsetMinutes: i16) !void

nowComponents

Gets current time components.

pub fn nowComponents() TimeComponents

currentSeconds

Returns current Unix timestamp in seconds.

pub fn currentSeconds() i64

currentMillis

Returns current timestamp in milliseconds.

pub fn currentMillis() i64

currentNanos

Returns current timestamp in nanoseconds.

pub fn currentNanos() i128

isSameDay

Checks if two timestamps are on the same day.

pub fn isSameDay(ts1: i64, ts2: i64) bool

isSameHour

Checks if two timestamps are in the same hour.

pub fn isSameHour(ts1: i64, ts2: i64) bool

startOfDay

Returns the start of the day (midnight) as epoch seconds.

pub fn startOfDay(timestamp: i64) i64

startOfHour

Returns the start of the hour as epoch seconds.

pub fn startOfHour(timestamp: i64) i64

elapsedMs

Calculates elapsed time in milliseconds since startTime.

pub fn elapsedMs(startTime: i64) u64

elapsedSeconds

Calculates elapsed time in seconds since startTime.

pub fn elapsedSeconds(startTime: i64) u64

durationSinceNs

Calculates duration in nanoseconds since a start time.

pub fn durationSinceNs(startTime: i128) u64

Math & Rate Utilities

calculateRate

Calculates a rate (0.0 to 1.0) given a numerator and denominator.

pub fn calculateRate(numerator: u64, denominator: u64) f64

calculateErrorRate

Calculates error rate (0.0 to 1.0) given error count and total count.

pub fn calculateErrorRate(errors: u64, total: u64) f64

calculateAverage

Calculates average value given a sum and count.

pub fn calculateAverage(sum: u64, count: u64) f64

calculateThroughput

Calculates throughput (items/sec) given a count and duration in nanoseconds.

pub fn calculateThroughput(count: u64, elapsedNs: u64) f64

calculateBytesPerSecond

Calculates bytes per second given bytes and duration in milliseconds.

pub fn calculateBytesPerSecond(bytes: u64, elapsedMs: i64) f64

calculateCRC32

Calculates CRC32 checksum of data.

pub fn calculateCRC32(data: []const u8) u32

lzmaHash

Calculates LZMA hash for match finding.

pub fn lzmaHash(data: []const u8, len: usize) u14

getCompressionExtension

Returns the canonical file extension for a given compression algorithm. Useful when generating archive or compressed file names consistently across rotation, scheduler, and compression utilities.

pub fn getCompressionExtension(algo: anytype) []const u8

Example:

const ext = Utils.getCompressionExtension(CompressionAlgorithm.zstd); // ".zst"

Note: Returns an empty string for .none.

Trace Context Utilities

TraceparentContext

Parsed W3C trace context fields returned by parseTraceparentHeader.

pub const TraceparentContext = struct {
    version: []const u8,
    traceId: []const u8,
    spanId: []const u8,
    flags: []const u8,
    sampled: bool,
};

TraceparentError

Errors returned by formatTraceparentHeader validation.

pub const TraceparentError = error{
    InvalidTraceId,
    InvalidSpanId,
};

parseTraceparentHeader

Parses a W3C traceparent header.

Expected format: 00-<32_hex_trace_id>-<16_hex_span_id>-<2_hex_flags>.

pub fn parseTraceparentHeader(header: []const u8) ?TraceparentContext

Returns null for malformed headers, invalid hex values, or all-zero trace/span IDs.

formatTraceparentHeader

Formats a W3C traceparent header string from validated IDs.

pub fn formatTraceparentHeader(
    allocator: std.mem.Allocator,
    traceId: []const u8,
    spanId: []const u8,
    sampled: bool
) ![]u8

Returns:

• TraceparentError.InvalidTraceId when traceId is invalid.
• TraceparentError.InvalidSpanId when spanId is invalid.

Example:

const traceparent = try Utils.formatTraceparentHeader(
    allocator,
    "4bf92f3577b34da6a3ce929d0e0e4736",
    "00f067aa0ba902b7",
    true,
);
defer allocator.free(traceparent);

Date Formatting

formatDatePattern

Formats a date/time using a custom pattern.

pub fn formatDatePattern(
    writer: anytype,
    fmt: []const u8,
    year: i32,
    month: u8,
    day: u8,
    hour: u64,
    minute: u64,
    second: u64,
    millis: u64
) !void

formatDatePatternWithOffset

Formats a date/time pattern and enables timezone tokens (ZZZ, ZZ).

pub fn formatDatePatternWithOffset(
    writer: anytype,
    fmt: []const u8,
    year: i32,
    month: u8,
    day: u8,
    hour: u64,
    minute: u64,
    second: u64,
    millis: u64,
    timezoneOffsetMinutes: i16
) !void

Supported tokens:

Token	Description
YYYY	4-digit year
YY	2-digit year
ZZZ	Timezone offset (+HH:MM)
MM	2-digit month (01-12)
DD	2-digit day (01-31)
HH	2-digit hour (00-23)
mm	2-digit minute (00-59)
ss	2-digit second (00-59)
ZZ	Timezone offset (+HHMM)
M	1-2 digit month
D	1-2 digit day
H	1-2 digit hour

formatDateToBuf

Formats a date/time to a buffer.

pub fn formatDateToBuf(buf: []u8, fmt: []const u8, year: i32, month: u8, day: u8, hour: u64, minute: u64, second: u64, millis: u64) ![]u8

formatDateToBufWithOffset

Formats a date/time pattern to a buffer with timezone token support.

pub fn formatDateToBufWithOffset(buf: []u8, fmt: []const u8, year: i32, month: u8, day: u8, hour: u64, minute: u64, second: u64, millis: u64, timezoneOffsetMinutes: i16) ![]u8

formatIsoDate

Formats an ISO 8601 date (YYYY-MM-DD).

pub fn formatIsoDate(buf: []u8, tc: TimeComponents) ![]u8

formatIsoTime

Formats an ISO 8601 time (HH:MM:SS).

pub fn formatIsoTime(buf: []u8, tc: TimeComponents) ![]u8

formatIsoDateTime

Formats an ISO 8601 datetime (YYYY-MM-DDTHH:MM:SS).

pub fn formatIsoDateTime(buf: []u8, tc: TimeComponents) ![]u8

formatFilenameSafe

Formats a filename-safe datetime (YYYY-MM-DD_HH-MM-SS).

pub fn formatFilenameSafe(buf: []u8, tc: TimeComponents) ![]u8

Pattern Matching

matchRegexPattern

Anchored regex-like matching starting from the beginning of the string.

pub fn matchRegexPattern(input: []const u8, pattern: []const u8) ?usize

Supported Syntax:

• . - Any character
• * - Zero or more of previous token
• + - One or more of previous token
• ? - Zero or one of previous token
• \d, \D - Digit / Non-digit
• \w, \W - Alphanumeric + `` / Non-alphanumeric
• \s, \S - Whitespace / Non-whitespace

findRegexPattern

Searches for the first occurrence of a regex pattern anywhere in the string.

pub fn findRegexPattern(input: []const u8, pattern: []const u8) ?[]const u8

Example:

if (Utils.findRegexPattern("error at line 42", "\\d+")) |match| {
    // match = "42"
}

String & Redaction Utilities

replaceString

Replaces all occurrences of a substring with a replacement string. Allocates a new string for the result.

pub fn replaceString(allocator: std.mem.Allocator, input: []const u8, needle: []const u8, replacement: []const u8) ![]u8

maskString

Masks a string for redaction purposes. Supports full masking, partial start/end, and middle masking.

pub fn maskString(
    allocator: std.mem.Allocator,
    value: []const u8,
    maskChar: u8,
    startReveal: usize,
    endReveal: usize,
    mode: enum { full, partialStart, partialEnd, maskMiddle }
) ![]u8

Modes:

• full: Masks the entire string (result length = input length).
• partialStart: Shows the beginning of the string, masks the rest.
• partialEnd: Shows the end of the string, masks the beginning.
• maskMiddle: Shows start and end, masks the middle (e.g., credit cards).

computeRedactionHash

Computes a short SHA256 hash (first 8 bytes) formatted as hex for consistent redaction replacement.

pub fn computeRedactionHash(allocator: std.mem.Allocator, value: []const u8) ![]u8

Format: [HASH:<16_char_hex>]

I/O Utilities

defaultIo / io

Returns a stateless single-threaded std.Io handle targeting standard I/O and process-level file systems. This serves as the default fallback for all Logly subsystems when explicit I/O handles are omitted.

pub fn defaultIo() std.Io;
pub const io = defaultIo;

Usage:

const io_handle = logly.defaultIo(); // or logly.Utils.defaultIo()

General Utilities

clamp

Clamps a value between min and max bounds.

pub fn clamp(comptime T: type, value: T, minVal: T, max_val: T) T

safeToUnsigned

Safely converts a signed integer to unsigned (returns 0 for negatives).

pub fn safeToUnsigned(comptime T: type, value: anytype) T

min / max

Returns the minimum or maximum of two values.

pub fn min(comptime T: type, a: T, b: T) T
pub fn max(comptime T: type, a: T, b: T) T

Usage Example

const std = @import("std");
const logly = @import("logly");

pub fn main() !void {
    // Parse configuration sizes
    const maxSize = logly.Utils.parseSize("10MB") orelse 10485760;
    const timeout = logly.Utils.parseDuration("30s") orelse 30000;
    
    // Get current time
    const now = logly.Utils.nowComponents();
    
    // Format for display
    var buf: [32]u8 = undefined;
    const date_str = try logly.Utils.formatIsoDate(&buf, now);
    std.debug.print("Today: {s}\n", .{date_str});
    
    // Calculate elapsed time
    const start = logly.Utils.currentMillis();
    // ... do work ...
    const elapsed = logly.Utils.elapsedMs(start);
    std.debug.print("Elapsed: {d}ms\n", .{elapsed});
}

See Also

• Config API - Configuration options
• Rotation Guide - Log rotation