/**
 * @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_string.h
 * @brief Counted-length strings for Subversion, plus some C string goodies.
 *
 * There are two string datatypes: @c svn_string_t and @c svn_stringbuf_t.
 * The former is a simple pointer/length pair useful for passing around
 * strings (or arbitrary bytes) with a counted length. @c svn_stringbuf_t is
 * buffered to enable efficient appending of strings without an allocation
 * and copy for each append operation.
 *
 * @c svn_string_t contains a <tt>const char *</tt> for its data, so it is
 * most appropriate for constant data and for functions which expect constant,
 * counted data. Functions should generally use <tt>const @c svn_string_t
 * *</tt> as their parameter to indicate they are expecting a constant,
 * counted string.
 *
 * @c svn_stringbuf_t uses a plain <tt>char *</tt> for its data, so it is
 * most appropriate for modifiable data.
 *
 * <h3>Invariants</h3>
 *
 *   1. Null termination:
 *
 *      Both structures maintain a significant invariant:
 *
 *         <tt>s->data[s->len] == '\\0'</tt>
 *
 *      The functions defined within this header file will maintain
 *      the invariant (which does imply that memory is
 *      allocated/defined as @c len+1 bytes).  If code outside of the
 *      @c svn_string.h functions manually builds these structures,
 *      then they must enforce this invariant.
 *
 *      Note that an @c svn_string(buf)_t may contain binary data,
 *      which means that strlen(s->data) does not have to equal @c
 *      s->len. The null terminator is provided to make it easier to
 *      pass @c s->data to C string interfaces.
 *
 *
 *   2. Non-NULL input:
 *
 *      All the functions assume their input data pointer is non-NULL,
 *      unless otherwise documented, and may seg fault if passed
 *      NULL.  The input data may *contain* null bytes, of course, just
 *      the data pointer itself must not be NULL.
 *
 * <h3>Memory allocation</h3>
 *
 *   All the functions make a deep copy of all input data, and never store
 *   a pointer to the original input data.
 */


#ifndef SVN_STRING_H
#define SVN_STRING_H

#include <apr.h>          /* for apr_size_t */
#include <apr_pools.h>    /* for apr_pool_t */
#include <apr_tables.h>   /* for apr_array_header_t */

#include "svn_types.h"    /* for svn_boolean_t, svn_error_t */

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

/**
 * @defgroup svn_string String handling
 * @{
 */