contrib/subversion/subversion/include/svn_path.h

   1 /**
   2  * @copyright
   3  * ====================================================================
   4  *    Licensed to the Apache Software Foundation (ASF) under one
   5  *    or more contributor license agreements.  See the NOTICE file
   6  *    distributed with this work for additional information
   7  *    regarding copyright ownership.  The ASF licenses this file
   8  *    to you under the Apache License, Version 2.0 (the
   9  *    "License"); you may not use this file except in compliance
  10  *    with the License.  You may obtain a copy of the License at
  11  *
  12  *      http://www.apache.org/licenses/LICENSE-2.0
  13  *
  14  *    Unless required by applicable law or agreed to in writing,
  15  *    software distributed under the License is distributed on an
  16  *    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  17  *    KIND, either express or implied.  See the License for the
  18  *    specific language governing permissions and limitations
  19  *    under the License.
  20  * ====================================================================
  21  * @endcopyright
  22  *
  23  * @file svn_path.h
  24  * @brief A path manipulation library
  25  *
  26  * All incoming and outgoing paths are non-NULL and in UTF-8, unless
  27  * otherwise documented.
  28  *
  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.
  31  *
  32  * Nearly all the @c svn_path_xxx functions expect paths passed into
  33  * them to be in canonical form as defined by the Subversion path
  34  * library itself.  The only functions which do *not* have such
  35  * expectations are:
  36  *
  37  *    - @c svn_path_canonicalize()
  38  *    - @c svn_path_is_canonical()
  39  *    - @c svn_path_internal_style()
  40  *    - @c svn_path_uri_encode()
  41  *
  42  * For the most part, we mean what most anyone would mean when talking
  43  * about canonical paths, but to be on the safe side, you must run
  44  * your paths through @c svn_path_canonicalize() before passing them to
  45  * other functions in this API.
  46  */
  47
  48 #ifndef SVN_PATH_H
  49 #define SVN_PATH_H
  50
  51 #include <apr.h>
  52 #include <apr_pools.h>
  53 #include <apr_tables.h>
  54
  55 #include "svn_types.h"
  56 #include "svn_string.h"
  57 #include "svn_dirent_uri.h"
  58
  59
  60 #ifdef __cplusplus
  61 extern "C" {
  62 #endif /* __cplusplus */
  63
  64 \f
  65
  66 /** Convert @a path from the local style to the canonical internal style.
  67  *
  68  * @deprecated Provided for backward compatibility with the 1.6 API.
  69  * New code should use svn_dirent_internal_style().
  70  */
  71 SVN_DEPRECATED
  72 const char *
  73 svn_path_internal_style(const char *path, apr_pool_t *pool);
  74
  75 /** Convert @a path from the canonical internal style to the local style.
  76  *
  77  * @deprecated Provided for backward compatibility with the 1.6 API.
  78  * New code should use svn_dirent_local_style().
  79  */
  80 SVN_DEPRECATED
  81 const char *
  82 svn_path_local_style(const char *path, apr_pool_t *pool);
  83
  84
  85 /** Join a base path (@a base) with a component (@a component), allocating
  86  * the result in @a pool. @a component need not be a single component: it
  87  * can be any path, absolute or relative to @a base.
  88  *
  89  * If either @a base or @a component is the empty path, then the other
  90  * argument will be copied and returned.  If both are the empty path the
  91  * empty path is returned.
  92  *
  93  * If the @a component is an absolute path, then it is copied and returned.
  94  * Exactly one slash character ('/') is used to join the components,
  95  * accounting for any trailing slash in @a base.
  96  *
  97  * Note that the contents of @a base are not examined, so it is possible to
  98  * use this function for constructing URLs, or for relative URLs or
  99  * repository paths.
 100  *
 101  * This function is NOT appropriate for native (local) file
 102  * paths. Only for "internal" canonicalized paths, since it uses '/'
 103  * for the separator. Further, an absolute path (for @a component) is
 104  * based on a leading '/' character.  Thus, an "absolute URI" for the
 105  * @a component won't be detected. An absolute URI can only be used
 106  * for the base.
 107  *
 108  * @deprecated Provided for backward compatibility with the 1.6 API.
 109  * New code should use svn_dirent_join(), svn_relpath_join() or
 110  * svn_fspath__join().
 111  */
 112 SVN_DEPRECATED
 113 char *
 114 svn_path_join(const char *base, const char *component, apr_pool_t *pool);
 115
 116 /** Join multiple components onto a @a base path, allocated in @a pool. The
 117  * components are terminated by a @c SVN_VA_NULL.
 118  *
 119  * If any component is the empty string, it will be ignored.
 120  *
 121  * If any component is an absolute path, then it resets the base and
 122  * further components will be appended to it.
 123  *
 124  * This function does not support URLs.
 125  *
 126  * See svn_path_join() for further notes about joining paths.
 127  *
 128  * @deprecated Provided for backward compatibility with the 1.6 API.
 129  * For new code, consider using svn_dirent_join_many() or a sequence of
 130  * calls to one of the *_join() functions.
 131  */
 132 SVN_DEPRECATED
 133 char *
 134 svn_path_join_many(apr_pool_t *pool,
 135                    const char *base,
 136                    ...) SVN_NEEDS_SENTINEL_NULL;
 137
 138
 139 /** Get the basename of the specified canonicalized @a path.  The
 140  * basename is defined as the last component of the path (ignoring any
 141  * trailing slashes).  If the @a path is root ("/"), then that is
 142  * returned.  Otherwise, the returned value will have no slashes in
 143  * it.
 144  *
 145  * Example: svn_path_basename("/foo/bar") -> "bar"
 146  *
 147  * The returned basename will be allocated in @a pool.
 148  *
 149  * @note If an empty string is passed, then an empty string will be returned.
 150  *
 151  * @deprecated Provided for backward compatibility with the 1.6 API.
 152  * New code should use svn_dirent_basename(), svn_uri_basename(),
 153  * svn_relpath_basename() or svn_fspath__basename().
 154  */
 155 SVN_DEPRECATED
 156 char *
 157 svn_path_basename(const char *path, apr_pool_t *pool);
 158
 159 /** Get the dirname of the specified canonicalized @a path, defined as
 160  * the path with its basename removed.  If @a path is root ("/"), it is
 161  * returned unchanged.
 162  *
 163  * The returned dirname will be allocated in @a pool.
 164  *
 165  * @deprecated Provided for backward compatibility with the 1.6 API.
 166  * New code should use svn_dirent_dirname(), svn_uri_dirname(),
 167  * svn_relpath_dirname() or svn_fspath__dirname().
 168  */
 169 SVN_DEPRECATED
 170 char *
 171 svn_path_dirname(const char *path, apr_pool_t *pool);
 172
 173 /** Split @a path into a root portion and an extension such that
 174  * the root + the extension = the original path, and where the
 175  * extension contains no period (.) characters.  If not @c NULL, set
 176  * @a *path_root to the root portion.  If not @c NULL, set
 177  * @a *path_ext to the extension (or "" if there is no extension
 178  * found).  Allocate both @a *path_root and @a *path_ext in @a pool.
 179  *
 180  * @since New in 1.5.
 181  */
 182 void
 183 svn_path_splitext(const char **path_root, const char **path_ext,
 184                   const char *path, apr_pool_t *pool);
 185
 186 /** Return the number of components in the canonicalized @a path.
 187  *
 188  * @since New in 1.1.
 189 */
 190 apr_size_t
 191 svn_path_component_count(const char *path);
 192
 193 /** Add a @a component (a NULL-terminated C-string) to the
 194  * canonicalized @a path.  @a component is allowed to contain
 195  * directory separators.
 196  *
 197  * If @a path is non-empty, append the appropriate directory separator
 198  * character, and then @a component.  If @a path is empty, simply set it to
 199  * @a component; don't add any separator character.
 200  *
 201  * If the result ends in a separator character, then remove the separator.
 202  */
 203 void
 204 svn_path_add_component(svn_stringbuf_t *path, const char *component);
 205
 206 /** Remove one component off the end of the canonicalized @a path. */
 207 void
 208 svn_path_remove_component(svn_stringbuf_t *path);
 209
 210 /** Remove @a n components off the end of the canonicalized @a path.
 211  * Equivalent to calling svn_path_remove_component() @a n times.
 212  *
 213  * @since New in 1.1.
 214  */
 215 void
 216 svn_path_remove_components(svn_stringbuf_t *path, apr_size_t n);
 217
 218 /** Divide the canonicalized @a path into @a *dirpath and @a
 219  * *base_name, allocated in @a pool.
 220  *
 221  * If @a dirpath or @a base_name is NULL, then don't set that one.
 222  *
 223  * Either @a dirpath or @a base_name may be @a path's own address, but they
 224  * may not both be the same address, or the results are undefined.
 225  *
 226  * If @a path has two or more components, the separator between @a dirpath
 227  * and @a base_name is not included in either of the new names.
 228  *
 229  *   examples:
 230  *             - <pre>"/foo/bar/baz"  ==>  "/foo/bar" and "baz"</pre>
 231  *             - <pre>"/bar"          ==>  "/"  and "bar"</pre>
 232  *             - <pre>"/"             ==>  "/"  and "/"</pre>
 233  *             - <pre>"X:/"           ==>  "X:/" and "X:/"</pre>
 234  *             - <pre>"bar"           ==>  ""   and "bar"</pre>
 235  *             - <pre>""              ==>  ""   and ""</pre>
 236  *
 237  * @deprecated Provided for backward compatibility with the 1.6 API.
 238  * New code should use svn_dirent_split(), svn_uri_split(),
 239  * svn_relpath_split() or svn_fspath__split().
 240  */
 241 SVN_DEPRECATED
 242 void
 243 svn_path_split(const char *path,
 244                const char **dirpath,
 245                const char **base_name,
 246                apr_pool_t *pool);
 247
 248
 249 /** Return non-zero iff @a path is empty ("") or represents the current
 250  * directory -- that is, if prepending it as a component to an existing
 251  * path would result in no meaningful change.
 252  */
 253 int
 254 svn_path_is_empty(const char *path);
 255
 256
 257 #ifndef SVN_DIRENT_URI_H
 258 /* This declaration has been moved to svn_dirent_uri.h, and remains
 259    here only for compatibility reasons. */
 260 svn_boolean_t
 261 svn_dirent_is_root(const char *dirent, apr_size_t len);
 262 #endif /* SVN_DIRENT_URI_H */
 263
 264
 265 /** Return a new path (or URL) like @a path, but transformed such that
 266  * some types of path specification redundancies are removed.
 267  *
 268  * This involves collapsing redundant "/./" elements, removing
 269  * multiple adjacent separator characters, removing trailing
 270  * separator characters, and possibly other semantically inoperative
 271  * transformations.
 272  *
 273  * Convert the scheme and hostname to lowercase (see issue #2475)
 274  *
 275  * The returned path may be statically allocated, equal to @a path, or
 276  * allocated from @a pool.
 277  *
 278  * @deprecated Provided for backward compatibility with the 1.6 API.
 279  * New code should use svn_dirent_canonicalize(), svn_uri_canonicalize(),
 280  * svn_relpath_canonicalize() or svn_fspath__canonicalize().
 281  */
 282 SVN_DEPRECATED
 283 const char *
 284 svn_path_canonicalize(const char *path, apr_pool_t *pool);
 285
 286 /** Return @c TRUE iff path is canonical. Use @a pool for temporary
 287  * allocations.
 288  *
 289  * @since New in 1.5.
 290  * @deprecated Provided for backward compatibility with the 1.6 API.
 291  * New code should use svn_dirent_is_canonical(), svn_uri_is_canonical(),
 292  * svn_relpath_is_canonical() or svn_fspath__is_canonical().
 293  */
 294 SVN_DEPRECATED
 295 svn_boolean_t
 296 svn_path_is_canonical(const char *path, apr_pool_t *pool);
 297
 298
 299 /** Return an integer greater than, equal to, or less than 0, according
 300  * as @a path1 is greater than, equal to, or less than @a path2.
 301  *
 302  * This function works like strcmp() except that it orders children in
 303  * subdirectories directly after their parents. This allows using the
 304  * given ordering for a depth first walk.
 305  */
 306 int
 307 svn_path_compare_paths(const char *path1, const char *path2);
 308
 309
 310 /** Return the longest common path shared by two canonicalized paths,
 311  * @a path1 and @a path2.  If there's no common ancestor, return the
 312  * empty path.
 313  *
 314  * @a path1 and @a path2 may be URLs.  In order for two URLs to have
 315  * a common ancestor, they must (a) have the same protocol (since two URLs
 316  * with the same path but different protocols may point at completely
 317  * different resources), and (b) share a common ancestor in their path
 318  * component, i.e. 'protocol://' is not a sufficient ancestor.
 319  *
 320  * @deprecated Provided for backward compatibility with the 1.6 API.
 321  * New code should use svn_dirent_get_longest_ancestor(),
 322  * svn_uri_get_longest_ancestor(), svn_relpath_get_longest_ancestor() or
 323  * svn_fspath__get_longest_ancestor().
 324  */
 325 SVN_DEPRECATED
 326 char *
 327 svn_path_get_longest_ancestor(const char *path1,
 328                               const char *path2,
 329                               apr_pool_t *pool);
 330
 331 /** Convert @a relative canonicalized path to an absolute path and
 332  * return the results in @a *pabsolute, allocated in @a pool.
 333  *
 334  * @a relative may be a URL, in which case no attempt is made to convert it,
 335  * and a copy of the URL is returned.
 336  *
 337  * @deprecated Provided for backward compatibility with the 1.6 API.
 338  * New code should use svn_dirent_get_absolute() on a non-URL input.
 339  */
 340 SVN_DEPRECATED
 341 svn_error_t *
 342 svn_path_get_absolute(const char **pabsolute,
 343                       const char *relative,
 344                       apr_pool_t *pool);
 345
 346 /** Return the path part of the canonicalized @a path in @a
 347  * *pdirectory, and the file part in @a *pfile.  If @a path is a
 348  * directory, set @a *pdirectory to @a path, and @a *pfile to the
 349  * empty string.  If @a path does not exist it is treated as if it is
 350  * a file, since directories do not normally vanish.
 351  *
 352  * @deprecated Provided for backward compatibility with the 1.6 API.
 353  * New code should implement the required logic directly; no direct
 354  * replacement is provided.
 355  */
 356 SVN_DEPRECATED
 357 svn_error_t *
 358 svn_path_split_if_file(const char *path,
 359                        const char **pdirectory,
 360                        const char **pfile,
 361                        apr_pool_t *pool);
 362
 363 /** Find the common prefix of the canonicalized paths in @a targets
 364  * (an array of <tt>const char *</tt>'s), and remove redundant paths if @a
 365  * remove_redundancies is TRUE.
 366  *
 367  *   - Set @a *pcommon to the absolute path of the path or URL common to
 368  *     all of the targets.  If the targets have no common prefix, or
 369  *     are a mix of URLs and local paths, set @a *pcommon to the
 370  *     empty string.
 371  *
 372  *   - If @a pcondensed_targets is non-NULL, set @a *pcondensed_targets
 373  *     to an array of targets relative to @a *pcommon, and if
 374  *     @a remove_redundancies is TRUE, omit any paths/URLs that are
 375  *     descendants of another path/URL in @a targets.  If *pcommon
 376  *     is empty, @a *pcondensed_targets will contain full URLs and/or
 377  *     absolute paths; redundancies can still be removed (from both URLs
 378  *     and paths).  If @a pcondensed_targets is NULL, leave it alone.
 379  *
 380  * Else if there is exactly one target, then
 381  *
 382  *   - Set @a *pcommon to that target, and
 383  *
 384  *   - If @a pcondensed_targets is non-NULL, set @a *pcondensed_targets
 385  *     to an array containing zero elements.  Else if
 386  *     @a pcondensed_targets is NULL, leave it alone.
 387  *
 388  * If there are no items in @a targets, set @a *pcommon and (if
 389  * applicable) @a *pcondensed_targets to @c NULL.
 390  *
 391  * @note There is no guarantee that @a *pcommon is within a working
 392  * copy.
 393  *
 394  * @deprecated Provided for backward compatibility with the 1.6 API.
 395  * New code should use svn_dirent_condense_targets() or
 396  * svn_uri_condense_targets().
 397  */
 398 SVN_DEPRECATED
 399 svn_error_t *
 400 svn_path_condense_targets(const char **pcommon,
 401                           apr_array_header_t **pcondensed_targets,
 402                           const apr_array_header_t *targets,
 403                           svn_boolean_t remove_redundancies,
 404                           apr_pool_t *pool);
 405
 406
 407 /** Copy a list of canonicalized @a targets, one at a time, into @a
 408  * pcondensed_targets, omitting any targets that are found earlier in
 409  * the list, or whose ancestor is found earlier in the list.  Ordering
 410  * of targets in the original list is preserved in the condensed list
 411  * of targets.  Use @a pool for any allocations.
 412  *
 413  * How does this differ in functionality from svn_path_condense_targets()?
 414  *
 415  * Here's the short version:
 416  *
 417  * 1.  Disclaimer: if you wish to debate the following, talk to Karl. :-)
 418  *     Order matters for updates because a multi-arg update is not
 419  *     atomic, and CVS users are used to, when doing 'cvs up targetA
 420  *     targetB' seeing targetA get updated, then targetB.  I think the
 421  *     idea is that if you're in a time-sensitive or flaky-network
 422  *     situation, a user can say, "I really *need* to update
 423  *     wc/A/D/G/tau, but I might as well update my whole working copy if
 424  *     I can."  So that user will do 'svn up wc/A/D/G/tau wc', and if
 425  *     something dies in the middles of the 'wc' update, at least the
 426  *     user has 'tau' up-to-date.
 427  *
 428  * 2.  Also, we have this notion of an anchor and a target for updates
 429  *     (the anchor is where the update editor is rooted, the target is
 430  *     the actual thing we want to update).  I needed a function that
 431  *     would NOT screw with my input paths so that I could tell the
 432  *     difference between someone being in A/D and saying 'svn up G' and
 433  *     being in A/D/G and saying 'svn up .' -- believe it or not, these
 434  *     two things don't mean the same thing.  svn_path_condense_targets()
 435  *     plays with absolute paths (which is fine, so does
 436  *     svn_path_remove_redundancies()), but the difference is that it
 437  *     actually tweaks those targets to be relative to the "grandfather
 438  *     path" common to all the targets.  Updates don't require a
 439  *     "grandfather path" at all, and even if it did, the whole
 440  *     conversion to an absolute path drops the crucial difference
 441  *     between saying "i'm in foo, update bar" and "i'm in foo/bar,
 442  *     update '.'"
 443  */
 444 svn_error_t *
 445 svn_path_remove_redundancies(apr_array_header_t **pcondensed_targets,
 446                              const apr_array_header_t *targets,
 447                              apr_pool_t *pool);
 448
 449
 450 /** Decompose the canonicalized @a path into an array of <tt>const
 451  * char *</tt> components, allocated in @a pool.  If @a path is
 452  * absolute, the first component will be a lone dir separator (the
 453  * root directory).
 454  */
 455 apr_array_header_t *
 456 svn_path_decompose(const char *path, apr_pool_t *pool);
 457
 458 /** Join an array of <tt>const char *</tt> components into a '/'
 459  * separated path, allocated in @a pool.  The joined path is absolute if
 460  * the first component is a lone dir separator.
 461  *
 462  * Calling svn_path_compose() on the output of svn_path_decompose()
 463  * will return the exact same path.
 464  *
 465  * @since New in 1.5.
 466  */
 467 const char *
 468 svn_path_compose(const apr_array_header_t *components, apr_pool_t *pool);
 469
 470 /** Test that @a name is a single path component, that is:
 471  *   - not @c NULL or empty.
 472  *   - not a `/'-separated directory path
 473  *   - not empty or `..'
 474  */
 475 svn_boolean_t
 476 svn_path_is_single_path_component(const char *name);
 477
 478
 479 /**
 480  * Test to see if a backpath, i.e. '..', is present in @a path.
 481  * If not, return @c FALSE.
 482  * If so, return @c TRUE.
 483  *
 484  * @since New in 1.1.
 485  */
 486 svn_boolean_t
 487 svn_path_is_backpath_present(const char *path);
 488
 489
 490 /**
 491  * Test to see if a dotpath, i.e. '.', is present in @a path.
 492  * If not, return @c FALSE.
 493  * If so, return @c TRUE.
 494  *
 495  * @since New in 1.6.
 496  */
 497 svn_boolean_t
 498 svn_path_is_dotpath_present(const char *path);
 499
 500
 501 /** Test if @a path2 is a child of @a path1.
 502  * If not, return @c NULL.
 503  * If so, return a copy of the remainder path, allocated in @a pool.
 504  * (The remainder is the component which, added to @a path1, yields
 505  * @a path2.  The remainder does not begin with a dir separator.)
 506  *
 507  * Both paths must be in canonical form, and must either be absolute,
 508  * or contain no ".." components.
 509  *
 510  * If @a path2 is the same as @a path1, it is not considered a child, so the
 511  * result is @c NULL; an empty string is never returned.
 512  *
 513  * @note In 1.5 this function has been extended to allow a @c NULL @a pool
 514  *       in which case a pointer into @a path2 will be returned to
 515  *       identify the remainder path.
 516  *
 517  * @deprecated Provided for backward compatibility with the 1.6 API.
 518  * For replacement functionality, see svn_dirent_skip_ancestor(),
 519  * svn_dirent_is_child(), svn_uri_skip_ancestor(), and
 520  * svn_relpath_skip_ancestor().
 521  */
 522 SVN_DEPRECATED
 523 const char *
 524 svn_path_is_child(const char *path1, const char *path2, apr_pool_t *pool);
 525
 526 /** Return TRUE if @a path1 is an ancestor of @a path2 or the paths are equal
 527  * and FALSE otherwise.
 528  *
 529  * @since New in 1.3.
 530  *
 531  * @deprecated Provided for backward compatibility with the 1.6 API.
 532  * For replacement functionality, see svn_dirent_skip_ancestor(),
 533  * svn_uri_skip_ancestor(), and svn_relpath_skip_ancestor().
 534  */
 535 SVN_DEPRECATED
 536 svn_boolean_t
 537 svn_path_is_ancestor(const char *path1, const char *path2);
 538
 539 /**
 540  * Check whether @a path is a valid Subversion path.
 541  *
 542  * A valid Subversion pathname is a UTF-8 string without control
 543  * characters.  "Valid" means Subversion can store the pathname in
 544  * a repository.  There may be other, OS-specific, limitations on
 545  * what paths can be represented in a working copy.
 546  *
 547  * ASSUMPTION: @a path is a valid UTF-8 string.  This function does
 548  * not check UTF-8 validity.
 549  *
 550  * Return @c SVN_NO_ERROR if valid and @c SVN_ERR_FS_PATH_SYNTAX if
 551  * invalid.
 552  *
 553  * @note Despite returning an @c SVN_ERR_FS_* error, this function has
 554  * nothing to do with the versioned filesystem's concept of validity.
 555  *
 556  * @since New in 1.2.
 557  */
 558 svn_error_t *
 559 svn_path_check_valid(const char *path, apr_pool_t *pool);
 560
 561 \f
 562 /** URI/URL stuff
 563  *
 564  * @defgroup svn_path_uri_stuff URI/URL conversion
 565  * @{
 566  */
 567
 568 /** Return TRUE iff @a path looks like a valid absolute URL. */
 569 svn_boolean_t
 570 svn_path_is_url(const char *path);
 571
 572 /** Return @c TRUE iff @a path is URI-safe, @c FALSE otherwise. */
 573 svn_boolean_t
 574 svn_path_is_uri_safe(const char *path);
 575
 576 /** Return a URI-encoded copy of @a path, allocated in @a pool.  (@a
 577     path can be an arbitrary UTF-8 string and does not have to be a
 578     canonical path.) */
 579 const char *
 580 svn_path_uri_encode(const char *path, apr_pool_t *pool);
 581
 582 /** Return a URI-decoded copy of @a path, allocated in @a pool. */
 583 const char *
 584 svn_path_uri_decode(const char *path, apr_pool_t *pool);
 585
 586 /** Extend @a url by @a component, URI-encoding that @a component
 587  * before adding it to the @a url; return the new @a url, allocated in
 588  * @a pool.  If @a component is @c NULL, just return a copy of @a url,
 589  * allocated in @a pool.
 590  *
 591  * @a component need not be a single path segment, but if it contains
 592  * multiple segments, they must be separated by '/'.  @a component
 593  * should not begin with '/', however; if it does, the behavior is
 594  * undefined.
 595  *
 596  * @a url must be in canonical format; it may not have a trailing '/'.
 597  *
 598  * @note To add a component that is already URI-encoded, use
 599  *       <tt>svn_path_join(url, component, pool)</tt> instead.
 600  *
 601  * @note gstein suggests this for when @a component begins with '/':
 602  *
 603  *       "replace the path entirely
 604  *        https://example.com:4444/base/path joined with /leading/slash,
 605  *        should return: https://example.com:4444/leading/slash
 606  *        per the RFCs on combining URIs"
 607  *
 608  *       We may implement that someday, which is why leading '/' is
 609  *       merely undefined right now.
 610  *
 611  * @since New in 1.6.
 612  */
 613 const char *
 614 svn_path_url_add_component2(const char *url,
 615                             const char *component,
 616                             apr_pool_t *pool);
 617
 618 /** Like svn_path_url_add_component2(), but allows path components that
 619  * end with a trailing '/'
 620  *
 621  * @deprecated Provided for backward compatibility with the 1.5 API.
 622  */
 623 SVN_DEPRECATED
 624 const char *
 625 svn_path_url_add_component(const char *url,
 626                            const char *component,
 627                            apr_pool_t *pool);
 628
 629 /**
 630  * Convert @a iri (Internationalized URI) to an URI.
 631  * The return value may be the same as @a iri if it was already
 632  * a URI.  Else, allocate the return value in @a pool.
 633  *
 634  * @since New in 1.1.
 635  */
 636 const char *
 637 svn_path_uri_from_iri(const char *iri, apr_pool_t *pool);
 638
 639 /**
 640  * URI-encode certain characters in @a uri that are not valid in an URI, but
 641  * doesn't have any special meaning in @a uri at their positions.  If no
 642  * characters need escaping, just return @a uri.
 643  *
 644  * @note Currently, this function escapes <, >, ", space, {, }, |, \, ^, and `.
 645  * This may be extended in the future to do context-dependent escaping.
 646  *
 647  * @since New in 1.1.
 648  */
 649 const char *
 650 svn_path_uri_autoescape(const char *uri, apr_pool_t *pool);
 651
 652 /** @} */
 653
 654 /** Charset conversion stuff
 655  *
 656  * @defgroup svn_path_charset_stuff Charset conversion
 657  * @{
 658  */
 659
 660 /** Convert @a path_utf8 from UTF-8 to the internal encoding used by APR. */
 661 svn_error_t *
 662 svn_path_cstring_from_utf8(const char **path_apr,
 663                            const char *path_utf8,
 664                            apr_pool_t *pool);
 665
 666 /** Convert @a path_apr from the internal encoding used by APR to UTF-8. */
 667 svn_error_t *
 668 svn_path_cstring_to_utf8(const char **path_utf8,
 669                          const char *path_apr,
 670                          apr_pool_t *pool);
 671
 672
 673 /** @} */
 674
 675 \f
 676 /** Repository relative URLs
 677  *
 678  * @defgroup svn_path_repos_relative_urls Repository relative URLs
 679  * @{
 680  */
 681
 682 /**
 683  * Return @c TRUE iff @a path is a repository-relative URL:  specifically
 684  * that it starts with the characters "^/"
 685  *
 686  * @a path is in UTF-8 encoding.
 687  *
 688  * Does not check whether @a path is a properly URI-encoded, canonical, or
 689  * valid in any other way.
 690  *
 691  * @since New in 1.8.
 692  */
 693 svn_boolean_t
 694 svn_path_is_repos_relative_url(const char *path);
 695
 696 /**
 697  * Set @a absolute_url to the absolute URL represented by @a relative_url
 698  * relative to @a repos_root_url, preserving any peg revision
 699  * specifier present in @a relative_url.  Allocate @a absolute_url
 700  * from @a pool.
 701  *
 702  * @a relative_url is in repository-relative syntax: "^/[REL-URL][@PEG]"
 703  *
 704  * @a repos_root_url is the absolute URL of the repository root.
 705  *
 706  * All strings are in UTF-8 encoding.
 707  *
 708  * @a repos_root_url and @a relative_url do not have to be properly
 709  * URI-encoded, canonical, or valid in any other way.  The caller is
 710  * expected to perform canonicalization on @a absolute_url after the
 711  * call to the function.
 712  *
 713  * @since New in 1.8.
 714  */
 715 svn_error_t *
 716 svn_path_resolve_repos_relative_url(const char **absolute_url,
 717                                     const char *relative_url,
 718                                     const char *repos_root_url,
 719                                     apr_pool_t *pool);
 720
 721 /** Return a copy of @a path, allocated from @a pool, for which control
 722  * characters have been escaped using the form "\NNN" (where NNN is the
 723  * octal representation of the byte's ordinal value).
 724  *
 725  * @since New in 1.8. */
 726 const char *
 727 svn_path_illegal_path_escape(const char *path, apr_pool_t *pool);
 728
 729 /** @} */
 730
 731 #ifdef __cplusplus
 732 }
 733 #endif /* __cplusplus */
 734
 735
 736 #endif /* SVN_PATH_H */