---

NSPathUtilities

Overview

The NSPathUtilities class provides numerous methods for manipulating file paths. The capabilities include dividing file paths into individual path components, combining individual path components into a full file path, obtaining paths to standard locations in the file system, and retrieving and setting file attributes.

Tasks

Constructors

• NSPathUtilities

Obtaining Standard Paths

• searchPathForDirectoriesInDomains
• temporaryDirectory

Converting Between Paths and URLs

• URLWithPath
• pathFromURL

Getting and Setting File Attributes

• fileAttributes
• setFileAttributes

Manipulating Path Strings

• displayNameAtPath
• isAbsolutePath
• lastPathComponent
• pathComponents
• pathExtension
• pathWithComponents
• pathsMatchingExtensions
• stringByAbbreviatingWithTildeInPath
• stringByAppendingPathComponent
• stringByAppendingPathExtension
• stringByDeletingLastPathComponent
• stringByDeletingPathExtension
• stringByExpandingTildeInPath
• stringByResolvingSymlinksInPath
• stringByStandardizingPath
• stringsByAppendingPaths

Static Methods

displayNameAtPath

Returns the name of the file or directory at path in a form appropriate for presentation to the user.

public static String displayNameAtPath(String path)

fileAttributes

Returns an NSDictionary containing various objects that represent the POSIX attributes of the file specified at path.

public static NSDictionary fileAttributes(String path, boolean flag)

Discussion

You access these objects using the keys described in the “Constants” section.

If flag is true and path is a symbolic link, the attributes of the linked-to file are returned; if the link points to a nonexistent file, this method returns null. If flag is false, the attributes of the symbolic link are returned.

See Also

• setFileAttributes

isAbsolutePath

Interprets aString as a path, returning true if it represents an absolute path, false if it represents a relative path.

public static boolean isAbsolutePath(String aString)

lastPathComponent

Returns the last path component of aString.

public static String lastPathComponent(String aString)

Discussion

The following table illustrates the effect of lastPathComponent on a variety of different paths:

pathComponents

Interprets aString as a path, returning an array of strings containing, in order, each path component of aString.

public static NSArray pathComponents(String aString)

Discussion

The strings in the array appear in the order they did in aString. If aString begins or ends with the path separator, then the first or last component, respectively, contains the separator. Empty components (caused by consecutive path separators) are deleted.

If aString begins with a slash—for example, “/tmp/scratch”—the array has these contents:

If aString has no separators—for example, “scratch”—the array contains aString itself, in this case “scratch”.

See Also

• pathWithComponents
• stringByStandardizingPath

pathExtension

Interprets aString as a path, returning the extension of aString, if any (not including the extension divider).

public static String pathExtension(String aString)

Discussion

The following table illustrates the effect of pathExtension on a variety of different paths:

pathFromURL

Returns the path of aURL conforming to RFC 1808.

public static String pathFromURL(java.net.URL aURL)

Discussion

If aURL does not conform to RFC 1808, returns null.

pathsMatchingExtensions

Returns an array containing all the elements from the pathNames array that have filename extensions from the filterTypes array.

public static NSArray pathsMatchingExtensions(NSArray pathNames, NSArray filterTypes)

Discussion

The extensions in filterTypes should not include the dot (“.”) character.

pathWithComponents

Returns a string built from the strings in components, by concatenating them with a path separator between each pair.

public static String pathWithComponents(NSArray components)

Discussion

To create an absolute path, use a slash mark (/) as the first component. To include a trailing path divider, use an empty string as the last component. This method doesn’t clean up the path created; use stringByStandardizingPath to resolve empty components, references to the parent directory, and so on.

See Also

• pathComponents

searchPathForDirectoriesInDomains

Creates a list of path strings for the specified directories in the specified domains.

public static NSArray searchPathForDirectoriesInDomains(int directory, int domainMask, boolean expandTilde)

Discussion

The list is in the order in which you should search the directories. The list of values for directory and domainMask is described in “Constants.” If expandTilde is true, tildes are expanded as described in stringByExpandingTildeInPath.

setFileAttributes

Changes the attributes of the file or directory specified by path.

public static boolean setFileAttributes(String path, NSDictionary attributes)

Discussion

The attributes that you can change include the owner, group, file permissions, and modification date. (The list of file attribute keys are given in the “Constants” section; their values cannot all be changed, however.) As in the POSIX standard, the application either must own the file or directory or must be running as superuser for attribute changes to take effect. The method attempts to make all changes specified in attributes and ignores any rejection of an attempted modification. If all changes succeed, it returns true. If any change fails, the method returns false, but it is undefined whether any changes actually occurred.

The FilePosixPermissions value must be initialized with the code representing the POSIX file-permissions bit pattern. FileHFSCreatorCode and FileHFSTypeCode will only be heeded when path specifies a file.

You can change single attributes or any combination of attributes; you need not specify keys for all attributes.

See Also

• fileAttributes

stringByAbbreviatingWithTildeInPath

Returns a string representing aString as a path, with a tilde, “~”, substituted for the full path to the current user’s home directory, or “~user” for a user other than the current user.

public static String stringByAbbreviatingWithTildeInPath(String aString)

Discussion

Returns aString unaltered if it doesn’t begin with the user’s home directory.

See Also

• stringByExpandingTildeInPath

stringByAppendingPathComponent

Returns a string made by appending aString1 with aString2, preceded if necessary by a path separator.

public static String stringByAppendingPathComponent(String aString1, String aString2)

Discussion

The following table illustrates the effect of this method on a variety of different paths, assuming that aString2 is supplied as “scratch.tiff”:

This method may fail to append if PATH_MAX is exceeded. Its failure mode is to return the original string passed to the method as string1, rather than a string with anything appended to it. The method also logs in console.log the fact that the attempt failed.

See Also

• stringsByAppendingPaths
• stringByAppendingPathExtension
• stringByDeletingLastPathComponent

stringByAppendingPathExtension

Returns a string made by appending to aString1 an extension separator followed by aString2.

public static String stringByAppendingPathExtension(String aString1, String aString2)

Discussion

The following table illustrates the effect of this method on a variety of different paths, assuming that aString2 is supplied as "tiff":

See Also

• stringByAppendingPathComponent
• stringByDeletingPathExtension

stringByDeletingLastPathComponent

Returns a string made by deleting the last path component from aString, along with any final path separator.

public static String stringByDeletingLastPathComponent(String aString)

Discussion

If aString represents the root path, however, it’s returned unaltered. The following table illustrates the effect of this method on a variety of different paths:

See Also

• stringByDeletingPathExtension
• stringByAppendingPathComponent

stringByDeletingPathExtension

Returns a string made by deleting the extension (if any, and only the last) from aString.

public static String stringByDeletingPathExtension(String aString)

Discussion

Strips any trailing path separator before checking for an extension. If aString represents the root path, however, it’s returned unaltered. The following table illustrates the effect of this method on a variety of different paths:

See Also

• pathExtension
• stringByDeletingLastPathComponent

stringByExpandingTildeInPath

Returns a string made by expanding the initial component of aString, if it begins with “~” or “~user”, to its full path value.

public static String stringByExpandingTildeInPath(String aString)

Discussion

Returns aString unaltered if that component can’t be expanded.

See Also

• stringByAbbreviatingWithTildeInPath

stringByResolvingSymlinksInPath

Expands an initial tilde expression in aPath, then resolves all symbolic links and references to current or parent directories if possible, returning a standardized path.

public static String stringByResolvingSymlinksInPath(String aPath)

Discussion

If the original path is absolute, all symbolic links are guaranteed to be removed; if it’s a relative path, symbolic links that can’t be resolved are left unresolved in the returned string. Returns this if an error occurs.

If the name of aPath begins with /private, this method strips off the /private designator, provided the result is the name of an existing file.

See Also

• stringByStandardizingPath
• stringByExpandingTildeInPath

stringByStandardizingPath

Returns a string representing the path of aString, with extraneous path components removed.

public static String stringByStandardizingPath(String aString)

Discussion

If stringByStandardizingPath detects symbolic links in a pathname, the stringByResolvingSymlinksInPath method is called to resolve them. If an invalid pathname is provided, stringByStandardizingPath may attempt to resolve it by calling stringByResolvingSymlinksInPath, and the results are undefined. If any other kind of error is encountered (such as a path component not existing), this is returned.

This method can make the following changes in the provided string:

• Expand an initial tilde expression using stringByExpandingTildeInPath.

• Reduce empty components and references to the current directory (that is, the sequences “//” and “/./”) to single path separators.

• In absolute paths only, resolve references to the parent directory (that is, the component “..”) to the real parent directory if possible using stringByResolvingSymlinksInPath, which consults the file system to resolve each potential symbolic link.

  In relative paths, because symbolic links can’t be resolved, references to the parent directory are left in place.

• Remove an initial component of “/private” from the path if the result still indicates an existing file or directory (checked by consulting the file system).

See Also

• stringByExpandingTildeInPath
• stringByResolvingSymlinksInPath

stringsByAppendingPaths

Returns an array of strings made by separately appending each string in paths to aString, preceded if necessary by a path separator.

public static NSArray stringsByAppendingPaths(String aString, NSArray paths)

Discussion

See stringByAppendingPathComponent for an individual example.

temporaryDirectory

Returns the path to the system’s temporary directory.

public static String temporaryDirectory()

URLWithPath

Returns a newly created URL referencing the file or directory at path.

public static java.net.URL URLWithPath(String path)

Constants

The following constants for directory locations are provided by NSPathUtilities:

The following masks are provided for working with paths:

The following are keys used to access attributes of a mounted file system:

The following are keys used to access file attributes contained in the attribute dictionaries returned from fileAttributes and passed to setFileAttributes:

The following constants are the possible values for the FileType attribute key:

---