haiku/docs/user/storage/Path.dox

/*
 * Copyright 2002-2013 Haiku Inc. All rights reserved.
 * Distributed under the terms of the MIT License.
 *
 * Authors:
 *		Tyler Dauwalder
 *		Axel Dörfler, axeld@pinc-software.de
 *		John Scipione, jscipione@gmail.com
 *		Ingo Weinhold, bonefish@users.sf.net
 *
 * Corresponds to:
 *		headers/os/storage/Path.h	hrev47402
 *		src/kits/storage/Path.cpp	hrev47402
 */


/*!
	\file Path.h
	\ingroup storage
	\ingroup libbe
	\brief Provides the BPath class.
*/


/*!
	\class BPath
	\ingroup storage
	\ingroup libbe
	\brief A class representing a file system path.

	\since BeOS R3
*/


/*!
	\fn BPath::BPath()
	\brief Creates an uninitialized BPath object.

	\see SetTo()
*/


/*!
	\fn BPath::BPath(const BPath& path)
	\brief Creates a copy of the given BPath object.

	\param path the object to be copied.

	\since BeOS R3
*/


/*!
	\fn BPath::BPath(const entry_ref* ref)
	\brief Creates a BPath object and initializes it to the filesystem entry
	       specified by the passed in entry_ref struct.

	\param ref the entry_ref to initialize from.

	\since BeOS R5
*/


/*!
	\fn BPath::BPath(const BEntry* entry)
	\brief Creates a BPath object and initializes it to the filesystem entry
	       specified by the passed in BEntry object.

	\param entry the BEntry object to initialize from.

	\since BeOS R4
*/


/*!
	\fn BPath::BPath(const char* dir, const char* leaf, bool normalize)
	\brief Creates a BPath object and initializes it to the specified path or
	       path and filename combination.

	\param dir The base component of the pathname. May be absolute or relative.
	       If relative, it is based off the current working directory.
	\param leaf The (optional) leaf component of the pathname. Must be
	       relative. The value of \a leaf is concatenated to the end of \a dir
	       (a "/" will be added as a separator, if necessary).
	\param normalize boolean flag used to force normalization; normalization
	       may sometimes occur even if \c false. The following items require
	       normalization:
	       - Relative pathnames (after concatenation; e.g. "boot/ltj")
	       - The presence of "." or ".." ("/boot/ltj/../ltj/./gwar")
	       - Redundant slashes ("/boot//ltj")
	       - A trailing slash ("/boot/ltj/")

	\since BeOS R3
*/


/*!
	\fn BPath::BPath(const BDirectory* dir, const char* leaf, bool normalize)
	\brief Creates a BPath object and initializes it to the specified directory
	       and filename combination.

	\param dir The directory that provides the base component of the pathname.
	\param leaf The (optional) leaf component of the pathname. Must be
	       relative. The value of \a leaf is concatenated to the end of \a dir
	       (a "/" will be added as a separator, if necessary).
	\param normalize boolean flag used to force normalization; normalization
	       may sometimes occur even if \c false. The following items require
	       normalization:
	       - Relative pathnames (after concatenation; e.g. "boot/ltj")
	       - The presence of "." or ".." ("/boot/ltj/../ltj/./gwar")
	       - Redundant slashes ("/boot//ltj")
	       - A trailing slash ("/boot/ltj/")

	\since BeOS R3
*/


/*!
	\fn BPath::~BPath()
	\brief Destroys the BPath object and frees any associated resources.

	\since BeOS R3
*/


/*!
	\name Constructor Helpers
*/


//! @{


/*!
	\fn status_t BPath::InitCheck() const
	\brief Checks whether or not the object was properly initialized.

	\return \c B_OK, if the BPath object was properly initialized, an error
	        code otherwise.

	\since BeOS R3
*/


/*!
	\fn status_t BPath::SetTo(const entry_ref* ref)
	\brief Reinitializes the object to the filesystem entry specified by the
	       passed in entry_ref struct.
	\param ref The entry_ref to reinitialize the entry from.

	\returns A status code.
	\retval B_OK Initialization was successful.
	\retval B_BAD_VALUE \a ref was \c NULL.
	\retval B_NAME_TOO_LONG The pathname was longer than \c B_PATH_NAME_LENGTH.

	\since BeOS R5
*/


/*!
	\fn status_t BPath::SetTo(const BEntry* entry)
	\brief Reinitializes the object to the specified filesystem entry.

	\param entry The BEntry to reinitialize the entry from.

	\returns A status code.
	\retval B_OK Initialization was successful.
	\retval B_BAD_VALUE \a ref was \c NULL.
	\retval B_NAME_TOO_LONG The pathname was longer than \c B_PATH_NAME_LENGTH.

	\since BeOS R4
*/


/*!
	\fn status_t BPath::SetTo(const char* path, const char* leaf, bool normalize)
	\brief Reinitializes the object to the passed in \a path or \a path and
	       \a leaf combination.

	\remarks The following pseudocode is safe:
	         \code path.SetTo(path.Path(), "new leaf") \endcode

	\param path The \a path name to use.
	\param leaf The \a leaf name to use (may be \c NULL).
	\param normalize Boolean flag used to force normalization; normalization
	       may sometimes occur even if \c false. The following items require
	       normalization:
	       - Relative pathnames (after concatenation; e.g. "boot/ltj")
	       - The presence of "." or ".." ("/boot/ltj/../ltj/./gwar")
	       - Redundant slashes ("/boot//ltj")
	       - A trailing slash ("/boot/ltj/")

	\returns A status code.
	\retval B_OK Initialization was successful.
	\retval B_BAD_VALUE \a ref was \c NULL.
	\retval B_NAME_TOO_LONG The pathname was longer than \c B_PATH_NAME_LENGTH.

	\since BeOS R3
*/


/*!
	\fn status_t BPath::SetTo(const BDirectory* dir, const char* path,
		bool normalize)
	\brief Reinitializes the object to the passed in \a dir and relative
	       \a path combination.

	\param dir The directory that provides the base component of the pathname.
	\param path the relative \a path name (may be \c NULL).
	\param normalize boolean flag used to force normalization; normalization
	       may sometimes occur even if \c false. The following items require
	       normalization:
	       - Relative pathnames (after concatenation; e.g. "boot/ltj")
	       - The presence of "." or ".." ("/boot/ltj/../ltj/./gwar")
	       - Redundant slashes ("/boot//ltj")
	       - A trailing slash ("/boot/ltj/")

	\returns A status code.
	\retval B_OK Initialization was successful.
	\retval B_BAD_VALUE \a ref was \c NULL.
	\retval B_NAME_TOO_LONG The pathname was longer than \c B_PATH_NAME_LENGTH.

	\since BeOS R3
*/


/*!
	\fn void BPath::Unset()
	\brief Returns the object to an uninitialized state.

	Frees any resources it allocated and marks the object as uninitialized.

	\since BeOS R3
*/


//! @}


/*!
	\name Path Manipulation
*/


//! @{


/*!
	\fn status_t BPath::Append(const char* path, bool normalize)
	\brief Appends the passed in relative path to the end of the current path.

	This method fails if the path is absolute or the BPath object is
	uninitialized.

	\param path Relative pathname to append to current path (may be \c NULL).
	\param normalize Boolean flag used to force normalization; normalization
	       may sometimes occur even if \c false. The following items require
	       normalization:
	       - Relative pathnames (after concatenation; e.g. "boot/ltj")
	       - The presence of "." or ".." ("/boot/ltj/../ltj/./gwar")
	       - Redundant slashes ("/boot//ltj")
	       - A trailing slash ("/boot/ltj/")

	\returns A status code.
	\retval B_OK Initialization was successful.
	\retval B_BAD_VALUE \a ref was \c NULL.
	\retval B_NAME_TOO_LONG The pathname was longer than \c B_PATH_NAME_LENGTH.

	\since BeOS R3
*/


//! @}


/*!
	\name Path Information
*/


//! @{


/*!
	\fn const char* BPath::Path() const
	\brief Gets the entire path of the object.

	\returns The path name of the object, or \c NULL if it is not properly
	         initialized.

	\since BeOS R3
*/


/*!
	\fn const char* BPath::Leaf() const
	\brief Gets the leaf portion of the path.

	The leaf portion of the path is defined to be the string after the last
	\c '/'. For the root path (\c "/") it is an empty string (\c "").

	\returns The leaf portion of the path or \c NULL if it is not properly
	         initialized.

	\since BeOS R3
*/


/*!
	\fn status_t BPath::GetParent(BPath* path) const
	\brief Initializes \a path with the parent directory of the BPath object.

	No normalization is performed on the path.

	\param path The BPath object to be initialized to the parent directory.

	\returns A status code.
	\retval B_OK Everything went fine.
	\retval B_BAD_VALUE \a path was \c NULL.
	\retval B_ENTRY_NOT_FOUND The BPath object represents the root path and
	        thus has no parent.
*/


/*!
	\fn bool BPath::IsAbsolute() const
	\brief Gets whether or not the path is absolute or relative.

	\warning This method returns \c false if the object is initialized.

	\returns \c true if the path is absolute, \c false if relative or if the
	         object is uninitialized.
*/


//! @}


/*!
	\name Operators
*/


//! @{


/*!
	\fn bool BPath::operator==(const BPath& item) const
	\brief Performs a simple (string-wise) comparison of paths for equality.

	\warning No normalization takes place, two uninitialized BPath objects are
	         considered equal.

	\param item the BPath object to compare.

	\return \c true, if the paths are equal, \c false otherwise.

	\since BeOS R3
*/


/*!
	\fn bool BPath::operator==(const char* path) const
	\brief Performs a simple (string-wise) comparison of paths for equality.

	\warning No normalization takes place.

	\param path The path to compare.

	\return \c true, if the path names are equal, \c false otherwise.

	\since BeOS R3
*/


/*!
	\fn bool BPath::operator!=(const BPath& item) const
	\brief Performs a simple (string-wise) comparison of paths for inequality.

	\warning No normalization takes place, two uninitialized BPath objects are
	         considered equal.

	\param item the BPath object to compare.

	\return \c true, if the path names are \b not equal, \c false otherwise.

	\since BeOS R3
*/


/*!
	\fn bool BPath::operator!=(const char* path) const
	\brief Performs a simple (string-wise) comparison of paths for inequality.

	\warning No normalization takes place.

	\param path The path to compare.

	\return \c true, if the path names are \b not equal, \c false otherwise.

	\since BeOS R3
*/


/*!
	\fn BPath& BPath::operator=(const BPath& item)
	\brief Initializes the object as a copy of \a item.

	\param item The BPath object to copy

	\return A pointer to the newly initialized BPath object.

	\since BeOS R3
*/


/*!
	\fn BPath& BPath::operator=(const char* path)
	\brief Initializes the object with the passed in \a path.

	Has the same effect as \code SetTo(path) \endcode

	\param path the path to be assign to this object.

	\return A pointer to the newly initialized BPath object.

	\since BeOS R3
*/


//! @}


/*!
	\name BFlattenable Method Implementations
*/


//! @{


/*!
	\fn bool BPath::IsFixedSize() const
	\brief Implements BFlattenable::IsFixedSize(). Always returns \c false.

	\return \c false

	\since BeOS R3
*/


/*!
	\fn type_code BPath::TypeCode() const
	\brief Implements BFlattenable::TypeCode(). Always returns \c B_REF_TYPE.

	\return \c B_REF_TYPE

	\since BeOS R3
*/


/*!
	\fn ssize_t BPath::FlattenedSize() const
	\brief Implements BFlattenable::FlattenedSize(). Gets the size of the
	       flattened entry_ref struct that represents the path in bytes.

	\return The size of the flattened entry_ref struct that represents the
	        path in bytes.

	\since BeOS R3
*/


/*!
	\fn status_t BPath::Flatten(void* buffer, ssize_t size) const
	\brief Implements BFlattenable::Flatten(). Converts the path of the object
	       to an entry_ref and writes it into <em>buffer</em>.

	\param buffer The buffer that the data is to be stored in.
	\param size Size of <em>buffer</em>.

	\returns A status code.
	\retval B_OK Everything went fine.
	\retval B_BAD_VALUE \a buffer was \c NULL or of insufficient size.

	\since BeOS R3
*/


/*!
	\fn bool BPath::AllowsTypeCode(type_code code) const
	\brief Implements BFlattenable::AllowsTypeCode(). Checks if type code is
	       equal to \c B_REF_TYPE.

	\param code The type code to test.

	\return \c true if code is \c B_REF_TYPE, \c false otherwise.

	\since BeOS R3
*/


/*!
	\fn status_t BPath::Unflatten(type_code code, const void* buffer,
		ssize_t size)
	\brief Implements BFlattenable::Unflatten(). Initializes the object with
	       the flattened entry_ref data from the passed in buffer.

	The type code must be set to \c B_REF_TYPE.

	\param code The type code of the flattened data, must be \c B_REF_TYPE.
	\param buffer A pointer to a buffer containing the flattened data.
	\param size The size of \a buffer in bytes.

	\returns A status code.
	\retval B_OK Everything went fine.
	\retval B_BAD_VALUE \a buffer was \c NULL or didn't contain an entry_ref.

	\since BeOS R3
*/


//! @}