subversion/include/svn_path.h

24  * @brief A path manipulation library
29  * No result path ever ends with a separator, no matter whether the
30  * path is a file or directory, because we always canonicalize() it.
33  * them to be in canonical form as defined by the Subversion path
67 /** Convert @a path from the local style to the canonical internal style.
74 svn_path_internal_style(const char *path, apr_pool_t *pool);
76 /** Convert @a path from the canonical internal style to the local style.
83 svn_path_local_style(const char *path, apr_pool_t *pool);
86 /** Join a base path (@a base) with a component (@a component), allocating
88  * can be any path, absolute or relative to @a base.
90  * If either @a base or @a component is the empty path, then the other
91  * argument will be copied and returned.  If both are the empty path the
92  * empty path is returned.
94  * If the @a component is an absolute path, then it is copied and returned.
104  * for the separator. Further, an absolute path (for @a component) is
117 /** Join multiple components onto a @a base path, allocated in @a pool. The
122  * If any component is an absolute path, then it resets the base and
140 /** Get the basename of the specified canonicalized @a path.  The
141  * basename is defined as the last component of the path (ignoring any
142  * trailing slashes).  If the @a path is root ("/"), then that is
158 svn_path_basename(const char *path, apr_pool_t *pool);
160 /** Get the dirname of the specified canonicalized @a path, defined as
161  * the path with its basename removed.  If @a path is root ("/"), it is
172 svn_path_dirname(const char *path, apr_pool_t *pool);
174 /** Split @a path into a root portion and an extension such that
175  * the root + the extension = the original path, and where the
185                   const char *path, apr_pool_t *pool);
187 /** Return the number of components in the canonicalized @a path.
192 svn_path_component_count(const char *path);
195  * canonicalized @a path.  @a component is allowed to contain
198  * If @a path is non-empty, append the appropriate directory separator
199  * character, and then @a component.  If @a path is empty, simply set it to
205 svn_path_add_component(svn_stringbuf_t *path, const char *component);
207 /** Remove one component off the end of the canonicalized @a path. */
209 svn_path_remove_component(svn_stringbuf_t *path);
211 /** Remove @a n components off the end of the canonicalized @a path.
217 svn_path_remove_components(svn_stringbuf_t *path, apr_size_t n);
219 /** Divide the canonicalized @a path into @a *dirpath and @a
224  * Either @a dirpath or @a base_name may be @a path's own address, but they
227  * If @a path has two or more components, the separator between @a dirpath
244 svn_path_split(const char *path,
250 /** Return non-zero iff @a path is empty ("") or represents the current
252  * path would result in no meaningful change.
255 svn_path_is_empty(const char *path);
266 /** Return a new path (or URL) like @a path, but transformed such that
267  * some types of path specification redundancies are removed.
276  * The returned path may be statically allocated, equal to @a path, or
285 svn_path_canonicalize(const char *path, apr_pool_t *pool);
287 /** Return @c TRUE iff path is canonical. Use @a pool for temporary
297 svn_path_is_canonical(const char *path, apr_pool_t *pool);
311 /** Return the longest common path shared by two canonicalized paths,
313  * empty path.
317  * with the same path but different protocols may point at completely
318  * different resources), and (b) share a common ancestor in their path
332 /** Convert @a relative canonicalized path to an absolute path and
347 /** Return the path part of the canonicalized @a path in @a
348  * *pdirectory, and the file part in @a *pfile.  If @a path is a
349  * directory, set @a *pdirectory to @a path, and @a *pfile to the
350  * empty string.  If @a path does not exist it is treated as if it is
359 svn_path_split_if_file(const char *path,
368  *   - Set @a *pcommon to the absolute path of the path or URL common to
376  *     descendants of another path/URL in @a targets.  If *pcommon
439  *     path" common to all the targets.  Updates don't require a
440  *     "grandfather path" at all, and even if it did, the whole
441  *     conversion to an absolute path drops the crucial difference
451 /** Decompose the canonicalized @a path into an array of <tt>const
452  * char *</tt> components, allocated in @a pool.  If @a path is
457 svn_path_decompose(const char *path, apr_pool_t *pool);
460  * separated path, allocated in @a pool.  The joined path is absolute if
464  * will return the exact same path.
471 /** Test that @a name is a single path component, that is:
473  *   - not a `/'-separated directory path
481  * Test to see if a backpath, i.e. '..', is present in @a path.
488 svn_path_is_backpath_present(const char *path);
492  * Test to see if a dotpath, i.e. '.', is present in @a path.
499 svn_path_is_dotpath_present(const char *path);
504  * If so, return a copy of the remainder path, allocated in @a pool.
516  *       identify the remainder path.
541  * Check whether @a path is a valid Subversion path.
548  * ASSUMPTION: @a path is a valid UTF-8 string.  This function does
560 svn_path_check_valid(const char *path, apr_pool_t *pool);
570 /** Return TRUE iff @a path looks like a valid absolute URL. */
572 svn_path_is_url(const char *path);
574 /** Return @c TRUE iff @a path is URI-safe, @c FALSE otherwise. */
576 svn_path_is_uri_safe(const char *path);
578 /** Return a URI-encoded copy of @a path, allocated in @a pool.  (@a
579     path can be an arbitrary UTF-8 string and does not have to be a
580     canonical path.) */
582 svn_path_uri_encode(const char *path, apr_pool_t *pool);
584 /** Return a URI-decoded copy of @a path, allocated in @a pool. */
586 svn_path_uri_decode(const char *path, apr_pool_t *pool);
593  * @a component need not be a single path segment, but if it contains
605  *       "replace the path entirely
606  *        https://example.com:4444/base/path joined with /leading/slash,
620 /** Like svn_path_url_add_component2(), but allows path components that
686  * Return @c TRUE iff @a path is a repository-relative URL:  specifically
689  * @a path is in UTF-8 encoding.
691  * Does not check whether @a path is a properly URI-encoded, canonical, or
697 svn_path_is_repos_relative_url(const char *path);
724 /** Return a copy of @a path, allocated from @a pool, for which control
730 svn_path_illegal_path_escape(const char *path, apr_pool_t *pool);