/*
 * 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	hrev45260
 *		src/kits/storage/Path.cpp	hrev45260
 */


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


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


/*!
	\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.
*/


/*!
	\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.
*/


/*!
	\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.
*/


/*!
	\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/")
	
*/


/*!
	\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/")
*/


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


/*!
	\name Constructor helper methods
*/


//! @{


/*!
	\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.
*/


/*!
	\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 \c NULL \a ref.
	\retval B_NAME_TOO_LONG The pathname was longer than \c B_PATH_NAME_LENGTH.
*/


/*!
	\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 \c NULL \a ref.
	\retval B_NAME_TOO_LONG The pathname was longer than \c B_PATH_NAME_LENGTH.
*/


/*!
	\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 \c NULL \a ref.
	\retval B_NAME_TOO_LONG The pathname was longer than \c B_PATH_NAME_LENGTH.
*/


/*!
	\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 \c NULL \a ref.
	\retval B_NAME_TOO_LONG The pathname was longer than \c B_PATH_NAME_LENGTH.
*/


/*!
	\fn void BPath::Unset()
	\brief Returns the object to an uninitialized state.
	
	Frees any resources it allocated and marks the object as uninitialized.
*/


//! @}


/*!
	\name Path manipulation methods
*/


//! @{


/*!
	\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 \c NULL \a ref.
	\retval B_NAME_TOO_LONG The pathname was longer than \c B_PATH_NAME_LENGTH.
*/


//! @}


/*!
	\name Path information methods
*/


//! @{


/*!
	\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.
*/


/*!
	\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.
*/


/*!
	\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 \c NULL \a path.
	\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 Operator overload methods
*/


//! @{


/*!
	\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.
*/


/*!
	\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.
*/


/*!
	\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.
*/


/*!
	\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.
*/


/*!
	\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.
*/


/*!
	\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.
*/


//! @}


/*!
	\name BFlattenable override methods
*/


//! @{


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

	\return \c false
*/


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

	\return \c B_REF_TYPE
*/


/*!
	\fn ssize_t BPath::FlattenedSize() const
	\brief Overrides 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.
*/


/*!
	\fn status_t BPath::Flatten(void* buffer, ssize_t size) const
	\brief Overrides 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 \c NULL buffer or the buffer is of insufficient size.
*/


/*!
	\fn bool BPath::AllowsTypeCode(type_code code) const
	\brief Overrides 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.
*/


/*!
	\fn status_t BPath::Unflatten(type_code code, const void* buffer,
		ssize_t size)
	\brief Overrides 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 buf A pointer to 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 is \c NULL or doesn't contain an entry_ref.
*/


//! @}


/// private methods, won't show up in docs


/*!
	status_t BPath::_SetPath(const char* path)
	\brief Sets the supplied path.

	The path is copied. If \a path is \c NULL path of the object is set to
	\c NULL as well. The object's old path is deleted.

	\param path the path to be set

	\returns A status code.
	\retval B_OK Everything went fine.
	\retval B_NO_MEMORY Insufficient memory.
*/


/*!
	bool BPath::_MustNormalize(const char* path, status_t* _error)
	\brief Checks a path to see if normalization is required.

	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/")

	\param _error A pointer to an error variable that will be set if the input
		is not a valid path.

	\return \c true if \a path requires normalization, \c false otherwise.
*/