MapSetFirstL
Description
Update the value of the first existing entry that matches in_key. This is an update-only operation: if no entry exists for in_key the map is left unchanged and the call reports failure - it does NOT insert. (Use MapInsert to add, or MapSet to replace-or-add.) L-value form takes ownership of in_value on success when the value type has no copy_init handler. The key is always treated as an r-value lookup.
Parameters
| Name | Direction | Description |
|---|---|---|
m |
in,out | Map handle. |
in_key |
in | Lookup key (treated as r-value). |
in_value |
in | Addressable replacement value. |
Success
Returns true. An entry for in_key already existed and the first such entry’s value has been replaced with in_value (the previous value torn down via value_copy_deinit if configured). When value_copy_init is absent the in_value source has been zeroed; otherwise it is unchanged. The in_key source is never zeroed. Map length is unchanged.
Failure
Returns false when no entry exists for in_key (nothing is inserted) or on allocation failure during the value deep-copy. The map and both sources are unchanged.
Usage example (Cross-references)
Usage examples (Cross-references)
- In
Insert.h:522:
#define MapMustSetFirstL(m, in_key, in_value) \
do { \
if (!MapSetFirstL((m), (in_key), (in_value))) { \
LOG_FATAL("MapMustSetFirstL failed"); \
} \- In
Insert.c:519:
// Update-existing path: first value replaced, value source zeroed.
bool result = MapSetFirstL(&map, 11, value);
result = result && (value == 0);
result = result && (MapValueCountForKey(&map, 11) == 1);- In
Insert.c:526:
// Miss path: returns false, value source NOT zeroed, nothing inserted.
int miss = 220;
result = result && !MapSetFirstL(&map, 99, miss);
result = result && (miss == 220);
result = result && !MapContainsKey(&map, 99);