All built-in methods of objects created by Object() or {} may be accessed either as regular functions or as methods:
result := obj.Method(params)
Calling the method this way allows each object to implement its own behaviour for that method. However, if an object overrides a built-in method, it typically needs a way to access the original functionality. It can do that by using the function form:
result := ObjMethod(obj, params)
Calling the function directly is marginally faster since the name can be resolved at load-time, but the syntax is generally less intuitive. Any custom behaviour implemented by the object is bypassed, so these functions should typically be used only by the object itself.
Inserts key-value pairs into the object, automatically adjusting existing keys if appropriate.
Object.Insert(Index, Value1 [, Value2, ... ValueN ]) Object.Insert(Value) Object.Insert(Key, Value)
| Index | An integer key to insert Value1 at. Subsequent values are inserted at Index+1, Index+2, etc. If omitted, it defaults to MaxIndex()="" ? 1 : MaxIndex() + 1. |
| Key | A string or object key. If the key already exists, its value is overwritten. |
| Value | A string, number or object. |
| Returns | A true value if successful or an empty string if the script is out of memory. |
Note that this method bypasses the __Set mechanism and special behaviour of the base key. For instance, Object.Insert("base","") causes Object.base to return an empty string instead of the real base object, but doesn't prevent other operations from triggering the object's meta-functions.
Removes key-value pairs from an object.
Object.Remove(FirstKey, LastKey)
| FirstKey, LastKey | A range of integer or string keys to remove. If both keys are integers, any integer keys greater than LastKey are decremented by (LastKey - FirstKey + 1) to emulate a typical numerically-indexed array. Both keys must be the same type (integer or string). |
| Returns | The actual number of key-value pairs which were removed if successful, zero if no keys were found, or an empty string on failure. |
Object.Remove(Key = MaxIndex())
| Key | Any valid key. If omitted, it defaults to the highest existing integer key; if none exist, nothing is removed. Existing keys are adjusted as though Remove(Key,Key) was used. |
| Returns | The value which was removed, if any; otherwise an empty string. |
Object.Remove(IntKey, "")
[AHK_L 61+]: Removes an integer key and returns its value, but does not affect other integer keys.
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.
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, the object is shrunk to fit. |
| 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. |
MaxItems := Object.GetCapacity() ByteSize := Object.GetCapacity(Key)
Returns the current capacity of an object or one of its fields.
Ptr := Object.GetAddress(Key)
Returns the current address of the field's string buffer, if it has one.
Enum := Object._NewEnum()
Returns a new enumerator to enumerate this object's key-value pairs.
Object.HasKey(Key)
Returns true if Key is associated with a value (even "") within Object, otherwise false.
Clone := Object.Clone()
Returns a shallow copy of the object.