/* Copyright 2006 Joachim Zobel <jz-2006@heute-morgen.de>.
 *
 * Licensed 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.
 */

#include "apr.h"
#include "apr_general.h"
#include "apr_tables.h"

/*
 * A fragment buffer is an array of strings with length. This can be 
 * "written" without copying.
 * This allows to delay string concatenation until the final length is
 * known and prevents reallocs.
 */
typedef apr_array_header_t frag_buffer_t;

/**
 * Create a fragment buffer
 * @param p - The pool to use for the buffer.
 * @return The newly created fragment buffer.
 */
frag_buffer_t *frag_create(apr_pool_t *p) ;

/**
 * Write to the fragment buffer
 * @param frag_buf - fragment buffer.
 * @param str - will be "written".
 * @param len - Length of str.
 */
void frag_write(frag_buffer_t *frag_buf, const char *str, apr_size_t len) ; 

/**
 * Write an xml encoded string to the fragment buffer
 * @param frag_buf - fragment buffer.
 * @param str - will be "written" - must be \0 terminated.
 * @return The space needed for the encoded string.
 */
apr_size_t frag_write_enc(frag_buffer_t *frag_buf, const char *str) ;

/**
 * Write an decoded string to the fragment buffer. This only decodes 
 * those entities that are encoded by frag_write_enc
 * @param frag_buf - fragment buffer.
 * @param str - will be "written" - must be \0 terminated.
 * @return The space needed for the decoded string.
 */
/* NOT USED - useful ?
apr_size_t frag_write_dec(frag_buffer_t *frag_buf, const char *str) ;
*/

/**
 * Removes all elements from the fragment buffer
 * @param frag_buf - fragment buffer.
 */
void frag_clean(frag_buffer_t *frag_buf) ;

/**
 * Writes the fragment buffer to a linear buffer.
 * @param frag_buf - fragment buffer.
 * @param offset - start offset in the fragment buffer.
 * @param buf - The buffer to write. This will not be terminated with 0.
 * @param avail - Available space in buf.
 * @return The length of what has NOT been written as a negative value 
 *         or the length of the remaining available space.
 */
apr_off_t frag_to_buffer(frag_buffer_t *frag_buf, apr_off_t offset,
			 char *buf, apr_size_t avail) ; 

/**
 * Computes the fragment buffers content length.
 * @param frag_buf - fragment buffer.
 * @param offset - start offset in the fragment buffer.
 * @return The length of the frag buffers content.
 */
apr_off_t frag_length(frag_buffer_t *frag_buf) ;