Introduction

You do not truly append one NSDictionary to another because NSDictionary is immutable. The usual solution is to create a mutable copy, add entries from the second dictionary, and optionally convert the result back to an immutable dictionary. The important part is deciding what should happen when both dictionaries contain the same key.

Merge with NSMutableDictionary

In Objective-C, the standard pattern is to start with one dictionary, create a mutable copy, and call addEntriesFromDictionary:.

1#import <Foundation/Foundation.h>
2
3int main(void) {
4    @autoreleasepool {
5        NSDictionary *first = @{@"name": @"Ava", @"role": @"Engineer"};
6        NSDictionary *second = @{@"city": @"Toronto", @"team": @"Platform"};
7
8        NSMutableDictionary *merged = [first mutableCopy];
9        [merged addEntriesFromDictionary:second];
10
11        NSLog(@"%@", merged);
12    }
13
14    return 0;
15}

This produces one combined dictionary containing keys from both inputs.

Understand Key Collision Behavior

If the same key exists in both dictionaries, the later dictionary wins. That means:

1NSDictionary *first = @{@"role": @"Engineer"};
2NSDictionary *second = @{@"role": @"Manager"};
3
4NSMutableDictionary *merged = [first mutableCopy];
5[merged addEntriesFromDictionary:second];

The merged result contains @"role": @"Manager". This behavior is often correct, but it should be intentional rather than accidental.

Return an Immutable Result When Appropriate

If the merged dictionary should not be modified later, convert it back to an immutable NSDictionary.

NSDictionary *result = [merged copy];
NSLog(@"%@", result);

This is common when the merge is just a construction step and the final value should be treated as stable configuration or payload data.

Build a Convenience Helper

If dictionary merging happens often, wrap it in a helper so key overwrite behavior is consistent.

1#import <Foundation/Foundation.h>
2
3NSDictionary *MergeDictionaries(NSDictionary *first, NSDictionary *second) {
4    NSMutableDictionary *merged = [first mutableCopy];
5    [merged addEntriesFromDictionary:second];
6    return [merged copy];
7}

Using a helper prevents merge logic from being repeated with slightly different assumptions across the codebase.

Swift Equivalent

The same concept exists in Swift dictionaries, which are value types rather than Foundation reference types. Swift offers a built-in merging API.

1import Foundation
2
3let first = ["name": "Ava", "role": "Engineer"]
4let second = ["role": "Manager", "city": "Toronto"]
5
6let merged = first.merging(second) { _, new in new }
7print(merged)

The closure controls how key conflicts are resolved. In this example, the value from the second dictionary wins, which matches addEntriesFromDictionary: semantics.

Choose Merge Behavior Deliberately

Dictionary merging is easy mechanically, but domain meaning still matters. When duplicate keys appear, there are several possible rules:

• second dictionary overwrites the first
• first dictionary keeps priority
• conflicting keys trigger an error or assertion

The right rule depends on whether the dictionaries represent defaults, user overrides, request metadata, or something else. The API makes merging easy, but the business rule is yours to define.

Shallow Merge Versus Deep Merge

addEntriesFromDictionary: performs a shallow merge. If a key contains another dictionary as its value, the nested dictionary is replaced as one whole object. It is not merged recursively.

That matters for configuration trees and nested JSON-like structures. If you need recursive merging, you have to implement that behavior explicitly.

Common Pitfalls

• Trying to mutate an NSDictionary directly instead of using NSMutableDictionary.
• Forgetting that duplicate keys are overwritten by the later dictionary.
• Returning a mutable dictionary when the caller expects an immutable result.
• Assuming nested dictionaries will be merged deeply when only a shallow merge is happening.
• Repeating merge logic inline instead of centralizing the key-collision rule.

Summary

• 'NSDictionary is immutable, so merging starts with a mutable copy.'
• 'addEntriesFromDictionary: is the standard Objective-C way to combine two dictionaries.'
• If keys overlap, the values from the later dictionary overwrite earlier ones.
• Convert back to NSDictionary when the final result should be immutable.
• In Swift, merging provides the same idea with explicit conflict handling.