# Object

AutoHotkey's basic object datatype is an associative array with features which allow its behaviour to be customized. By default, all objects created by `{}`, `[]`, `Object()` and `Array()` support the following:

Methods:

- InsertAt / RemoveAt
- Push / Pop
- Delete
- MinIndex / MaxIndex / Length / Count
- SetCapacity / GetCapacity
- GetAddress
- _NewEnum
- HasKey
- Clone

Properties:

- Base

Functions:

- ObjRawGet
- ObjRawSet
- ObjGetBase
- ObjSetBase

Deprecated (not recommended for use):

- Insert
- Remove

Each method also has an equivalent function, which can be used to bypass any custom behaviour implemented by the object -- it is recommended that these functions only be used for that purpose. To call one, prefix the method name with "Obj" and pass the target object as the first parameter. For example:

    array := [1, 2, 3]
    MsgBox % ObjMaxIndex(array) " = " array.MaxIndex()

If an Obj method-function is called with an object or value of the wrong type, it returns an empty string. Standalone functions such as ObjRawSet throw an exception.

## InsertAt [v1.1.21+]

Inserts one or more values at a given position within a linear array.

    Object.InsertAt(Pos, Value1 , Value2, ... ValueN)

Pos

  The position to insert Value1 at. Subsequent values are inserted at Pos+1, Pos+2, etc.

Value1 ...

  One or more values to insert. To insert an array of values, pass `theArray*` as the last parameter.

### Remarks

InsertAt is the counterpart of RemoveAt.

As Objects are associative arrays, Pos is also the integer key which will be associated with Value1. Any items previously at or to the right of Pos are shifted to the right by the exact number of value parameters, even if some values are missing (i.e. the object is a sparse array). For example:

    x := []
    x.InsertAt(1, "A", "B") ; =>  ["A", "B"]
    x.InsertAt(2, "C")      ; =>  ["A", "C", "B"]

    ; Sparse/unassigned elements are preserved:
    x := ["A", , "C"]
    x.InsertAt(2, "B")      ; =>  ["A", "B",    , "C"]

    x := ["C"]
    x.InsertAt(1, , "B")    ; =>  [   , "B", "C"]

InsertAt should be used only when the object's integer keys represent positions in a linear array. If the object contains arbitrary integer keys such as IDs or handles, InsertAt is likely to cause unwanted side-effects. For example:

    x := [], handleX := 0x4321, handleY := 0x1234
    x.InsertAt(handleX, "A")
    MsgBox % x[handleX]  ; A - okay
    x.InsertAt(handleY, "B")
    MsgBox % x[handleX]  ; Empty
    MsgBox % x[handleX+1]  ; This is the new "position" of "A"

InsertAt does not affect string or object keys, so can be safely used with objects containing mixed key types.

## RemoveAt [v1.1.21+]

Removes items from the given position in a linear array.

    Object.RemoveAt(Pos , Length)

Pos

  The position of the value or values to remove.

Length

  The length of the range of values to remove. Items from `Pos` to `Pos+Length-1` are removed. If omitted, one item is removed.

Return Value

  If Length is omitted, the value removed from Pos is returned (blank if none). Otherwise the return value is the number of removed items which had values, which can differ from Length in a sparse array, but is always between 0 and Length (inclusive).

### Remarks

RemoveAt is the counterpart of InsertAt.

The remaining items to the right of Pos are shifted to the left by Length (or 1 if omitted), even if some items in the removed range did not have values. For example:

    x := ["A", "B"]
    MsgBox % x.RemoveAt(1)  ; A
    MsgBox % x[1]           ; B

    x := ["A", , "C"]
    MsgBox % x.RemoveAt(1, 2)  ; 1
    MsgBox % x[1]              ; C

RemoveAt should be used only when the object's integer keys represent positions in a linear array. If the object contains arbitrary integer keys such as IDs or handles, RemoveAt is likely to cause unwanted side-effects. For example:

    x := {0x4321: "A", 0x1234: "B"}
    MsgBox % x.RemoveAt(0x1234) ; B
    MsgBox % x[0x4321]          ; Empty
    MsgBox % x[0x4321-1]        ; A

RemoveAt does not affect string or object keys, so can be safely used with objects containing mixed key types.

## Push [v1.1.21+]

Appends values to the end of an array.

    Object.Push( Value, Value2, ..., ValueN )

Value ...

  One or more values to insert. To insert an array of values, pass `theArray*` as the last parameter.

Return Value

  The position of the last inserted value. Can be negative if the array only contained elements at negative indices.

### Remarks

The first value is inserted at position 1 if the array is empty or contains only string or object keys.

Otherwise, the first value is inserted at `Object.MaxIndex() + 1`, even if that position is negative or zero. If this is undesired and the object can contain negative keys, `Object.InsertAt(Object.Length() + 1, ...)` can be used intead.

## Pop [v1.1.21+]

Removes and returns the last array element.

    Value := Object.Pop()

If there are no array elements, the return value is an empty string. Otherwise, it is equivalent to the following:

    Value := Object.RemoveAt(Object.Length())

## Delete [v1.1.21+]

Removes key-value pairs from an object.

    Object.Delete(Key)
    Object.Delete(FirstKey, LastKey)

Key

  Any single key.

FirstKey, LastKey

  Any valid range of integer or string keys, where FirstKey <= LastKey. Both keys must be the same type.

Return Value

  If there is exactly one parameter, the removed value is returned (blank if none). Otherwise the return value is the number of matching keys which were found and removed.

### Remarks

Unlike RemoveAt, Delete does not affect any of the key-value pairs that it does not remove. For example:

    x := ["A", "B"]
    MsgBox % x.RemoveAt(1)  ; A
    MsgBox % x[1]           ; B

    x := ["A", "B"]
    MsgBox % x.Delete(1)    ; A
    MsgBox % x[1]           ; Empty

## MinIndex / MaxIndex [AHK_L 31+]

    MinIndex := Object.MinIndex()
    MaxIndex := Object.MaxIndex()

If any integer keys are present, MinIndex returns the lowest and MaxIndex returns the highest. Otherwise an empty string is returned.

## Length [v1.1.21+]

    Length := Object.Length()

Returns the length of a linear array beginning at position 1; that is, the highest positive integer key contained by the object, or 0 if there aren't any.

    MsgBox % ["A", "B", "C"].Length()  ;  3
    MsgBox % ["A",    , "C"].Length()  ;  3
    MsgBox % {-10: 0, 10: 0}.Length()  ; 10
    MsgBox % {-10: 0, -1: 0}.Length()  ;  0

## Count [v1.1.29+]

    Count := Object.Count()

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

    MsgBox % {A: 1, Z: 26}.Count()    ;  2
    MsgBox % ["A", "B", "C"].Count()  ;  3
    MsgBox % ["A",    , "C"].Count()  ;  2

## SetCapacity [AHK_L 31+]

Adjusts the capacity of an object or one of its fields.

    Object.SetCapacity(MaxItems)
    Object.SetCapacity(Key, ByteSize)

MaxItems

  The maximum number of key-value pairs the object should be able to contain before it must be automatically expanded. If less than the current number of key-value pairs, that number is used instead, and any unused space is freed.

Key

  Any valid key.

ByteSize

  The new size in bytes of the field's string buffer, excluding the null-terminator. If the field does not exist, it is created. If ByteSize is zero, the buffer is freed but the empty field is not removed. If ByteSize is less than the current size, excess data is truncated; otherwise all existing data is preserved.

Returns

  The new capacity if successful, otherwise an empty string.

## GetCapacity [AHK_L 31+]

    MaxItems := Object.GetCapacity()
    ByteSize := Object.GetCapacity(Key)

Returns the current capacity of an object or one of its fields.

Returns an empty string if the field does not exist or does not contain a string.

## GetAddress [AHK_L 31+]

    Ptr := Object.GetAddress(Key)

Returns the current address of the field's string buffer, if it has one.

## NewEnum [AHK_L 49+]

    Enum := Object._NewEnum()

Returns a new enumerator to enumerate this object's key-value pairs. This method is usually not called directly, but by the for-loop.

## HasKey [AHK_L 53+]

    Object.HasKey(Key)

Returns true if Key is associated with a value (even "") within Object, otherwise false.

## Clone [AHK_L 60+]

    Clone := Object.Clone()

Returns a shallow copy of the object.

## Base

Retrieves or sets the object's base object.

    BaseObject := Object.Base

    Object.Base := BaseObject

BaseObject must be an object or an empty string.

Properties and methods defined by a base object are accessible only while that base object is in use. Therefore, changing Object's base also changes the set of available properties and methods.

See also: ObjGetBase(), ObjSetBase()

## ObjRawGet [v1.1.29+]

Retrieves the value associated with a given key within Object.

    Value := ObjRawGet(Object, Key)

If Object does not contain Key, the return value is an empty string. No meta-functions or property functions are called. The content of Object's base objects are not considered, and since base itself is a property and not a key-value pair by default, it is typically not returned.

An exception is thrown if Object is of an incorrect type.

## ObjRawSet [v1.1.21+]

Stores or overwrites a key-value pair in the object.

    ObjRawSet(Object, Key, Value)

This function is provided to allow scripts to bypass the __Set meta-function and properties. If that isn't required, a normal assignment should be used instead. For example: `Object[Key] := Value`

Since the purpose is to bypass meta-functions, this is a function only, not a method. Calling a built-in method generally causes the __Call meta-function to be called.

An exception is thrown if Object is of an incorrect type.

## ObjGetBase [v1.1.29+]

Returns the object's base object.

    BaseObject := ObjGetBase(Object)

No meta-functions are called. The object's base is returned even if the key "base" has been stored in the object (such as with ObjRawSet or SetCapacity). An empty string is returned if the object has no base.

An exception is thrown if Object is of an incorrect type.

See also: Base property

## ObjSetBase [v1.1.29+]

Sets the object's base object.

    ObjSetBase(Object, BaseObject)

No meta-functions are called. The object's base is set even if the key "base" has been stored in the object (such as with ObjRawSet or SetCapacity). An empty string is returned if the object has no base.

An exception is thrown if Object is of an incorrect type or if BaseObject is not an object or empty string.

See also: Base property

## Insert [AHK_L 31+]

Deprecated: Insert is not recommended for use in new scripts. Use InsertAt, Push, ObjRawSet or a simple assignment instead.

Inserts key-value pairs into the object, automatically adjusting existing keys if given an integer key.

    Object.Insert(Pos, Value1 , Value2, ... ValueN )
    Object.Insert(Value)
    Object.Insert(StringOrObjectKey, Value)

The behaviour of Insert depends on the number and type of its parameters:

- If there are multiple parameters and the first parameter is an integer, Insert behaves like InsertAt.
- If there are multiple parameters and the first parameter is not an integer, Insert behaves like ObjRawSet.
- If there is only one parameter, Insert behaves like Push.

Insert returns true. In [v1.1.21] and later, an exception is thrown if a memory allocation fails. Earlier versions returned an empty string in that case.

## Remove [AHK_L 31+]

Deprecated: Remove is not recommended for use in new scripts. Use RemoveAt, Delete or Pop instead.

Removes key-value pairs from an object.

    Object.Remove(FirstKey, LastKey)

The behaviour of Remove depends on the number and type of parameters:

- `Object.Remove(Integer)` behaves like `Object.RemoveAt(Integer)`.
- `Object.Remove(Integer, "")` behaves like `Object.Delete(Integer)`.
- `Object.Remove(Integer1, Integer2)` behaves like `Object.RemoveAt(Integer1, Integer2 - Integer1 + 1)`.
- `Object.Remove()` behaves like `Object.Pop()`.
- Any other valid combination of parameters behaves like Delete.