プロパティリスト

プロパティリストオブジェクトとそれに関する API. [詳解]

関数
MPlist *	mplist_deserialize (MText *mt)
	M-text をデシリアライズしてプロパティリストを作る.
MPlist *	mplist (void)
	プロパティリストオブジェクトを作る.
MPlist *	mplist_copy (MPlist *plist)
	プロパティリストをコピーする.
MPlist *	mplist_put (MPlist *plist, MSymbol key, void *val)
	プロパティリスト中のプロパティの値を設定する.
void *	mplist_get (MPlist *plist, MSymbol key)
	プロパティリスト中のプロパティの値を得る.
MPlist *	mplist_put_func (MPlist *plist, MSymbol key, M17NFunc func)
	プロパティリスト中のプロパティに関数ポインタである値を設定する.
M17NFunc	mplist_get_func (MPlist *plist, MSymbol key)
	プロパティリストからプロパティの関数ポインタである値を得る.
MPlist *	mplist_add (MPlist *plist, MSymbol key, void *val)
	プロパティリスト末尾にプロパティを追加する.
MPlist *	mplist_push (MPlist *plist, MSymbol key, void *val)
	プロパティリストの先頭にプロパティを挿入する.
void *	mplist_pop (MPlist *plist)
	プロパティリストの先頭からプロパティを削除する.
MPlist *	mplist_find_by_key (MPlist *plist, MSymbol key)
	プロパティリスト中から指定のキーを持つプロパティを探す.
MPlist *	mplist_find_by_value (MPlist *plist, void *val)
	プロパティリスト中から指定の値を持つプロパティを探す.
MPlist *	mplist_next (MPlist *plist)
	プロパティリストの次の部分リストを返す.
MPlist *	mplist_set (MPlist *plist, MSymbol key, void *val)
	プロパティリストの最初のプロパティを設定する.
int	mplist_length (MPlist *plist)
	プロパティリストの長さを返す.
MSymbol	mplist_key (MPlist *plist)
	プロパティリスト中の最初のプロパティのキーを返す.
void *	mplist_value (MPlist *plist)
	プロパティリスト中の最初のプロパティの値を返す.

変数
MSymbol	Minteger
	"integer" を名前として持つシンボル.
MSymbol	Mplist
	"plist" を名前として持つシンボル.
MSymbol	Mtext
	"mtext" を名前として持つシンボル.

詳解

プロパティリストオブジェクトとそれに関する API.

プロパティリスト (または plist) は 0 個以上のプロパティのリストである。プロパティは キー と 値 からなる。キーはシンボルであり、値は (void *) にキャストできるものならば何でも良い。

あるプロパティのキーが 管理キー ならば、その 値 は 管理下 オブジェクト である。プロパティリスト自体も管理下オブジェクトである。

関数詳解

mplist_deserialize()

MPlist * mplist_deserialize

(

MText *

mt

)

M-text をデシリアライズしてプロパティリストを作る.

関数 mplist_deserialize() は M-text mt を解析してプロパティリストを返す。

mt のシンタックスは以下の通り。

MT ::= '(' ELEMENT * ')'

ELEMENT ::= SYMBOL | INTEGER | M-TEXT | PLIST

SYMBOL ::= アスキー文字列

INTEGER ::= '-' ? [ '0' | .. | '9' ]+ | '0x' [ '0' | .. | '9' | 'A' | .. | 'F' | 'a' | .. | 'f' ]+

M-TEXT ::= '"' character-sequence '"'

ELEMENT の各選択肢はキー：Msymbol, Minteger, Mtext, Mplist のいずれかを割り当てられている。

アスキー文字列内では、バックスラッシュ () がエスケープ文字として用いられる。たとえば abc\ def は 4 文字目が空白文字であり長さが 7 である持つ名前を持つシンボルを生成する。

mplist()

MPlist * mplist

(

void

)

プロパティリストオブジェクトを作る.

関数 mplist() は長さ 0 のプロパティリストオブジェクトを新しく作って返す。

戻り値:

この関数は新しく作られたプロパティリストオブジェクトを返す。

エラー:

この関数は決して失敗しない。

mplist_copy()

MPlist * mplist_copy

(

MPlist *

plist

)

プロパティリストをコピーする.

関数 mplist_copy() はプロパティリスト plist をコピーする。コピーのすべての値はコピー元 plist の値と同じである。

戻り値:

この関数は新しく作られた、plist のコピーであるプロパティリストを返す。

エラー:

この関数は決して失敗しない。

mplist_put()

MPlist * mplist_put	(	MPlist *	plist,
		MSymbol	key,
		void *	val
	)

プロパティリスト中のプロパティの値を設定する.

関数 mplist_put() はプロパティリスト plist を始めから探して、キーが key であるプロパティを見つける。見つかれば、その値を value に変更する。見つからなければ、キーが key で値が value である新しいプロパティが plist の末尾に追加される。key と val に対する制限については、mplist_add() の説明を参照。

key が管理キーならば、 val は管理下オブジェクトでなくてはならない。この場合、古い値の参照数は NULL でなければ 1 減らされ、val の参照数は 1 増やされる。

戻り値:

処理が成功すれば mplist_put() は変更されたか追加された要素から始まる plist の部分リストを返す。そうでなければ NULL を返す。

mplist_get()

void * mplist_get	(	MPlist *	plist,
		MSymbol	key
	)

プロパティリスト中のプロパティの値を得る.

関数 mplist_get() は、プロパティリスト plist を始めから探して、キー が key であるプロパティを見つける。見つかれば、その値を (void *) 型で返す。見つからなければ NULL を返す。

NULL が返った際には二つの可能性がある: 上記のようにプロパティが見つからなかった場合と、プロパティが見つかり、その値が NULL である場合である。これらを区別する必要がある場合には関数 mplist_find_by_key() を使うこと。

参照:

mplist_find_by_key()

mplist_put_func()

MPlist * mplist_put_func	(	MPlist *	plist,
		MSymbol	key,
		M17NFunc	func
	)

プロパティリスト中のプロパティに関数ポインタである値を設定する.

関数 mplist_put_func() は関数 mplist_put() 同様、プロパティリスト plist 中でキーが key であるプロパティに値を設定する。但しその値は関数ポインタ func である。key は管理キーであってはならない。

参照:

mplist_put(), M17N_FUNC()

mplist_get_func()

M17NFunc mplist_get_func	(	MPlist *	plist,
		MSymbol	key
	)

プロパティリストからプロパティの関数ポインタである値を得る.

関数 mplist_get_func() は関数 mplist_get() と同様に、プロパティリ スト plist 中でキーが key であるプロパティの値、但し関数ポインタ、 を得る。

参照:

mplist_get()

mplist_add()

MPlist * mplist_add	(	MPlist *	plist,
		MSymbol	key,
		void *	val
	)

プロパティリスト末尾にプロパティを追加する.

関数 mplist_add() は、プロパティリスト plist の末尾にキーが key で値が val であるプロパティを追加する。key は、Mnil 以外の任意のシンボルでよい。

key が管理キーならば、val は管理下オブジェクトでなくてはならない。この場合、 val の参照数は 1 増やされる。

戻り値:

処理が成功すれば mplist_add() は追加された要素から始まる plist の部分リストを返す。そうでなければ NULL を返す。

mplist_push()

MPlist * mplist_push	(	MPlist *	plist,
		MSymbol	key,
		void *	val
	)

プロパティリストの先頭にプロパティを挿入する.

関数 mplist_push() はプロパティリスト plist の先頭にキーが key で値が val であるオブジェクトを挿入する。

key が管理キーならば、val は管理下オブジェクトでなくてはならない。この場合、 val の参照数は 1 増やされる。

戻り値:

処理が成功すればこの関数は plist を返し、そうでなければNULL を返す。

mplist_pop()

void * mplist_pop

(

MPlist *

plist

)

プロパティリストの先頭からプロパティを削除する.

関数 mplist_pop() はプロパティリスト plist の先頭のプロパティを削 除する。結果として、元の2番目のキーと値が先頭のキーと値になる。

戻り値:

処理に成功すれば、この関数は削除されたプロパティの値を返す。そうでなければ NULL を返す。

mplist_find_by_key()

MPlist * mplist_find_by_key	(	MPlist *	plist,
		MSymbol	key
	)

プロパティリスト中から指定のキーを持つプロパティを探す.

関数 mplist_find_by_key() はプロパティリスト plist を始めから探 して、キーが key であるプロパティを見つける。見つかれば、そのプロパティから始まる plist の部分リストを返す。そうでなければ NULL を返す。

key が Mnil ならば、plist の最後の要素から始まる部分リストを返す。

mplist_find_by_value()

MPlist * mplist_find_by_value	(	MPlist *	plist,
		void *	val
	)

プロパティリスト中から指定の値を持つプロパティを探す.

関数 mplist_find_by_value() はプロパティリスト plist を始めから探して、値が val であるプロパティを見つける。見つかれば、そのプロパティから始まる plist の部分リストを返す。そうでなければ NULL を返す。

mplist_next()

MPlist * mplist_next

(

MPlist *

plist

)

プロパティリストの次の部分リストを返す.

関数 mplist_next() はプロパティリスト plist の 2 番目の要素から始まる部分リストへのポインタを返す。plist の長さが 0 ならば NULL を返す。

mplist_set()

MPlist * mplist_set	(	MPlist *	plist,
		MSymbol	key,
		void *	val
	)

プロパティリストの最初のプロパティを設定する.

関数 mplist_set() はプロパティリスト plist の最初のプロパティのキーと値をそれぞれ key と value に設定する。 key と val に対する制限については、mplist_add() の説明を参照。

戻り値:

処理に成功すれば mplist_set() は plist を返す。そうでなければ NULL を返す。

mplist_length()

int mplist_length

(

MPlist *

plist

)

プロパティリストの長さを返す.

関数 mplist_length() はプロパティリスト plist 中のプロパティの数を返す。

mplist_key()

MSymbol mplist_key

(

MPlist *

plist

)

プロパティリスト中の最初のプロパティのキーを返す.

関数 mplist_key() は、プロパティリスト plist 中の最初のプロパティのキーを返す。plist の長さが 0 ならば、 Mnil を返す。

mplist_value()

void * mplist_value

(

MPlist *

plist

)

プロパティリスト中の最初のプロパティの値を返す.

関数 mplist_value() は、プロパティリスト plist 中の最初のプロパティの値を返す。 plist の長さが 0 ならば、 Mnil を返す。

変数詳解

Minteger

MSymbol Minteger

"integer" を名前として持つシンボル.

シンボル Minteger は "integer" という名前を持つ。キーが Minteger であるプロパティの値は整数値でなくてはならない。

Mplist

MSymbol Mplist

"plist" を名前として持つシンボル.

シンボル Mplist は "plist" という名前を持つ。これは管理キーである。キーが Mplist であるプロパティの値は plist でなくてはならない。

Mtext

MSymbol Mtext

"mtext" を名前として持つシンボル.

シンボル Mtext は "mtext" という名前を持つ管理キーである。キーが Mtext であるプロパティの値は M-text でなくてはならない。