#ifndef __GSTR_UTILS_H #define __GSTR_UTILS_H /*------------------------------------------------------------------------- * Copyright (c) 2000-2002 Kenneth W. Sodemann (stuffle@charter.net) *------------------------------------------------------------------------- * gstr_utils * * Synopsis: * A collection of utilities for working with GStrings * * $Id: gstr_utils.h,v 1.1 2003/03/09 20:59:11 stuffle Exp $ * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * 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 General Public License for more details. * * You should have received a copy of the GNU General Public License * along with this program; if not, write to * Free Software Foundation, Inc. * 59 Temple Place, Suite 330 * Boston, MA 02111-1307 USA *------------------------------------------------------------------------- */ /*! \file gstr_utils.h \brief A collection of utilities for working with GStrings. The functions contained here perform useful operations on GStrings. Some of these functions are just nice things to be able to do, other functions are specific to working with PostgreSQL databases. \author Kenneth W. Sodemann (stuffle@charter.net) $Revision: 1.1 $ $Date: 2003/03/09 20:59:11 $ */ #include /* * __BEGIN_DECLS should be used at the beginning of your declarations, * so that C++ compilers don't mangle their names. Use __END_DECLS at * the end of C declarations. */ #undef __BEGIN_DECLS #undef __END_DECLS #ifdef __cplusplus # define __BEGIN_DECLS extern "C" { # define __END_DECLS } #else # define __BEGIN_DECLS /* empty */ # define __END_DECLS /* empty */ #endif /* * __P is a macro used to wrap function prototypes, so that compilers * that don't understand ANSI C prototypes still work, and ANSI C * compilers can issue warnings about type mismatches. */ #undef __P #if defined (__STDC__) || defined (_AIX) \ || (defined (__mips) && defined (_SYSTYPE_SVR4)) \ || defined(WIN32) || defined(__cplusplus) # define __P(protos) protos #else # define __P(protos) () #endif __BEGIN_DECLS /*! \fn GString *g_string_strip (GString *str) \brief Strip the string of any trailing white spaces. \param str The string to remove the trailing spaces from. \return A pointer to the string that was passed in. */ GString *g_string_strip __P((GString *str)); /*! \fn void g_string_delete_char (GString *str, gint pos) \brief Delete a character from the string. Delete the character at the position given. Shift all following characters to the left. \param str The string to remove the character from. \param pos The position at which to remove the character. GStrings are zero indexed, just like regular C character arrays. */ void g_string_delete_char __P((GString *str, gint pos)); /*! \fn void g_string_insert_char (GString *str, gchar chr, gint pos); \brief Insert a character into a string Insert a character into any spot within a string without overwritting the original contenets of the string. Chacters at and after the insert position are shifted to the right. \param str The string to be inserted into. \param chr The character to insert. \param pos The position within the string to insert the character. GStrings are zero indexed. */ void g_string_insert_char __P((GString *str, gchar chr, gint pos)); /*! \fn void g_string_insert_str (GString *str1, gchar *str2, gint pos) \brief Insert a string into a string Insert a string into any spot within a string without overwritting the original contenets of the string. Chacters at and after the insert position are shifted to the right to make room for the string being inserted. \param str1 The string to be inserted into. \param str2 The string of characters to insert. \param pos The position within the string to insert the other string. GStrings are zero indexed. */ void g_string_insert_str __P((GString *str1, gchar *str2, gint pos)); /*! \fn void g_string_escape_char (GString *str, gchar chr) \brief Backslash escape occurrances of characters within a string. Sometimes characters need to be "backslash escaped" in order to be translated properly. For example if you want to put text containing single quotes into the text field of a database using SQL, you will need to backslash escape the single quotes. \verbatim The following code snippet will produce a string that contains: It\'s got\'s some single quotes, y\'all GString *str; str = g_string_new ("It's got's some single quotes, y'all"); g_string_escape_char (str, '''); \endverbatim \param str The string to work on. \param chr The character to escape in the string. */ void g_string_escape_char __P((GString *str, gchar chr)); /*! \fn void g_string_prepare_db_instr(GString *str) \brief Prepare a SQL string for sending to the database. Text data that is INSERT'ed or UPDATE'ed needs to be prepared before it can be used properly in an INSERT or UPDATE query. This function will strip any trailing white space, backslash escape any single quotes within the string, and surround the string with single quotes. If the string is empty or all white space, this function will return the string "NULL" (no quotes). \verbatim The following code snippet will produce a string that contains: 'It\'s got\'s some single quotes, y\'all' GString *str; str = g_string_new ("It's got's some single quotes, y'all"); g_string_prepare_db_instr (str); \endverbatim \param str The string that is to be prepared. */ void g_string_prepare_db_instr __P((GString *str)); /*! \fn void g_string_prepare_html(GString *str) \brief Prepare a string for use within an HTML document. Text that is displayed on an HTML document will need to be prepared so that characters that are used as part of the HTML syntax are replaced by their HTML symbols. Also, newline characters need to be changed into '
' symbols, since all whitespace in HTML documents is treated as a single space. \verbatim The following code snippet will produce a string that contins: This string has some <special> characters in it
dude. GString *str; str = g_string_new ("This string has some characters in it\ndude."); g_string_prepare_html (str); \endverbatim \param str The string that is to be prepared. \return Nothing. */ void g_string_prepare_html __P((GString *str)); __END_DECLS #endif