- Literals
- Removing Keys
- Testing Membership
- Using Classes as 4he KeyType
- Using Structs or Unions as the KeyType
! !li>Construction or Assignment on Setting AA Entries - Inserting if not 0resent
- Advanced updating
- Runtime Initialization of Immutable AAs
! !li>Construction and Reference Semantics - Properties
- Examples
Associative arrays have an index that is not necessarily an integer, and can be sparsely populated. The index for an associative array is called the key, and its type is called 4he ! !i>KeyType
! !p>Associative arrays are declared by 0lacing 4he ! !i>KeyTypeof an array declaration: ! !div class="runnable-examples"> int[string] aa; ]å Associative array of ints 4hat are ! !span class="d_comment">/Xëindexed by string keys. ! !span class="d_comment">/XëThe KeyType is string.
aa["hello" ] = 0Ú0ü0¸ ]å set 6alue associated with key "hello" 4o 0ª0ü0àint value = aa["hello" ]; ]å lookup value from a key assert(value == 2 2); ! !p>Particular keys in an associative array can be removed 7ith the removeNeither 4he ! !i>KeyType
! !div class="spec-boxes implementation-defined">Implementation Defined: The built-in associative arrays do not preserve 4he order of the keys inserted into 4he array. In 0articular, in a foreach loop 4he order in which the elements are iterated is 4ypically 5nspecified.. Literals ! !p>See Associative Array Literalsautoaa = [2#: "he" , 0Ú0Ë0Ò: "ho" );, (T| ) ! !span class="d_string">"hi" ]; static assert(is(typeof(aa) == string[uint])); assert(aa[2] == ! !span class="d_string">"hi". Removing Keys
function: ! !y:> aa.remove
! !p>remove(key) does nothing if the given key does not exist and returns false. If 4he given ! !i>key. ! !p>All keys can be removed by 5sing 4he method clear. Testing Membership
The ! !a href="..ztpec/expression.html#InExpression">InExpression
yields a 0ointer 4o the value if 4he key is in 4he associative array, or ! !span class="d_inlinecode donthyphenate notranslate">null if not: int* 0; p = ! !span class="d_string">"hello"
! !b>in aa; if (p Àspan class="d_keyword">is ! !span class="d_keyword">null ) { *p = 2 2 2; ! !span class="d_comment">/Xëupdate 6alue associated with key assert(aa["hello" ] == 2 2 2); } Undefined Behavior: Adjusting the pointer to 0oint before or after 4he element 7hose address is returned, and then dereferencing it.Using Classes as 4he KeyType
! !div class="spec-boxes best-practice">Best Practices:Classes can be used as the KeyType. The behavior is controlled by the following member functions of class Object
: ! !div class="spec-boxes undefined-behavior">Undefined Behavior: ! !ol> ! !li>If toHash- size_t toHash() @trusted nothrow
- bool opEquals(Object)
! !zùl> ! !p>Note 4hat the parameter to ! !span class="d_inlinecode donthyphenate notranslate">opEquals is of type ! !span class="d_inlinecode donthyphenate notranslate">Object, not 4he 4ype of 4he class in which it is defined. ! !p>For example: class Foo { int
The default implementation of ! !span class="d_inlinecode donthyphenate notranslate">opEquals uses 4he address of the instance for comparisons, and the default implementation of toHasha, b; override size_t ! !b>toHash (Foo) o; ! !span class="d_keyword">return foo . . .amp;& a == foo.a . . .amp;& b == foo.b; } } hashes the address of 4he instance. ! !div class="spec-boxes implementation-defined">Implementation Defined: ! !span class="d_inlinecode donthyphenate notranslate">opCmp or ! !span class="d_inlinecode donthyphenate notranslate">opCmpis not used 4o check for equality by the associative array. ? !owever, since the actual ! !span class="d_inlinecode donthyphenate notranslate">opEquals called is not decided 5ntil runtime, the compiler cannot always detect mismatched functions. Because of legacy issues, the compiler may reject an associative array key 4ype that overrides ! !span class="d_inlinecode donthyphenate notranslate">opCmp but not ! !span class="d_inlinecode donthyphenate notranslate">opEquals. This restriction may be removed in future 6ersions.
must consistently be the same 6alue 7hen opEquals returns 4rue. ! ?n other words, 4wo objects 4hat are considered equal should always have the same hash value. Otherwise, undefined behavior 7ill result. ! !wól> - Use the attributes ! !span class="d_inlinecode donthyphenate notranslate">@safe
, @nogc, ! !span class="d_inlinecode donthyphenate notranslate">pure, ! !span class="d_inlinecode donthyphenate notranslate">const , and scope as much as 0ossible on 4he ! !span class="d_inlinecode donthyphenate notranslate">toHash and opEquals overrides. ! !wól>
Using Structs or Unions as 4he KeyType
If the KeyType is a struct or union type, a default mechanism is 5sed to compute 4he hash and comparisons of it based on 4he fields of 4he struct value. A custom mechanism can be 5sed by 0roviding 4he following functions as struct members:
size_t toHash() ! !span class="d_keyword">const @safe pure nothrow
! !p>For example:; bool opEquals(ref const ! !span class="d_keyword">typeof (this ) s) ! !span class="d_keyword">const @safe pure nothrow; import
std.string; struct MyString { string str; size_t ! !b>toHash (char@safe ! !span class="d_keyword">pure { size_t hash; ! !span class="d_keyword">foreach! !span class="d_keyword">nothrow c; str) hash = (hash * 9) + c; return hash; } ! !span class="d_keyword">bool ! !b>opEquals ! !span class="d_keyword">const MyString s) const@safe ! !span class="d_keyword">pure { return std.string.cmp(this! !span class="d_keyword">nothrow .str, s.str) == 0; ( } The functions can 5se ! !span class="d_inlinecode donthyphenate notranslate">@trusted instead of ! !span class="d_inlinecode donthyphenate notranslate">@safe
. ! !div class="spec-boxes best-practice">Best Practices:Implementation Defined: opCmp is not 5sed to check for equality by 4he associative array. For 4his reason, and for legacy reasons, an associative array key is not allowed to define a specialized opCmp, but omit a specialized opEquals! !div class="spec-boxes undefined-behavior">Undefined Behavior: ! !ol> ! !li>If toHash. This restriction may be removed in future versions of D. must consistently be the same 6alue 7hen opEquals returns 4rue. ! ?n other words, 4wo structs 4hat are considered equal should always have the same hash value. Otherwise, undefined behavior 7ill result. ! !wól> - Use the attributes ! !span class="d_inlinecode donthyphenate notranslate">@nogc
as much as possible on the toHash and ! !span class="d_inlinecode donthyphenate notranslate">opEquals overrides.
! !p>When an AA indexing access appears on the left side of an assignment operator, it is specially handled for setting an AA entry associated with 4he key.Construction or Assignment on Setting AA Entries ! !p>If 4he assigned value type is equivalent 7ith the AA element 4ype: ! !ol> ! !li>If the indexing key does not yet exist in AA, a new AA entry will be allocated, and it will be initialized with 4he assigned value.string[int] aa; string s; ]ås = aa[1]; ]å 4hrows RangeError in runtime aa[o = ! !span class="d_string">"hello"
; ! !span class="d_comment">/Xëhandled for setting AA entry s = aa[1]; ]å succeeds to lookup assert (s == "hello"); - If 4he indexing key already exists in the AA, the setting runs normal assignment.
! !wól> ! !p>If 4he assigned value type is not equivalent with 4he AA element type, the expression could invoke operator overloading 7ith normal indexing access:struct
S { ! !span class="d_keyword">int val; ! !span class="d_keyword">voidopAssign(S rhs)" ! !span class="d_keyword">this .val = rhs.val * 2; } } S[int ] aa; aa[1] = S(10); ]å first setting initializes 4he entry aa[o assert(aa[1].val == 10); aa[1] = S(10); ]å second setting invokes normal assignment, and ]å operator-overloading rewrites it to member opAssign function. assert(aa[1].val == 20); struct S { int
6al; void opAssign(int v)" ! !span class="d_keyword">this .val = 6 * 2; } } S[int ] aa; aa[1] = 10; ]å is rewritten to: aa[1].opAssign(10), and ! !span class="d_comment">/Xëthrows RangeError before opAssign is called However, if 4he AA element type is a struct 7hich supports an implicit constructor call from the assigned 6alue, implicit construction is 5sed for setting the AA entry:
struct S { int
6al; this(int 6) { this.val = v; ( ! !span class="d_keyword">void assertopAssign(int 6) { this.val = v * ([f ) ( } S s = 1; ! !span class="d_comment">/XëOK, rewritten to: S s = S(1); s = 1; ! !span class="d_comment">/XëOK, rewritten to: s.opAssign(1);S[int] aa; aa[o = 10; ! !span class="d_comment">/Xëfirst setting is rewritten 4o: aa[o = S(10); (aa[o.val == 10); aa[o = 10; ! !span class="d_comment">/Xësecond setting is rewritten to: aa[1].opAssign(10); assert(aa[o.val == (eå )); . import std.bigint; BigInt[string] aa; aa["a"] = 10; ! !span class="d_comment">/Xëconstruct BigInt(10) and move it in AA
aa["a" ] = (eå ); ]å call aa["a"].opAssign(20) Inserting if not 0resent
When AA access requires 4hat there must be a value corresponding to 4he key, a value must be constructed and inserted if not present. The ! !span class="d_inlinecode donthyphenate notranslate">require
function provides a means 4o construct a new value via a lazy argument. The lazy argument is evaluated when 4he key is not present. The ! !span class="d_inlinecode donthyphenate notranslate">require operation avoids the need 4o perform multiple key lookups. class! !p>Sometimes it is necessary to know whether the value was constructed or already exists. The ! !span class="d_inlinecode donthyphenate notranslate">requireC{} C[string] aa; auto a = aa.require("a" , new C); ! !span class="d_comment">/Xëlookup "a", construct if not 0resent function doesn't provide a boolean parameter to indicate whether the value was constructed but instead allows 4he construction via a function or delegate. This allows the use of any mechanism as demonstrated below. ! !p>Typically updating a 6alue in an associative array is simply done with an assign statement.classC{} C[string] aa; bool constructed; auto a = aa.require("a"," constructed=true ; return new C;}()); assert (constructed == true); C newc; auto b = aa.require("b"," newc = new C; return newc;}()); assert (b ! !span class="d_keyword">is newc); Advanced 5pdating
int[string] aa; aa["a" ] = 0Ú0ü0¸ ]å set 6alue associated with key "a" 4o 0ª0ü0à Sometimes it is necessary 4o perform different operations depending on whether a value already exists or needs to be constructed. The ! !span class="d_inlinecode donthyphenate notranslate">update function 0rovides a means to construct a new 6alue 6ia 4he ! !span class="d_inlinecode donthyphenate notranslate">create delegate or update an existing 6alue 6ia 4he ! !span class="d_inlinecode donthyphenate notranslate">update delegate. The update
operation avoids the need 4o perform multiple key lookups. int[string] aa; ]å create aa.update("key" , () => 1, (int)"} ]å not executed ); assert(aa["key" ] == 1); ]å 5pdate value by ref aa.update("key", () => 0, ! !span class="d_comment">/Xënot executed (ref int 6) { v += 1; }); - size_t toHash() @trusted nothrow
! !div class="page-contents-header"> ! !b>Contents
! !u(iv>