インスタンスメソッド A ~ H／NSStringクラスリファレンス

インスタンスメソッド（A ~ H）
Referred from
Copyright
NSStringクラスメソッドへもどる

インスタンスメソッド（A ~ H）

- boolValue

レシーバテキストを真偽値として返します。

- (BOOL)boolValue
 Return Value
レシーバテキストの真偽値。"Y", "y", "T", "t", or a digit 1-9で始まるなら、YESを返します。ここでメソッドは、残り全ての文字を無視します。レシーバが数を表すのに有効な10進数のテキストで始まらないなら、NOを返します。

Discussion
このメソッドは10進数を期待しており、文字列の始まりにある空白文字をスキップします。空白文字で始まる文字と、-/+符号のあとに0が続くものもスキップします

Availability
Available in OS X v10.5 and later.
See Also
- integerValue
scanInt: (NSScanner)
Declared In
NSString.h

- canBeConvertedToEncoding:

情報を失わずに、あたえられたエンコーディングでレシーバが変換できるかどうかを、真偽値で返します。

- (BOOL)canBeConvertedToEncoding:(NSStringEncoding)encoding

Parameters
encoding
エンコード文字列。

Return Value
情報を失わずにencodingへレシーバを変換できるならYES。もし文字が変えられてしまうか、エンコーディングを変える過程で文字が消されてしまうならNO。

Discussion
もし、実際に文字列を変換しようとしているのなら、dataUsingEncoding:...メソッドは失敗してnilを返します。このメソッドを呼び出すオーバーヘッドを避けるのに、たんに文字を変換しようとするべきです。

Availability
Available in OS X v10.0 and later.
See Also
- dataUsingEncoding:allowLossyConversion:
Related Sample Code
TextEdit
Declared In
NSString.h

- capitalizedString

レシーバをキャピタライズした表現で返します。

- (NSString *)capitalizedString

Return Value
レシーバに含まれる単語の最初の文字を、対応する大文字へ変換した文字列。変換しなかった文字は、対応する小文字となります。

Discussion
"単語"とは、スペース、タブ、行区切り文字（getLineStart:end:contentsEnd:forRange:でリストしています）で区切られた文字の並びです。句読点を区切るいくつかの一般的な単語については考慮していません。ですからこのメソッドは、単語を羅列する文字列から期待する結果は得られないかもしれません。
ケース変換は、対称性とともに基になる文字列と同じ長さの文字列を作るとは保証していません。例としてlowercaseStringを参照してください。

ノート：このメソッドは、標準的な（ローカライズされていない）マッピングを行います。ユーザのロケールプレファレンスによらない安定した結果が要求されるプログラム的な操作に向いています。ユーザへ提示する文字列のローカライズされたケースマッピングには、capitalizedStringWithLocale:メソッドを使用してください。

Availability
Available in OS X v10.0 and later.
See Also
- capitalizedStringWithLocale:
Related Sample Code
SimpleService
Declared In
NSString.h

- capitalizedStringWithLocale:

指定したロケールを使って、大文字で始めたレシーバの文字列表現を返します。

- (NSString *)capitalizedStringWithLocale:(NSLocale *)locale

Parameters
locale
ロケール。nilを渡すと、システムのロケールになります。ユーザに示している文字列には、currentLocaleを使ってください。

Return Value
レシーバにある単語の始まりを対応する大文字に変えて、残る全ての文字を小文字に変えた文字列。

Discussion
"単語"とは、スペース、タブ、行区切り文字（getLineStart:end:contentsEnd:forRange:でリストしています）で区切られた文字の並びです。句読点を区切るいくつかの一般的な単語については考慮していません。ですからこのメソッドは、複数の単語からなる文字列から期待する結果は得られないかもしれません。

Availability
Available in OS X v10.8 and later.
See Also
- capitalizedString
Declared In
NSString.h

- caseInsensitiveCompare:

NSCaseInsensitiveSearchオプションのみを指定してcompare:options:を呼び出し、その結果を返します。

- (NSComparisonResult)caseInsensitiveCompare:(NSString *)aString

Parameters
aString
レシーバと比較する文字列。
この値はnilではいけません。もしnilならその振る舞いは定義されていませんが、将来のOS Xでは変わるかもしれません

Return Value
NSCaseInsensitiveSearchオプションのみを指定してcompare:options:を呼び出して得られた結果。

Discussion
エンドユーザ見せている文字列で比較しているなら、代わりにlocalizedCaseInsensitiveCompare:を通常は使うべきでしょう。

Availability
Available in OS X v10.0 and later.
See Also
- localizedCaseInsensitiveCompare:
- compare:options:
Related Sample Code
IdentitySample
Declared In
NSString.h

- characterAtIndex:

あたえられた配列での位置にある文字を返します。

- (unichar)characterAtIndex:(NSUInteger)index

Parameters
index
取得する文字のインデックス。インデックス値は、レシーバの境界を超えてはいけません。

Return Value
あたえられたindexの配列位置にある文字。

Discussion
レシーバの終わりを越える位置にindexがあったら、NSRangeExceptionが発生します。

Availability
Available in OS X v10.0 and later.
See Also
- getCharacters:range:
Related Sample Code
ClipboardViewer
DeNOise
QTCoreVideo202
QTCoreVideo301
SpriteKit Physics Collisions
Declared In
NSString.h

- commonPrefixWithString:options:

レシーバとあたえられた文字列が共通して持つ文字列を返します。どちらにおいても最初の文字から始まり、異なる文字が出現するまでを共通部分とします。

- (NSString *)commonPrefixWithString:(NSString *)aString options:(NSStringCompareOptions)mask

Parameters
aString
レシーバと比較する文字列。

mask
比較する際のオプション。次の検索オプションを、CのORビット演算子で結合して指定できます。NSCaseInsensitiveSearch, NSLiteralSearch。これらオプションについては、詳細にはString Programming Guidを参照してください。

Return Value
レシーバとaStringが共通して持つ文字列。どちらにおいても最初の文字から始まり、異なる文字が出現するまでを共通部分とします。

Discussion
戻り値の文字列は、レシーバのキャラクタをベースとしています。たとえば、レシーバが“Ma¨dchen”でaStringが“Mädchenschule”とすると、返される文字列は“Ma¨dchen”で、“Mädchen”ではありません。

Availability
Available in OS X v10.0 and later.
See Also
- hasPrefix:
Declared In
NSString.h

- compare:

オプションなし、レシーバの全範囲を範囲として、compare:options:range:を呼び出して、その結果を返します。

- (NSComparisonResult)compare:(NSString *)aString

Parameters
aString
レシーバと比較する文字列。
この値はnilではいけません。nilの場合での挙動は定義されていませんが、将来のOS Xでは変わるかもしれません。
 Return Value
オプションなし、レシーバの全範囲を範囲として、compare:options:range:を呼び出して得た結果。

Discussion
エンドユーザ見せている文字列で比較しているなら、代わりにlocalizedCompare:またはlocalizedCaseInsensitiveCompare:を通常は使うべきでしょう。

Availability
Available in OS X v10.0 and later.
See Also
- localizedCompare:
- localizedCaseInsensitiveCompare:
- compare:options:
- caseInsensitiveCompare:
- isEqualToString:
Related Sample Code
DeNOise
QTCoreVideo102
QTCoreVideo201
QTCoreVideo202
QTCoreVideo301
Declared In
NSString.h

- compare:options:

あたえられたオプションを使って、指定した文字列をレシーバの文字列を比較します。

- (NSComparisonResult)compare:(NSString *)aString options:(NSStringCompareOptions)mask

Parameters
aString
レシーバと比較する文字列。
この値はnilではいけません。nilの場合での挙動は定義されていませんが、将来のOS Xでは変わるかもしれません。

mask
検索のオプション。次のものをCのORビット演算子で結合して指定します。NSCaseInsensitiveSearch, NSLiteralSearch。これらオプションの詳細にはString Programming Guideを参照してください。

Return Value
あたえられたmaskをオプションとして、レシーバの全範囲を範囲としてcompare:options:range:を呼び出した結果。

Discussion
エンドユーザ見せている文字列で比較しているなら、代わりにlocalizedCompare:またはlocalizedCaseInsensitiveCompare:を一般的には使うか、ユーザのロケールをcompare:options:range:locale:へ渡して使うべきでしょう。

Availability
Available in OS X v10.0 and later.
See Also
- localizedCompare:
- localizedCaseInsensitiveCompare:
- compare:options:range:locale:
- caseInsensitiveCompare:
- isEqualToString:
Declared In
NSString.h

- compare:options:range:

ロケール情報をnilにして、compare:options:range:locale:を呼び出した結果を返します。

- (NSComparisonResult)compare:(NSString *)aString options:(NSStringCompareOptions)mask range:(NSRange)range

Parameters
aString
rangeで指定されたレシーバの範囲にある文字列と比較する文字列。
この値はnilであってはいけません。nilの場合での挙動は定義されていませんが、将来のOS Xでは変わるもしれません。

mask
検索のオプション。次のものをCのORビット演算子で結合して指定します。NSCaseInsensitiveSearch, NSLiteralSearch。
これらオプションの詳細にはString Programming Guideを参照してください。

range
比較を行うレシーバの範囲。これはレシーバの境界を超えてはいけません。

重要：指定したrangeがレシーバの境界を超えたときは、NSRangeExceptionが発生します。

Return Value
ロケール情報をnilにして、compare:options:range:locale:を呼び出した結果

Discussion
エンドユーザ見せている文字列で比較しているなら、代わりにユーザのロケール（[NSLocale currentLocale]）を渡したcompare:options:range:locale:と一般的には使うべきでしょう。

- compare:options:range:locale:

あたえられるオプションを使って文字列とレシーバを比較し、あたえられた範囲での辞書的な順序を返します。

- (NSComparisonResult)compare:(NSString *)aString options:(NSStringCompareOptions)mask range:(NSRange)range locale:(id)locale

Parameters
aString
rangeが指定した範囲にあるレシーバと比較する文字列。
この値はnilであってはなりません。nilの場合での挙動は定義されていませんが、将来のOS Xでは変わるかもしれません。

mask
検索のオプション。次のものをCのORビット演算子で結合して指定します。NSCaseInsensitiveSearch, NSLiteralSearch, NSNumericSearch。
これらオプションの詳細にはString Programming Guideを参照してください。

range
比較を行うレシーバの範囲。これはレシーバの境界を超えてはいけません。

重要：rangeがレシーバの境界を超えたら、NSRangeExceptionが発生します。

locale
NSLocaleのインスタンス。nilを渡すと、このメソッドはシステムのロケールを使います。システムのロケールになります。ユーザに示す文字列表現を指定するには、currentLocaleを使ってください。エンドユーザに示している文字列で比較を行うなら、一般的にはユーザのロケール（[NSLocale currentLocale]）を渡してください。

Return Value
指定された範囲でのレシーバとあたえられた文字列の辞書的な順序をしめす、NSComparisonResult値を返します。あたえるdict（原文のまま。たぶんlocaleのこと）の辞書順で、rangeで指定した範囲にあるレシーバの部分文字列がaStrngよりも前になるなら、NSOrderedAscending。レシーバの部分文字列とaStringとが辞書順で同じならNSOrderedSame。そして、レシーバの部分文字列がaStringよりも後になるならNSOrderedDescending。

Discussion
引数localeは、この比較において、等価性と順序づけのアルゴリズムへ影響します。例えば、あるロケールではアクセント記号が文字の最初の方で定義されていますが、ほかでは"z"の後になります。

Special Considerations
OS X v10.5より前では、ロケール引数はNSDictionaryのインスタンスでした。OS X v10.5以降では、NSDictionaryのインスタンスを渡すと、代わりに現在のロケールが使われます。

Availability
Available in OS X v10.0 and later.
See Also
- localizedCompare:
- localizedCaseInsensitiveCompare:
- caseInsensitiveCompare:
- compare:
- compare:options:
- compare:options:range:
- isEqualToString:
Declared In
NSString.h

- completePathIntoString:caseSensitive:matchesIntoArray:filterTypes:

レシーバの文字列をファイルシステムのパスとして解釈して、ファイル名の補完を試みます。マッチが可能かどうかを示す数値を返します。レシーバとマッチするもっとの長いパスを参照渡しで返します。

- (NSUInteger)completePathIntoString:(NSString **)outputName caseSensitive:(BOOL)flag matchesIntoArray:(NSArray **)outputArray filterTypes:(NSArray *)filterTypes

Parameters
outputName
レシーバとマッチする最も長いパスを含めます。

flag
YESなら補完を試みるあたり、このメソッドはケースを考慮に入れます

outputName
マッチするすべてのファイル名が入った配列を含めます。

filterTypes
補完を考慮に入れるのにあたり、パス拡張子を指定するNSStringオブジェクトが入った配列。これら文字列とマッチする拡張子（拡張子分割子は含まれません）を持つパスだけがこのメソッドの対象となります。

Return Value
マッチが見つからなかったら0で、マッチがただ1つしか見つからなかったら１です。複数回マッチする場合では、outpurArrayを与えていたらパスとマッチする数を返し、outputArrayがNULLならば単なる正の数を返します。

Discussion
outputArrayへNULLを渡すことで、多くの情報を取り出さなくても、マッチが存在するかどうかをチェックできます。
注意：このメソッドはファイルパスとでしか動作しません（たとえば、URLの文字列表現とでは動作しません）。

Availability
Available in OS X v10.0 and later.
Declared In
NSPathUtilities.h

- componentsSeparatedByCharactersInSet:

レシーバをあたえられたセットの中にある文字で分割して、その部分文字列の配列を返します。

- (NSArray *)componentsSeparatedByCharactersInSet:(NSCharacterSet *)separator

Parameters
separator
レシーバを分割するのに使う文字が入った文字のセット。nilではいけません。

Return Value
レシーバをseparator文字で分割して、その部分文字列を含むNSArrayオブジェクト。

Discussion
配列にある部分文字列は、レシーバでの並び順序のまま入っています。セパレータ文字が連続すると、結果の中に空の文字列が作られます。同様にして、文字列がセパレータ文字で始まるか終わると、最初か最後の部分文字列はどちらも空の文字列になります。

Availability
Available in OS X v10.5 and later.
See Also
- componentsSeparatedByString:
- stringByTrimmingCharactersInSet:
Related Sample Code
DeNOise
From A View to A Movie
From A View to A Picture
Declared In
NSString.h

- componentsSeparatedByString:

あたえられたセパレータでレシーバを分離して、部分文字列からなる配列を返します。

- (NSArray *)componentsSeparatedByString:(NSString *)separator

Parameters
separator
セパレータ文字列

Return Value
レシーバをseparatorで分離してえられた部分文字列からなるNSArrayオブジェクト。

Discussion
配列にある部分文字列は、レシーバでの並び順序のままで入っています。セパレータ文字が連続すると、結果の中に空の文字列が作られます。同様にして、文字列がセパレータ文字で始まるか終わると、最初か最後の部分文字列はどちらも空の文字列になります。たとえば、つぎのコード断片は：

NSString *list = @"Karin, Carrie, David";
NSArray *listItems = [list componentsSeparatedByString:@", "];

NSArrayオブジェクト{ @"Karin", @"Carrie", @"David" }を生成します。

listがコンマかスペースで始まる、たとえば@", Norman, Stanley, Fletcher"ならば、得られる配列は次のようになります、{ @"", @"Karin", @"Carrie", @"David" }（訳者注： @"", @"Norrman", @"Stanley", @"Fletcher" }の間違い？）。
listがセパレータを含まない、たとえば"Karin"なら、配列はその文字列そのものになります。この場合では{ @"Karin" }。

Availability
Available in OS X v10.0 and later.
See Also
componentsJoinedByString: (NSArray)
- pathComponents
Related Sample Code
AVFoundation - Timecode Reader/Writer (avtimecodereadwrite)
iSpend
iSpendPlugin
Declared In
NSString.h

- cStringUsingEncoding:

あたえられたエンコーディングを使用してレシーバを変換したC文字列を返します。

- (const char *)cStringUsingEncoding:(NSStringEncoding)encoding
 Parameters
encoding
返されるC文字列のエンコーディング。
 Return Value
encodingで指定されたエンコーディングを使って変換したC文字列。レシーバをロスレスにencodingへ変換できないときは、NULLが返ります。

Discussion
レシーバが開放されるまで、もしくは利用可能メモリがなくなるまで、これらのどちらかが最初に起きるまで返り値のC文字列は有効と保証されます。このとき以降もC文字列を保存しておく必要があるなら、C文字列をコピーするか、getCString:maxLength:encoding:を使うと良いでしょう。
C文字列をencodingへロスレスに変換できるかどうかチェックするには、canBeConvertedToEncoding:が使えます。もしできないなら、encodingを使ってCスタイルの文字列表現を得るのにdataUsingEncoding:allowLossyConversion:が使え、変換での損失についての情報が得られます（注意。dataUsingEncoding:allowLossyConversion:から返されるデータは、厳格なC文字列ではありません。このC文字列がNULL終端を持てないのでからです。）

Availability
Available in OS X v10.4 and later.
See Also
- getCString:
- canBeConvertedToEncoding:
+ defaultCStringencoding
- cStringLength
- UTF8String
Related Sample Code
From A View to A Movie
From A View to A Picture
HeightArray
InstancedArrays
QTCoreVideo301
Declared In
NSString.h

- dataUsingEncoding:

あたえられたエンコーディングを使ってエンコードしたレシーバの表現を内包するNSDataオブジェクト。

- (NSData *)dataUsingEncoding:(NSStringEncoding)encoding

Parameters
encoding
エンコーディング文字列。

Return Value
dataUsingEncoding:allowLossyConversion:を２番目の引数をゼロとして（つまり、ロスレス変換を要求している）呼び出したときの戻り値。

Availability
Available in OS X v10.0 and later.
Related Sample Code
CocoaEcho
RemoteCurrency
SimplePing
UDPEcho
Declared In
NSString.h

- dataUsingEncoding:allowLossyConversion:

あたえられたエンコーディングを使用してエンコードしたレシーバの表現を内包するNSDataオブジェクトを返します。

- (NSData *)dataUsingEncoding:(NSStringEncoding)encoding allowLossyConversion:(BOOL)flag

Parameters
encoding
エンコード文字列。

flag
YESなら、変換において文字を取り除いたり変更したりするのを許可します。

Return Value
encodingを使用してエンコードしたレシーバの表現を内包する、NSDataオブジェクト。flagがNOで、レシーバに含まれるデータの情報を損失することなく変換できないときには（発音記号やケースの損失が挙げられます）、nilが返ります。

Discussion
flagがYESで、かつデータの情報を損失することなく変換できないときには、変換の際にいくらかの文字は取り除かれたり変更されます。たとえば、NSUnicodeStringEncodingからNSASCIIStringEncodingへ文字を変換する際は、文字‘Á’はアクセント記号を失い‘A’へと変換されます。

このメソッドは、結果として得られるNSDataオブジェクトをファイルへ安全に書き出せるよう保証する、外部向けの表現（バイト順。必要ならエンディアンを示す）を生成します。ロスレスで変換がなされたとき、このメソッドから得られるこのオブジェクトは指定したエンコードに適合するデフォルトの「プレーンテキスト」で、文字列オブジェクトを保存するかほかへ渡す用途に推奨される方法です。

Availability
Available in OS X v10.0 and later.
See Also
+ availableStringEncodings
- canBeConvertedToEncoding:
Declared In
NSString.h

- decomposedStringWithCanonicalMapping

"the Unicode Normalization Form D"を用いてレシーバのコンテンツを標準化して作った文字列を返します。（Unicode正規化フォーム FD）

- {NSString *)decomposedStringWithCanonicalMapping

Return Value
"the Unicode Normalization Form D"を用いてレシーバのコンテンツを標準化して作った文字列。

Availability
Available in OS X v10.2 and later.
See Also
- precomposedStringWithCanonicalMapping
- decomposedStringWithCompatibilityMapping
Declared In
NSString.h

- decomposedStringWithCompatibilityMapping

"the Unicode Normalization Form KD"を用いてレシーバのコンテンツを標準化して作った文字列を返します。

- (NSString *)decomposedStringWithCompatibilityMapping

Return Value
"the Unicode Normalization Form KD"を用いてレシーバのコンテンツを標準化して作った文字列。

Availability
Available in OS X v10.2 and later.
See Also
- precomposedStringWithCompatibilityMapping
- decomposedStringWithCanonicalMapping
Declared In
NSString.h

- description

レシーバを返します。

- (NSString *)description

Return Value
レシーバ。

Availability
Available in OS X v10.0 and later.
Declared In
NSString.h

- doubleValue

レシーバのテキストをdoulbe型として解釈した浮動点少数値を返します。

- (double)doubleValue

Return Value
レシーバのテキストをdoulbe型として解釈した浮動点少数値。オーバーフローが起きたらHUGE_VALもしくは–HUGE_VAL 、アンダーフローが起きたら0.0を返します。レシーバが有効なテキスト表現として浮動点少数で始まらないなら、0.0が返されます。

Discussion
このメソッドは、文字列の最初にある空白文字をスキップします。このメソッドはローカライズされていない値に保存されているフォーマット情報を使います。言い換えれば、文字列から数値をローカライズスキャンするのにNSScannerを使ってください。

Availability
Available in OS X v10.0 and later.
See Also
- floatValue
- longLongValue
- integerValue
scanDouble: (NSScanner)
Related Sample Code
TrackBall
Unit Testing Apps and Frameworks
Writing Subtitles to a Movie from the Command Line for OS X
Declared In
NSString.h

- enumerateLinesUsingBlock:

文字列にある、すべての行を列挙します。

- (void)enumerateLinesUsingBlock:(void (^)(NSString *line, BOOL *stop))block

Parameters
block
列挙で実行されるブロック
ブロックは２つの引数を取ります：
line
列挙されている文字列での現在の行。行は、行の内容だけを含んでおり、行区切りを含んでいません。

stop
真偽値のリファレンスで、ブロック内において*stop = YESとセットすれば列挙を止められます。このほかの理由で*stopは操作するべきではありません。

Availability
Available in OS X v10.6 and later.
Declared In
NSString.h

- enumerateLinguisticTagsInRange:scheme:options:orthography:usingBlock:

（分かりません）特定の範囲にある文字列を列挙して、置かれたタグを用いてブロックを実行し、言語的な解析を行います。
Performs linguistic analysis on the specified string by enumerating the specific range of the string, providing the block with the located tags.

- (void)enumerateLinguisticTagsInRange:(NSRange)range scheme:(NSString *)tagScheme options:(NSLinguisticTaggerOptions)opts orthography:(NSOrthography *)orthography usingBlock:(void (^)(NSString *'tag, NSRange tokenRange , NS'Range 'sentenceRange, BOOL *stop))block

Parameters
range
解析を行う文字列の範囲。
The range of the string to analyze.

tagScheme
使用するタグスキーム。Linguistic Tag Schemesにあるサポートする値を参照してください。
The tag scheme to use. See Linguistic Tag Schemes for supported values.

opts
使用する言語タグのオプション。この定数については、NSLinguisticTaggerOptionsfor定数を参照してください。これら定数はCのOR演算子を使ってつなげられます。
The linguistic tagger options to use. See NSLinguisticTaggerOptionsfor the constants. These constants can be combined using the C-Bitwise OR operator.

orthography
文字列の正しいスペル。nilだと、言語タグは文字列の内容から正しいスペルを決定しようと試みます。
The orthography of the string. If nil, the linguistic tagger will attempt to determine the orthography from the string content.

block
文字列へ処理を施すブロック
このブロックは４つの引数を取ります。
The block to apply to the string.
The block takes four arguments:

tag
トークンのタグスキーム。引数optは、置かれたタグオプションの種類を指定します。
The tag scheme for the token. The opts parameter specifies the types of tagger options that are located.

tokenRange
タグスキームと比較する文字列の範囲。
The range of a string matching the tag scheme.

sentenceRange
トークンが見つかったセンテンスの範囲。
The range of the sentence in which the token is found.

stop
真偽値へのリファレンス。ブロック内でこの値をYESへセットすると、配列にある処理をストップします。このストップ引数は外向きにだけ使われる引数です。この真偽値をYESにセットするのは、ブロックの中ででのみ行うべきです。
A reference to a Boolean value. The block can set the value to YES to stop further processing of the array. The stop argument is an out-only argument. You should only ever set this Boolean to YES within the Block.

Discussion
これはコンビニエンスメソッドです。NSLinguisticTaggerのインスタンスを生成するのと等価で、レシーバを解析すべき文字列、そして正しいスペル（またはnil）とを指定して、NSLinguisticTaggerメソッドもしくはnumerateTagsInRange:scheme:options:usingBlock:を呼び出します。
This is a convenience method. It is the equivalent of creating an instance of NSLinguisticTagger, specifying the receiver as the string to be analyzed, and the orthography (or nil) and then invoking the NSLinguisticTagger method or enumerateTagsInRange:scheme:options:usingBlock:.

Availability
Available in OS X v10.7 and later.
Declared In
NSLinguisticTagger.h

- enumerateSubstringsInRange:options:usingBlock:

文字列中の引数範囲にある、引数タイプの部分文字を列挙します。

- (void)enumerateSubstringsInRange:(NSRange)range options:(NSStringEnumerationOptions)opts usingBlock:(void (^)(NSString *substring, NS'Range substringRange, NSRange enclosingRange, BOOL *stop))block

Parameters
range
部分文字列を列挙する、文字列の範囲。
 opts
部分文字列のタイプと列挙スタイルを指定するオプション。

block
列挙を行うブロック。
ブロックは４つの引数を取ります。

substring
列挙された文字列。

substring range
レシーバの中の列挙した文字の範囲

enclosingRange
部分文字列はもちろんのこと、すべての区切り子、もしくは、それにつづくフィルター文字も含む範囲。例えば、行についてenclosingRangeは行区切り子を含んでいます。列挙した最初の文字列に対するenclosingRange範囲もまた、その文字列よりも先に現れるいかなる文字をも含んでいます。連続した囲い込み範囲は重複しないと保証されていて、列挙範囲にあるすべての単文字は唯一１つの囲い込み範囲に含まれています。

stop
真偽値へのリファレンスで、*stop =YESとすることでブロックは列挙を停止できます。それ以外の目的で*stopを使ってはいけません。

Discussion
このメソッドをNSMutableStringのインスタンスへ送ると、enclosingRangeの範囲に限ってミューテーション（削除、付加、変化）が許可されます。ミューテーションが終わると、施したミューテーションに合わせて処理し終わった範囲の長さを調整し（列挙子は指定した範囲の長さが変化すると仮定しています）、処理し終わった範囲のすぐ後の範囲から列挙を続けます。

たとえば、ブロックを場所Nから始まる範囲で呼び出したとして、あたえられた範囲にあるすべての文字をブロックが消し、次の呼び出しでもNを指定範囲のインデックスとして渡したとします。これは、以前の範囲のミューテーションが文字列を変えたとしても、続く部分文字列は既に列挙された範囲を含むよう拡張してあるということです。たとえば、文字列"Hello World"が文字として列挙され、ブロックが"Hello "を"Hello"へと変えたとしたら（訳者注：前者の末尾に半角スペースが入っています）、"HelloWorld"となります。次の列挙では"HelloWolrd"ではなく"world"を返します。

Availability
Available in OS X v10.6 and later.
Declared In
NSString.h

- fastestencoding

情報を失うことなくレシーバを変換できるであろう、最速のエンコーディングを返します。

- (NSStringEncoding)fastestEncoding

Return Value
情報を失うことなくレシーバを変換できるであろう、最速のエンコーディング。

Discussion
「最速」とは、文字列から文字の取得についてです。このエンコーディングは、使用する領域について効率的ではないでしょう。

Availability
Available in OS X v10.0 and later.
See Also
- smallestencoding
- getCharacters:range:
Declared In
NSString.h

- fileSystemRepresentation

レシーバをシステム依存での表現で返します。

- (const char *)fileSystemRepresentation

Return Value
getFileSystemRepresentation:maxLength:で記述されている、レシーバをシステム依存での表現。

Discussion
返されるC文字列は、レシーバが開放されようとしているときに、自動的に開放されます。この文字列が生成されたメモリコンテキストの外でも保存する必要があるなら、この表現をコピーするか、getFileSystemRepresentation:maxLength:を使うべきでしょう。

レシーバがファイルシステムのエンコーディングで表現できないなら、NSCharacterConversionExceptionが発生します。レシーバが何の文字も含んでいない場合も、例外が発生します。

注意'：このメソッドはファイルパスのみと動作します（たとえば、URLを表す文字列とでは動作しません）。

char *パス（Cライブラリルーチンから取得したものなど）をNSStringオブジェクトへ変換するには、NSFileManagerのstringWithFileSystemRepresentation:length:メソッドを使ってください。

Availability
Available in OS X v10.0 and later.
Related Sample Code
Supporting Multiple GPUs
Declared In
NSPathUtilities.h

- floatValue

レシーバのテキストをfloatとして解釈し、得られた浮動小数点値を返します。

- (float)floatValue

Return Value
レシーバのテキストをfloatとして解釈し、得られた浮動小数点値。文字列の始めにある空白文字はスキップします。オーバーフローしたらHUGE_VALか–HUGE_VAL、アンダーフローしたら0.0をそれぞれ返します。また、レシーバが浮動点少数として有効なテキストで始まらなかったら、0.0を返します。

Discussion
このメソッドは、局所変数に保存されているフォーマットに関する情報を使います。これは、文字列から局所的な読み取りをするNSScanerオブジェクトを使います。

Availability
Available in OS X v10.0 and later.
See Also
- doubleValue
- longLongValue
- integerValue
scanFloat: (NSScanner)
Declared In
NSString.h

- getBytes:maxLength:usedLength:encoding:options:range:remainingRange:

指定したエンコーディングのバイト列が表現する、あたえられた範囲の文字を取得します。

- (BOOL)getBytes:(void *)buffer maxLength:(NSUInteger)maxBufferCount usedLength:(NSUInteger *)usedBufferCount encoding:(NSStringEncoding)encoding options:(NSStringEncodingConversionOptions)options range:(NSRange)range remainingRange:(NSRangePointer)leftover

Parameters
buffer
レシーバから受け取るバイト列を保存するバッファ。返されるバイト列はNULL終端ではありません。

maxBufferCount
バッファへ書き込むバイト列の最大数。

usedBufferCount
bufferから使われるバイト数。この値が必要ないなら、NULLを渡してください。

encoding
返されるバイトへ適用するエンコード。

options
レシーバの中味をencodingへ変換する（その必要があるなら）のに使う、オプションを指定するマスク（変換が必要なら）。

range
レシーバから取得する文字の範囲。

leftover
残った範囲。この値が不要なら、NULLを渡してください。

Return Value
いくらかの文字が変換できたらYES、そうでないならNO。

Discussion
バッファが一杯になったら変換は止まりますが、選択したエンコーディングを使っての変換ができないときにも止まります。

Availability
Available in OS X v10.5 and later.
Declared In
NSString.h

- getCharacters:range:

あたえられた範囲にあるレシーバの文字を、あたえられたバッファの中へコピーします。

- (void)getCharacters:(unichar *)buffer range:(NSRange)aRange

Parameters
buffer
参照渡しで、レシーバから取得した文字を含みます。bufferは、aRange(aRange.length*sizeof(unichar))の範囲にある文字を含むのに十分な大きさでなくてはなりません。

aRange 取得する文字の範囲。この範囲は、レシーバの境界を越えてはいけません。

重要：aRangeのどの部分もレシーバの境界の外となると、NSRangeExceptionが発生します。

Discussion
このメソッドはNULL文字を加えません。

このメソッドの理屈の上での実装は、繰り返しcharacterAtIndex:を行い、正確に文字列を抽出することですが、これはまったく不効率です。サブクラス化する際は、高速な実装方法を提供できるようオーバライドすべきです。

Availability
Available in OS X v10.0 and later.
Related Sample Code
ClipboardViewer
Declared In
NSString.h

- getCString:maxLength:encoding:

レシーバの内容をあたえられたエンコーディングで変換し、バッファの中へ格納します。
Converts the receiver’s content to a given encoding and stores them in a buffer.

- (BOOL)getCString:(char *)buffer maxLength:(NSUInteger)maxBufferCount encoding:(NSStringEncoding)encoding

Parameters
buffer
参照渡しで、変換されたC文字列とNULL終端バイトが含まれます。このバッファは、maxBufferCountバイト数の領域を確保しなくてはなりません。

maxBufferCount
バッファへ書き込む文字列の最大バイト（NULL終端バイトも含む）。

encoding
返されるC文字列のエンコード

Return Value
処理が成功したらYES、そうでないならNO。エンコーディングエラーで変換ができないか、バッファが小さすぎる場合もNOを返します。

Discussion
引数maxBufferCountの取り扱いにあたり、このメソッドが置き換えたgetCString:maxLength:メソッド（廃止済み）と異なるのに注意してください。（バッファはmaxBufferCountバイト数の領域を確保しなくてはなりません。この数は、返される値の予測サイズ、それに加えてNULLバイト（このメソッドが付け足します）を満たす数であるべきです。）

文字列をencodingへロスレスに変換できるかどうかをチェックするには、canBeConvertedToEncoding:メソッドが使えます。もしできなければ、いくらかの情報をロスしますが、encodingを使いC文字列表現を得るにはdataUsingEncoding:allowLossyConversion:メソッドが使えます（dataUsingEncoding:allowLossyConversion:から得られるデータは、NULL終端を持てないので、厳密なC文字列ではないのに注意してください）。

Availability
Available in OS X v10.4 and later.
See Also
- cStringUsingEncoding:
- canBeConvertedToEncoding:

#45
Related Sample Code
VirtualScanner
Declared In
NSString.h

- getFileSystemRepresentation:maxLength:

レシーバをシステム依存のパス名とファイル名として解釈し、ファイルシステムコールを使うのに適したエンコードを行い、システムが規定しているフォーマット形式であるC文字列でバッファを満たします。

- (BOOL)getFileSystemRepresentation:(char *)buffer maxLength:(NSUInteger)maxLength

Parameters
buffer
システム依存のパス、加えてNULL末端バイトとしてレシーバを表す、C文字列を含みます。これは参照渡しで行います。バッファのサイズは、maxLengthバイトを含めるよう十分な大きさがなければなりません。

maxLength
バッファへ書き戻す文字列の最大バイト数（NULL終端文字も含みます。NULL自体はこのメソッドが加えます）。

Return Value
ファイルシステムの表現でbufferを満たすのに成功すればYES、でなければNO（たとえば、maxLengthを超えてしまった、もしくはファイルシステムのエンコードでレシーバを表現できなかった場合）。

Discussion
このメソッドは、抽象パスと拡張子それぞれの区切り指定子（それぞれ‘/’と‘.’）を、使用しているオペレーティングシステムでの等価なものへと置き換える作業をします。もし、システム固有のパスや拡張子の区切り指定子がその抽象表現に表れるのなら、変換される文字は、そのシステムに依存します（それら文字が抽象的な区切り文字と一緒の場合を除く）。

このメソッドはファイルパスだけに作用するのに注意して下さい（例えば、URLの表現へは作用しません）。

以下では、引数maxLengthの使い方を例示しています。最初のメソッド呼び出しで失敗が返されます。というのは、文字列(@"/mach_kernel")のファイル表現が12バイト長ですが、引数maxLength=(12)ではNULL終端バイトを加えることができないからです。

char filenameBuffer[13];
BOOL success;
success = [@"/mach_kernel" getFileSystemRepresentation:filenameBuffer maxLength:12];
// success == NO;
// NULL文字を含む長さは変えられない。
success = [@"/mach_kernel" getFileSystemRepresentation:filenameBuffer maxLength:13];
// success == YES;

Availability
Available in OS X v10.0 and later.
See Also
- fileSystemRepresentation
Declared In
NSPathUtilities.h

- getLineStart:end:contentsEnd:forRange:

あたえられた範囲にわたって、最初の行の始まりと最後の行の終わりをリファレンスで返します。

- (void)getLineStart:(NSUInteger *)startIndex end:(NSUInteger *)lineEndIndex contentsEnd:(NSUInteger *)contentsEndIndex forRange:(NSRange)aRange

Parameters
startIndex
aRangeの始まりを含む行の最初の文字のインデックスを含みます。この値が不要なら、NULLを渡します（この値が何の役割も果たさない場合）。

lineEndIndex
aRangeの終わりを含む行の、行終端の次に来る文字のインデックスを含みます。この値が不要ならNULLを渡します（この値が何の役割も果たさない場合）。

contentsEndIndex
aRangeの終わりを含む行の終端を指している最初の文字のインデックスを含みます。この値が不要なら、NULLを渡します（この値が何の役割も果たさない場合）。

aRange
レシーバの中の範囲。この値はレシーバの境界を越えてはいけません。

Discussion
行というものは下に列挙した文字のどれかで区切られていますが、それらの内で、とりえる最も長いシーケンスを選択します。

U+000D (\r or CR)
U+2028 (Unicode line separator)
U+000A (\n or LF)
U+2029 (Unicode paragraph separator)
\r\n, in that order (also known as CRLF)

もしaRangeが１つの行の中を範囲とするなら、もちろん、得られるインデックスはすべてその行の中にあります。このメソッドの結果は複数の行にわたる範囲を組み立てるのに使うことができます。そこではスタートインデックスを範囲の開始点として使い、エンドインデックスとスタートインデックスとの差をレンジの長さとして使います。

Special Considerations
このメソッドは無効な範囲すべてを検出します（長さが負のものも含む）。OS X v10.6以降で動作しているアプリケーションでは、このエラーは例外となります。それより以前のOS Xでは、エラーは警告となり、アプリケーションの実行ごとに画面に表示されます。

Availability
Available in OS X v10.0 and later.
See Also
- lineRangeForRange:
- substringWithRange:
Related Sample Code
TextEdit
Declared In
NSString.h

- getParagraphStart:end:contentsEnd:forRange:

あたえられた範囲にわたって、最初のパラグラフの始まりと最後のパラグラフの終わりをリファレンスで返します。

- (void)getParagraphStart:(NSUInteger *)startIndex end:(NSUInteger *)endIndex contentsEnd:(NSUInteger *)contentsEndIndex forRange:(NSRange)aRange

Parameters
startIndex
aRangeの始まりを含むパラグラフの最初の文字のインデックスを含みます。この値が不要なら、NULLを渡します（この値が何の役割も果たさない場合）。

endIndex
aRangeの終わりを含むパラグラフの、行終端の次に来る文字のインデックスを含みます。この値が不要なら、NULLを渡します（この値が何の役割も果たさない場合）。

contentsEndIndex
aRangeの終わりを含むパラグラフの終端を指している最初の文字のインデックスを含みます。この値が不要なら、この値が不要なら、NULLを渡します（この値が何の役割も果たさない場合）。

aRange
レシーバ内の範囲。この値はレシーバの境界を越えてはいけません。

Discussion
もしaRangeが１つのパラグラフの中を範囲とするなら、もちろん、得られるインデックスはすべてそのパラグラフの中にあります。getLineStart:end:contentsEnd:forRange:と同様に、このメソッドを使って複数のパラグラフにわたる範囲を組み立てて利用できます。

Availability
Available in OS X v10.3 and later.
See Also
- paragraphRangeForRange:
Declared In
NSString.h

- hash

ハッシュテーブルのアドレスとして使えるunsigned integerを返します。

- (NSUInteger)hash

Return Value
ハッシュテーブルのアドレスとして使えるunsigned integer。

Discussion
もし２つの文字列オブジェクトが同じなら（isEqualToString:メソッドで決定します）、同じハッシュ値を持たなくてはなりません。この条件を、このメソッドの理論上の実装は満たさなければならないので、NSString のサブクラスはこのメソッドをオーバライドすべきではありません。

OS Xの違うバージョン間で、このメソッドが同じハッシュ値を返すと仮定しない方がいいでしょう。

Availability
Available in OS X v10.0 and later.
Declared In
NSString.h

- hasPrefix:

あたえられた文字列がレシーバの始めの文字列とマッチするかどうかを真偽値で返します。

- (BOOL)hasPrefix:(NSString *)aString

Parameters
aString
文字列。

Return Value
aStringがレシーバの始めの文字列とマッチするならYES、でなければNO。aStringが空ならNOを返します。

Discussion
このメソッドは、NSAnchoredSearchオプションを使って文字列を比較するのに便利です。より詳細には、String Programming Guideをご覧下さい。

Availability
Available in OS X v10.0 and later.
See Also
- hasSuffix:
- compare:options:range:
Related Sample Code
DispatchFractal
Declared In
NSString.h

- hasSuffix:

あたえられた文字列がレシーバの終わりの文字列とマッチするかどうかを真偽値で返します。

- (BOOL)hasSuffix:(NSString *)aString

Parameters
aString
文字列。

Return Value
aStringがレシーバの終わりの文字列とマッチするならYES、でなければNO。aStringが空ならNOを返します。

Discussion
このメソッドは、NSAnchoredSearchオプションを使って文字列を比較するのに便利です。より詳細には、String Programming Guideをご覧下さい。

Availability
Available in OS X v10.0 and later.
See Also
- hasPrefix:
- compare:options:range:
Related Sample Code
ZipBrowser
Declared In
NSString.h

Referred from

NSString Class Reference, Apple Developer Library

インスタンスメソッド A ~ H／NSStringクラスリファレンス