Autohotkey - Object #1 (Tradução) (Pt-Br)

Object

O tipo de dados de objeto básico do AutoHotkey é um array associativo com recursos que permitem que seu comportamento seja personalizado. Por padrão, todos os objetos criados por {}, [], Object () e Array () suportam o seguinte:

Methods:

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

Properties:

• Base

Functions:

• ObjRawGet
• ObjRawSet
• ObjGetBase
• ObjSetBase

Deprecated (não recomendado para uso):

• Insert
• Remove

Cada método também possui uma função equivalente, que pode ser usada para ignorar qualquer comportamento personalizado implementado pelo objeto - é recomendável que essas funções sejam usadas apenas para essa finalidade. Para chamar um, prefixe o nome do método com "Obj" e passe o objeto de destino como o primeiro parâmetro. Por exemplo:

array := [1, 2, 3]

MsgBox % ObjMaxIndex(array) " = " array.MaxIndex()

Se uma função de método Obj for chamada com um objeto ou valor do tipo errado, ela retornará uma string vazia. Funções autônomas, como ObjRawSet, lançam uma exceção. 

InsertAt [v1.1.21+]

Insere um ou mais valores em uma determinada posição dentro de um array linear.

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

Pos

A posição para inserir o valor1 em. Valores subseqüentes são inseridos em Pos + 1, Pos + 2, etc.

Value1 ...

Um ou mais valores para inserir. Para inserir uma matriz de valores, passe theArray * como o último parâmetro.

Remarks

InsertAt é a contraparte do RemoveAt.

Como Objetos são matrizes associativas, Pos também é a chave inteira que será associada a Value1. Todos os itens anteriormente à direita de Pos são deslocados para a direita pelo número exato de parâmetros de valor, mesmo que alguns valores estejam faltando (ou seja, o objeto é uma matriz esparsa). Por exemplo:

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 deve ser usado somente quando as chaves inteiras do objeto representam posições em uma matriz linear. Se o objeto contiver chaves inteiras arbitrárias, como IDs ou identificadores, é provável que InsertAt cause efeitos colaterais indesejados. Por exemplo:

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]  ; Esta é a nova "posição" de "A"

InsertAt não afeta as chaves de string ou objeto, portanto, pode ser usado com segurança com objetos que contenham tipos de chave mistos.

RemoveAt [v1.1.21+]

Remove itens da posição determinada em um array linear.

Object.RemoveAt(Pos , Length)

Pos

A posição do valor ou valores a serem removidos.

Length

O comprimento do intervalo de valores a serem removidos. Itens de Pos para Pos + Comprimento-1 são removidos. Se omitido, um item é removido.

Return Value

Se Length for omitido, o valor removido de Pos será retornado (em branco, se nenhum). Caso contrário, o valor de retorno é o número de itens removidos que possuem valores, que podem diferir de Comprimento em uma matriz esparsa, mas estão sempre entre 0 e Comprimento (inclusive).

Remarks

RemoveAt é a contraparte do InsertAt.

Os itens restantes à direita de Pos são deslocados para a esquerda por Comprimento (ou 1 se omitidos), mesmo que alguns itens no intervalo removido não tenham valores. Por exemplo:

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 deve ser usado somente quando as chaves inteiras do objeto representam posições em uma matriz linear. Se o objeto contiver chaves inteiras arbitrárias, como IDs ou identificadores, é provável que o RemoveAt cause efeitos colaterais indesejados. Por exemplo:

x := {0x4321: "A", 0x1234: "B"}

MsgBox % x.RemoveAt(0x1234) ; B

MsgBox % x[0x4321]          ; Empty

MsgBox % x[0x4321-1]        ; A

RemoveAt não afeta as chaves de string ou objeto, portanto, pode ser usado com segurança com objetos que contenham tipos de chave mistos.

Push [v1.1.21+]

Acrescenta valores ao final de uma matriz.

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

Value ...

Um ou mais valores para inserir. Para inserir uma matriz de valores, passe theArray * como o último parâmetro.

Return Value

A posição do último valor inserido. Pode ser negativo se o array contiver apenas elementos em índices negativos.

Remarks

O primeiro valor é inserido na posição 1 se a matriz estiver vazia ou contiver apenas chaves de string ou objeto.

Caso contrário, o primeiro valor é inserido em Object.MaxIndex () + 1, mesmo se essa posição for negativa ou zero. Se isso não for desejado e o objeto puder conter chaves negativas, Object.InsertAt (Object.Length () + 1, ...) poderá ser usado intead.

Pop [v1.1.21+]

Remove e retorna o último elemento da matriz.

Value := Object.Pop()

Se não houver elementos de matriz, o valor de retorno será uma string vazia. Caso contrário, é equivalente ao seguinte:

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

Delete [v1.1.21+]

Remove os pares de valores-chave de um objeto.

Object.Delete(Key)

Object.Delete(FirstKey, LastKey)

Key

Qualquer tecla única

FirstKey, LastKey

Qualquer intervalo válido de chaves inteiras ou de string, em que FirstKey <= LastKey. Ambas as chaves devem ser do mesmo tipo.

Return Value

Se houver exatamente um parâmetro, o valor removido será retornado (em branco, se não houver nenhum). Caso contrário, o valor de retorno é o número de chaves correspondentes encontradas e removidas.

Remarks

Ao contrário de RemoveAt, Delete não afeta nenhum dos pares de valor-chave que ele não remove. Por exemplo:

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 [v1.0.90+]

MinIndex := Object.MinIndex()

MaxIndex := Object.MaxIndex()

Se houver chaves inteiras, MinIndex retorna o menor e MaxIndex retorna o maior. Caso contrário, uma string vazia é retornada.

Length [v1.1.21+]

Length := Object.Length()

Retorna o comprimento de um array linear começando na posição 1; isto é, a maior chave inteira positiva contida pelo objeto, ou 0, se não houver nenhuma.

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()

Retorna o número de pares de valores-chave presentes no objeto.

MsgBox % {A: 1, Z: 26}.Count()    ;  2

MsgBox % ["A", "B", "C"].Count()  ;  3

MsgBox % ["A",    , "C"].Count()  ;  2

SetCapacity [v1.0.90+]

Ajusta a capacidade de um objeto ou um de seus campos.

Object.SetCapacity(MaxItems)

Object.SetCapacity(Key, ByteSize)

MaxItems

O número máximo de pares de valores-chave que o objeto deve conter antes de ser expandido automaticamente. Se for menor que o número atual de pares de valores-chave, esse número será usado e todo espaço não utilizado será liberado.

Key

Qualquer chave válida.

ByteSize

O novo tamanho em bytes do buffer de string do campo, excluindo o terminador nulo. Se o campo não existir, ele será criado. Se ByteSize for zero, o buffer será liberado, mas o campo vazio não será removido. Se ByteSize for menor que o tamanho atual, o excesso de dados será truncado; caso contrário, todos os dados existentes serão preservados.

Returns

A nova capacidade se for bem sucedida, caso contrário, uma string vazia.

GetCapacity [v1.0.90+]

MaxItems := Object.GetCapacity()

ByteSize := Object.GetCapacity(Key)

Retorna a capacidade atual de um objeto ou um de seus campos.

Retorna uma string vazia se o campo não existir ou não contiver uma string.

GetAddress [v1.0.90+]

Ptr := Object.GetAddress(Key)

Retorna o endereço atual do buffer da string do campo, se tiver um.

NewEnum [v1.0.90+]

Enum := Object._NewEnum()

Retorna um novo enumerador para enumerar os pares de valores-chave desse objeto. Este método geralmente não é chamado diretamente, mas pelo loop.

HasKey [v1.0.90+]

Object.HasKey(Key)

Retorna true se Key estiver associado a um valor (mesmo "") dentro de Object, caso contrário, false.

Clone [v1.0.90+]

Clone := Object.Clone()

Retorna uma cópia superficial do objeto.

Base

Recupera ou define o objeto base do objeto.

BaseObject := Object.Base

Object.Base := BaseObject

BaseObject deve ser um objeto ou uma string vazia.

Propriedades e métodos definidos por um objeto base são acessíveis apenas enquanto o objeto base estiver em uso. Portanto, alterar a base do objeto também altera o conjunto de propriedades e métodos disponíveis.

Veja também: ObjGetBase, ObjSetBase

ObjRawGet [v1.1.29+]

Recupera o valor associado a uma determinada chave dentro de Object.

Value := ObjRawGet(Object, Key)

Se Object não contiver Key, o valor de retorno será uma string vazia. Nenhuma meta função ou função de propriedade é chamada. O conteúdo dos objetos base do objeto não é considerado e, como a base em si é uma propriedade e não um par de valores-chave por padrão, normalmente não é retornada.

Uma exceção é lançada se o objeto for de um tipo incorreto.

ObjRawSet [v1.1.21+]

Armazena ou sobrescreve um par de valores-chave no objeto.

ObjRawSet(Object, Key, Value)

Essa função é fornecida para permitir que os scripts ignorem a meta função e as propriedades do __Set. Se isso não for necessário, uma atribuição normal deve ser usada em seu lugar. Por exemplo: Object [Key]: = Value

Como o propósito é ignorar meta-funções, isso é apenas uma função, não um método. Chamar um método interno geralmente faz com que a meta função __Call seja chamada.

Uma exceção é lançada se o objeto for de um tipo incorreto.

ObjGetBase [v1.1.29+]

Retorna o objeto base object.

BaseObject := ObjGetBase(Object)

Nenhuma meta-função é chamada. A base do objeto é retornada mesmo que a chave "base" tenha sido armazenada no objeto (como com ObjRawSet ou SetCapacity). Uma string vazia é retornada se o objeto não tiver base.

Uma exceção é lançada se o objeto for de um tipo incorreto.

Veja também: Base property

ObjSetBase [v1.1.29+]

Define o objeto base object.

ObjSetBase(Object, BaseObject)

Nenhuma meta-função é chamada. A base do objeto é definida mesmo que a chave "base" tenha sido armazenada no objeto (como com ObjRawSet ou SetCapacity). Uma string vazia é retornada se o objeto não tiver base.

Uma exceção é lançada se Object for de um tipo incorreto ou se BaseObject não for um objeto ou uma string vazia.

Veja também: Base property

Insert [v1.0.90+]

Deprecated: Inserir não é recomendado para uso em novos scripts. Use InsertAt, Push, ObjRawSet ou uma atribuição simples.

Insere pares de valor-chave no objeto, ajustando automaticamente as chaves existentes se for fornecida uma chave inteira.

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

Object.Insert(Value)

Object.Insert(StringOrObjectKey, Value)

• O comportamento do Insert depende do número e tipo de seus parâmetros:
• • Se houver vários parâmetros e o primeiro parâmetro for um inteiro, Insert se comportará como InsertAt.
• • Se houver vários parâmetros e o primeiro parâmetro não for um inteiro, Insert se comportará como ObjRawSet.
• • Se houver apenas um parâmetro, Insert se comporta como Push.

Inserir retorna verdadeiro. Em [v1.1.21] e, posteriormente, uma exceção é lançada se uma alocação de memória falhar. Versões anteriores retornavam uma string vazia nesse caso.

Remove [v1.0.90+]

Deprecated: Remover não é recomendado para uso em novos scripts. Usar RemoveAt, Delete or Pop em vez de.

Remove os pares de valores-chave de um objeto.

Object.Remove(FirstKey, LastKey)

O comportamento do Remove depende do número e tipo de parâmetros:

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

Copyright © 2003-2019 - LIC: GNU GPLv2