Instance Method インスタンスメソッド

replaceItemAtURL(originalItemURL:withItemAtURL:backupItemName:options:)

Replaces the contents of the item at the specified URL in a manner that ensures no data loss occurs. データ損失が生じないことを保証する流儀で、指定されたURLで項目の内容を置き換えます。

Declaration 宣言

func replaceItemAtURL(originalItemURL: NSURL, withItemAtURL newItemURL: NSURL, backupItemName: String? = nil, options: FileManager.ItemReplacementOptions = []) throws -> NSURL?

Parameters パラメータ

originalItemURL: The item containing the content you want to replace. あなたが置き換えるのを望む内容を含んでいる項目。
newItemURL: The item containing the new content for originalItemURL. It is recommended that you put this item in a temporary directory as provided by the OS. If a temporary directory is not available, put this item in a uniquely named directory that is in the same directory as the original item. originalItemURLに対する新しい内容を含んでいる項目。あなたがこの項目をOSによって提供されるような一時ディレクトリの中に置くことは推奨されます。一時ディレクトリが利用可能でないならば、この項目を独特に命名されたディレクトリの中においてください、それは元の項目と同じディレクトリの中にです。
backupItemName: If provided, the name used to create a backup of the original item. 提供されるならば、元の項目のバックアップを作成するのに使われる名前。

The backup is placed in the same directory as the original item. If an error occurs during the creation of the backup item, the operation fails. If there is already an item with the same name as the backup item, that item will be removed. バックアップは、元の項目と同じディレクトリの中に位置します。バックアップ項目の作成の間にエラーが発生するならば、操作は失敗します。バックアップ項目と同じ名前を持つ項目が既にあるならば、その項目は取り除かれます。

The backup item will be removed in the event of success unless the withoutDeletingBackupItem option is provided in options. バックアップ項目は、うまくいったイベントにおいて除去されるでしょう、withoutDeletingBackupItemオプションがoptionsにおいて提供される場合を除いて。
options オプション: The options to use during the replacement. Typically, you pass usingNewMetadataOnly for this parameter, which uses only the metadata from the new item. You can also combine the options described in FileManager.ItemReplacementOptions using the C-bitwise OR operator. 置換の間に使うためのオプション。概して、あなたはusingNewMetadataOnlyをこのパラメータに渡します、それは新しい項目からのメタデータのみ使います。あなたはまた、FileManager.ItemReplacementOptionsで記述されるオプションをCビット単位OR演算子を使って結合できます。

Return Value 戻り値

The URL of the new item. If no new file system object is required, the URL object in this parameter may be the same passed to the originalItemURL parameter. However, if a new file system object is required, the URL object may be different. For example, replacing an RTF document with an RTFD document requires the creation of a new file. 新しい項目のURL。新しいファイルシステムオブジェクトが必要とされないならば、このパラメータの中のURLオブジェクトはoriginalItemURLパラメータに渡されたものと同じであるかもしれません。しかしながら、新しいファイルシステムオブジェクトが必要とされるならば、URLオブジェクトは異なるでしょう。例えば、RTF書類をRTFD書類で置き換えることは、新しいファイルの作成を必要とします。

Discussion 議論

By default, the creation date, permissions, Finder label and color, and Spotlight comments of the original item are preserved on the new item. You can configure which metadata is preserved using the options parameter. 初期状態で、元の項目の作成日、権限、Finderのラベルとカラー、そしてSpotlightコメントは、新しい項目上で保たれます。あなたはどのメタデータが保全されるかをoptionsパラメータを使って構成設定できます。

This method works only when the originalItemURL and newItemURL parameters are located on the same volume. Attempting to call this method by passing originalItemURL and newItemURL parameters that have locations on different volumes results in an error. Instead, you can call the url(for:in:appropriateFor:create:) method, passing FileManager.SearchPathDirectory.itemReplacementDirectory as the search path directory, to get a temporary URL on the destination's volume that is suitable for use with this method. このメソッドは、originalItemURLとnewItemURLパラメータが同じボリューム上に位置する場合にのみ働きます。このメソッドを異なるボリューム上に位置するoriginalItemURLとnewItemURLパラメータを渡すことによって呼び出す試みは、エラーという結果になります。代わりに、あなたはurl(for:in:appropriateFor:create:)メソッドを呼び出して、FileManager.SearchPathDirectory.itemReplacementDirectoryを検索パスディレクトリとして渡して、行き先のボリューム上の一時URLを得ることができます、それはこのメソッドで使うのに適します。

If an error occurs and the original item is not in the original location or a temporary location, the resulting error object contains a user info dictionary with the key "NSFileOriginalItemLocationKey". The value assigned to that key is an NSURL object with the location of the item. The error code is one of the file-related errors described in NSError Codes. エラーが発生するそして元の項目が元の場所や一時的場所にないならば、結果のエラーオブジェクトはキー"NSFileOriginalItemLocationKey"をもつユーザ情報辞書を含みます。そのキーに割り当てられた値は、項目の場所を持つNSURLオブジェクトです。エラーコードは、NSErrorコードにおいて記述されるファイル関連エラーの１つです。