【MQL5】StringToShortArray関数について

MQL5リファレンス
スポンサーリンク

StringToShortArray関数の働き・役割

StringToShortArray関数は、文字列をシンボル(特定の文字や記号)ごとにushort型配列にコピーし、複製された要素の数を返す関数です。
これは、文字列データをバイナリ形式(0と1の並びの形式)で処理したり、保存したりする際に役立ちます。
ushort型配列文字列に変換するShortArrayToString関数とは逆方向の変換を行う、ということになります。

StringToShortArray関数の引数について

int StringToShortArray(
  string  text_string,    // ソース文字列
  ushort& array[],        // 配列
  int    start=0,        // 配列でのコピー開始位置
  int    count=-1        // シンボル数
);

第1引数: text_string
種類: string型

説明: 複製する文字列を指定します。

第2引数: array[]
種類: ushort型 配列への参照
説明: 複製された結果の16ビット整数配列を格納するための配列です。ここでの「参照」とは、変数そのものではなく、変数の場所を指し示すものを意味します。

※このあたりの事については、下記の参照渡しについての記事をご確認ください。

第3引数: start
種類: int型
説明: 配列でのコピー開始位置を指定します。初期値は0です。

第4引数: count
種類: int型
説明: 複製するシンボル数を指定します。初期値は-1で、これは配列の最後または終端ゼロまで複製することを意味します。
終端ゼロとは、文字列の終わりを示すNULL文字(\0)のことです。
※「NULL」というのは、何のデータも含まれない状態のことを指し示す用語です

StringToShortArray関数の戻り値について

StringToShortArray関数は、複製された要素の数(整数値)を返します。これは、変換された16ビット整数の数を示します。

StringToShortArray関数を使う際の注意点

  1. StringToShortArray関数は、配列のサイズを自動的に変更し、文字列の内容を16ビット整数に変換して第2引数に指定した配列に格納します。
  2. count引数を-1に設定すると、文字列の全体が配列にコピーされます。部分的にコピーしたい場合は、具体的なシンボル(特定の文字や記号)数を指定します。

StringToShortArray関数を使ったサンプルコード

以下は、StringToShortArray関数を使用したサンプルコードです。この例では、文字列を16ビット整数の配列に変換し、その内容をエキスパートログに出力します。

// OnStart関数はスクリプトの実行が開始されたときに自動的に呼び出されます
void OnStart()
  {
   // 変換する文字列を定義します
   string str = "Hello, MQL5!";

   // 変換後の16ビット整数配列を定義します
   ushort shortArray[];

   // 文字列を16ビット整数配列に変換します
   int size = StringToShortArray(str, shortArray, 0, -1);

   // 変換された配列の内容をエキスパートログに出力します
   Print("変換された配列のサイズ: ", size);
   for(int i = 0; i < size; i++)
     {
      Print("shortArray[", i, "] = ", shortArray[i]);
     }
  }

出力結果↓

変換された配列のサイズ: 13
※↑終端ゼロも含んでいる為です。

shortArray[0] = 72
shortArray[1] = 101
shortArray[2] = 108
shortArray[3] = 108
shortArray[4] = 111
shortArray[5] = 44
shortArray[6] = 32
shortArray[7] = 77
shortArray[8] = 81
shortArray[9] = 76
shortArray[10] = 53
shortArray[11] = 33
shortArray[12] = 0 ←終端ゼロです。

サンプルコードに使われた関数や文法要素の簡単な解説

OnStart関数

OnStart関数は、スクリプトが実行されるときに自動的に呼び出される関数です。スクリプトの開始点となります。

StringToShortArray関数

StringToShortArray関数は、文字列を16ビット整数の配列に変換するために使用されます。この関数は、文字列データをバイナリ形式で処理する際に便利です。

ushort型

ushort型は、16ビットの符号なし整数型を表します。範囲は0から65535までです。メモリの節約が必要な場合や、特定のデータ形式を扱う際に使用されます。

Print関数

Print関数は、指定したメッセージをエキスパートログに出力するために使用されます。デバッグや情報の確認に役立ちます。

“Hello, MQL5!”が数字配列になる理由

文字列 “Hello, MQL5!” が数字の配列に変換されるのは、各文字が対応するASCIIコード(またはUnicodeコード)に変換されるためです。
例えば、’H’ は 72、’e’ は 101、’l’ は 108 などです。これにより、文字列の各文字がその数値表現に変換され、ushort型配列に格納されます。
この方法は、文字列を数値として処理する必要がある場合に使用されます。

公式リファレンスのサンプルコードについて

公式リファレンスに掲載されているStringToShortArray関数についてのサンプルコードは以下の通りです

//+------------------------------------------------------------------+
//| スクリプトプログラム開始関数                                              |
//+------------------------------------------------------------------+
void OnStart()
 {
//--- 変換する文字を含む文字列
  string text = "Chars: ❤♫☎✈✣☏☀✉☆☁♕♠®✧❆♣   ";
  ushort short_array[];
//--- 入力文字列内の「:」文字の位置を検索し、次の文字から始まる部分文字列を抽出する
  int   pos=StringFind(text, ":");
  string str=(pos<0 ? text : StringSubstr(text, pos+1));
//--- 結果の文字列の左右からスペース、キャリッジ移動、タブ文字を削除する
  StringTrimLeft(str);
  StringTrimRight(str);
//--- 結果の文字列をushort配列にコピーし、結果の配列を操作ログに出力する
  int copied=StringToShortArray(str, short_array);
  PrintFormat("String of characters length: %u\n"
              "Number of characters copied (with terminal 0): %d\n"
              "Array of chars for the string '%s':",
              StringLen(str), copied, str);
  ArrayPrint(short_array, 0, " | ");
  /*
  結果:
  String of characters length: 16
  Number of characters copied (with terminal 0): 17
  Array of chars for the string '❤♫☎✈✣☏☀✉☆☁♕♠®✧❆♣':
  10084 | 9835 | 9742 | 9992 | 10019 | 9743 | 9728 | 9993 | 9734 | 9729 | 9813 | 9824 |   174 | 10023 | 10054 | 9827 |     0
  */
 }

少し難しいので、小分けにして説明していきます。まずは以下の部分

//--- 変換する文字を含む文字列
  string text = "Chars: ❤♫☎✈✣☏☀✉☆☁♕♠®✧❆♣   ";
  ushort short_array[];
//--- 入力文字列内の「:」文字の位置を検索し、次の文字から始まる部分文字列を抽出する
  int   pos=StringFind(text, ":");

string text: これは、変換する文字列を定義しています。この文字列には、様々な特殊文字や記号が含まれています。

ushort short_array[]: これは、変換された結果を格納するための16ビット整数型配列です。ushortは符号なしの16ビット整数型を意味します。

int pos: これは、「:」文字の位置を格納する変数です。int整数型を意味します

StringFind(text, “:”): StringFind関数は、指定した文字列(この場合は「:」)がtextの中で最初に現れる位置を返します。見つからない場合は -1 を返します。

※「:」が現れる位置を見つけようとしているのは、この位置を基準にして、指定された文字列の中で「:」の後に続く部分を抽出するためです。具体的には、「Chars: ❤♫☎✈✣☏☀✉☆☁♕♠®✧❆♣」という文字列の中で、「:」の後に続く部分、「❤♫☎✈✣☏☀✉☆☁♕♠®✧❆♣」を取り出すために使用されています。

 string str=(pos<0 ? text : StringSubstr(text, pos+1));
//--- 結果の文字列の左右からスペース、キャリッジ移動、タブ文字を削除する
  StringTrimLeft(str);
  StringTrimRight(str);

三項演算子 (?:): これは条件演算子です。pos < 0が真(true)の場合、textを返し、偽(false)の場合は、StringSubstr(text, pos + 1)を返します。

三項演算子についての詳細は↓の記事をご参照ください。

StringFind関数で「:」が見つからなかった場合(pos < 0)、text全体をstr代入します。見つかった場合、StringSubstr関数で「:」の次の位置から始まる部分文字列str代入します。

StringSubstr関数は指定した文字列の一部を抽出するために使用されます。詳細は↓の記事をご参照ください。

StringTrimLeft(str): 文字列の左側からスペース、キャリッジリターン(\r)、タブ文字(\t)を削除します。

StringTrimRight(str): 文字列の右側からスペース、キャリッジリターン、タブ文字を削除します。

※キャリッジリターン(\r)は、文字列内の制御文字の一種で、テキストのカーソルを行の先頭に移動させる役割を持ちます。

StringTrimLeft関数文字列の先頭にある改行文字、スペース、およびタブを削除するために使用されます。

StringTrimRight関数は、文字列の末尾にある改行文字、スペース、およびタブを削除するために使用されます。

//--- 結果の文字列をushort配列にコピーし、結果の配列を操作ログに出力する
int copied = StringToShortArray(str, short_array);
PrintFormat("String of characters length: %u\n"
            "Number of characters copied (with terminal 0): %d\n"
            "Array of chars for the string '%s':",
            StringLen(str), copied, str);
ArrayPrint(short_array, 0, " | ");

StringToShortArray(str, short_array): 文字列strを16ビットの整数(ushort)配列short_arrayに変換します。この処理により、ハート記号(❤)や音符記号(♫)などの特殊文字を含む文字列をushort配列に変換し、これらの文字のバイナリ表現を得ることができます。戻り値として、コピーされた要素の数を返します。

int copied: 変換された配列要素数を格納するための変数です。

PrintFormat関数: フォーマットされた文字列を操作ログに出力します。

フォーマット指定子とその対応部分の解説:

%u: 符号なし整数として、StringLen(str)の値を出力します。ここでは、変換する部分文字列の長さを表します。StringLen関数は指定された文字列の長さ(文字数)を返すために使用されます。

%d: 符号付き整数として、copiedの値を出力します。

ここでは、コピーされた要素の数を示します(終端ゼロを含む)。%s: 文字列として、strの内容を出力します。ここでは、変換対象の文字列そのものを表示します。
変数strには、変数textから「:」以降の部分文字列が入ります。また、文字列の左右にあるスペース、キャリッジリターン(\r)、タブ文字(\t)は削除されます。

トリミングされた後、変数strには特定の文字列の部分が含まれることになります。

コメント

タイトルとURLをコピーしました