VarSetCapacity()

変数に確保されているメモリのサイズを変更する。

VarSetCapacity(Var [, RequestedCapacity, FillByte])

Parameters

返り値

実際に確保された領域のサイズ。
終端のnull文字の分は含まれない。
RequestedCapacityで指定したサイズと同じか、それより小さくなる。
何らかの問題があって確保が行われなかった場合、0が返る。
RequestedCapacity引数を省略した場合、Varで指定した変数に現在確保されているメモリ領域のサイズが返る。

Remarks

空きメモリが不足していて領域の再確保ができないなどの場合、エラーダイアログが表示され、現在のスレッドが強制終了する。

AutoHotkeyのコマンドや関数などを実行する場合、変数のサイズは必要に応じて自動的に伸張される。
この場合、頻繁なサイズの変化によって再確保が多発してパフォーマンスが低下するのを防ぐため、内容のサイズよりも少し大きい領域を確保する。
内容のサイズが64バイト未満の場合、0,1,6,63バイトが確保される。
確保されているサイズが4096バイト以上の場合、「Var=」などとして変数の内容を空にすると、領域を開放して0バイトになる。
それ未満の場合や、変数の内容が空にならない場合は、確保された領域はずっとそのままになる。

4096バイト未満の変数でも、「VarSetCapacity(Var,0)」とすることで領域を解放することができる。
ただし、64バイト未満の領域は開放されない。
どうしても開放したい場合は、一旦「VarSetCapacity(Var,64)」などとしてから開放する。

変数の内容のサイズと確保されている領域のサイズは、ListVarsコマンドなどで表示される変数の一覧で見られる。

RequestedCapacityに「-1」を指定すると、内部で保持されているサイズを数え直す。
これは、DllCallで「UInt,&var」のように変数のアドレスを渡し、DLLの関数内で変数の内容が書き換えられたときなどに利用される。
以下の例では、3行目が有るときと無いときで変数の文字数として表示される値が変わる。 「Str,var」のように文字列としてアドレスを渡した場合には、自動的に文字数は数え直される。

VarSetCapacity(var,256)
DllCall("msvcrt.dll\_mbscpy",UInt,&var,Str,"aaa",Str)
VarSetCapacity(var,-1)
ListVars
MsgBox

主に、DllCall()で一定のメモリを確保して渡す必要がある場合や、バッファの確保されているサイズを引数として渡す必要がある場合に使用する。

また、細かな文字列の連結を繰り返す場合などに、あらかじめ大きな領域を確保しておくことで、再確保の発生を減らしてパフォーマンスを向上させることもできる。

Related

DllCall(), #MaxMem

Examples

VarSetCapacity(MyVar, 1000)
Loop
{

	...
	MyVar = %MyVar%%StringToConcatenate%
	...
}