Arrayオブジェクト

class Array extends Object

配列オブジェクトは、値のリストまたはシーケンスを含んでいます。

値は、配列内の位置（配列インデックス）で指定され、位置1が最初の要素になります。

配列は、値のリストを括弧で囲むことで作成されることが多い。事例：

veg := ["Asparagus", "Broccoli", "Cucumber"]
Loop veg.Length
    MsgBox veg[A_Index]

負のインデックスは、要素を逆にアドレスするために使用することができ、-1は最後の要素、-2は2番目の最後の要素、といった具合です。

範囲外の配列インデックス（ゼロや絶対値が配列の長さより大きい場合など）を使用しようとすると、エラーとみなされ、IndexErrorがスローされます。配列に新しい要素を追加するには、InsertAtまたはPushを呼び出すのが最適です。事例：

users := Array()
users.Push A_UserName
MsgBox users[1]

また、Lengthに大きな値を代入することで、配列を拡張することができる。これにより、有効なインデックスが変わりますが、Hasは新要素に価値がないことを示します。値のない要素は、通常、バリアドコールや バリアド関数によって使用されるが、どのような目的にも使用できる。

「Array」はクラスそのものなので、以下ではあらゆるArrayオブジェクトのプレースホルダとして 「ArrayObj」を使用します。

配列オブジェクトは、オブジェクトから継承されたメソッドとプロパティに加え、以下の定義済みのメソッドとプロパティを持ちます。

目次

静的メソッド

Call

指定された値を含む新しい配列を作成します。

ArrayObj := Array(Value, Value2, ..., ValueN)
ArrayObj := Array.Call(Value, Value2, ..., ValueN)

パラメータは__Newで定義します。

メソッド

Clone

配列のシャローコピーを返します。

Clone := ArrayObj.Clone()

配列の全要素が新しい配列にコピーされます。オブジェクトの参照はコピーされますが（通常の代入と同様）、オブジェクトそのものはコピーされません。

Obj.Cloneに準じて、自プロパティ、自メソッド、ベースはコピーされます。

Delete

配列の要素の値を削除し、インデックスに値を残さないようにします。

RemovedValue := ArrayObj.Delete(Index)

パラメータ

Index

型：整数

有効な配列のインデックス。

戻り値

型：任意

This method returns the removed value (blank if none).

備考

This method does not affect the Length of the array.

Indexが範囲外の場合、ValueErrorが投げられる。

Get

指定されたインデックスにある値、またはデフォルト値を返します。

Value := ArrayObj.Get(Index , Default)

この方法では、次のようなことができます：

Defaultが省略された場合、__Itemが呼び出されないことを除いてArrayObj[Index]と同等となる。

Has

Returns a non-zero number if the index is valid and there is a value at that position.

HasIndex := ArrayObj.Has(Index)

InsertAt

指定された位置に1つまたは複数の値を挿入します。

ArrayObj.InsertAt(Index, Value1 , Value2, ... ValueN)

パラメータ

Index

型：整数

Value1を挿入する位置を指定します。それ以降の値は、Index+1、Index+2 などに挿入されます。0を指定すると、Length+1を指定したのと同じになります。

Value1 ...

型：任意

挿入する1つまたは複数の値。値の配列を挿入するには、次のように渡します。 theArray*を最後のパラメータとして指定します。

備考

InsertAtは、RemoveAtと対になるものです。

これまでIndexの右側にあったアイテムは、右側に移動します。欠落したパラメータも挿入されるが、値はない。事例：

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

; 欠けている要素はそのままです：
x := ["A", , "C"]
x.InsertAt(2, "B")      ; =>  ["A", "B",    , "C"]

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

Indexが-ArrayObj.Lengthよりも小さいか、ArrayObj.Length + 1よりも大きい場合はValueErrorがスローされます。例えば、3つの項目からなる配列の場合、Indexは-3から4までの間でなければならない。

Pop

配列の最後の要素を削除して返します。

RemovedValue := ArrayObj.Pop()

以下はすべて同等です：

RemovedValue := ArrayObj.Pop()
RemovedValue := ArrayObj.RemoveAt(ArrayObj.Length)
RemovedValue := ArrayObj.RemoveAt(-1)

配列が空の場合（Lengthが0）、エラーとなる。

Push

配列の末尾に値を追加します。

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

パラメータ

Value ...

型：任意

挿入する1つまたは複数の値。値の配列を挿入するには、次のように渡します。 theArray*を最後のパラメータとして指定します。

RemoveAt

配列から項目を削除します。

RemovedValue := ArrayObj.RemoveAt(Index)
ArrayObj.RemoveAt(Index, Length)

パラメータ

Index

型：整数

削除する値（複数可）のインデックス。

Length

型：整数

省略された場合は、1つの項目が削除されます。Otherwise, specify the length of the range of values to remove.

戻り値

型：任意

Lengthが省略された場合は、削除された値が返される（ない場合は空白）。そうでない場合は、戻り値はありません。

備考

RemoveAtはInsertAtの対になるものです。

Indexと Lengthで示される範囲が、配列の現在の範囲に完全に収まっていない場合、ValueErrorがスローされます。

Posの右にある残りの項目は、Length（省略時は1）だけ左にシフトされます。事例：

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

__New

項目を追加します。プッシュに相当します。

ArrayObj.__New(Value, Value2, ..., ValueN)

このメソッドはCallをサポートするために存在し、直接呼び出すことは意図していません。建設と破壊をご覧ください。

__Enum

配列の要素を列挙します。

For Value in ArrayObj
For Index, Value in ArrayObj

新しい列挙者を返します。このメソッドは通常、直接呼び出されることはありません。その代わり、配列オブジェクトは直接forループに渡され、forループは__Enumを一度呼び出し、ループの各繰り返しで列挙器を一度呼び出します。列挙者を呼び出すたびに、次の配列要素が返されます。forループの変数は、列挙者のパラメータに対応しており、次のようになっています：

Index

型：整数

配列のインデックス。通常はA_Indexと同じ。2パラメータモード時のみ存在します。

Value

型：任意

値（値がない場合、Valueは 未初期化される）。

プロパティ

Length

配列の長さを取得または設定します。

Length := ArrayObj.Length
ArrayObj.Length := Length

長さには、価値のない要素も含まれます。長さを長くすると、どのインデックスが有効とみなされるかが変わりますが、新しい要素には価値がありません（Hasで示されます）。長さを小さくすると、配列は切り捨てられます。

MsgBox ["A", "B", "C"].Length  ;  3
MsgBox ["A",    , "C"].Length  ;  3

Capacity

配列の現在の容量を取得または設定します。

MaxItems := ArrayObj.Capacity
ArrayObj.Capacity := MaxItems

MaxItems is an integer representing the maximum number of elements the array should be able to contain before it must be automatically expanded. Lengthより小さい値を設定すると、要素が削除されます。

Default

値のない要素が要求されたときに返されるデフォルト値を定義します。

ArrayObj.Default := Value

このプロパティは、実はデフォルトでは存在せず、スクリプトで定義することができます。If defined, its value is returned by __Item or Get if the requested element has no value, instead of throwing an UnsetItemError. 動的プロパティや メタファンクションなど、通常の方法で実装できますが、どのキーが照会されたかを判断するには、代わりに__ItemやGetをオーバーライドする必要があります。

デフォルト値を設定しても、インデックスが範囲外である場合にエラーが発生することは防げません。

__Item

配列の要素の値を取得または設定します。

Value := ArrayObj[Index]
Value := ArrayObj.__Item[Index]
ArrayObj[Index] := Value
ArrayObj.__Item[Index] := Value

Index is an integer representing a valid array index; that is, an integer with absolute value between 1 and Length (inclusive). 負のインデックスは、-1が最後の要素、-2が2番目の最後の要素というように、要素を逆にアドレスするために使用することができます。範囲外のインデックス（ゼロや絶対値が配列の長さより大きい場合など）を使用しようとすると、エラーとみなされ、IndexErrorがスローされます。

プロパティ名 __Item は、上記のように通常は省略されますが、プロパティをオーバーライドする際に使用されます。