# StructInsert

Inserts a key/value pair in to a struct - with an optional overwrite argument

## Method Signature

```
StructInsert(struct=[modifiableStruct], key=[any], value=[any], overwrite=[boolean])
```

### Arguments

| Argument    | Type               | Required | Description                                                                  | Default |
| ----------- | ------------------ | -------- | ---------------------------------------------------------------------------- | ------- |
| `struct`    | `modifiableStruct` | `true`   | The target struct                                                            |         |
| `key`       | `any`              | `true`   | The struct key                                                               |         |
| `value`     | `any`              | `true`   | The value to assign for the specified key                                    |         |
| `overwrite` | `boolean`          | `false`  | Whether to overwrite the existing value if the key exists ( default: false ) | `false` |

## Examples

### Simple Example

Inserts a new key/value into the structure

[Run Example](https://try.boxlang.io/?code=eJwli1EKgzAQBb%2BbUzz2q4InqHgAaaFnSNtFA5qG3Q0i4t2N%2BjUwzEw%2BocUKd6PBByE8QB%2F5z5HqonhhPVUvzJHc1jg1yV%2FrorLYHZNPNWgMSalQ%2BEeoGjdLMH5nS7kk1%2FDk5RX0OlAd0Q6fbSUY)

```java
map = { 
	"hair" : "brown",
	"eyes" : "green"
};
structInsert( map, "lips", "red" );
writeOutput( structKeyList( map ) );

```

Result: eyes,lips,hair

### Overwrite Example

Throws exception when you try to add a duplicate key, when allowoverwrite parameter is false.

[Run Example](https://try.boxlang.io/?code=eJwljEEOgjAQRdfMKb6zgoQTSDyAK89Q6ygkUprpNNgQ7m7F1Ute%2Fvuzi7hgAzU8ukkZZ%2FBdlzVwX5UUSYd6qUhg2gcyLdioSabZ2zUkUWsxu9jjf1Cp8qh4uncSdAPt8M78iNaFAvl0v3zVyeSWLeZas6gueuJjTF80fCtJ)

```java
map = { 
	"hair" : "brown",
	"eyes" : "green"
};
try {
	structInsert( map, "hair", "red", false );
} catch (any ex) {
	writeOutput( "error!" );
}

```

Result: error!

### Additional Examples

[Run Example](https://try.boxlang.io/?code=eJxljs0KwjAQhM%2FNUyx7qlDoXelBKkhPCj14jkmgwWQjaWIO4rvbPwvF4%2BzMfjOctOWmhwrewLL6coM9oHUOC5Zdm%2FOonKYHss%2BBlSW0nUsgoveKAvD5l52ifeZg%2BF2ZCuutiQW8uK8WBbuJ0lCvfADBA2gKbgW1wUcRZjf%2FXQvAIThw0CqXcEFMQ9YEDUKTMFGqfsRuJx2X8qRDN5VyKZX8X%2FYFW0NWfw%3D%3D)

```java
animals = { 
	COW : "moo",
	PIG : "oink"
};
// Show current animals
Dump( label="Current animals", var=animals );
// Insert cat into animals
StructInsert( animals, "cat", "meow" );
// Show animals, now includes cat
Dump( label="Animals with cat added", var=animals );

```

## Related

* [StructAppend](https://boxlang.ortusbooks.com/boxlang-language/reference/built-in-functions/struct/structappend)
* [StructClear](https://boxlang.ortusbooks.com/boxlang-language/reference/built-in-functions/struct/structclear)
* [StructCopy](https://boxlang.ortusbooks.com/boxlang-language/reference/built-in-functions/struct/structcopy)
* [StructDelete](https://boxlang.ortusbooks.com/boxlang-language/reference/built-in-functions/struct/structdelete)
* [StructEach](https://boxlang.ortusbooks.com/boxlang-language/reference/built-in-functions/struct/structeach)
* [StructEquals](https://boxlang.ortusbooks.com/boxlang-language/reference/built-in-functions/struct/structequals)
* [StructEvery](https://boxlang.ortusbooks.com/boxlang-language/reference/built-in-functions/struct/structevery)
* [StructFilter](https://boxlang.ortusbooks.com/boxlang-language/reference/built-in-functions/struct/structfilter)
* [StructFind](https://boxlang.ortusbooks.com/boxlang-language/reference/built-in-functions/struct/structfind)
* [StructFindKey](https://boxlang.ortusbooks.com/boxlang-language/reference/built-in-functions/struct/structfindkey)
* [StructFindValue](https://boxlang.ortusbooks.com/boxlang-language/reference/built-in-functions/struct/structfindvalue)
* [StructGet](https://boxlang.ortusbooks.com/boxlang-language/reference/built-in-functions/struct/structget)
* [StructGetMetadata](https://boxlang.ortusbooks.com/boxlang-language/reference/built-in-functions/struct/structgetmetadata)
* [StructIsCaseSensitive](https://boxlang.ortusbooks.com/boxlang-language/reference/built-in-functions/struct/structiscasesensitive)
* [StructIsOrdered](https://boxlang.ortusbooks.com/boxlang-language/reference/built-in-functions/struct/structisordered)
* [StructKeyArray](https://boxlang.ortusbooks.com/boxlang-language/reference/built-in-functions/struct/structkeyarray)
* [StructKeyExists](https://boxlang.ortusbooks.com/boxlang-language/reference/built-in-functions/struct/structkeyexists)
* [StructKeyList](https://boxlang.ortusbooks.com/boxlang-language/reference/built-in-functions/struct/structkeylist)
* [StructKeyTranslate](https://boxlang.ortusbooks.com/boxlang-language/reference/built-in-functions/struct/structkeytranslate)
* [StructMap](https://boxlang.ortusbooks.com/boxlang-language/reference/built-in-functions/struct/structmap)
* [StructNew](https://boxlang.ortusbooks.com/boxlang-language/reference/built-in-functions/struct/structnew)
* [StructNone](https://boxlang.ortusbooks.com/boxlang-language/reference/built-in-functions/struct/structnone)
* [StructReduce](https://boxlang.ortusbooks.com/boxlang-language/reference/built-in-functions/struct/structreduce)
* [StructSome](https://boxlang.ortusbooks.com/boxlang-language/reference/built-in-functions/struct/structsome)
* [StructSort](https://boxlang.ortusbooks.com/boxlang-language/reference/built-in-functions/struct/structsort)
* [StructToQueryString](https://boxlang.ortusbooks.com/boxlang-language/reference/built-in-functions/struct/structtoquerystring)
* [StructToSorted](https://boxlang.ortusbooks.com/boxlang-language/reference/built-in-functions/struct/structtosorted)
* [StructUpdate](https://boxlang.ortusbooks.com/boxlang-language/reference/built-in-functions/struct/structupdate)
* [StructValueArray](https://boxlang.ortusbooks.com/boxlang-language/reference/built-in-functions/struct/structvaluearray)