blob: b854799a42ae1661ccc995a1ed7310389ad00873 [file] [log] [blame]
/*
* Copyright (C) Tildeslash Ltd. All rights reserved.
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU Affero General Public License version 3.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU Affero General Public License for more details.
*
* You should have received a copy of the GNU Affero General Public License
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*
* In addition, as a special exception, the copyright holders give
* permission to link the code of portions of this program with the
* OpenSSL library under certain conditions as described in each
* individual source file, and distribute linked combinations
* including the two.
*
* You must obey the GNU Affero General Public License in all respects
* for all of the code used other than OpenSSL.
*/
#ifndef STRINGBUFFER_INCLUDED
#define STRINGBUFFER_INCLUDED
/**
* A <b>StringBuffer</b> implements a mutable sequence of characters.
* Indexing starts at 0 and it is a checked runtime error to access
* index out of the range.
*
* This class is reentrant but not thread-safe
*
* @see http://www.mmonit.com/
* @file
*/
#define T StringBuffer_T
typedef struct T *T;
/**
* Constructs a string buffer so that it represents the same sequence of
* characters as the string argument; in other words, the initial contents
* of the string buffer is a copy of the argument string.
* @param s the initial contents of the buffer
* @return A new StringBuffer object
* @exception MemoryException if allocation failed
*/
T StringBuffer_new(const char *s);
/**
* Factory method, create an empty string buffer
* @param hint The initial capacity of the buffer in bytes (hint > 0)
* @return A new StringBuffer object
* @exception AssertException if hint is less than or equal to 0
* @exception MemoryException if allocation failed
*/
T StringBuffer_create(int hint);
/**
* Destroy a StringBuffer object and free allocated resources
* @param S a StringBuffer object reference
*/
void StringBuffer_free(T *S);
/**
* The characters of the String argument are appended, in order, to the
* contents of this string buffer, increasing the length of this string
* buffer by the length of the argument.
* @param S StringBuffer object
* @param s A string with optional var args
* @return a reference to this StringBuffer
* @exception MemoryException if allocation was used and failed
*/
T StringBuffer_append(T S, const char *s, ...) __attribute__((format (printf, 2, 3)));
/**
* The characters of the String argument are appended, in order, to the
* contents of this string buffer, increasing the length of this string
* buffer by the length of the arguments.
* @param S StringBuffer object
* @param s A string with optional var args
* @param ap A variable argument list
* @return a reference to this StringBuffer
* @exception MemoryException if allocation was used and failed
*/
T StringBuffer_vappend(T S, const char *s, va_list ap);
/**
* Returns the character in the given <code>index</code> position. The
* first char in the string buffer is located at position 0 and the last
* character is located at StringBuffer_length() - 1. The index parameter
* must be greater than or equal to 0 and less than the length of the
* StringBuffer.
* @param S StringBuffer object
* @param index The index of the character to return
* @return The char located at index
* @exception AssertException if the index parameter is negative
* or greater than or equal to the StringBuffer length.
*/
char StringBuffer_charAt(T S, int index);
/**
* Set the character in the StringBuffer to <code>c</code> at the
* <code>index</code> position. The index parameter must be greater
* than or equal to 0 and less than the length of the StringBuffer.
* @param S StringBuffer object
* @param index The index of the character to set
* @param c The character to set
* @exception AssertException if the index parameter is negative
* or greater than or equal to the StringBuffer length.
*/
void StringBuffer_setCharAt(T S, int index, char c);
/**
* Replace all occurences of <code>a</code> with <code>b</code>. Example:
* <pre>
* StringBuffer_T b = StringBuffer_new("foo bar baz foo foo bar baz");
* StringBuffer_replace(b, "baz", "bar") -> "foo bar bar foo foo bar bar"
* StringBuffer_replace(b, "foo bar ", "") -> "bar foo bar"
* </pre>
* @param S StringBuffer object
* @param a The sub-string to be replaced with <code>b</code>
* @param b The string to replace <code>a</code>
* @return The number of replacements that took place
* @exception MemoryException if allocation was used and failed
*/
int StringBuffer_replace(T S, const char *a, const char *b);
/**
* Remove (any) leading and trailing white space [ \\t\\r\\n]. Example
* <pre>
* StringBuffer_T b = StringBuffer_new("\t 'foo bar' \n");
* StringBuffer_trim(b) -> "'foo bar'"
* </pre>
* @param S StringBuffer object
* @return a reference to this StringBuffer
*/
T StringBuffer_trim(T S);
/**
* Remove all characters from the given <code>index</code> position and
* to the end of the StringBuffer. The index parameter must be greater
* than or equal to 0 and less than the length of the StringBuffer.
* @param S StringBuffer object
* @param index The position of the buffer to start truncating
* @exception AssertException if the index parameter is negative
* or greater than or equal to the StringBuffer length.
* @return a reference to this StringBuffer
*/
T StringBuffer_delete(T S, int index);
/**
* Locate the first occurrence of the string <code>s</code>
* in the StringBuffer. Example:
* <pre>
* StringBuffer_T b = StringBuffer_new("foo bar");
* StringBuffer_indexOf(b, "foo") -> 0
* StringBuffer_indexOf(b, "bar") -> 4
* StringBuffer_indexOf(b, "a") -> 5
* StringBuffer_indexOf(b, "xy") -> -1
* </pre>
* @param S StringBuffer object
* @param s The string to search for in the buffer
* @return The index of the first occurence of <code>s</code> in the
* buffer or -1 if not found.
*/
int StringBuffer_indexOf(T S, const char *s);
/**
* Locate the last occurrence of the string <code>s</code>
* in the StringBuffer.
* @param S StringBuffer object
* @param s The string to search for in the buffer
* @return The index of the last occurence of <code>s</code> in the
* buffer or -1 if not found.
*/
int StringBuffer_lastIndexOf(T S, const char *s);
/**
* Returns a substring of characters currently contained in this character
* sequence. The substring begins at the specified index and extends to the
* end of this sequence
* @param S StringBuffer object
* @param index The start index of the substring
* @return A substring of StringBuffer
* @exception AssertException if the index parameter is negative
* or greater than or equal to the StringBuffer length.
*/
const char *StringBuffer_substring(T S, int index);
/**
* Returns the length (character count) of this string buffer <i>not
* including the last '\\0' char used to terminate a C-string</i>.
* @param S StringBuffer object
* @return the length of the sequence of characters currently represented
* by this string buffer <i>not including the last NUL character</i>.
*/
int StringBuffer_length(T S);
/**
* Clears the contents of the string buffer and set buffer length to 0.
* @param S StringBuffer object
* @return a reference to this StringBuffer
*/
T StringBuffer_clear(T S);
/**
* Returns a string representing the data in this string buffer.
* @param S StringBuffer object
* @return a string representation of the string buffer
*/
const char *StringBuffer_toString(T S);
#undef T
#endif