C APIの関数と型：newstate–pcallk

`lua_newstate`

[-0, +0, –]

lua_State *lua_newstate (lua_Alloc f, void *ud,
                                   unsigned int seed);

新しい独立したステートを作成し、そのメインスレッドを返します。（メモリ不足によって）ステートを作成できなければNULLを返します。引数fはアロケーター関数です。Luaはこの関数を通じて、このステートのすべてのメモリ割り当てを行います（lua_Allocを参照）。第2引数udは、Luaが呼び出しのたびにアロケーターへ渡す不透明ポインターです。第3引数seedは文字列ハッシュ用のシードです。

`lua_newtable`

[-0, +1, m]

void lua_newtable (lua_State *L);

新しい空のテーブルを作成し、スタックへプッシュします。lua_createtable(L,0,0)と等価です。

`lua_newthread`

[-0, +1, m]

lua_State *lua_newthread (lua_State *L);

新しいスレッドを作成してスタックへプッシュし、この新しいスレッドを表すlua_Stateへのポインターを返します。この関数が返す新しいスレッドは、元のスレッドとグローバル環境を共有しますが、独立した実行スタックを持ちます。

スレッドはほかのLuaオブジェクトと同様にガベージコレクションの対象です。

`lua_newuserdatauv`

[-0, +1, m]

void *lua_newuserdatauv (lua_State *L, size_t size, int nuvalue);

この関数は、user values（ユーザー値）と呼ばれるnuvalue個の関連付けられたLua値と、sizeバイトの関連付けられた生のメモリブロックを持つ、新しいフルユーザーデータを作成してスタックへプッシュします。

ユーザー値は関数lua_setiuservalueとlua_getiuservalueで設定・読み取りできます。メモリブロックは任意のISO Cオブジェクトに適切にアラインされます。（そのほかのアラインメント要件については、ファイルluaconf.hのマクロLUAI_MAXALIGNを参照。）

関数はメモリブロックのアドレスを返します。対応するユーザーデータが生存している限り、このアドレスが有効であることをLuaが保証します（§2.5を参照）。さらに、ユーザーデータがファイナライズ対象として印を付けられていれば（§2.5.3を参照）、少なくともそのファイナライザーの呼び出しまでアドレスは有効です。

`lua_next`

[-1, +(2|0), v]

int lua_next (lua_State *L, int index);

スタックからキーをポップし、指定されたインデックスのテーブルから、指定されたキーの「次」にあるキーと値の組をプッシュします。テーブルにそれ以上要素がなければ、lua_nextは0を返して何もプッシュしません。

典型的なテーブル走査は次のようになります。

     /* table is in the stack at index 't' */
     lua_pushnil(L);  /* first key */
     while (lua_next(L, t) != 0) {
       /* uses 'key' (at index -2) and 'value' (at index -1) */
       printf("%s - %s\n",
              lua_typename(L, lua_type(L, -2)),
              lua_typename(L, lua_type(L, -1)));
       /* removes 'value'; keeps 'key' for next iteration */
       lua_pop(L, 1);
     }

テーブルの走査中、キーが実際に文字列であると分かっている場合を除き、キーに対して直接lua_tolstringを呼び出すことは避けてください。lua_tolstringは指定されたインデックスの値を変更する可能性があり、これによって次のlua_next呼び出しが混乱することを思い出してください。

指定されたキーがnilでもテーブル内に存在するものでもない場合、この関数はエラーを発生させる可能性があります。

走査の詳細については関数nextを参照してください。

`lua_Number`

typedef ... lua_Number;

Luaにおける浮動小数点数の型です。

デフォルトでこの型はdoubleですが、single floatまたはlong doubleへ変更できます。（luaconf.hのLUA_FLOAT_TYPEを参照。）

`lua_numbertointeger`

int lua_numbertointeger (lua_Number n, lua_Integer *p);

Lua浮動小数点数をLua整数へ変換しようとします。浮動小数点数nは整数値を持つ必要があります。その値がLua整数の範囲内なら、整数へ変換して*pへ代入します。マクロの結果は変換が成功したかを示すブール値です。（丸めのため、このマクロなしでこの範囲検査を正しく行うのは難しい場合があります。）

このマクロは引数を複数回評価する場合があります。

`lua_numbertocstring`

[-0, +0, –]

unsigned lua_numbertocstring (lua_State *L, int idx,
                                        char *buff);

許容されるインデックスidxの数値を文字列へ変換し、結果をbuffへ格納します。バッファーは少なくともLUA_N2SBUFFSZバイトのサイズを持つ必要があります。変換は規定されていない形式に従います（§3.4.3を参照）。関数はバッファーへ書き込んだバイト数（最後のゼロを含む）を返し、idxの値が数値でなければ0を返します。

`lua_pcall`

[-(nargs + 1), +(nresults|1), –]

int lua_pcall (lua_State *L, int nargs, int nresults, int msgh);

関数（または呼び出し可能なオブジェクト）を保護モードで呼び出します。

nargsとnresultsはどちらもlua_callと同じ意味を持ちます。呼び出し中にエラーがなければ、lua_pcallはlua_callとまったく同様に動作します。ただし、エラーがある場合、lua_pcallはエラーを捕捉し、単一の値（エラーオブジェクト）をスタックへプッシュして、エラーコードを返します。lua_callと同様に、lua_pcallは常に関数とその引数をスタックから除去します。

msghが0なら、スタックへ返されるエラーオブジェクトは元のエラーオブジェクトそのものです。それ以外の場合、msghはメッセージハンドラーのスタックインデックスです。（このインデックスを疑似インデックスにすることはできません。）実行時エラーの場合、このハンドラーはエラーオブジェクトを指定して呼び出され、その戻り値がlua_pcallによってスタックへ返されるオブジェクトになります。

通常、メッセージハンドラーはスタックトレースバックなど、エラーオブジェクトへさらにデバッグ情報を追加するために使われます。lua_pcallが返った後ではスタックが巻き戻されているため、このような情報を収集できません。

関数lua_pcallは、次のステータスコードのいずれかを返します：LUA_OK、LUA_ERRRUN、LUA_ERRMEM、LUA_ERRERR。

`lua_pcallk`

[-(nargs + 1), +(nresults|1), –]

int lua_pcallk (lua_State *L,
                int nargs,
                int nresults,
                int msgh,
                lua_KContext ctx,
                lua_KFunction k);

この関数は、呼び出された関数がyieldすることを許可する点（§4.5を参照）を除き、lua_pcallとまったく同様に動作します。