Skip to content
Standard libraryZig 0.17.1Official documentation
Sourcestd/buf_map.zig

Source line 1

std.buf_map.Allocator

alias

Source line 4

Alias of std.mem.Allocator

std.buf_map.BufMap

container

Source line 9

BufMap copies keys and values before they go into the map and frees them when they get removed.

Fields

hash_map: BufMapHashMap

std.buf_map.BufMap.BufMapHashMap

type

Source line 12

std.buf_map.BufMap.copy

function

Source line 97

fn copy(self: BufMap, value: []const u8) ![]u8

Parameters

self: BufMap
value: []const u8

std.buf_map.BufMap.count

function

Source line 84

Returns the number of KV pairs stored in the map.

pub fn count(self: BufMap) BufMapHashMap.Size

Parameters

self: BufMap

std.buf_map.BufMap.deinit

function

Source line 23

Free the backing storage of the map, as well as all of the stored keys and values.

pub fn deinit(self: *BufMap) void

Parameters

self: *BufMap

std.buf_map.BufMap.free

function

Source line 93

fn free(self: BufMap, value: []const u8) void

Parameters

self: BufMap
value: []const u8

std.buf_map.BufMap.get

function

Source line 71

Return the map's copy of the value associated with a key. The returned string is invalidated if this key is removed from the map.

pub fn get(self: BufMap, key: []const u8) ?[]const u8

Parameters

self: BufMap
key: []const u8

std.buf_map.BufMap.getPtr

function

Source line 64

Find the address of the value associated with a key. The returned pointer is invalidated if the map resizes.

pub fn getPtr(self: BufMap, key: []const u8) ?*[]const u8

Parameters

self: BufMap
key: []const u8

std.buf_map.BufMap.init

function

Source line 17

Create a BufMap backed by a specific allocator. That allocator will be used for both backing allocations and string deduplication.

pub fn init(allocator: Allocator) BufMap

Parameters

allocator: Allocator

std.buf_map.BufMap.iterator

function

Source line 89

Returns an iterator over entries in the map.

pub fn iterator(self: *const BufMap) BufMapHashMap.Iterator

Parameters

self: *const BufMap

std.buf_map.BufMap.put

function

Source line 47

key and value are copied into the BufMap.

pub fn put(self: *BufMap, key: []const u8, value: []const u8) !void

Parameters

self: *BufMap
key: []const u8
value: []const u8

std.buf_map.BufMap.putMove

function

Source line 36

Same as put but the key and value become owned by the BufMap rather than being copied. If putMove fails, the ownership of key and value does not transfer.

pub fn putMove(self: *BufMap, key: []u8, value: []u8) !void

Parameters

self: *BufMap
key: []u8
value: []u8

std.buf_map.BufMap.remove

function

Source line 77

Removes the item from the map and frees its value. This invalidates the value returned by get() for this key.

pub fn remove(self: *BufMap, key: []const u8) void

Parameters

self: *BufMap
key: []const u8

std.buf_map.mem

alias

Source line 3

Alias of std.mem

std.buf_map.std

alias

Source line 1

Alias of std

std.buf_map.StringHashMap

alias

Source line 2

Alias of std.StringHashMap

std.buf_map.testing

alias

Source line 5

Alias of std.testing

Source code

std/buf_map.zig

const std = @import("std.zig");
const StringHashMap = std.StringHashMap;
const mem = std.mem;
const Allocator = mem.Allocator;
const testing = std.testing;

/// BufMap copies keys and values before they go into the map and
/// frees them when they get removed.
pub const BufMap = struct {
    hash_map: BufMapHashMap,

    const BufMapHashMap = StringHashMap([]const u8);

    /// Create a BufMap backed by a specific allocator.
    /// That allocator will be used for both backing allocations
    /// and string deduplication.
    pub fn init(allocator: Allocator) BufMap {
        return .{ .hash_map = BufMapHashMap.init(allocator) };
    }

    /// Free the backing storage of the map, as well as all
    /// of the stored keys and values.
    pub fn deinit(self: *BufMap) void {
        var it = self.hash_map.iterator();
        while (it.next()) |entry| {
            self.free(entry.key_ptr.*);
            self.free(entry.value_ptr.*);
        }

        self.hash_map.deinit();
    }

    /// Same as `put` but the key and value become owned by the BufMap rather
    /// than being copied.
    /// If `putMove` fails, the ownership of key and value does not transfer.
    pub fn putMove(self: *BufMap, key: []u8, value: []u8) !void {
        const get_or_put = try self.hash_map.getOrPut(key);
        if (get_or_put.found_existing) {
            self.free(get_or_put.key_ptr.*);
            self.free(get_or_put.value_ptr.*);
            get_or_put.key_ptr.* = key;
        }
        get_or_put.value_ptr.* = value;
    }

    /// `key` and `value` are copied into the BufMap.
    pub fn put(self: *BufMap, key: []const u8, value: []const u8) !void {
        const value_copy = try self.copy(value);
        errdefer self.free(value_copy);
        const get_or_put = try self.hash_map.getOrPut(key);
        if (get_or_put.found_existing) {
            self.free(get_or_put.value_ptr.*);
        } else {
            get_or_put.key_ptr.* = self.copy(key) catch |err| {
                _ = self.hash_map.remove(key);
                return err;
            };
        }
        get_or_put.value_ptr.* = value_copy;
    }

    /// Find the address of the value associated with a key.
    /// The returned pointer is invalidated if the map resizes.
    pub fn getPtr(self: BufMap, key: []const u8) ?*[]const u8 {
        return self.hash_map.getPtr(key);
    }

    /// Return the map's copy of the value associated with
    /// a key.  The returned string is invalidated if this
    /// key is removed from the map.
    pub fn get(self: BufMap, key: []const u8) ?[]const u8 {
        return self.hash_map.get(key);
    }

    /// Removes the item from the map and frees its value.
    /// This invalidates the value returned by get() for this key.
    pub fn remove(self: *BufMap, key: []const u8) void {
        const kv = self.hash_map.fetchRemove(key) orelse return;
        self.free(kv.key);
        self.free(kv.value);
    }

    /// Returns the number of KV pairs stored in the map.
    pub fn count(self: BufMap) BufMapHashMap.Size {
        return self.hash_map.count();
    }

    /// Returns an iterator over entries in the map.
    pub fn iterator(self: *const BufMap) BufMapHashMap.Iterator {
        return self.hash_map.iterator();
    }

    fn free(self: BufMap, value: []const u8) void {
        self.hash_map.allocator.free(value);
    }

    fn copy(self: BufMap, value: []const u8) ![]u8 {
        return self.hash_map.allocator.dupe(u8, value);
    }
};

test "BufMap" {
    const allocator = std.testing.allocator;
    var bufmap = BufMap.init(allocator);
    defer bufmap.deinit();

    try bufmap.put("x", "1");
    try testing.expect(mem.eql(u8, bufmap.get("x").?, "1"));
    try testing.expect(1 == bufmap.count());

    try bufmap.put("x", "2");
    try testing.expect(mem.eql(u8, bufmap.get("x").?, "2"));
    try testing.expect(1 == bufmap.count());

    try bufmap.put("x", "3");
    try testing.expect(mem.eql(u8, bufmap.get("x").?, "3"));
    try testing.expect(1 == bufmap.count());

    bufmap.remove("x");
    try testing.expect(0 == bufmap.count());

    try bufmap.putMove(try allocator.dupe(u8, "k"), try allocator.dupe(u8, "v1"));
    try bufmap.putMove(try allocator.dupe(u8, "k"), try allocator.dupe(u8, "v2"));
}