svn_path.h

linux subdivision ying gai ke yi le ba

/**
 * @copyright
 * ====================================================================
 * Copyright (c) 2000-2004 CollabNet.  All rights reserved.
 *
 * This software is licensed as described in the file COPYING, which
 * you should have received as part of this distribution.  The terms
 * are also available at http://subversion.tigris.org/license-1.html.
 * If newer versions of this license are posted there, you may use a
 * newer version instead, at your option.
 *
 * This software consists of voluntary contributions made by many
 * individuals.  For exact contribution history, see the revision
 * history and logs, available at http://subversion.tigris.org/.
 * ====================================================================
 * @endcopyright
 *
 * @file svn_path.h
 * @brief A path manipulation library
 *
 * All incoming and outgoing paths are non-null and in UTF-8, unless
 * otherwise documented.
 * 
 * No result path ever ends with a separator, no matter whether the
 * path is a file or directory, because we always canonicalize() it.
 *
 * All paths passed to the @c svn_path_xxx functions, with the exceptions of
 * the @c svn_path_canonicalize and @c svn_path_internal_style functions, must
 * be in canonical form.
 *
 * todo: this library really needs a test suite!
 */

#ifndef SVN_PATH_H
#define SVN_PATH_H


#include <apr_pools.h>
#include <apr_tables.h>

#include "svn_string.h"
#include "svn_error.h"


#ifdef __cplusplus
extern "C" {
#endif /* __cplusplus */



/** Convert @a path from the local style to the canonical internal style. */
const char *svn_path_internal_style (const char *path, apr_pool_t *pool);

/** Convert @a path from the canonical internal style to the local style. */
const char *svn_path_local_style (const char *path, apr_pool_t *pool);


/** Join a base path (@a base) with a component (@a component), allocated in 
 * @a pool.
 *
 * If either @a base or @a component is the empty path, then the other 
 * argument will be copied and returned.  If both are the empty path the 
 * empty path is returned.
 *
 * If the @a component is an absolute path, then it is copied and returned.
 * Exactly one slash character ('/') is used to joined the components,
 * accounting for any trailing slash in @a base.
 *
 * Note that the contents of @a base are not examined, so it is possible to
 * use this function for constructing URLs, or for relative URLs or
 * repository paths.
 *
 * This function is NOT appropriate for native (local) file
 * paths. Only for "internal" canonicalized paths, since it uses '/'
 * for the separator. Further, an absolute path (for @a component) is
 * based on a leading '/' character.  Thus, an "absolute URI" for the
 * @a component won't be detected. An absolute URI can only be used
 * for the base.
 */
char *svn_path_join (const char *base,
                     const char *component,
                     apr_pool_t *pool);

/** Join multiple components onto a @a base path, allocated in @a pool. The
 * components are terminated by a @c NULL.
 *
 * If any component is the empty string, it will be ignored.
 *
 * If any component is an absolute path, then it resets the base and
 * further components will be appended to it.
 *
 * See @c svn_path_join() for further notes about joining paths.
 */
char *svn_path_join_many (apr_pool_t *pool, const char *base, ...);


/** Get the basename of the specified canonicalized @a path.  The
 * basename is defined as the last component of the path (ignoring any
 * trailing slashes).  If the @a path is root ("/"), then that is
 * returned.  Otherwise, the returned value will have no slashes in
 * it.
 *
 * Example: svn_path_basename("/foo/bar") -> "bar"
 *
 * The returned basename will be allocated in @a pool.
 *
 * Note: if an empty string is passed, then an empty string will be returned.
 */
char *svn_path_basename (const char *path, apr_pool_t *pool);

/** Get the dirname of the specified canonicalized @a path, defined as
 * the path with its basename removed.
 *
 * Get the dirname of the specified @a path, defined as the path with its
 * basename removed.  If @a path is root ("/"), it is returned unchanged.
 *
 * The returned dirname will be allocated in @a pool.
 */
char *svn_path_dirname (const char *path, apr_pool_t *pool);

/** Return the number of components in the canonicalized @a path. */
apr_size_t
svn_path_component_count (const char *path);

/** Add a @a component (a null-terminated C-string) to the
 * canonicalized @a path.  @a component is allowed to contain
 * directory separators.
 *
 * If @a path is non-empty, append the appropriate directory separator
 * character, and then @a component.  If @a path is empty, simply set it to
 * @a component; don't add any separator character.
 *
 * If the result ends in a separator character, then remove the separator.
 */
void svn_path_add_component (svn_stringbuf_t *path, 
                             const char *component);

/** Remove one component off the end of the canonicalized @a path. */
void svn_path_remove_component (svn_stringbuf_t *path);

/** Remove @a n components off the end of the canonizalized @a path.
 * Equivalent to calling @c svn_remove_component @a n times. */
void svn_path_remove_components (svn_stringbuf_t *path, apr_size_t n);

/** Divide the canonicalized @a path into @a *dirpath and @a
 * *base_name, allocated in @a pool.
 *
 * If @a dirpath or @a base_name is null, then don't set that one.
 *
 * Either @a dirpath or @a base_name may be @a path's own address, but they 
 * may not both be the same address, or the results are undefined.
 *
 * If @a path has two or more components, the separator between @a dirpath
 * and @a base_name is not included in either of the new names.
 *
 *   examples:
 *             - <pre>"/foo/bar/baz"  ==>  "/foo/bar" and "baz"</pre>
 *             - <pre>"/bar"          ==>  "/"  and "bar"</pre>
 *             - <pre>"/"             ==>  "/"  and "/"</pre>
 *             - <pre>"bar"           ==>  ""   and "bar"</pre>
 *             - <pre>""              ==>  ""   and ""</pre>
 */
void svn_path_split (const char *path, 
                     const char **dirpath,
                     const char **base_name,
                     apr_pool_t *pool);


/** Return non-zero iff @a path is empty ("") or represents the current
 * directory -- that is, if prepending it as a component to an existing
 * path would result in no meaningful change.
 */
int svn_path_is_empty (const char *path);


/** Return a new path (or URL) like @a path, but transformed such that
 * some types of path specification redundancies are removed.
 *
 * This involves collapsing redundant "/./" and "/../" elements,
 * removing multiple adjacent separator characters, removing trailing
 * separator characters, and possibly other semantically inoperative
 * transformations.
 *
 * The returned path may be statically allocated, equal to @a path, or
 * allocated from @a pool.
 */
const char *svn_path_canonicalize (const char *path, apr_pool_t *pool);


/** Return an integer greater than, equal to, or less than 0, according
 * as @a path1 is greater than, equal to, or less than @a path2.
 */
int svn_path_compare_paths (const char *path1, const char *path2);


/** Return the longest common path shared by two canonicalized paths,
 * @a path1 and @a path2.  If there's no common ancestor, return the
 * empty path.
 *
 * @a path1 and @a path2 may be URLs.  In order for two URLs to have 
 * a common ancestor, they must (a) have the same protocol (since two URLs 
 * with the same path but different protocols may point at completely 
 * different resources), and (b) share a common ancestor in their path 
 * component, i.e. 'protocol://' is not a sufficient ancestor.
 */
char *svn_path_get_longest_ancestor (const char *path1,
                                     const char *path2,
                                     apr_pool_t *pool);

/** Convert @a relative canonicalized path to an absolute path and
 * return the results in @a *pabsolute, allocated in @a pool.
 *
 * @a relative may be a URL, in which case no attempt is made to convert it, 
 * and a copy of the URL is returned. 
 */
svn_error_t *
svn_path_get_absolute (const char **pabsolute,