// SPDX-FileCopyrightText: © 2026 Jeffrey C. Ollie // SPDX-License-Identifier: MIT //! Query-string manipulation. //! //! Every function returns a *new* slice rather than mutating in place, matching //! the immutability of `Uri`. The returned slice's `QueryParam` strings are //! borrowed from the inputs, so the result lives only as long as they do; //! `Uri`'s wrappers deep-copy it into the new URI's arena. const std = @import("std"); const components = @import("components.zig"); const QueryParam = components.QueryParam; /// Index of the first parameter named `name`, if any. pub fn find(query: []const QueryParam, name: []const u8) ?usize { for (query, 0..) |param, i| { if (std.mem.eql(u8, param.key, name)) return i; } return null; } /// Index of the last parameter named `name`, if any. pub fn findLast(query: []const QueryParam, name: []const u8) ?usize { var i = query.len; while (i > 0) { i -= 1; if (std.mem.eql(u8, query[i].key, name)) return i; } return null; } /// The first parameter named `name`, if any. Its `value` is null when the key /// appeared bare, so `?flag` and `?flag=` stay distinguishable. pub fn first(query: []const QueryParam, name: []const u8) ?QueryParam { const i = find(query, name) orelse return null; return query[i]; } /// The last parameter named `name`, if any. /// /// Which of the two you want depends on the server: a repeated parameter has /// no meaning in RFC 3986, and receivers disagree about whether the first or /// the last occurrence wins. `get` returns every value if you would rather /// decide for yourself. pub fn last(query: []const QueryParam, name: []const u8) ?QueryParam { const i = findLast(query, name) orelse return null; return query[i]; } /// Every value recorded for `name`, in order. Only the returned array is /// allocated; the values themselves are borrowed from `query`. pub fn get(alloc: std.mem.Allocator, query: []const QueryParam, name: []const u8) ![]const ?[]const u8 { var count: usize = 0; for (query) |param| { if (std.mem.eql(u8, param.key, name)) count += 1; } const out = try alloc.alloc(?[]const u8, count); var n: usize = 0; for (query) |param| { if (std.mem.eql(u8, param.key, name)) { out[n] = param.value; n += 1; } } return out; } /// Append `name=value` (or a bare `name` when `value` is null), keeping any /// parameter that already uses that name. pub fn add( alloc: std.mem.Allocator, query: []const QueryParam, name: []const u8, value: ?[]const u8, ) ![]const QueryParam { const out = try alloc.alloc(QueryParam, query.len + 1); @memcpy(out[0..query.len], query); out[query.len] = .{ .key = name, .value = value }; return out; } /// Make `name` appear exactly once, with `value`. /// /// The first existing parameter with that name is overwritten in place so that /// the query's ordering is preserved; any later duplicates are dropped. If the /// name is absent the parameter is appended. /// /// (Python's `hyperlink` also appends-if-absent, but inserts before the last /// element rather than at the end; this appends, which is what the docstring /// there describes.) pub fn set( alloc: std.mem.Allocator, query: []const QueryParam, name: []const u8, value: ?[]const u8, ) ![]const QueryParam { const idx = find(query, name) orelse return add(alloc, query, name, value); var count: usize = 0; for (query) |param| { if (std.mem.eql(u8, param.key, name)) count += 1; } const out = try alloc.alloc(QueryParam, query.len - count + 1); var n: usize = 0; for (query, 0..) |param, i| { if (i == idx) { out[n] = .{ .key = name, .value = value }; n += 1; } else if (!std.mem.eql(u8, param.key, name)) { out[n] = param; n += 1; } } return out; } /// Drop every parameter named `name`. pub fn remove(alloc: std.mem.Allocator, query: []const QueryParam, name: []const u8) ![]const QueryParam { return removeWhere(alloc, query, name, null, null); } /// Drop parameters named `name`, optionally only those whose value matches /// `value`, and optionally only the first `limit` of them. /// /// `value` is a double optional: null means "any value", `.{null}` means "only /// the bare `?name` form", and `.{"v"}` means "only where the value is `v`". pub fn removeWhere( alloc: std.mem.Allocator, query: []const QueryParam, name: []const u8, value: ??[]const u8, limit: ?usize, ) ![]const QueryParam { const matches = struct { fn f(param: QueryParam, n: []const u8, v: ??[]const u8) bool { if (!std.mem.eql(u8, param.key, n)) return false; const want = v orelse return true; if (want == null or param.value == null) { return (want == null) == (param.value == null); } return std.mem.eql(u8, want.?, param.value.?); } }.f; var removed: usize = 0; for (query) |param| { if (limit != null and removed >= limit.?) break; if (matches(param, name, value)) removed += 1; } const out = try alloc.alloc(QueryParam, query.len - removed); var n: usize = 0; var dropped: usize = 0; for (query) |param| { const may_drop = limit == null or dropped < limit.?; if (may_drop and matches(param, name, value)) { dropped += 1; continue; } out[n] = param; n += 1; } return out; }