sscanf

string からの書式付きデータの読み込み

構文

A = sscanf(str,formatSpec)

A = sscanf(str,formatSpec,sizeA)

[A,n] = sscanf(___)

[A,n,errmsg] = sscanf(___)

[A,n,errmsg,nextindex] = sscanf(___)

説明

A = sscanf(str,formatSpec) は、str からデータを読み取り、formatSpec で指定された書式に従って変換し、結果を配列で返します。str は文字配列または string スカラーです。sscanf 関数は、str の末尾に達するか、formatSpec が文字シーケンスに一致しなくなるまで、str の文字シーケンスに対して formatSpec を繰り返し適用します。str が複数行の文字配列である場合、sscanf は列順に文字を読み取ります。

A = sscanf(str,formatSpec,sizeA) は出力配列のサイズを sizeA に設定し、str からデータを読み取り、出力配列に格納します。sizeA は正の整数、または [m n] という形式でなければなりません。ここで、m と n は正の整数です。

また、[A,n] = sscanf(___) は、sscanf が A に正常に読み込んだ要素の数を返します。

また、[A,n,errmsg] = sscanf(___) は、sscanf がすべてのデータを A に読み込めなかった場合に、エラー メッセージを含む文字ベクトルを返します。sscanf が成功した場合、errmsg は空の文字ベクトルになります。

また、[A,n,errmsg,nextindex] = sscanf(___) は、sscanf によってスキャンされた最後の文字の直後にある str 内の位置のインデックスも返します。

例

文字ベクトルを数値に変換

空白文字で区切られた複数の数値を表す文字ベクトルを作成します。文字ベクトルを数値の列ベクトルに変換します。sscanf は空白文字を数値間の区切り文字として扱います。

chr = '2.7183  3.1416  0.0073'

chr = 
'2.7183  3.1416  0.0073'

A = sscanf(chr,'%f')

A = 3×1

    2.7183
    3.1416
    0.0073

テキストを変換して出力配列のサイズを変更

複数の数値を表す string を作成し、sscanf を使用して変換します。出力配列のサイズを指定します。

str = "2.7183  3.1416  0.0073"

str = 
"2.7183  3.1416  0.0073"

A = sscanf(str,'%f',[1 3])

A = 1×3

    2.7183    3.1416    0.0073

str を 2 行 2 列の行列に変換します。str が 3 つの数値しか表していないため、sscanf は行列を埋めるために A を十分な個数のゼロでパディングします。

A = sscanf(str,'%f',[2 2])

A = 2×2

    2.7183    0.0073
    3.1416         0

テキスト内で検出された要素をカウント

空白文字で区切られた数値を含む string を作成します。sscanf が string を数値に変換するときに、出力配列に格納する要素をカウントします。

str = "78 72 64 66 49"

str = 
"78 72 64 66 49"

出力配列 A 内の要素をカウントします。%d 演算子を使用して string 内の数値を変換します。%d は空白で区切られた整数に一致します。A 内の要素数を返すには、2 番目の出力引数を指定します。

[A,n] = sscanf(str,'%d')

A = 5×1

    78
    72
    64
    66
    49

n = 
5

エラー メッセージの表示

string を作成し、そこからデータを読み取ります。sscanf がすべての入力 string を変換できなかった場合、エラー メッセージを表示します。

str = "3.14159 are the first 6 digits of pi"

str = 
"3.14159 are the first 6 digits of pi"

str 内の数値を変換します。str には %f で一致しない文字も含まれているため、sscanf はエラー メッセージを返します。sscanf は単語 'are' に遭遇すると、数値に変換できないため処理を停止します。

[A,n,errmsg] = sscanf(str,'%f')

A = 
3.1416

n = 
1

errmsg = 
'Matching failure in format.'

最後にスキャンされた位置を返す

文字ベクトルを作成し、そこからデータを読み取ります。sscanf がすべての入力を変換できなかった場合、sscanf が処理を停止した位置の直後のインデックスを返します。このインデックスを使用して、スキャンされなかった入力を表示します。

chr = '3.14159 are the first 6 digits of pi'

chr = 
'3.14159 are the first 6 digits of pi'

chr 内のデータを変換します。インデックスを返します。

[A,~,~,nextindex] = sscanf(chr,'%f')

A = 
3.1416

nextindex = 
9

sscanf がスキャンしなかった chr 内の文字を表示します。

chr(nextindex:end)

ans = 
'are the first 6 digits of pi'

指定された文字と一致させる

度記号と文字 F で示される複数の温度を含む string を作成します。その温度を数値配列に変換します。

度記号 (char(176)) を挿入するには、insertBefore 関数を使用します。

T = "78F 72F 64F 66F 49F";
degreeSymbol = char(176);
T = insertBefore(T,'F',degreeSymbol)

T = 
"78°F 72°F 64°F 66°F 49°F"

温度を数値配列として返します。

A = sscanf(T,strcat("%d",degreeSymbol,"F"))

A = 5×1

    78
    72
    64
    66
    49

入力引数

str — スキャンする入力テキスト

文字配列 | string スカラー

スキャンする入力テキスト。文字配列または string スカラーとして指定します。str が文字配列である場合、複数行を含むことがあるので、sscanf は列順に文字を読み取ります。

データ型: char | string

formatSpec — 入力フィールドの書式

書式演算子

入力フィールドの書式。書式演算子を使用して指定します。formatSpec は一重引用符で囲まれた文字ベクトルか、または string スカラーとすることができます。

数値フィールド

この表は、テキストを数値出力に変換する場合に使用できる変換指定子の一覧です。sscanf は値を 10 進数 (基数 10) 表現に変換します。

数値フィールド タイプ	変換指定子	説明
整数、符号付き	%d	基数 10。
	%i	値により基数が決定されます。 既定の設定は基数 10 です。 最初の数字が 0x または 0X の場合、値は基数 16 (16 進法) になります。 最初の数字が 0 の場合、値は基数 8 (8 進法) になります。
	%ld または %li	64 ビットの値、基数 10、8、または 16。
整数、符号なし	%u	基数 10。
	%o	基数 8 (8 進法)。
	%x	基数 16 (16 進法)。
	%lu, %lo, %lx	64 ビットの値、基数 10、8、または 16。
浮動小数点数	%f、%e、または %g	浮動小数点値。入力フィールドには、次のどれでも含めることができます (大文字と小文字の区別なし)。Inf、-Inf、NaN、-NaN。浮動小数点数を表す入力フィールドには、先頭に + 記号または - 記号を含めることも、e または E を使用する指数表記を含めることもできます。変換指定子 %f、%e、および %g は、いずれも同じ方法で入力フィールドを処理します。

文字フィールド

この表は、出力が文字配列になるようにテキストを変換する変換指定子をまとめたものです。

文字フィールド タイプ	変換指定子	説明
文字ベクトルまたは string スカラー	%s	sscanf は空白文字を見つけるまでテキストを読み取ります。
	%c	空白も含め、任意の 1 文字を読み取ります。 一度に複数の文字を読み取るには、フィールド幅を指定します。たとえば、%10c は一度に 10 文字を読み取ります。
パターンマッチング	%[...]	大かっこ内の文字のみを、不一致文字または空白に達するまで読み込みます。 例: %[mus] は 'summer ' を 'summ' として読み取ります。

formatSpec に数値と文字の指定子の組み合わせが含まれる場合、sscanf は各文字をそれに相当する数値に変換します。

オプションの演算子

• 無視するフィールドと文字

  sscanf は、特定のフィールドまたはフィールドの一部を無視するように指示していない限り、すべての数値および文字を順番に読み取ります。フィールドをスキップするには、パーセント記号 (%) の後にアスタリスク (*) を挿入します。たとえば、整数をスキップするには、%*d を指定します。

• フィールド幅

  一度に読み取る桁またはテキスト文字の最大数を指定するには、パーセント文字の後に数値を挿入します。たとえば、%10c は一度に最大 10 文字 (空白を含む) を読み取ります。%4f は、一度に最大 4 桁 (小数点を含む) を読み取ります。

• 無視するリテラル テキスト

  sscanf は、変換指定子の直前または直後に指定されたテキストを無視します。

  例: Level%u は 'Level1' を 1 として読み取ります。

  例: %uStep は '2Step' を 2 として読み取ります。

データ型: char | string

sizeA — 出力配列の次元

Inf (既定値) | 整数 | 2 要素の行ベクトル

出力配列 A の次元。Inf、正の整数、または 2 要素の行ベクトルとして指定します。

入力 sizeA の形式	説明
Inf	入力を最後まで読み取ります。 数値データの場合、A は列ベクトルになります。 テキスト データの場合、A は文字ベクトルになります。
n	最大 n 個の数値またはスペース区切り形式の文字フィールドを読み取ります。 数値データの場合、A は列ベクトルになります。 テキスト データの場合、A は文字ベクトルになります。
[m n]	最大 m*n 個の数値または文字フィールドを読み取ります。n には Inf を指定できますが、m には指定できません。A は m 行 n 列で、列順に埋められます。

データ型: double | single | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

出力引数

A — 出力データ

列ベクトル | 行列 | 文字配列

出力データ。列ベクトル、行列、または文字配列として返されます。A のクラスおよびサイズは、formatSpec で指定された変換内容と、sizeA で指定された出力配列のサイズに依存します。

• formatSpec に数値指定子のみが含まれる場合、A は数値列ベクトルになります。sizeA 引数も指定した場合、A は指定されたサイズの行列になり、必要に応じてゼロでパディングされます。入力に含まれている要素が sizeA 値より少ない場合、A のサイズは sizeA よりも小さくなります。代わりに、入力からスキャンされた値を格納するために必要なサイズになります。

  • formatSpec に 64 ビットの符号付き整数指定子のみが含まれる場合、A のクラスは int64 になります。

  • formatSpec に 64 ビットの符号なしの整数指定子のみが含まれる場合、A のクラスは uint64 になります。

  • それ以外の場合、A はクラス double です。

• formatSpec に %c または %s の指定子のみが含まれている場合、A は文字ベクトルになります。sizeA も指定した場合、A は文字配列になり、必要に応じて null 文字でパディングされます。(null 文字は値がゼロの制御文字です。)入力に sizeA よりも少ない文字が含まれている場合、A のサイズは sizeA よりも小さくなります。代わりに、入力からスキャンされた文字を格納するために必要なサイズになります。

• formatSpec に数値と文字の指定子の組み合わせが含まれる場合、A はクラス double の数値になり、sscanf は各文字をそれに相当する数値に変換します。この変換は、formatSpec がすべての数値フィールドを明示的にスキップする場合 (たとえば、formatSpec が '%*d %s' の場合など) でも発生します。

• sscanf がすべての入力を formatSpec と照合できない場合、A は数値または文字配列になります。A のクラスは、処理が終了する前に sscanf が読み取る値によって異なります。

データ型: double | int64 | uint64 | char

n — 出力配列に読み取られた要素数

整数

出力配列に読み取られた要素数。整数として返されます。

データ型: double

errmsg — エラー メッセージ

文字ベクトル

エラー メッセージ。文字ベクトルとして返されます。str に sscanf が変換できないデータが含まれている場合、errmsg にエラー メッセージが格納されます。sscanf がすべてのデータを正常に変換した場合、errmsg は空の文字ベクトルになります。

データ型: char

nextindex — 最後にスキャンされた文字の直後の位置

整数

最後にスキャンされた文字の直後の位置。整数として返されます。

データ型: double

ヒント

• 関数 sscanf および fscanf の読み取りに対する書式指定子は、関数 sprintf および fprintf の書き込み用の形式とは異なります。読み取り関数は精度フィールドをサポートしません。幅フィールドは、書き込み用には最小値を、読み取り用には最大値を指定します。

拡張機能

C/C++ コード生成

MATLAB® Coder™ を使用して C および C++ コードを生成します。

使用上の注意および制限:

• 入力引数 formatSpec は定数でなければなりません。

• %s および %[...] 変換指定子はサポートされません。

• 出力引数 errmsg および nextinput はサポートされていません。

• 動的メモリ割り当てをオフにする場合は、入力引数 sizeA を指定する必要があります。この引数は定数でなければなりません。

• 生成されたコードの動作が MATLAB^® と異なる可能性があります。このような場合、生成されたコードの動作は、C 言語の sscanf の動作と一致します。以下にいくつかの例を示します。

  • 生成されたコードでは、sscanf が null バイトを読み取ると、返される値が切り捨てられる場合があります。

  • 整数値 x を、intmax が x より小さい整数形式に読み込むと、MATLAB 出力は intmax で飽和します。生成されたコードでは、この飽和でオーバーフローが発生することがあります。

  • 書式指定子 %c を使用して、入力テキスト str で使用可能な文字数より大きいフィールド幅を指定した場合、MATLAB は、使用可能な文字数のみを含む、指定された長さより短い string を返します。生成されたコードは指定された長さの string を返しますが、返される string の内容は、使用する C/C++ コンパイラによって異なる場合があります。場合によっては、返される string には、null 文字 (char(0)) が埋め込まれた入力 string が含まれることがあります。また、返される string に null 文字のみが含まれることもあります。

スレッドベースの環境

MATLAB® の backgroundPool を使用してバックグラウンドでコードを実行するか、Parallel Computing Toolbox™ の ThreadPool を使用してコードを高速化します。

この関数はスレッドベースの環境を完全にサポートしています。詳細については、スレッドベースの環境での MATLAB 関数の実行を参照してください。

バージョン履歴

R2006a より前に導入

参考

fscanf | sprintf | compose | textscan | fprintf | string | char

トピック

• テキストの書式設定