/**
 * @copyright
 * ====================================================================
 *    Licensed to the Apache Software Foundation (ASF) under one
 *    or more contributor license agreements.  See the NOTICE file
 *    distributed with this work for additional information
 *    regarding copyright ownership.  The ASF licenses this file
 *    to you under the Apache License, Version 2.0 (the
 *    "License"); you may not use this file except in compliance
 *    with the License.  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 *    Unless required by applicable law or agreed to in writing,
 *    software distributed under the License is distributed on an
 *    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 *    KIND, either express or implied.  See the License for the
 *    specific language governing permissions and limitations
 *    under the License.
 * ====================================================================
 * @endcopyright
 *
 * @file svn_dirent_uri.h
 * @brief A library to manipulate URIs, relative paths and directory entries.
 *
 * This library makes a clear distinction between several path formats:
 *
 *  - a dirent is a path on (local) disc or a UNC path (Windows) in
 *    either relative or absolute format.
 *    Examples:
 *       "/foo/bar", "X:/temp", "//server/share", "A:/" (Windows only), ""
 *    But not:
 *       "http://server"
 *
 *  - a uri, for our purposes, is a percent-encoded, absolute path
 *    (URI) that starts with a schema definition.  In practice, these
 *    tend to look like URLs, but never carry query strings.
 *    Examples:
 *       "http://server", "file:///path/to/repos",
 *       "svn+ssh://user@host:123/My%20Stuff/file.doc"
 *    But not:
 *       "file", "dir/file", "A:/dir", "/My%20Stuff/file.doc", ""
 *
 *  - a relative path (relpath) is an unrooted path that can be joined
 *    to any other relative path, uri or dirent. A relative path is
 *    never rooted/prefixed by a '/'.
 *    Examples:
 *       "file", "dir/file", "dir/subdir/../file", ""
 *    But not:
 *       "/file", "http://server/file"
 *
 * This distinction is needed because on Windows we have to handle some
 * dirents and URIs differently. Since it's not possible to determine from
 * the path string if it's a dirent or a URI, it's up to the API user to
 * make this choice. See also issue #2028.
 *
 * All incoming and outgoing paths are non-NULL unless otherwise documented.
 *
 * All of these functions expect paths passed into them to be in canonical
 * form, except:
 *
 *    - @c svn_dirent_canonicalize()
 *    - @c svn_dirent_canonicalize_safe()
 *    - @c svn_dirent_is_canonical()
 *    - @c svn_dirent_internal_style()
 *    - @c svn_relpath_canonicalize()
 *    - @c svn_relpath_canonicalize_safe()
 *    - @c svn_relpath_is_canonical()
 *    - @c svn_uri_canonicalize()
 *    - @c svn_uri_canonicalize_safe()
 *    - @c svn_uri_is_canonical()
 *
 * The Subversion codebase also recognizes some other classes of path:
 *
 *  - A Subversion filesystem path (fspath) -- otherwise known as a
 *    path within a repository -- is a path relative to the root of
 *    the repository filesystem, that starts with a slash ("/").  The
 *    rules for a fspath are the same as for a relpath except for the
 *    leading '/'.  A fspath never ends with '/' except when the whole
 *    path is just '/'.  The fspath API is private (see
 *    private/svn_fspath.h).
 *
 *  - A URL path (urlpath) is just the path part of a URL (the part
 *    that follows the schema, username, hostname, and port).  These
 *    are also like relpaths, except that they have a leading slash
 *    (like fspaths) and are URI-encoded.  The urlpath API is also
 *    private (see private/svn_fspath.h)
 *    Example:
 *       "/svn/repos/trunk/README",
 *       "/svn/repos/!svn/bc/45/file%20with%20spaces.txt"
 *
 * So, which path API is appropriate for your use-case?
 *
 *  - If your path refers to a local file, directory, symlink, etc. of
 *    the sort that you can examine and operate on with other software
 *    on your computer, it's a dirent.
 *
 *  - If your path is a full URL -- with a schema, hostname (maybe),
 *    and path portion -- it's a uri.
 *
 *  - If your path is relative, and is somewhat ambiguous unless it's
 *    joined to some other more explicit (possible absolute) base
 *    (such as a dirent or URL), it's a relpath.
 *
 *  - If your path is the virtual path of a versioned object inside a
 *    Subversion repository, it could be one of two different types of
 *    paths.  We'd prefer to use relpaths (relative to the root
 *    directory of the virtual repository filesystem) for that stuff,
 *    but some legacy code uses fspaths.  You'll need to figure out if
 *    your code expects repository paths to have a leading '/' or not.
 *    If so, they are fspaths; otherwise they are relpaths.
 *
 *  - If your path refers only to the path part of URL -- as if
 *    someone hacked off the initial schema and hostname portion --
 *    it's a urlpath.  To date, the ra_dav modules are the only ones
 *    within Subversion that make use of urlpaths, and this is because
 *    WebDAV makes heavy use of that form of path specification.
 *
 * When translating between local paths (dirents) and uris code should
 * always go via the relative path format, perhaps by truncating a
 * parent portion from a path with svn_*_skip_ancestor(), or by
 * converting portions to basenames and then joining to existing
 * paths.
 *
 * SECURITY WARNING: If a path that is received from an untrusted
 * source -- such as from the network -- is converted to a dirent it
 * should be tested with svn_dirent_is_under_root() before you can
 * assume the path to be a safe local path.
 *
 * MEMORY ALLOCATION: A function documented as allocating the result
 * in a pool may instead return a static string such as "." or "". If
 * the result is equal to an input, it will duplicate the input.
 */

#ifndef SVN_DIRENT_URI_H
#define SVN_DIRENT_URI_H

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

#include "svn_types.h"

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

