---
title: "updateValue(_:forKey:)"
framework: swift
role: symbol
role_heading: Instance Method
path: "swift/dictionary/updatevalue(_:forkey:)"
---

# updateValue(_:forKey:)

Updates the value stored in the dictionary for the given key, or adds a new key-value pair if the key does not exist.

## Declaration

```swift
@discardableResult mutating func updateValue(_ value: Value, forKey key: Key) -> Value?
```

## Parameters

- `value`: The new value to add to the dictionary.
- `key`: The key to associate with value. If key already exists in the dictionary, value replaces the existing associated value. If key isn’t already a key of the dictionary, the (key, value) pair is added.

## Return Value

Return Value The value that was replaced, or nil if a new key-value pair was added.

## Discussion

Discussion Use this method instead of key-based subscripting when you need to know whether the new value supplants the value of an existing key. If the value of an existing key is updated, updateValue(_:forKey:) returns the original value. var hues = ["Heliotrope": 296, "Coral": 16, "Aquamarine": 156]

if let oldValue = hues.updateValue(18, forKey: "Coral") {     print("The old value of \(oldValue) was replaced with a new one.") } // Prints "The old value of 16 was replaced with a new one." If the given key is not present in the dictionary, this method adds the key-value pair and returns nil. if let oldValue = hues.updateValue(330, forKey: "Cerise") {     print("The old value of \(oldValue) was replaced with a new one.") } else {     print("No value was found in the dictionary for that key.") } // Prints "No value was found in the dictionary for that key."

## See Also

### Adding Keys and Values

- [reserveCapacity(_:)](swift/dictionary/reservecapacity(_:).md)