;
;	HSP help manager用 HELPソースファイル
;	(先頭が「;」の行はコメントとして処理されます)
;

%type
内蔵命令
%ver
3.6
%note
ver3.6標準命令
%date
2020/01/07
%author
onitama
%url
http://hsp.tv/
%port
Win
Cli
Let



%index
getstr
バッファから文字列読み出し
%group
文字列操作命令
%prm
p1,p2,p3,p4,p5
p1=変数   : 内容を読み出す先の変数名
p2=変数   : バッファを割り当てた変数名
p3=0〜    : バッファのインデックス(Byte単位)
p4=0〜255 : 区切りキャラクタのASCIIコード
p5=0〜(1024) : 読み出しを行なう最大文字数

%inst
メモリ上のバッファの任意の場所にある内容を文字列として変数に読み出します。
文字列は、00というコードか、改行コードがあるまで読み出されます。改行コードは文字列には含まれません。
^
また、区切りキャラクタコードを指定することができ任意の文字で区切られた文字列を取り出すこともできます。
^
この命令で読み出されたByte数は自動的に strsizeというシステム変数に代入されます。strsizeは、次のインデックスまでの移動量を得る時に使用します。
^
たとえば、変数bのバッファに'A' 'B' 'C' ',' 'D' 'E' 'F' 00(終了コード)というデータが入っている場合、
^p
getstr a,b,0,','
^p
を実行すると、変数aの内容は、'A' 'B' 'C' の部分が読み出されて"ABC"という文字列になり、strsize は4になります。
^
p5パラメーターにより、読み出しを行なう最大文字数(byte数)を指定することができます。
p5パラメーターが省略された場合には、1024文字(byte)までの読み出しを行ないます。
(p1で指定された変数のバッファは自動的に確保されるので、sdim命令等でバッファの設定を行なっておく必要はありません。)
^
この命令は、複数行を含むテキスト文字列データや、特定の文字で区切られたデータを効率よく切り出すためのものです。
複数行を含むテキストを扱うためには、他にもメモリノートパッド命令セットがあります。また、文字列から特定数の文字を取り出すためには、strmid命令が用意されています。

%href
strmid




%index
noteadd
指定行の追加・変更
%group
文字列操作命令
%prm
p1,p2,p3
p1=文字列  : 追加・変更をする文字列または変数名
p2=0〜(-1) : 追加するインデックス
p3=0〜1(0) : 上書きモード指定(0=追加・1=上書き)

%inst
メモリノートパッドの内容を追加・変更します。
^
p1に追加・変更するための文字列を指定します。p2で、対象となるインデックスを指定します。
p2パラメータを省略するか、-1を指定すると最終行が対象になります。
p3パラメータで、追加か上書きかを指定します。省略するか、0を指定すると、追加モードとなり、対象となるインデックス以降が１つづつシフトします。
p3が1の場合は、上書きモードとなり、 対象となるインデックスの内容は消去され、指定した文字列に置き換えられます。
^
noteaddは、 変数バッファにsdim命令などであらかじめ確保された容量を超えて内容を追加しようとした場合は、自動的に確保容量を増加させて格納します。
つまり、「sdim a,64」 で６４文字までしか記憶できないメモリバッファであっても、追加するサイズに応じて自動的にメモリサイズを調節して安全に記憶させることができます。
^
メモリノートパッド命令(noteget,noteadd,notedel,noteinfo)を使用するためには、最初にnotesel命令で対象となるバッファを設定しなければなりません。

%href
notesel

%sample
	sdim a,10000
	notesel a
	noteadd "newidx1"
	noteadd "newidx3"
	noteadd "newidx2",1
	mes a
	stop




%index
notedel
行の削除
%group
文字列操作命令
%prm
p1
p1=0〜 : 削除するインデックス

%inst
メモリノートパッドの指定したインデックスを削除します。
p1で指定したインデックスの内容は削除され、以降のインデックスが１つづつシフトします。
^
メモリノートパッド命令(noteget,noteadd,notedel,noteinfo)を使用するためには、最初にnotesel命令で対象となるバッファを設定しなければなりません。

%href
notesel




%index
noteget
指定行を読み込み
%group
文字列操作命令
%prm
p1,p2
p1=変数   : 読み出し先の変数名
p2=0〜(0) : 読み出すインデックス

%inst
メモリノートパッド内の、p2で指定したインデックスの内容をp1で指定された変数に代入します。メモリノートパッド内の任意の行にある内容を読み出すことができます。
^
インデックスは0から始まるので注意してください。
p1で指定する変数には、変数バッファにsdim命令などであらかじめ確保された容量を超えて内容を追加しようとした場合は、自動的に確保容量を増加させて格納します。また、p1の変数は強制的に文字列型に変更されます。
^
メモリノートパッド命令(noteget,noteadd,notedel,noteinfo)を使用するためには、最初にnotesel命令で対象となるバッファを設定しなければなりません。

%href
notesel

%sample
	a="idx0\nidx1\nidx2"
	notesel a
	noteget b,1
	mes b
	stop




%index
noteinfo
メモリノートパッド情報取得
%group
文字列操作関数
%prm
(p1)
p1(0) : 情報取得モード

%inst
noteinfo関数は、現在対象となっているメモリノートパッドについての情報を取得します。
p1で情報取得モードを指定します。また、それぞれのモードに対応したマクロが定義されています。
^p
   モード : マクロ    内容
 -----------------------------------------------------------
      0   : notemax   全体の行数
      1   : notesize  全体の文字数(バイト数)
^p
notemaxマクロは、 複数行の文字列ですべての行に対して繰り返し処理を行ないたい場合などに使用します。
全体の行数とは、つまりメモリノートパッド内にある要素の数です。
「APPLE」「ORANGE」「GRAPE」という行がある場合には、3になります。
この場合、インデックスは0〜2までになります。
^
メモリノートパッド命令(noteget,noteadd,notedel,noteinfo)を使用するためには、最初にnotesel命令で対象となるバッファを設定しなければなりません。

%href
notesel
noteget
notedel
notemax
notesize

%sample
	nmax=0
	notesel a
	noteload "aaa.txt"
	idx=0
	repeat notemax
		noteget b,idx
		print "index"+idx+"="+b
		idx++
	loop
	stop




%index
notesel
対象バッファ指定
%group
文字列操作命令
%prm
p1
p1=変数 : バッファを割り当てた変数名

%inst
p1で指定した変数をメモリノートパッド命令のバッファに設定します。
^
p1で指定した変数は、強制的に文字列型に変更されます。
他のメモリノートパッド命令(noteget,noteadd,notedel,noteinfo)を使用するためには、最初に notesel命令で対象となるバッファを設定しなければなりません。

%href
noteunsel
noteget
noteadd
notedel
noteinfo
notemax
notesize
notefind

%sample
notesel a
noteadd "test strings"
mes a
stop


%index
noteunsel
対象バッファの復帰
%group
文字列操作命令
%prm

%inst
noteunsel命令は、notesel命令で対象となるバッファを設定する前に設定されていたバッファ設定に戻します。
noteunsel命令は必ず入れておく必要はありませんが、notesel命令で設定したバッファを使い終わった後に入れておくことで、noteselによるバッファ指定が多重に行なわれることを防止します。

%href
notesel





%index
strmid
文字列の一部を取り出す
%group
文字列操作関数
%prm
(p1,p2,p3)
p1=変数名 : 取り出すもとの文字列が格納されている変数名
p2=-1〜   : 取り出し始めのインデックス
p3=0〜    : 取り出す文字数
%inst
p1で指定した文字列型変数の中から、 p2,p3で指定した条件で文字を取り出したものを返します。
p2で取り出し始めるインデックスを指定します。これは、文字列の始まり１文字目を0として、1,2,3...と順番に増えていくものです。1から始まりではないので注意してください。
p3で取り出す文字数を指定します。実際に格納されている文字数よりも多く指定した場合は、実際の文字数までが取り出されます。
また、p2に-1を指定すると文字列の右からp3で指定した文字数だけ取り出します。
%sample
	b="ABCDEF"
	a=strmid(b,-1,3)   ; 右から３文字を取り出す
	a=strmid(b,1,3)    ; 左から２文字目から３文字を取り出す
%href
getstr


%index
instr
文字列の検索をする
%group
文字列操作関数
%prm
(p1,p2,"string")
p1=変数名 : 検索される文字列が格納されている文字列型変数名
p2=0〜(0) : 検索を始めるインデックス
"string"  : 検索する文字列
%inst
p1で指定した文字列型変数の中に、"string"で指定した文字列があるかどうか調べて、インデックスを返します。
^
指定した文字列が見つかった場合には、インデックス値が返されます。これは、文字列の始まり１文字目を0として、1,2,3...と順番に増えていくものです(strmid命令で指定するインデックスと同様です)。
1から始まりではないので注意してください。
(p2を指定した場合、インデックスはp2を起点(0)とするものになります。)
(p2がマイナス値の場合は常に-1が返されます。)
もし、指定した文字列が見つからなかった場合には-1が返されます。
%href
strmid
strrep
notefind



%index
notesave
対象バッファ保存
%group
文字列操作命令
%prm
"filename"
"filename" : 書き込みファイル名
%inst
メモリノートパッド命令のバッファの内容を指定したファイルにテキストファイルとして保存します。
必ず最初にnotesel命令で対象となるバッファを設定する必要があるので注意してください。
notesave命令は、指定バッファに含まれる文字列の長さで保存します。

%href
notesel
noteload
noteget
noteadd
notedel
noteinfo
%port-
Let



%index
noteload
対象バッファ読み込み
%group
文字列操作命令
%prm
"filename",p1
"filename" : 読み込みファイル名
p1(-1)     : 読み込みサイズの上限値
%inst
指定したファイルをメモリノートパッド命令のバッファに読み込みます。
通常は、テキストファイルを読み込み、メモリノートパッド命令で読み出す対象とします。
メモリノートパッド命令のバッファは、自動的にファイルのサイズに従って確保サイズが調節されるため、バッファのサイズをあらかじめ指定しておく必要はありません。
p1で、読み込むファイルの最大サイズを指定することができます。
指定を省略またはマイナス値にした場合は、どんなサイズでも読み込みます。
テキストファイル以外のファイルを読み込むことも可能です。
必ず最初にnotesel命令で対象となるバッファを設定する必要があるので注意してください。
%href
notesel
notesave
noteget
noteadd
notedel
noteinfo
notemax
notesize
notefind


%index
getpath
パスの一部を取得
%group
文字列操作関数
%prm
(p1,p2)
p1=文字列 : 取り出す元の文字列
p2=0〜    : 情報のタイプ指定
%inst
p1で指定したファイルパスを示す文字列をp2で指定したタイプの情報に変換したものを文字列として返します。
^p
例 :
	a="c:\\disk\\test.bmp"
	b = getpath(a,8+1)
	mes b
	↓(結果)
	"test"となる
^p
タイプ指定の詳細は以下の通りです。
^p
   タイプ : 内容
 -----------------------------------------------------------
     0    : 文字列のコピー(操作なし)
     1    : 拡張子を除くファイル名
     2    : 拡張子のみ(.???)
     8    : ディレクトリ情報を取り除く
    16    : 文字列を小文字に変換する
    32    : ディレクトリ情報のみ
^p
タイプ値は、合計することで複数指定を行なうことが可能です。
タイプ16が指定された場合は、すべての英文字列を小文字に変換します。
%href
getstr
instr





%index
strf
書式付き文字列を変換
%group
文字列操作関数
%prm
("format",p1...)
"format" : 書式指定文字列
p1       : 書式指定パラメーター
%inst
整数または実数値を適切な書式で文字列に変換した文字列を返します。
"format"で、以下のような書式指定文字列を指定します。
^p
例 :
	a=123
	mes strf("10進[%d]",a)
	mes strf("16進[%x]",a)
	mes strf("10進桁数指定付き[%05d]",a)
	mes strf("16進桁数指定付き[%05x]",a)
	a=sqrt(2)
	mes strf("10進実数[%f]",a)
	mes strf("10進実数桁数指定付き[%3.10f]",a)
^p
p1以降で指定したパラメーターを示す部分には、「%」に続く指定を行ないます。
「%d」は整数値を、「%x」は１６進整数値を、「%c」は文字コード、「%f」は実数値をそれぞれ表示させることができます。
複数のパラメーターを書式で指定した場合は、その数だけ「,」で区切ってパラメーターを続けて記述してください。
通常の「%」記号を表示したい場合は、「%%」を指定してください。
^p
例 :
	a=1:b=2.0:c="ABC"
	mes strf("[%03d] [%f] [%s]",a,b,c)
^p
書式指定文字列は、Cランタイムライブラリがサポートしているsprintfの書式とほぼ同様です。
^p
	%[width][.precision][I64]type

	width : 出力する最小文字数
	precision : 出力する最大文字数
	            (typeがfの場合は小数点以下の桁数)
	I64   : 64bit値を示すプレフィックス
	type  : 入力されるパラメーターの型
^p
のような形式となり、[]内の記述は省略することが可能です。
typeで指定可能な文字は以下の通りです。
^p
	文字           内容
	---------------------------------------------
	  c     1バイト文字コード
	  d	符号付き 10 進整数
	  i	符号付き 10 進整数
	  u	符号なし 10 進整数
	  o	符号なし 8 進整数
	  x	符号なし 16 進整数(小文字)
	  X	符号なし 16 進整数(大文字)
	  e	[sign]dd[d] 形式の符号付きの実数値
	  E	[sign]dd[d] 形式の符号付きの実数値(大文字)
	  f	dddd.dddd 形式の符号付きの実数値
		(整数部の桁数は、その数値の絶対値によって決定され、
		 小数部の桁数は要求される精度によって決定されます。)
	  g	書式fまたはeで出力される符号付きの値のうち、
		指定された値および精度を表現できる短い方の書式
	  G	書式Gと同様で大文字を使用する
	  p	16進数の引数が指すアドレスを出力します
	  s	文字列
^p
書式指定文字列は、1023文字までの文字列のみ認識されますので注意してください。

%href
mes
print




%index
cnvwtos
unicodeを通常文字列に変換
%group
文字列操作関数
%prm
(p1)
p1=変数 : 内容を読み出す元の変数名

%inst
変数に保存されたデータをunicode(UTF-16)として読み取り、 通常の文字列に変換したものを返します。
unicodeデータを扱う場合や、外部DLL、 COMオブジェクトとのデータ変換などで使用することができます。

%href
cnvstow
cnvstoa
cnvatos
str
%port-
Let




%index
cnvstow
通常文字列をunicodeに変換
%group
文字列操作命令
%prm
p1,"string"
p1=変数  : 結果を書き込む変数名
"string" : 変換元の文字列

%inst
"文字列"で指定されたデータをunicode(UTF-16)文字列に変換して変数バッファに保存します。
p1で指定される変数には、あらかじめ文字列型として変換に十分なバッファサイズを確保しておく必要があります。
unicodeデータを扱う場合や、外部DLL、 COMオブジェクトへのデータ変換などで使用することができます。

%href
cnvwtos
cnvstoa
cnvatos
str
%port-
Let


%index
strtrim
指定した文字だけを取り除く
%group
文字列操作関数
%prm
(p1,p2,p3)
p1=変数 : 元の文字列が代入された変数
p2=0〜3(0) : 除去する位置の指定
p3=0〜65535(32) : 文字コード
%inst
p1で指定した変数に格納されている文字列の中から指定した文字だけを取り除きます。
p2で、除去する位置の指定を行なうことができます。
p2が省略された場合は、文字列の両端が指定文字だった場合のみ除去されます。
p3で除去する文字コードを指定することができます。
p3が省略された場合は、半角スペース(32)となります。
^p
例 :
	a=" ABC DEF "
	b = strtrim(a,0,' ')
	mes b
^p
p2で指定する、除去位置を示す値の詳細は以下の通りです。
^p
   タイプ : 内容
 -----------------------------------------------------------
     0    : 両端にある指定文字を除去する(デフォルト)
     1    : 左端にある指定文字を除去する
     2    : 右端にある指定文字を除去する
     3    : 文字列内にあるすべての指定文字を除去する
^p
p3で指定する文字コードには、全角文字を示す2バイトコードを指定することができます。
^p
例 :
	s="　こんにちは　全角文字です　"
	zenspace="　"				; 全角スペース
	code = wpeek(zenspace,0)		; 全角スペースのコードを取得
	mes strtrim(s,3,code)
^p
%href
strmid
instr



%index
split
文字列から分割された要素を代入
%group
文字列操作命令
%prm
p1,"string",p2...
p1=変数  : 元の文字列が代入された変数
"string" : 区切り用文字列
p2=変数  : 分割された要素が代入される変数

%inst
指定した文字列で分割された要素を変数に代入します。
たとえば、「12,34,56」のように「,」で区切られた文字列から、「12」「34」「56」の要素を取り出して、別々の変数に代入することができます。
p1で、もとの文字列が代入された変数名を指定します。(変数は、文字列型である必要があります)
"string"に区切るための文字列を指定します。
p2以降に、分割された要素が代入される変数名を指定します。
代入される変数は、「,」で区切っていくつでも指定することができます。
最初に指定した変数から順番に、分割された要素が代入されます。
^p
例 :
	buf="12,34,56"
	split buf, ",", a, b, c
	mes a
	mes b
	mes c
^p
指定された変数の数よりも、もともとの要素の数が少ない場合は、残りの変数に空の文字列("")が代入されます。
指定された変数の数よりも、分割された要素が多い場合は、指定された変数の配列に代入されていきます。
^p
例 :
	buf="12,34,56,78"
	split buf, ",", results
	repeat stat
		mes "配列("+cnt+")="+results(cnt)
	loop
^p
実行後に、システム変数statに分割できた数が代入されます。

%href
getstr
csvnote
%port-
Let



%index
strrep
文字列の置換をする
%group
文字列操作命令
%prm
p1,"検索文字列","置換文字列"
p1=変数名 : 検索される文字列が格納されている文字列型変数名
"検索文字列" : 検索する文字列
"置換文字列" : 置換する文字列
%inst
p1で指定した文字列型変数の内容すべてにおいて、
"検索文字列"で指定した文字列を、"置換文字列"に置き換えます。
^
実行後、システム変数statに文字列を置換した回数が代入されます。

%href
instr



%index
notefind
メモリノートパッド検索
%group
文字列操作関数
%prm
("string",p1)
"string" : 検索する文字列
p1(0)    : 検索モード

%inst
現在対象となっているメモリノートパッドの中から、特定の文字列を含む行を検索します。
p1で検索モードを指定します。それぞれのモードに対応したマクロが定義されています。
^p
   モード : マクロ            内容
 -----------------------------------------------------------
      0   : notefind_match    "string"と完全に一致した行を検索
      1   : notefind_first    "string"で始まる行を検索
      2   : notefind_instr    "string"を含む行を検索
^p
メモリノートパッドのすべての行から、指定された文字列と一致する行(インデックス)が戻り値となります。
検索に一致する行がない場合は、-1が返されます。
^
notefind関数を使用するためには、最初にnotesel命令で対象となるバッファを設定しなければなりません。

%href
notesel
noteget
notedel
notemax
notesize



%index
cnvatos
ANSI文字列を通常文字列に変換
%note
hsp3utf.asをインクルードすること。
%group
文字列操作関数
%prm
(p1)
p1=変数 : 内容を読み出す元の変数名

%inst
変数に保存されたデータをANSI(ShiftJIS)文字列として読み取り、 通常の文字列に変換したものを返します。
この命令は、UTF-8を標準の文字列コードとして扱うランタイム(hsp3utf)上でのみ動作します。標準のHSP3ではエラーとなりますので注意してください。


%href
cnvstow
cnvwtos
cnvstoa
str
%port-
Let



%index
cnvstoa
通常文字列をANSI文字列に変換
%note
hsp3utf.asをインクルードすること。
%group
文字列操作命令
%prm
p1,"string"
p1=変数  : 結果を書き込む変数名
"string" : 変換元の文字列

%inst
"文字列"で指定されたデータをANSI(ShiftJIS)文字列に変換して変数バッファに保存します。
p1で指定される変数には、あらかじめ文字列型として変換に十分なバッファサイズを確保しておく必要があります。
この命令は、UTF-8を標準の文字列コードとして扱うランタイム(hsp3utf)上でのみ動作します。標準のHSP3ではエラーとなりますので注意してください。

%href
cnvstow
cnvwtos
cnvatos
str
%port-
Let




%index
strexchange
スクリプト内の文字列を置き換える
%group
文字列操作命令
%prm
"filename",p1
"filename" : 置き換え文字列(strmap)が記録されたファイル名
p1(0)      : 置き換えオプション

%inst
スクリプトに含まれる文字列データをすべてまとめて置き換えます。
あらかじめ、置き換え文字列とハッシュコードが記録されたファイル(strmap)を用意しておく必要があります。
(strmapは、hspcmpコマンドかまたは、hspcmpプラグイン命令により生成することができます。詳しくは、sample/new36/strex_test1.hspサンプルを参照してください)
"filename"で指定されたファイル(strmap)をもとに、スクリプト内の文字列が置き換えられます。
p1で置き換えオプションを指定します。
p1が0の場合は、該当するハッシュコードの文字列のみを変換します。
p1が1の場合は、置き換えデータ(strmap)内にあるすべてのハッシュコードが一致しない場合は置き換えを実行しません。
strexchange実行後に、システム変数statに結果が代入されます。
システム変数statが0の場合は正常終了、それ以外の場合はエラーがあったことを示してします。

%port-
Let




