/*
 * svn_string.h :  counted-length strings for Subversion, plus 
 *                 some C string goodies
 *
 * ====================================================================
 * Copyright (c) 2000-2002 CollabNet.  All rights reserved.
 *
 * This software is licensed as described in the file COPYING, which
 * you should have received as part of this distribution.  The terms
 * are also available at http://subversion.tigris.org/license-1.html.
 * If newer versions of this license are posted there, you may use a
 * newer version instead, at your option.
 *
 * This software consists of voluntary contributions made by many
 * individuals.  For exact contribution history, see the revision
 * history and logs, available at http://subversion.tigris.org/.
 * ====================================================================
 */


#ifndef SVN_STRING_H
#define SVN_STRING_H

#include <apr.h>
#include <apr_tables.h>
#include <apr_pools.h>       /* APR memory pools for everyone. */
#include <apr_strings.h>

#include "svn_types.h"

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


/* DATA TYPES

   There are two string datatypes: svn_string_t and svn_stringbuf_t.
   The former is a simple pointer/length pair useful for passing around
   strings (or arbitrary bytes) with a counted length. svn_stringbuf_t is
   buffered to enable efficient appending of strings without an allocation
   and copy for each append operation.

   svn_string_t contains a "const char *" for its data, so it is most
   appropriate for constant data and for functions which expect constant,
   counted data. Functions should generally use "const svn_string_t *" as
   their parameter to indicate they are expecting a constant, counted
   string.

   svn_stringbuf_t uses a plain "char *" for its data, so it is most
   appropriate for modifiable data.


   INVARIANT

   Both structures maintain a significant invariant:

       s->data[s->len] == '\0'

   The functions defined within this header file will maintain the invariant
   (which does imply that memory is allocated/defined as len+1 bytes). If
   code outside of the svn_string.h functions manually builds these
   structures, then they must enforce this invariant.

   Note that an svn_string(buf)_t may contain binary data, which means that
   strlen(s->data) does not have to equal s->len. The null terminator is
   provided to make it easier to pass s->data to C string interfaces.
*/

typedef struct
{
  const char *data;
  apr_size_t len;
} svn_string_t;


typedef struct
{
  char *data;                /* pointer to the bytestring */
  apr_size_t len;            /* length of bytestring */
  apr_size_t blocksize;      /* total size of buffer allocated */
  /* pool from which this string was originally allocated, and is not
     necessarily specific to this string.  This is used only for
     allocating more memory from when the string needs to grow.  */
  apr_pool_t *pool;          
} svn_stringbuf_t;


/* svn_string_t functions. */

/* Create a new bytestring containing a C string (null-terminated), or
   containing a generic string of bytes (NON-null-terminated) */
svn_string_t *svn_string_create (const char *cstring, 
                                 apr_pool_t *pool);
svn_string_t *svn_string_ncreate (const char *bytes,
                                  const apr_size_t size, 
                                  apr_pool_t *pool);

/* Create a new string with the contents of the given stringbuf */
svn_string_t *svn_string_create_from_buf (const svn_stringbuf_t *strbuf,
                                          apr_pool_t *pool);

/* Create a new bytestring by formatting CSTRING (null-terminated)
   from varargs, which are as appropriate for apr_psprintf. */
svn_string_t *svn_string_createf (apr_pool_t *pool,
                                  const char *fmt,
                                  ...)
       __attribute__ ((format (printf, 2, 3)));

/* Create a new bytestring by formatting CSTRING (null-terminated)
   from a va_list (see svn_stringbuf_createf). */
svn_string_t *svn_string_createv (apr_pool_t *pool,
                                  const char *fmt,
                                  va_list ap)
       __attribute__ ((format (printf, 2, 0)));

/* Return true if a bytestring is empty (has length zero). */
svn_boolean_t svn_string_isempty (const svn_string_t *str);

/* Return a duplicate of ORIGNAL_STRING. */
svn_string_t *svn_string_dup (const svn_string_t *original_string,
                              apr_pool_t *pool);

/* Return TRUE iff STR1 and STR2 have identical length and data. */
svn_boolean_t svn_string_compare (const svn_string_t *str1, 
                                  const svn_string_t *str2);

/** convenience routines **/

/* Return offset of first non-whitespace character in STR, or -1 if none. */
apr_size_t svn_string_first_non_whitespace (const svn_string_t *str);

/* Strips whitespace from both sides of STR (modified in place). */
void svn_string_strip_whitespace (svn_string_t *str);

/* Return position of last occurrence of CHAR in STR, or return
   STR->len if no occurrence. */ 
apr_size_t svn_string_find_char_backward (const svn_string_t *str, char ch);


/* svn_stringbuf_t functions. */

/* Create a new bytestring containing a C string (null-terminated), or
   containing a generic string of bytes (NON-null-terminated) */
svn_stringbuf_t *svn_stringbuf_create (const char *cstring, 
                                       apr_pool_t *pool);
svn_stringbuf_t *svn_stringbuf_ncreate (const char *bytes,
                                        const apr_size_t size, 
                                        apr_pool_t *pool);

/* Create a new stringbuf with the contents of the given string */
svn_stringbuf_t *svn_stringbuf_create_from_string (const svn_string_t *str,
                                                   apr_pool_t *pool);

/* Create a new bytestring by formatting CSTRING (null-terminated)
   from varargs, which are as appropriate for apr_psprintf. */
svn_stringbuf_t *svn_stringbuf_createf (apr_pool_t *pool,
                                        const char *fmt,
                                        ...)
       __attribute__ ((format (printf, 2, 3)));

/* Create a new bytestring by formatting CSTRING (null-terminated)
   from a va_list (see svn_stringbuf_createf). */
svn_stringbuf_t *svn_stringbuf_createv (apr_pool_t *pool,
                                        const char *fmt,
                                        va_list ap)
       __attribute__ ((format (printf, 2, 0)));

/* Make sure that the string STR has at least MINIMUM_SIZE bytes of
   space available in the memory block.  (MINIMUM_SIZE should include
   space for the terminating null character.)  */
void svn_stringbuf_ensure (svn_stringbuf_t *str,
                           apr_size_t minimum_size);

/* Set a bytestring STR to VALUE */
void svn_stringbuf_set (svn_stringbuf_t *str, const char *value);

/* Set a bytestring STR to empty (0 length). */
void svn_stringbuf_setempty (svn_stringbuf_t *str);

/* Return true if a bytestring is empty (has length zero). */
svn_boolean_t svn_stringbuf_isempty (const svn_stringbuf_t *str);

/* Chop NBYTES bytes off end of STR, but not more than STR->len. */
void svn_stringbuf_chop (svn_stringbuf_t *str, apr_size_t bytes);

/* Fill bytestring STR with character C. */
void svn_stringbuf_fillchar (svn_stringbuf_t *str, const unsigned char c);

/* Append either a string of bytes, an svn_stringbuf_t, or a C-string
   onto TARGETSTR.  reallocs() if necessary.  TARGETSTR is affected,
   nothing else is. */
void svn_stringbuf_appendbytes (svn_stringbuf_t *targetstr,
                                const char *bytes, 
                                const apr_size_t count);
void svn_stringbuf_appendstr (svn_stringbuf_t *targetstr, 
                              const svn_stringbuf_t *appendstr);
void svn_stringbuf_appendcstr (svn_stringbuf_t *targetstr,
                               const char *cstr);

/* Return a duplicate of ORIGNAL_STRING. */
svn_stringbuf_t *svn_stringbuf_dup (const svn_stringbuf_t *original_string,
                                    apr_pool_t *pool);


/* Return TRUE iff STR1 and STR2 have identical length and data. */
svn_boolean_t svn_stringbuf_compare (const svn_stringbuf_t *str1, 
                                     const svn_stringbuf_t *str2);

/** convenience routines **/

/* Return offset of first non-whitespace character in STR, or -1 if none. */
apr_size_t svn_stringbuf_first_non_whitespace (const svn_stringbuf_t *str);

/* Strips whitespace from both sides of STR (modified in place). */
void svn_stringbuf_strip_whitespace (svn_stringbuf_t *str);

/* Return position of last occurrence of CHAR in STR, or return
   STR->len if no occurrence. */ 
apr_size_t svn_stringbuf_find_char_backward (const svn_stringbuf_t *str, 
                                             char ch);

/* Chop STR back to CHAR, inclusive.  Returns number of chars
   chopped, so if no such CHAR in STR, chops nothing and returns 0. */
apr_size_t svn_stringbuf_chop_back_to_char (svn_stringbuf_t *str, char ch);

/* Return TRUE iff STR1 and STR2 have identical length and data. */
svn_boolean_t svn_string_compare_stringbuf (const svn_string_t *str1,
                                            const svn_stringbuf_t *str2);


/*** C strings. ***/

/* Divide INPUT into substrings along SEP_CHAR boundaries, return an
 * array of copies of the substrings, all allocated in POOL.
 *
 * No element of the array contains SEP_CHAR, though some elements
 * may be empty.  If there are N occurrences of SEP_CHAR in INPUT,
 * then return N+1 elements; thus, the minimum number of elements
 * returned is 1.
 *
 * If CHOP_WHITESPACE is true, then remove leading and trailing
 * whitespace from the returned strings.
 */
apr_array_header_t *svn_cstring_split (const char *input,
                                       char sep_char,
                                       svn_boolean_t chop_whitespace,
                                       apr_pool_t *pool);


/* A general in-memory representation of a single property.  Most of
   the time, property lists will be stored completely in hashes.  But
   sometimes it's useful to have an "ordered" collection of
   properties, in which case we use an apr_array of the type below.

   Also: sometimes we want a list that represents a set of property
   *changes*, and in this case, an apr_hash_t won't work -- there's no
   way to represent a property deletion, because we can't store a NULL
   value in a hash.  So instead, we use these structures.  */
typedef struct svn_prop_t
{
  const char *name;
  const svn_string_t *value;
} svn_prop_t;


/* ### This structure is in svn_string.h because it uses a binary
   string as the value; ideally, we'd like it to be in svn_types.h,
   but that file is always #included before this one. */


#ifdef __cplusplus
}
#endif /* __cplusplus */

#endif  /* SVN_STRING_H */

/* ----------------------------------------------------------------
 * local variables:
 * eval: (load-file "../../tools/dev/svn-dev.el")
 * end:
 */