# Namespace goog.object

code »
Show:Public Protected Private

## Global Functions

code »`<K, V>` goog.object.add ( obj, key, val )

Adds a key-value pair to the object. Throws an exception if the key is already in use. Use set if you want to change an existing pair.

Parameters

obj: `Object.<K, V>`
  The object to which to add the key-value pair.
key: `string`
  The key to add.
val: `V`
  The value to add.

code »goog.object.clear ( obj )

Removes all key value pairs from the object/map/hash.

Parameters

obj: `Object`
  The object to clear.

code »`<K, V>` goog.object.clone ( obj ) ⇒ `!Object.<K, V>`

Does a flat clone of the object.

Parameters

obj: `Object.<K, V>`
  Object to clone.

Returns

Clone of the input object.

code »`<K, V>` goog.object.contains ( obj, val ) ⇒ `boolean`

Whether the object/hash/map contains the given object as a value. An alias for goog.object.containsValue(obj, val).

Parameters

obj: `Object.<K, V>`
  The object in which to look for val.
val: `V`
  The object for which to check.

Returns

true if val is present.

code »goog.object.containsKey ( obj, key ) ⇒ `boolean`

Whether the object/map/hash contains the given key.

Parameters

obj: `Object`
  The object in which to look for key.
key: `*`
  The key for which to check.

Returns

true If the map contains the key.

code »`<K, V>` goog.object.containsValue ( obj, val ) ⇒ `boolean`

Whether the object/map/hash contains the given value. This is O(n).

Parameters

obj: `Object.<K, V>`
  The object in which to look for val.
val: `V`
  The value for which to check.

Returns

true If the map contains the value.

code »goog.object.create ( var_args ) ⇒ `!Object`

Creates a new object built from the key-value pairs provided as arguments.

Parameters

var_args: `...*`
  If only one argument is provided and it is an array then this is used as the arguments, otherwise even arguments are used as the property names and odd arguments are used as the property values.

Returns

The new object.

Throws

`Error`
  If there are uneven number of arguments or there is only one non array argument.

code »`<K, V>` goog.object.createImmutableView ( obj ) ⇒ `!Object.<K, V>`

Creates an immutable view of the underlying object, if the browser supports immutable objects. In default mode, writes to this view will fail silently. In strict mode, they will throw an error.

Parameters

obj: `!Object.<K, V>`
  An object.

Returns

An immutable view of that object, or the original object if this browser does not support immutables.

code »goog.object.createSet ( var_args ) ⇒ `!Object`

Creates a new object where the property names come from the arguments but the value is always set to true

Parameters

var_args: `...*`
  If only one argument is provided and it is an array then this is used as the arguments, otherwise the arguments are used as the property names.

Returns

The new object.

code »`<K, V>` goog.object.equals ( a, b ) ⇒ `boolean`

Compares two objects for equality using === on the values.

Parameters

a
b

code »`<T, K, V>` goog.object.every ( obj, f, opt_obj ) ⇒ `boolean`

Calls a function for each element in an object/map/hash. If all calls return true, returns true. If any call returns false, returns false at this point and does not continue to check the remaining elements.

Parameters

obj: `Object.<K, V>`
  The object to check.
f: `?function(this: T, V, ?, Object.<K, V>): boolean`
  The function to call for every element. This function takes 3 arguments (the element, the index and the object) and should return a boolean.
opt_obj: `T=`
  This is used as the 'this' object within f.

Returns

false if any element fails the test.

code »goog.object.extend ( target, var_args )

Extends an object with another object. This operates 'in-place'; it does not create a new Object. Example: var o = {}; goog.object.extend(o, {a: 0, b: 1}); o; // {a: 0, b: 1} goog.object.extend(o, {b: 2, c: 3}); o; // {a: 0, b: 2, c: 3}

Parameters

target: `Object`
  The object to modify. Existing properties will be overwritten if they are also present in one of the objects in `var_args`.
var_args: `...Object`
  The objects from which values will be copied.

code »`<T, K, V>` goog.object.filter ( obj, f, opt_obj ) ⇒ `!Object.<K, V>`

Calls a function for each element in an object/map/hash. If that call returns true, adds the element to a new object.

Parameters

obj: `Object.<K, V>`
  The object over which to iterate.
f: `function(this: T, V, ?, Object.<K, V>): boolean`
  The function to call for every element. This function takes 3 arguments (the element, the index and the object) and should return a boolean. If the return value is true the element is added to the result object. If it is false the element is not included.
opt_obj: `T=`
  This is used as the 'this' object within f.

Returns

a new object in which only elements that passed the test are present.

code »`<T, K, V>` goog.object.findKey ( obj, f, opt_this ) ⇒ `(string|undefined)`

Searches an object for an element that satisfies the given condition and returns its key.

Parameters

obj: `Object.<K, V>`
  The object to search in.
f: `function(this: T, V, string, Object.<K, V>): boolean`
  The function to call for every element. Takes 3 arguments (the value, the key and the object) and should return a boolean.
opt_this: `T=`
  An optional "this" context for the function.

Returns

The key of an element for which the function returns true or undefined if no such element is found.

code »`<T, K, V>` goog.object.findValue ( obj, f, opt_this ) ⇒ `V`

Searches an object for an element that satisfies the given condition and returns its value.

Parameters

obj: `Object.<K, V>`
  The object to search in.
f: `function(this: T, V, string, Object.<K, V>): boolean`
  The function to call for every element. Takes 3 arguments (the value, the key and the object) and should return a boolean.
opt_this: `T=`
  An optional "this" context for the function.

Returns

The value of an element for which the function returns true or undefined if no such element is found.

code »`<T, K, V>` goog.object.forEach ( obj, f, opt_obj )

Calls a function for each element in an object/map/hash.

Parameters

obj: `Object.<K, V>`
  The object over which to iterate.
f: `function(this: T, V, ?, Object.<K, V>): ?`
  The function to call for every element. This function takes 3 arguments (the element, the index and the object) and the return value is ignored.
opt_obj: `T=`
  This is used as the 'this' object within f.

code »`<K, V, R>` goog.object.get ( obj, key, opt_val ) ⇒ `(V|R|undefined)`

Returns the value for the given key.

Parameters

obj: `Object.<K, V>`
  The object from which to get the value.
key: `string`
  The key for which to get the value.
opt_val: `R=`
  The value to return if no item is found for the given key (default is undefined).

Returns

The value for the given key.

code »goog.object.getAnyKey ( obj ) ⇒ `(string|undefined)`

Returns one key from the object map, if any exists. For map literals the returned key will be the first one in most of the browsers (a know exception is Konqueror).

Parameters

obj: `Object`
  The object to pick a key from.

Returns

The key or undefined if the object is empty.

code »`<K, V>` goog.object.getAnyValue ( obj ) ⇒ `(V|undefined)`

Returns one value from the object map, if any exists. For map literals the returned value will be the first one in most of the browsers (a know exception is Konqueror).

Parameters

obj: `Object.<K, V>`
  The object to pick a value from.

Returns

The value or undefined if the object is empty.

code »goog.object.getCount ( obj ) ⇒ `number`

Returns the number of key-value pairs in the object map.

Parameters

obj: `Object`
  The object for which to get the number of key-value pairs.

Returns

The number of key-value pairs in the object map.

code »goog.object.getKeys ( obj ) ⇒ `!Array.<string>`

Returns the keys of the object/map/hash.

Parameters

obj: `Object`
  The object from which to get the keys.

Returns

Array of property keys.

code »goog.object.getValueByKeys ( obj, var_args ) ⇒ `*`

Get a value from an object multiple levels deep. This is useful for pulling values from deeply nested objects, such as JSON responses. Example usage: getValueByKeys(jsonObj, 'foo', 'entries', 3)

Parameters

obj: `!Object`
  An object to get the value from. Can be array-like.
var_args: `...(string|number|!Array)`
  A number of keys (as strings, or numbers, for array-like objects). Can also be specified as a single array of keys.

Returns

The resulting value. If, at any point, the value for a key is undefined, returns undefined.

code »`<K, V>` goog.object.getValues ( obj ) ⇒ `!Array.<V>`

Returns the values of the object/map/hash.

Parameters

obj: `Object.<K, V>`
  The object from which to get the values.

Returns

The values in the object/map/hash.

code »goog.object.isEmpty ( obj ) ⇒ `boolean`

Whether the object/map/hash is empty.

Parameters

obj: `Object`
  The object to test.

Returns

true if obj is empty.

code »goog.object.isImmutableView ( obj ) ⇒ `boolean`

Parameters

obj: `!Object`
  An object.

Returns

Whether this is an immutable view of the object.

code »`<T, K, V, R>` goog.object.map ( obj, f, opt_obj ) ⇒ `!Object.<K, R>`

For every element in an object/map/hash calls a function and inserts the result into a new object.

Parameters

obj: `Object.<K, V>`
  The object over which to iterate.
f: `function(this: T, V, ?, Object.<K, V>): R`
  The function to call for every element. This function takes 3 arguments (the element, the index and the object) and should return something. The result will be inserted into a new object.
opt_obj: `T=`
  This is used as the 'this' object within f.

Returns

a new object with the results from f.

code »goog.object.remove ( obj, key ) ⇒ `boolean`

Removes a key-value pair based on the key.

Parameters

obj: `Object`
  The object from which to remove the key.
key: `*`
  The key to remove.

Returns

Whether an element was removed.

code »`<K, V>` goog.object.set ( obj, key, value )

Adds a key-value pair to the object/map/hash.

Parameters

obj: `Object.<K, V>`
  The object to which to add the key-value pair.
key: `string`
  The key to add.
value: `V`
  The value to add.

code »`<K, V>` goog.object.setIfUndefined ( obj, key, value ) ⇒ `V`

Adds a key-value pair to the object/map/hash if it doesn't exist yet.

Parameters

obj: `Object.<K, V>`
  The object to which to add the key-value pair.
key: `string`
  The key to add.
value: `V`
  The value to add if the key wasn't present.

Returns

The value of the entry at the end of the function.

code »`<T, K, V>` goog.object.some ( obj, f, opt_obj ) ⇒ `boolean`

Calls a function for each element in an object/map/hash. If any call returns true, returns true (without checking the rest). If all calls return false, returns false.

Parameters

obj: `Object.<K, V>`
  The object to check.
f: `function(this: T, V, ?, Object.<K, V>): boolean`
  The function to call for every element. This function takes 3 arguments (the element, the index and the object) and should return a boolean.
opt_obj: `T=`
  This is used as the 'this' object within f.

Returns

true if any element passes the test.

code »goog.object.transpose ( obj ) ⇒ `!Object`

Returns a new object in which all the keys and values are interchanged (keys become values and values become keys). If multiple keys map to the same value, the chosen transposed value is implementation-dependent.

Parameters

obj: `Object`
  The object to transpose.

Returns

The transposed object.

code »goog.object.unsafeClone ( obj ) ⇒ `*`

Clones a value. The input may be an Object, Array, or basic type. Objects and arrays will be cloned recursively. WARNINGS: `goog.object.unsafeClone` does not detect reference loops. Objects that refer to themselves will cause infinite recursion. `goog.object.unsafeClone` is unaware of unique identifiers, and copies UIDs created by `getUid` into cloned results.

Parameters

obj: `*`
  The value to clone.

Returns

A clone of the input value.

## Global Properties

code »goog.object.PROTOTYPE_FIELDS_ : `Array.<string>`

The names of the fields that are defined on Object.prototype.