InsertAt

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 "B"

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

RemoveAt

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

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.Length() + 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

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

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

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

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

SetCapacity

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

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

GetCapacity

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

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

GetAddress

Ptr := Object.GetAddress(Key)

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

NewEnum

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

Object.HasKey(Key)

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

Clone

Clone := Object.Clone([From, To])

Note, the order of From integers To strings.

obj:={1:1,2:2,3:3,4:4,5:5,test:"test",ahk:"ahk",var:"var",(""):"empty",([]):"object"}
for k,v in obj.Clone(,obj.Length()) ; clone all integer keys
  out1.=k "=" v "`n"
MsgBox % out1
for k,v in obj.Clone("") ; clone all string keys
  out2.=k "=" v "`n"
MsgBox % out2
for k,v in obj.Clone("t","x") ; only string keys from t - x
  out3.=k "=" v "`n"
MsgBox % out3
for k,v in obj.Clone(2,4) ; only integer keys from 2,4
  out4.=k "=" v "`n"
MsgBox % out4
for k,v in obj.Clone() ; clone all
  out4.=k "=" v "`n"
MsgBox % out4

ObjRawSet

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. 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.