Class: TPathName

Declaration: FileSystemInterface.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

None.

Inherited By:

None.

Purpose:

This class provides a mechanism for specifying file system entities via portable paths.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

Do not derive from this class.

Concurrency:

Not multithread safe.

Resource Use:

Allocates an array of TStandardText objects internally.

Member Function: TPathName::TPathName

TPathName ()
TPathName (const TPathName & copyMe)
TPathName (const THostSpecificPathName & path, const TPathNameParser & aParser =TPathNameParser :: GetDefaultParser ())
TPathName (const TFileSystemEntity & anEntity)
TPathName (const TDirectory & startHere, const THostSpecificPathName & partialPath, const TPathNameParser & aParser =TPathNameParser :: GetDefaultParser ())
TPathName (const TDirectory & startHere, const TPathName & partialPath)

Interface Category:

API.

Purpose:

Default constructor.
Copy constructor.
Converts a host-specific path to a TPathName object.
Converts a file system entity to a TPathName object.
Builds a TPathName object from the two supplied components.
Builds a TPathName object by concatenating its two arguments.

Calling Context:

Called by the stream-in operators and to create an uninitialized TPathName object for later assignment.
Called to copy an object.
Called to convert from a host-specific path string to a TPathName object.
Called to find the path for a particular file system entity.
Called to construct a path object from a directory and a partial path string.
Called to construct a path object from a directory and another path object that is a partial

Parameters:

Takes no parameters.
const TPathName & copyMe -The object to copy from.
const THostSpecificPathName & path -The host-specific path to be converted to a TPathName; can be absolute or relative.
const TPathNameParser & aParser =TPathNameParser :: GetDefaultParser () -A parser; defaults to an appropriate parser for the client machine.
const TFileSystemEntity & anEntity -The file system entity to be converted to a TPathName.
const TDirectory & startHere -The directory to construct the relative path in.
const THostSpecificPathName & partialPath -A host-specific relative path.
const TPathNameParser & aParser =TPathNameParser :: GetDefaultParser () -A parser; defaults to an appropriate parser for the client machine.
const TDirectory & startHere -The directory to construct the relative path in.
const TPathName & partialPath -A host-specific relative path.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.
Throws no exceptions, passes all exceptions through.
Throws TFileSystemEntityNotAvailable for ill-formed paths (but not for well-formed paths specifying entities that do not exist; that is, the path must be well-formed but need not represent an existing on-disk entity).
Throws TFileSystemEntityNotAvailable if the specified entity is invalid or does not exist on-disk.
Throws TFileSystemEntityNotAvailable for ill-formed paths (but not for well-formed paths specifying entities that do not exist; that is, the path must be well-formed but need not represent an existing on-disk entity).
Throws TFileSystemEntityNotAvailable if the specified TDirectory is invalid or does not exist on-disk.
Throws TFileSystemEntityNotAvailable for ill-formed paths (but not for well-formed paths specifying entities that do not exist; that is, the path must be well-formed but need not represent an existing on-disk entity).
Throws TFileSystemEntityNotAvailable if the specified TDirectory is invalid or does not exist on-disk.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPathName::GetTaligentRoot

static TDirectory GetTaligentRoot ()

Interface Category:

API.

Purpose:

Returns the topmost directory of the CommonPoint installation hierarchy.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

The topmost directory of the the CommonPoint installation hierarchy.

Exceptions:

Throws TFileSystemEntityNotAvailable if the TaligentRoot environment variable is not set. (AIX only.) Throws TFileSystemEntityNotAvailable if the directory specified by the TaligentRoot environment variable cannot be found. Throws TFileSystemTypeMismatch if the pathname specified by the TaligentRoot environment variable is not a directory.

Concurrency:

Not multithread safe.

Other Considerations:

This will soon be made obsolete and removed from the interface. Use TMultipleRootLocator instead.

Member Function: TPathName::Hash

long Hash () const

Interface Category:

API.

Purpose:

Returns a hash value that can be used by collection classes.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

The long hash value.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPathName::GetComponentAt

void GetComponentAt (unsigned long index, TStandardText & fillIn) const

Interface Category:

API.

Purpose:

Extracts the path component at the requested index.

Calling Context:

Call this function directly.

Parameters:

unsigned long index -The index of the requested component.
TStandardText & fillIn -On return, holds the component.

Return Value:

None.

Exceptions:

Throws TFileSystemEntityNotAvailable if the TPathName is uninitialized. Throws TCollectionException if the index is out of range.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPathName::GetNumberOfComponents

unsigned long GetNumberOfComponents () const

Interface Category:

API.

Purpose:

Returns the number of components in the path.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

The number of components in the path.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

The first component is defined as the volume name on systems that support such notion. On UNIX, the name space does not begin with a volume name, so the first component is empty. For example, /usr/include/sys/mode.h would return a count of 5, including one for the empty volume name.

Member Function: TPathName::Append

void Append (const TPathName & relativePath)

Interface Category:

API.

Purpose:

Appends a relative path to this path. Can be used to build an absolute or longer relative path.

Calling Context:

Call this function directly.

Parameters:

const TPathName & relativePath -The relative path to append to this.

Return Value:

None.

Exceptions:

Throws TFileSystemEntityNotAvailable for ill-formed paths (but not for well-formed paths specifying entities that do not exist; that is, the path must be well-formed but need not represent an existing on-disk entity).

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPathName::FactorCommonRoot

void FactorCommonRoot (const TPathName & anotherPath, TPathName & commonRoot, TPathName & fromRootToLeaf)

Interface Category:

API.

Purpose:

Extracts the common root of this and anotherPath, the initial part of the absolute path that is identical in both paths.

Calling Context:

Call this function directly.

Parameters:

const TPathName & anotherPath -A path to be compared to this.
TPathName & commonRoot -On return, holds the common root.
TPathName & fromRootToLeaf -On return, holds the remainder of this path, from the end of the common root to end of the path.

Return Value:

None.

Exceptions:

Throws TFileSystemEntityNotAvailable for uninitialized TPathNames. Throws TFileSystemPathNameError if fromRootToLeaf would be empty.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPathName::GetEntity

TFileSystemEntity GetEntity ()

Interface Category:

API.

Purpose:

Returns the file system entity represented by this path.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

The file system entity represented by this path.

Exceptions:

Throws TFileSystemEntityNotAvailable if the entity cannot be found on-disk. Throws TFileSystemInternalError if the entity is not a recognized type (for example, not a file, directory, or volume).

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPathName::operator==

bool operator ==(const TPathName & anotherPath) const

Interface Category:

API.

Purpose:

Determines if this path is identical to another path.

Calling Context:

Call this function directly.

Parameters:

const TPathName & anotherPath -The path to compare this to.

Return Value:

Returns true if this and anotherPath are identical.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPathName::operator<<=

TStream & operator <<= (TStream & fromWhere)

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Called to stream in data.

Parameters:

TStream & fromwhere -The stream the object streams itself in from.

Return Value:

Returns a reference to the stream the object streams itself in from.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPathName::operator>>=

TStream & operator >>=(TStream & toWhere) const

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Called to stream out data.

Parameters:

TStream & toWhere -The stream the object streams itself out to.

Return Value:

Returns a reference to the stream the object streams itself out to.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPathName::operator=

TPathName & operator =(const TPathName & copyMe)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Called when an object is assigned to another compatible object.

Parameters:

const TPathName & copyMe -The pathname to copy from.

Return Value:

A non-const reference to the left-hand side object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPathName::Truncate

void Truncate (const TPathName & relativePath)
void Truncate (unsigned long numberOfPathSegmentsToRemove)

Interface Category:

API.

Purpose:

Truncates the path by removing the end string common to this path and another path.
Removes the requested number of path components from the end of this path.

Calling Context:

Call this function directly.
Call this function directly.

Parameters:

const TPathName & relativePath -The relative path to compare this to.
unsigned long numberOfPathSegmentsToRemove -The number of components to remove from the end of this.

Return Value:

None.

Exceptions:

Throws TFileSystemEntityNotAvailable if this is not initialized.
Throws TFileSystemPathNameError if the specified path has more components than this.
Throws TFileSystemPathNameError if the specified path is not identical to the end of this.
Throws TFileSystemEntityNotAvailable if this is not initialized.
Throws TFileSystemPathNameError if numberOfPathSegmentsToRemove is greater than the number of components in the path.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPathName::~TPathName

virtual ~ TPathName ()

Interface Category:

API.

Purpose:

Destructor.

Calling Context:

Called to destroy an object.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Click the icon to mail questions or corrections about this material to Taligent personnel.