sábado, 15 de junho de 2019

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:
Properties:
Functions:
Deprecated (não recomendado para uso):
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.
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.
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

Nenhum comentário: