Notes C API探訪: LIST(データ型)その2

前回のLIST型に関する記事はこちらです。

https://note.com/chiburu/n/n65ff052db241

今回は、テキストリストに関する他の関数を紹介します。

ListAddEntry

ListAddEntry関数は、割り当てられているLIST領域を拡張して、テキストエントリーを1つ追加します。

STATUS LNPUBLIC ListAddEntry (
  DHANDLE hList,
  BOOL fPrefixDataType,
  WORD far *pListSize,
  WORD EntryNumber,
  const char far *Text,
  WORD TextSize);

hListは、LIST領域へのハンドルです。
fPrefixDataTypeは、確保している領域にデータタイププレフィックスが含まれるかどうかを示します。
pListSizeは、現在のLIST領域サイズを渡し、処理されると新しいサイズが返ります。
EntryNumberは、新しいエントリーを挿入する位置を示し、現在のエントリー数と同じであれば、終端に追加されます。
TextとTextSizeは、挿入するテキストのポインタとサイズを渡します。

ListAddText関数では、ListAllocate関数であらかじめ設定したサイズの範囲でしかテキストを追加できませんが、ListAddEntry関数では、現在のエントリー数、領域サイズに縛られずにテキストを追加できます。

ListGetNumEntry

ListGetNumEntry関数は、割り当てられているLIST領域のエントリー数を返します。

WORD LNPUBLIC ListGetNumEntries (
  const void far *vList,
  BOOL NoteItem);

vListは、ロックされたLIST領域へのポインタです。
NoteItemは、確保している領域にデータタイププレフィックスが含まれるかどうかを示します。
関数はLIST領域が有しているエントリー数を返します。

ListGetNumEntry関数は、エントリー数が不明なハンドルのポインタでも、エントリー数を把握できるようになります(ポインタをLISTポインタにキャストすればエントリー数はわかりますが)。

ListGetSize

ListGetSize関数は、割り当てられているLIST領域の全体のサイズを返します。

WORD   LNPUBLIC ListGetSize (
  void far *pList,
  BOOL fPrefixDataType);

pListは、ロックされたLIST領域へのポインタです。
fPrefixDataTypeは、確保している領域にデータタイププレフィックスが含まれるかどうかを示します。
関数はLIST領域が有している全体のサイズを返します。

ListGetSize関数は、全体のサイズが不明なハンドルのポインタでも、全体サイズを把握できるようになります(ポインタをLISTポインタにキャストすればわかりますが、こちらは少々面倒です)。

ListRemoveEntry

ListRemoveEntry関数は、LIST領域の指定した番号のエントリーを削除します。

STATUS LNPUBLIC ListRemoveEntry (
  DHANDLE hList,
  BOOL fPrefixDataType,
  WORD far *pListSize,
  WORD EntryNumber);

hListは、LIST領域へのハンドルです。
fPrefixDataTypeは、確保している領域にデータタイププレフィックスが含まれるかどうかを示します。
pListSizeは、現在のLIST領域サイズを渡し、処理されると新しいサイズが返ります。
EntryNumberは、エントリーを削除する位置を示します。

ListRemoveAllEntries

ListRemoveAllEntries関数は、LIST領域のすべてのエントリーを削除します。

STATUS LNPUBLIC ListRemoveAllEntries (
  DHANDLE hList,
  BOOL fPrefixDataType,
  WORD far *pListSize);

hListは、LIST領域へのハンドルです。
fPrefixDataTypeは、確保している領域にデータタイププレフィックスが含まれるかどうかを示します。
pListSizeは、現在のLIST領域サイズを渡し、処理されると新しいサイズが返ります。LIST領域のエントリー数は0になります。

ListDuplicate

ListDuplicate関数は、既存LIST領域全体を複製したあたらしいLIST領域へのハンドルを返します。

STATUS LNPUBLIC ListDuplicate(
  LIST far *pInList,
  BOOL	fNoteItem,
  DHANDLE far *phOutList);

pInListは、ロックされたLIST領域へのポインタです。
fNoteItemは、確保している領域にデータタイププレフィックスが含まれるかどうかを示します。
phOutListは、関数が作成したLIST領域へのハンドルを受け取るポインタを示します。

ListDuplicate関数を使えば、コピー元のリストから、ListGetNumEntry関数でエントリー数、ListGetSizeで全体サイズを取得し、ListAllocate関数で新しい領域を確保し、ListAddTextでテキストを追加する手間が省けます。

まとめ

std::vectorなどのコンテナクラスに比べれば必要最低限の機能しかないLIST型とその操作関数ですが、うまくラップすれば使い勝手を向上させることができるでしょう。加えて、コンテナクラスとの相互変換機能を追加できれば、さらに使いやすくなると思います。