mir.string_map

enum auto isStringMap(T);

Checks if the type is instance of StringMap.

Examples:

static assert(isStringMap!(StringMap!int));
static assert(isStringMap!(const StringMap!int));
static assert(!isStringMap!int);

struct StringMap(T);

Ordered string-value associative array with extremely fast lookup.

Parameters:

T	mutable value type, can be instance of Algebraic  for example.
U	an unsigned type that can hold an index of keys. U.max must be less then the maximum possible number of struct members.

Examples:

class C
{
    this(int x) { this.x = x; }
    int x;
    bool opEquals(scope const C rhs) const scope @safe pure nothrow @nogc
    {
        return x == rhs.x;
    }

    override size_t toHash() @safe const scope pure nothrow @nogc
    {
        return x;
    }
}
StringMap!(const C) table;
const v0 = new C(42);
const v1 = new C(43);
table["0"] = v0;
table["1"] = v1;
assert(table.keys == ["0", "1"]);
assert(table.values == [v0, v1]); // TODO: qualify unittest as `pure` when this is inferred `pure`
static assert(is(typeof(table.values) == const(C)[]));

Examples:

StringMap!int table;
table["L"] = 3;
table["A"] = 2;
table["val"] = 1;
assert(table.keys == ["L", "A", "val"]);
assert(table.values == [3, 2, 1]);
assert(table["A"] == 2);
table.values[2] += 10;
assert(table["A"] == 2);
assert(table["L"] == 3);
assert(table["val"] == 11);
assert(table.keys == ["L", "A", "val"]);
assert(table.values == [3, 2, 11]);
table.remove("A");
assert(table.keys == ["L", "val"]);
assert(table.values == [3, 11]);
assert(table["L"] == 3);
assert(table["val"] == 11);

assert(table == table);

// sorting
table["A"] = 2;
table.sort;
assert(table.keys == ["A", "L", "val"]);
assert(table.values == [2, 3, 11]);
assert(table["A"] == 2);
assert(table["L"] == 3);
assert(table["val"] == 11);

Examples:

static void testEquals(X, Y)()
{
    X x;
    Y y;
    assert(x == y);

    x["L"] = 3;
    assert(x != y);
    x["A"] = 2;
    assert(x != y);
    x["val"] = 1;
    assert(x != y);

    y["val"] = 1;
    assert(x != y);
    y["L"] = 3;
    assert(x != y);
    y["A"] = 2;
    assert(x == y);

    x = X.init;
    assert(x != y);

    y = Y.init;
    assert(x == y);
}

testEquals!(StringMap!int, StringMap!uint)();
testEquals!(StringMap!int, uint[string])();
testEquals!(uint[string], StringMap!int)();

struct KeyValue;

string key;

T value;

const pure nothrow @nogc @trusted size_t toHash() scope;

hashOf Implementation. Doesn't depend on order

const pure nothrow @nogc @trusted bool opEquals(V)(scope const StringMap!V rhs) scope;

const bool opEquals(K, V)(scope const const(V)[const(K)] rhs) scope
if (is(typeof(K.init == string.init) : bool) && is(typeof(V.init == T.init) : bool));

== implementation. Doesn't depend on order

pure nothrow @nogc ref @safe auto opAssign()(typeof(null)) return;

Reset the associative array

Examples:

StringMap!int map = ["key" : 1];
map = null;

pure nothrow @nogc @safe this()(typeof(null) aa);

Initialize the associative array with default value.

Examples:

Usefull for default funcion argument.

StringMap!int map = null; //

pure nothrow @trusted this()(T[string] aa);

Constructs an associative array using keys and values from the builtin associative array

Complexity O(n log(n))

Examples:

StringMap!int map = ["key" : 1];
assert(map.findPos("key") == 0);

const string toString()() scope;

const void toString(W)(ref scope W w) scope;

pure nothrow @trusted this()(string[] keys, T[] values);

Constructs an associative array using keys and values.

Parameters:

string[] keys	mutable array of keys
T[] values	mutable array of values Key and value arrays must have the same length.

Complexity O(n log(n))

Examples:

auto keys = ["ba", "a"];
auto values = [1.0, 3.0];
auto map = StringMap!double(keys, values);
assert(map.keys is keys);
assert(map.values is values);

const pure nothrow @nogc @property @safe size_t length()();

Returns:

number of elements in the table.

const pure nothrow @nogc @property @safe bool empty()();

Returns:

number of elements in the table.

Examples:

StringMap!double map;
assert(map.length == 0);
map["a"] = 3.0;
assert(map.length == 1);
map["c"] = 4.0;
assert(map.length == 2);
assert(map.remove("c"));
assert(map.length == 1);
assert(!map.remove("c"));
assert(map.length == 1);
assert(map.remove("a"));
assert(map.length == 0);

const pure nothrow @nogc @property @safe const(string)[] keys()();

Returns a dynamic array, the elements of which are the keys in the associative array. Doesn't allocate a new copy.

The keys returned are guaranteed to be in the ordered inserted as long as no key removals followed by at least one key insertion has been performed.

Complexity O(1)

alias byKey = keys;

Examples:

StringMap!double map;
assert(map.keys == []);
map["c"] = 4.0;
assert(map.keys == ["c"]);
map["a"] = 3.0;
assert(map.keys == ["c", "a"]);
map.remove("c");
assert(map.keys == ["a"]);
map.remove("a");
assert(map.keys == []);
map["c"] = 4.0;
assert(map.keys == ["c"]);

inout pure nothrow @nogc @property @safe inout(T)[] values()();

alias byValue = values;

Returns a dynamic array, the elements of which are the values in the associative array. Doesn't allocate a new copy.

The values returned are guaranteed to be in the ordered inserted as long as no key removals followed by at least one key insertion has been performed.

Complexity O(1)

Examples:

StringMap!double map;
assert(map.byKeyValue == StringMap!double.KeyValue[].init);
map["c"] = 4.0;
map["a"] = 3.0;
assert(map.byKeyValue == [StringMap!double.KeyValue("c", 4.0), StringMap!double.KeyValue("a", 3.0)]);

pure nothrow @nogc @trusted auto byKeyValue(this This)();

Return a range over all elements (key-values pairs) currently stored in the associative array.

The elements returned are guaranteed to be in the ordered inserted as long as no key removals nor no value mutations has been performed.

Examples:

StringMap!double map;
assert(map.values == []);
map["c"] = 4.0;
assert(map.values == [4.0]);
map["a"] = 3.0;
assert(map.values == [4.0, 3.0]);
map.values[0]++;
assert(map.values == [5.0, 3.0]);
map.remove("c");
assert(map.values == [3.0]);
map.remove("a");
assert(map.values == []);
map["c"] = 4.0;
assert(map.values == [4.0]);

pure nothrow @nogc @trusted auto opIndex(this This)();

@trusted auto dup(this This)();

const pure nothrow @property @safe size_t capacity()();

(Property) Gets the current capacity of an associative array. The capacity is the size that the underlaynig slices can grow to before the underlying arrays may be reallocated or extended.

Complexity O(1)

Examples:

StringMap!double map;
assert(map.capacity == 0);
map["c"] = 4.0;
assert(map.capacity >= 1);
map["a"] = 3.0;
assert(map.capacity >= 2);
map.remove("c");
map.assumeSafeAppend;
assert(map.capacity >= 2);

pure nothrow @trusted size_t reserve()(size_t newcapacity);

Reserves capacity for an associative array. The capacity is the size that the underlaying slices can grow to before the underlying arrays may be reallocated or extended.

Examples:

StringMap!double map;
auto capacity = map.reserve(10);
assert(capacity >= 10);
assert(map.capacity == capacity);
map["c"] = 4.0;
assert(map.capacity == capacity);
map["a"] = 3.0;
assert(map.capacity >= 2);
assert(map.remove("c"));
capacity = map.reserve(20);
assert(capacity >= 20);
assert(map.capacity == capacity);

inout nothrow ref inout(typeof(this)) assumeSafeAppend()() return;

Assume that it is safe to append to this associative array. Appends made to this associative array after calling this function may append in place, even if the array was a slice of a larger array to begin with. Use this only when it is certain there are no elements in use beyond the associative array in the memory block. If there are, those elements will be overwritten by appending to this associative array.

Warning Calling this function, and then using references to data located after the given associative array results in undefined behavior.

Returns:

The input is returned.

Examples:

StringMap!double map;
map["c"] = 4.0;
map["a"] = 3.0;
assert(map.capacity >= 2);
map.remove("c");
assert(map.capacity == 0);
map.assumeSafeAppend;
assert(map.capacity >= 2);

pure nothrow @nogc @safe void clear()();

Removes all remaining keys and values from an associative array.

Complexity O(1)

Examples:

StringMap!double map;
map["c"] = 4.0;
map["a"] = 3.0;
map.clear;
assert(map.length == 0);
assert(map.capacity == 0);
map.assumeSafeAppend;
assert(map.capacity >= 2);

pure nothrow @nogc @trusted bool remove()(scope const(char)[] key);

remove(key) does nothing if the given key does not exist and returns false. If the given key does exist, it removes it from the AA and returns true.

Complexity O(log(s)) (not exist) or O(n) (exist), where s is the count of the strings with the same length as they key.

Examples:

StringMap!double map;
map["a"] = 3.0;
map["c"] = 4.0;
assert(map.remove("c"));
assert(!map.remove("c"));
assert(map.remove("a"));
assert(map.length == 0);
assert(map.capacity == 0);
assert(map.assumeSafeAppend.capacity >= 2);

const pure nothrow @nogc @trusted ptrdiff_t findPos()(scope const(char)[] key);

Finds position of the key in the associative array .

Return An index starting from 0 that corresponds to the key or -1 if the associative array doesn't contain the key.

Complexity O(log(s)), where s is the number of the keys with the same length as the input key.

Examples:

StringMap!double map;
map["c"] = 3.0;
map["La"] = 4.0;
map["a"] = 5.0;

assert(map.findPos("C") == -1);
assert(map.findPos("c") == 0);
assert(map.findPos("La") == 1);
assert(map.findPos("a") == 2);

map.remove("c");

assert(map.findPos("c") == -1);
assert(map.findPos("La") == 0);
assert(map.findPos("a") == 1);

inout pure nothrow @nogc inout(T)* opBinaryRight(string op : "in")(scope const(char)[] key);

Complexity O(log(s)), where s is the number of the keys with the same length as the input key.

Examples:

StringMap!double map;
assert(("c" in map) is null);
map["c"] = 3.0;
assert(*("c" in map) == 3.0);

inout pure ref @trusted inout(T) opIndex()(scope const(char)[] key);

Complexity O(log(s)), where s is the number of the keys with the same length as the input key.

Examples:

StringMap!double map;
map["c"] = 3.0;
map["La"] = 4.0;
map["a"] = 5.0;

map["La"] += 10;
assert(map["La"] == 14.0);

pure nothrow ref @trusted T opIndexAssign(R)(auto ref R value, string key);

pure nothrow ref @trusted T opIndexAssign()(T value, string key);

Complexity O(log(s)) (exist) or O(n) (not exist), where s is the count of the strings with the same length as they key.

inout inout(T) get()(scope const(char)[] key, lazy inout(T) defaultValue);

Looks up key; if it exists returns corresponding value else evaluates and returns defaultValue.

Complexity O(log(s)), where s is the number of the keys with the same length as the input key.

Examples:

StringMap!int map;
map["c"] = 3;
assert(map.get("c", 1) == 3);
assert(map.get("C", 1) == 1);

ref T require()(string key, lazy T value = T.init);

Looks up key; if it exists returns corresponding value else evaluates value, adds it to the associative array and returns it.

Complexity O(log(s)) (exist) or O(n) (not exist), where s is the count of the strings with the same length as they key.

Examples:

StringMap!int map = ["aa": 1];
int add3(ref int x) { x += 3; return x; }
assert(add3(map.require("aa", 10)) == 4);
assert(add3(map.require("bb", 10)) == 13);
assert(map.require("a", 100));
assert(map.require("aa") == 4);
assert(map.require("bb") == 13);
assert(map.keys == ["aa", "bb", "a"]);

template toAA()

Converts to a builtin associative array.

Complexity O(n).

Examples:

StringMap!int map = ["k": 1];
int[string] aa = map.toAA;
assert(aa["k"] == 1);

const T[string] toAA()();

ref auto sort(alias less = "a < b")() return;

Sorts table according to the keys

const @trusted int opCmp()(scope const typeof(this) rhs) scope;

opCmp Implementation. Doesn't depend on order

alias serdeKeysProxy = Unqual!T;

template intersectionMap(alias merger)

Examples:

import mir.test: should;
import mir.string_map : StringMap;
auto m0 = StringMap!int(["foo", "bar"], [1, 2]);
auto m1 = StringMap!int(["foo"], [2]);
auto m2 = StringMap!int(["foo"], [3]);
intersectionMap!"a + b"(m0, m1).should == m2;

StringMap!V intersectionMap(V)(StringMap!V a, StringMap!V b);

template unionMap(alias merger)

Examples:

import mir.test: should;
import mir.string_map : StringMap;
auto m0 = StringMap!int(["foo", "bar"], [1, 2]);
auto m1 = StringMap!int(["foo"], [2]);
auto m2 = StringMap!int(["foo", "bar"], [3, 2]);
unionMap!"a + b"(m0, m1).should == m2;

StringMap!V unionMap(V)(StringMap!V a, StringMap!V b);