A path manipulation library. More...

#include <apr.h>
#include <apr_pools.h>
#include <apr_tables.h>
#include "svn_types.h"
#include "svn_string.h"

Functions
const char *	svn_path_internal_style (const char path, apr_pool_t pool)
	Convert path from the local style to the canonical internal style.
const char *	svn_path_local_style (const char path, apr_pool_t pool)
	Convert path from the canonical internal style to the local style.
char *	svn_path_join (const char base, const char component, apr_pool_t *pool)
	Join a base path (base) with a component (component), allocating the result in pool.
char *	svn_path_join_many (apr_pool_t pool, const char base,...)
	Join multiple components onto a base path, allocated in pool.
char *	svn_path_basename (const char path, apr_pool_t pool)
	Get the basename of the specified canonicalized path.
char *	svn_path_dirname (const char path, apr_pool_t pool)
	Get the dirname of the specified canonicalized path, defined as the path with its basename removed.
void	svn_path_splitext (const char path_root, const char path_ext, const char path, apr_pool_t pool)
	Split path into a root portion and an extension such that the root + the extension = the original path, and where the extension contains no period (.) characters.
apr_size_t	svn_path_component_count (const char *path)
	Return the number of components in the canonicalized path.
void	svn_path_add_component (svn_stringbuf_t path, const char component)
	Add a component (a NULL-terminated C-string) to the canonicalized path.
void	svn_path_remove_component (svn_stringbuf_t *path)
	Remove one component off the end of the canonicalized path.
void	svn_path_remove_components (svn_stringbuf_t *path, apr_size_t n)
	Remove n components off the end of the canonicalized path.
void	svn_path_split (const char path, const char dirpath, const char base_name, apr_pool_t pool)
	Divide the canonicalized path into dirpath and base_name, allocated in pool.
int	svn_path_is_empty (const char *path)
	Return non-zero iff 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.
svn_boolean_t	svn_dirent_is_root (const char *dirent, apr_size_t len)
const char *	svn_path_canonicalize (const char path, apr_pool_t pool)
	Return a new path (or URL) like path, but transformed such that some types of path specification redundancies are removed.
svn_boolean_t	svn_path_is_canonical (const char path, apr_pool_t pool)
	Return `TRUE` iff path is canonical.
int	svn_path_compare_paths (const char path1, const char path2)
	Return an integer greater than, equal to, or less than 0, according as path1 is greater than, equal to, or less than path2.
char *	svn_path_get_longest_ancestor (const char path1, const char path2, apr_pool_t *pool)
	Return the longest common path shared by two canonicalized paths, path1 and path2.
svn_error_t *	svn_path_get_absolute (const char *pabsolute, const char relative, apr_pool_t *pool)
	Convert relative canonicalized path to an absolute path and return the results in pabsolute, allocated in pool*.
svn_error_t *	svn_path_split_if_file (const char path, const char pdirectory, const char pfile, apr_pool_t pool)
	Return the path part of the canonicalized path in pdirectory, and the file part in pfile.
svn_error_t *	svn_path_condense_targets (const char pcommon, apr_array_header_t pcondensed_targets, const apr_array_header_t targets, svn_boolean_t remove_redundancies, apr_pool_t pool)
	Find the common prefix of the canonicalized paths in targets (an array of `const char `'s), and remove redundant paths if remove_redundancies* is TRUE.
svn_error_t *	svn_path_remove_redundancies (apr_array_header_t *pcondensed_targets, const apr_array_header_t targets, apr_pool_t *pool)
	Copy a list of canonicalized targets, one at a time, into pcondensed_targets, omitting any targets that are found earlier in the list, or whose ancestor is found earlier in the list.
apr_array_header_t *	svn_path_decompose (const char path, apr_pool_t pool)
	Decompose the canonicalized path into an array of `const char ` components, allocated in pool*.
const char *	svn_path_compose (const apr_array_header_t components, apr_pool_t pool)
	Join an array of `const char ` components into a '/' separated path, allocated in pool*.
svn_boolean_t	svn_path_is_single_path_component (const char *name)
	Test that name is a single path component, that is: not `NULL` or empty.
svn_boolean_t	svn_path_is_backpath_present (const char *path)
	Test to see if a backpath, i.e.
svn_boolean_t	svn_path_is_dotpath_present (const char *path)
	Test to see if a dotpath, i.e.
const char *	svn_path_is_child (const char path1, const char path2, apr_pool_t *pool)
	Test if path2 is a child of path1.
svn_boolean_t	svn_path_is_ancestor (const char path1, const char path2)
	Return TRUE if path1 is an ancestor of path2 or the paths are equal and FALSE otherwise.
svn_error_t *	svn_path_check_valid (const char path, apr_pool_t pool)
	Check whether path is a valid Subversion path.
svn_boolean_t	svn_path_is_url (const char *path)
	Return TRUE iff path looks like a valid absolute URL.
svn_boolean_t	svn_path_is_uri_safe (const char *path)
	Return `TRUE` iff path is URI-safe, `FALSE` otherwise.
const char *	svn_path_uri_encode (const char path, apr_pool_t pool)
	Return a URI-encoded copy of path, allocated in pool.
const char *	svn_path_uri_decode (const char path, apr_pool_t pool)
	Return a URI-decoded copy of path, allocated in pool.
const char *	svn_path_url_add_component2 (const char url, const char component, apr_pool_t *pool)
	Extend url by component, URI-encoding that component before adding it to the url; return the new url, allocated in pool.
const char *	svn_path_url_add_component (const char url, const char component, apr_pool_t *pool)
	Like svn_path_url_add_component2, but allows path components that end with a trailing '/'.
const char *	svn_path_uri_from_iri (const char iri, apr_pool_t pool)
	Convert iri (Internationalized URI) to an URI.
const char *	svn_path_uri_autoescape (const char uri, apr_pool_t pool)
	URI-encode certain characters in uri that are not valid in an URI, but doesn't have any special meaning in uri at their positions.
svn_error_t *	svn_path_cstring_from_utf8 (const char *path_apr, const char path_utf8, apr_pool_t *pool)
	Convert path_utf8 from UTF-8 to the internal encoding used by APR.
svn_error_t *	svn_path_cstring_to_utf8 (const char *path_utf8, const char path_apr, apr_pool_t *pool)
	Convert path_apr from the internal encoding used by APR to UTF-8.

Detailed Description

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.

Nearly all the svn_path_xxx functions expect paths passed into them to be in canonical form as defined by the Subversion path library itself. The only functions which do *not* have such expectations are:

For the most part, we mean what most anyone would mean when talking about canonical paths, but to be on the safe side, you must run your paths through svn_path_canonicalize() before passing them to other functions in this API.

Definition in file svn_path.h.

Function Documentation

void svn_path_add_component	(	svn_stringbuf_t *	path,
		const char *	component
	)

Add a component (a NULL-terminated C-string) to the canonicalized path.

component is allowed to contain directory separators.

If path is non-empty, append the appropriate directory separator character, and then component. If path is empty, simply set it to component; don't add any separator character.

If the result ends in a separator character, then remove the separator.

char* svn_path_basename	(	const char *	path,
		apr_pool_t *	pool
	)

Get the basename of the specified canonicalized path.

The basename is defined as the last component of the path (ignoring any trailing slashes). If the 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 pool.

Note:: If an empty string is passed, then an empty string will be returned.

const char* svn_path_canonicalize	(	const char *	path,
		apr_pool_t *	pool
	)

Return a new path (or URL) like path, but transformed such that some types of path specification redundancies are removed.

This involves collapsing redundant "/./" elements, removing multiple adjacent separator characters, removing trailing separator characters, and possibly other semantically inoperative transformations.

Convert the scheme and hostname to lowercase (see issue #2475)

The returned path may be statically allocated, equal to path, or allocated from pool.

svn_error_t* svn_path_check_valid	(	const char *	path,
		apr_pool_t *	pool
	)

Check whether path is a valid Subversion path.

A valid Subversion pathname is a UTF-8 string without control characters. "Valid" means Subversion can store the pathname in a repository. There may be other, OS-specific, limitations on what paths can be represented in a working copy.

ASSUMPTION: path is a valid UTF-8 string. This function does not check UTF-8 validity.

Return SVN_NO_ERROR if valid and SVN_ERR_FS_PATH_SYNTAX if invalid.

Note:: Despite returning an SVN_ERR_FS_* error, this function has nothing to do with the versioned filesystem's concept of validity.

Since:: New in 1.2.

apr_size_t svn_path_component_count ( const char * path )

Return the number of components in the canonicalized path.

Since:: New in 1.1.

const char* svn_path_compose	(	const apr_array_header_t *	components,
		apr_pool_t *	pool
	)

Join an array of const char * components into a '/' separated path, allocated in pool.

The joined path is absolute if the first component is a lone dir separator.

Calling svn_path_compose() on the output of svn_path_decompose() will return the exact same path.

Since:: New in 1.5.

svn_error_t* svn_path_condense_targets	(	const char **	pcommon,
		apr_array_header_t **	pcondensed_targets,
		const apr_array_header_t *	targets,
		svn_boolean_t	remove_redundancies,
		apr_pool_t *	pool
	)

Find the common prefix of the canonicalized paths in targets (an array of const char *'s), and remove redundant paths if remove_redundancies is TRUE.

Set *pcommon to the absolute path of the path or URL common to all of the targets. If the targets have no common prefix, or are a mix of URLs and local paths, set *pcommon to the empty string.

If pcondensed_targets is non-NULL, set *pcondensed_targets to an array of targets relative to *pcommon, and if remove_redundancies is TRUE, omit any paths/URLs that are descendants of another path/URL in targets. If *pcommon is empty, *pcondensed_targets will contain full URLs and/or absolute paths; redundancies can still be removed (from both URLs and paths). If pcondensed_targets is NULL, leave it alone.

Else if there is exactly one target, then

Set *pcommon to that target, and

If pcondensed_targets is non-NULL, set *pcondensed_targets to an array containing zero elements. Else if pcondensed_targets is NULL, leave it alone.

If there are no items in targets, set *pcommon and (if applicable) *pcondensed_targets to NULL.

Note:: There is no guarantee that *pcommon is within a working copy.

apr_array_header_t* svn_path_decompose	(	const char *	path,
		apr_pool_t *	pool
	)

Decompose the canonicalized path into an array of const char * components, allocated in pool.

If path is absolute, the first component will be a lone dir separator (the root directory).

char* svn_path_dirname	(	const char *	path,
		apr_pool_t *	pool
	)

Get the dirname of the specified canonicalized path, defined as the path with its basename removed.

If path is root ("/"), it is returned unchanged.

The returned dirname will be allocated in pool.

svn_error_t* svn_path_get_absolute	(	const char **	pabsolute,
		const char *	relative,
		apr_pool_t *	pool
	)

Convert relative canonicalized path to an absolute path and return the results in *pabsolute, allocated in pool.

relative may be a URL, in which case no attempt is made to convert it, and a copy of the URL is returned.

char* svn_path_get_longest_ancestor	(	const char *	path1,
		const char *	path2,
		apr_pool_t *	pool
	)

Return the longest common path shared by two canonicalized paths, path1 and path2.

If there's no common ancestor, return the empty path.

path1 and 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.

const char* svn_path_internal_style	(	const char *	path,
		apr_pool_t *	pool
	)

Convert path from the local style to the canonical internal style.

svn_boolean_t svn_path_is_ancestor	(	const char *	path1,
		const char *	path2
	)

Return TRUE if path1 is an ancestor of path2 or the paths are equal and FALSE otherwise.

Since:: New in 1.3.

svn_boolean_t svn_path_is_backpath_present ( const char * path )

Test to see if a backpath, i.e.

'..', is present in path. If not, return FALSE. If so, return TRUE.

Since:: New in 1.1.

svn_boolean_t svn_path_is_canonical	(	const char *	path,
		apr_pool_t *	pool
	)

Return TRUE iff path is canonical.

Use pool for temporary allocations.

Since:: New in 1.5.

const char* svn_path_is_child	(	const char *	path1,
		const char *	path2,
		apr_pool_t *	pool
	)

Test if path2 is a child of path1.

If not, return NULL. If so, return a copy of the remainder path, allocated in pool. (The remainder is the component which, added to path1, yields path2. The remainder does not begin with a dir separator.)

Both paths must be in canonical form, and must either be absolute, or contain no ".." components.

If path2 is the same as path1, it is not considered a child, so the result is NULL; an empty string is never returned.

Note:: In 1.5 this function has been extended to allow a NULL pool in which case a pointer into path2 will be returned to identify the remainder path.

###

Todo:: the ".." restriction is unfortunate, and would ideally be lifted by making the implementation smarter. But this is not trivial: if the path is "../foo", how do you know whether or not the current directory is named "foo" in its parent?

svn_boolean_t svn_path_is_dotpath_present ( const char * path )

Test to see if a dotpath, i.e.

'.', is present in path. If not, return FALSE. If so, return TRUE.

Since:: New in 1.6.

svn_boolean_t svn_path_is_single_path_component ( const char * name )

Test that name is a single path component, that is:

not NULL or empty.

not a `/'-separated directory path
not empty or `..'

char* svn_path_join	(	const char *	base,
		const char *	component,
		apr_pool_t *	pool
	)

Join a base path (base) with a component (component), allocating the result in pool.

component need not be a single component: it can be any path, absolute or relative to base.

If either base or 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 component is an absolute path, then it is copied and returned. Exactly one slash character ('/') is used to join the components, accounting for any trailing slash in base.

Note that the contents of 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 component) is based on a leading '/' character. Thus, an "absolute URI" for the component won't be detected. An absolute URI can only be used for the base.

char* svn_path_join_many	(	apr_pool_t *	pool,
		const char *	base,
			...
	)

Join multiple components onto a base path, allocated in pool.

The components are terminated by a 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.

This function does not support URLs.

See svn_path_join() for further notes about joining paths.

const char* svn_path_local_style	(	const char *	path,
		apr_pool_t *	pool
	)

Convert path from the canonical internal style to the local style.

void svn_path_remove_component ( svn_stringbuf_t * path )

Remove one component off the end of the canonicalized path.

void svn_path_remove_components	(	svn_stringbuf_t *	path,
		apr_size_t	n
	)

Remove n components off the end of the canonicalized path.

Equivalent to calling svn_path_remove_component() n times.

Since:: New in 1.1.

svn_error_t* svn_path_remove_redundancies	(	apr_array_header_t **	pcondensed_targets,
		const apr_array_header_t *	targets,
		apr_pool_t *	pool
	)

Copy a list of canonicalized targets, one at a time, into pcondensed_targets, omitting any targets that are found earlier in the list, or whose ancestor is found earlier in the list.

Ordering of targets in the original list is preserved in the condensed list of targets. Use pool for any allocations.

How does this differ in functionality from svn_path_condense_targets()?

Here's the short version:

1. Disclaimer: if you wish to debate the following, talk to Karl. :-) Order matters for updates because a multi-arg update is not atomic, and CVS users are used to, when doing 'cvs up targetA targetB' seeing targetA get updated, then targetB. I think the idea is that if you're in a time-sensitive or flaky-network situation, a user can say, "I really *need* to update wc/A/D/G/tau, but I might as well update my whole working copy if I can." So that user will do 'svn up wc/A/D/G/tau wc', and if something dies in the middles of the 'wc' update, at least the user has 'tau' up-to-date.

2. Also, we have this notion of an anchor and a target for updates (the anchor is where the update editor is rooted, the target is the actual thing we want to update). I needed a function that would NOT screw with my input paths so that I could tell the difference between someone being in A/D and saying 'svn up G' and being in A/D/G and saying 'svn up .' -- believe it or not, these two things don't mean the same thing. svn_path_condense_targets() plays with absolute paths (which is fine, so does svn_path_remove_redundancies()), but the difference is that it actually tweaks those targets to be relative to the "grandfather path" common to all the targets. Updates don't require a "grandfather path" at all, and even if it did, the whole conversion to an absolute path drops the crucial difference between saying "i'm in foo, update bar" and "i'm in foo/bar, update '.'"

void svn_path_split	(	const char *	path,
		const char **	dirpath,
		const char **	base_name,
		apr_pool_t *	pool
	)

Divide the canonicalized path into *dirpath and *base_name, allocated in pool.

If dirpath or base_name is NULL, then don't set that one.

Either dirpath or base_name may be path's own address, but they may not both be the same address, or the results are undefined.

If path has two or more components, the separator between dirpath and base_name is not included in either of the new names.

examples:

"/foo/bar/baz"  ==>  "/foo/bar" and "baz"

```
"/bar"          ==>  "/"  and "bar"
```
```
"/"             ==>  "/"  and "/"
```
```
"X:/"           ==>  "X:/" and "X:/"
```
```
"bar"           ==>  ""   and "bar"
```
```
""              ==>  ""   and ""
```

svn_error_t* svn_path_split_if_file	(	const char *	path,
		const char **	pdirectory,
		const char **	pfile,
		apr_pool_t *	pool
	)

Return the path part of the canonicalized path in *pdirectory, and the file part in *pfile.

If path is a directory, set *pdirectory to path, and *pfile to the empty string. If path does not exist it is treated as if it is a file, since directories do not normally vanish.

void svn_path_splitext	(	const char **	path_root,
		const char **	path_ext,
		const char *	path,
		apr_pool_t *	pool
	)

Split path into a root portion and an extension such that the root + the extension = the original path, and where the extension contains no period (.) characters.

If not NULL, set *path_root to the root portion. If not NULL, set *path_ext to the extension (or "" if there is no extension found). Allocate both *path_root and *path_ext in pool.

Since:: New in 1.5.

svn_path.h File Reference

Functions

Detailed Description

Function Documentation