Luaでのプログラミング: 24.2.2

この第1版はLua 5.0向けに書かれました。後続のバージョンでも大部分は引き続き関連性はありますが、相違点もあります。
第4版はLua 5.3を対象とし、Amazonやその他の書店で入手できます。
本を購入することで、Luaプロジェクトをサポートすることもできます。

LuaでのプログラミングLua

第4部. C API 第24章. C APIの概要

24.2.2 – 要素のクエリ

スタック内の要素を参照するために、APIはインデックスを使用します。スタック内の最初の要素（つまり、最初にプッシュされた要素）のインデックスは1、次の要素のインデックスは2、という具合です。負のインデックスを使用して、スタックの先頭を基準として要素にアクセスすることもできます。その場合、-1は先頭の要素（つまり、最後にプッシュされた要素）を参照し、-2は前の要素を参照し、という具合です。たとえば、lua_tostring(L, -1)という呼び出しは文字列としてスタックの先頭の値を返します。後述するように、スタックを下から（つまり、正のインデックスを使用して）インデックス付けすることが自然な場合と、負のインデックスを使用することが自然な場合が数多くあります。

要素に特定の型があるかどうかを検査するために、APIはlua_is*関数のファミリーを提供します。ここで*は任意のLuaの型です。つまり、lua_isnumber、lua_isstring、lua_istableなどが存在します。これらの関数すべては同じプロトタイプを持っています

    int lua_is... (lua_State *L, int index);

lua_isnumber関数とlua_isstring関数は、値がその特定の型であるかどうかを検査するのではなく、値がその型に変換できるかどうかを検査します。たとえば、任意の数字はlua_isstringを満たします。

また、スタック内の要素の型を返すlua_type関数もあります。（一部のlua_is*関数は実際には、この関数を使用しているマクロです。）各型はヘッダファイルlua.hで定義されている定数、すなわちLUA_TNIL、LUA_TBOOLEAN、LUA_TNUMBER、LUA_TSTRING、LUA_TTABLE、LUA_TFUNCTION、LUA_TUSERDATA、およびLUA_TTHREADで表されます。この関数は主にswitchステートメントと組み合わせて使用されます。文字列と数字を強制変換せずに検査する必要がある場合にも役立ちます。

スタックから値を取得するには、lua_to*関数があります

    int            lua_toboolean (lua_State *L, int index);
    double         lua_tonumber (lua_State *L, int index);
    const char    *lua_tostring (lua_State *L, int index);
    size_t         lua_strlen (lua_State *L, int index);

指定された要素が正しい型を持たない場合でも、これらの関数を呼び出すことができます。この場合、lua_toboolean、lua_tonumber、およびlua_strlenはゼロを返し、他の関数はNULLを返します。ゼロは役に立ちませんが、ANSI Cではエラーを示すために使用できる無効な数値はありません。ただし、他の関数の場合は、対応するlua_is*関数を使用する必要はほとんどありません。lua_to*を呼び出してから結果がNULLでないかどうかをテストするだけです。

lua_tostring関数は文字列の内部コピーへのポインタを返します。変更することはできません（リマインドとしてconstがあります）。Luaは、対応する値がスタック内にある限り、このポインタが有効であることを保証します。C関数が返されると、Luaはそのスタックをクリアします。したがって、ルールとして、それらを取得した関数の外部にLua文字列へのポインタを格納することは決してありません。

lua_tostringが返す文字列は、必ず最後にゼロがありますが、内部に他のゼロを含むことがあります。lua_strlen関数は文字列の正しい長さを返します。特に、スタックの頂上の値が文字列であると仮定すると、次のアサーションは常に有効です

    const char *s = lua_tostring(L, -1);   /* any Lua string */
    size_t l = lua_strlen(L, -1);          /* its length */
    assert(s[l] == '\0');
    assert(strlen(s) <= l);