Search packages:
 Sourcecode: aegis version 4.114.11-2.24.214.21-24.224.22-24.22-2ubuntu14.244.24-24.24-34.24-3.14.24-44.24-54.24-5.24.24-5.2ubuntu14.24.24.24.2-14.24.2-24.24.2-34.24.2-44.24.3-14.24.3-24.24.3-3

# str.h

/*
*    aegis - project change supervisor
*    Copyright (C) 1991-1995, 1998, 1999, 2001, 2002 Peter Miller;
*
*    This program is free software; you can redistribute it and/or modify
*    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 the Free Software
*    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, USA.
*
* MANIFEST: interface definition for common/str.c
*/

#ifndef STR_H
#define STR_H

#include <ac/stddef.h>
#include <ac/stdarg.h>
#include <main.h>

typedef unsigned long str_hash_ty;

/**
* \struct string_ty
* The string_ty struct is used to remember information about strings.
* Users should always refer to strings as \em pointers.  The only
* members within the struct that should be accessed are the str_text
* member, which is a NUL terminated array of characters, and the
* str_length member, which contains the length of the string's text
* (not including the NUL terminator).
*
* It is guaranteed that all equal strings will not only have the same
* hash, but will, if fact, be exactly the same sting.  The reference
* count is how many strings currently exist with this value.  Thus,
* the commonest string test, a string equality test becomes a pointer
* equality test.
*
* <b>Thou shalt not</b> modify any member of a string struct, or the
* forces of evil shall wreak misery in thy life.
*/
typedef struct string_ty string_ty;
00051 struct string_ty
{
/**
* The hash of the string.  Used internally by the string table,
* users shall never access this member.
*/
00057     str_hash_ty     str_hash;

/**
* The next string in a hash bucket.  Used internally by the string
* table, users shall never access this member.
*/
00063     string_ty         *str_next;

/**
* The reference count for this string.  It is guaranteed that
* all equal strings will not only have the same hash, but will,
* if fact, be exactly the same sting.  The reference count is how
* many strings currently exist with this value.  Used internally
* by the string table, users shall never access this member.
*/
00072     long        str_references;

/**
* The length of the string (not including the terminating NUL).
* Read-only access permitted to users.
*/
00078     size_t      str_length;

/**
* The text value of the string.  It's actually longer than its
* declaration when the string length is more than zero.
* Read-only access permitted to users.
*/
00085     char        str_text[1];
};

/**
* \brief
*   start up string table
*
* The str_initialize function is used to create the hash table and
* initialize it to empty.
*
* This function must be called before any other defined in this file.
*
* \return
*   void
*/
void str_initialize(void);

/**
* \brief
*   make string from C string
*
* The str_from_c function is used to make a string from a null
* terminated C string.
*
* \param str
*   The C string to be copied.  Will not be modified.
*
* \return
*   a pointer to a string in dynamic memory.  Use str_free() when
*   finished with.    The contents of the structure pointed to <b>shall
*   not</b> be altered.
*/
string_ty *str_from_c(const char *str);

/**
* \brief
*   make string from C string
*
* The str_n_from_c function is used to make a string from an array of
* characters.  No null terminator is assumed.
*
* \param str
*   The C string to be copied.  Will not be modified.
* \param len
*   The maximum number of characters to be used (fewer will be used
*   if there is an included NUL).
*
* \return
*   a pointer to a string in dynamic memory.  Use str_free() when
*   finished with.    The contents of the structure pointed to <b>shall
*   not</b> be altered.
*/
string_ty *str_n_from_c(const char *str, size_t len);

/**
* \brief
*   make a copy of a string
*
* The str_copy function is used to make a copy of a string.
*
* \param str
*   The string to be copied.  Will not be modified.
*
* \return
*   a pointer to a string in dynamic memory.  Use str_free() when
*   finished with.    The contents of the structure pointed to <b>shall
*   not</b> be altered.
*/
string_ty *str_copy(string_ty *str);

/**
* \brief
*   release a string
*
* The str_free function is used to indicate that a string hash
* been finished with.  This is the only way to release strings.
* <b>Do not</b> use the free() function.
*
* \param str
*   The string to be freed.
*
* \return
*      void
*/
void str_free(string_ty *str);

/**
* \brief
*   join two strings together
*
* The str_catenate function is used to join two strings togther to
* form a new string.  The are joined in the order given.
*
* \param str1
*   A string to be joined.  Will not be modified.
* \param str2
*   A string to be joined.  Will not be modified.
*
* \return
*   a pointer to a string in dynamic memory.  Use str_free() when
*   finished with.    The contents of the structure pointed to <b>shall
*   not</b> be altered.
*/
string_ty *str_catenate(string_ty *str1, string_ty *str2);

/**
* \brief
*   joing strings together
*
* The str_cat_three function is used to join three strings together
* to form a new string.  The are joined in the order given.
*
* \param str1
*   A string to be joined.  Will not be modified.
* \param str2
*   A string to be joined.  Will not be modified.
* \param str3
*   A string to be joined.  Will not be modified.
*
* \return
*   a pointer to a string in dynamic memory.  Use str_free() when
*   finished with.    The contents of the structure pointed to <b>shall
*   not</b> be altered.
*/
string_ty *str_cat_three(string_ty *str1, string_ty *str2, string_ty *str3);

/**
* \brief
*   test a boolean
*
* The str_bool function is used to test the value of a string, as if
* it contained a number.  If it doesn't contain a number, it is as if
* the strings was "1".
*
* \param str
*   The string to be tested.  Will not be modified.
*
* \return
*   Zero if the numeric value in the strings was zero, or the empty
*   string.  One if the numeric value in the string was non-zero,
*   or the string was non-numeric.
*/
int str_bool(string_ty *str);

/**
* \brief
*   convert to upper case
*
* The str_upcase function is used to create a new string where the
* lower case characters in the input string are converted to upper
* case.
*
* \param str
*   The string to be converted.  Will not be modified (the operation
*   is <b>not</b> performed <i>in situ</i>).
*
* \return
*   a pointer to a string in dynamic memory.  Use str_free() when
*   finished with.    The contents of the structure pointed to <b>shall
*   not</b> be altered.
*/
string_ty *str_upcase(string_ty *str);

/**
* \brief
*   convert to lower case
*
* The str_downcase function is used to create a new string where the
* upper case characters in the input string are converted to lower
* case.
*
* \param str
*   The string to be converted.  Will not be modified (the operation
*   is <b>not</b> performed <i>in situ</i>).
*
* \return
*   a pointer to a string in dynamic memory.  Use str_free() when
*   finished with.    The contents of the structure pointed to <b>shall
*   not</b> be altered.
*/
string_ty *str_downcase(string_ty *str);

/**
* \brief
*   convert to title case
*
* The str_capitalize function is used to create a new string where the
* first letter or each word of the inopuyt string are upper case, and
* the remaining letters in each word are lower case.  (Sometimes called
* Title Case.)
*
* \param str
*   The string to be converted.  Will not be modified (the operation
*   is <b>not</b> performed <i>in situ</i>).
*
* \return
*   a pointer to a string in dynamic memory.  Use str_free() when
*   finished with.    The contents of the structure pointed to <b>shall
*   not</b> be altered.
*/
string_ty *str_capitalize(string_ty *str);

/**
* \brief
*   dump the string table
*
* The str_dum function is used to dump the contents of the string
* table to the standard error.  Only useful for debugging.
*
* \return
*   void
*/
void str_dump(void);

/**
* \brief
*   extract a field
*
* The str_field function is used to extract the \a nth field, where
* each field is separated by the \a sep string.
*
* \param str
*   The string from which the field is to be extracted.  Will not
*   be modified (the operation >not</b> performed <i>in situ</i>).
* \param sep
*   The string which separates each field.
* \param nth
*   The number of the field to be extracted.  Zero based.
*   If too high, the emtry string is returned.
*
* \return
*   a pointer to a string in dynamic memory.  Use str_free() when
*   finished with.    The contents of the structure pointed to <b>shall
*   not</b> be altered.
*/
string_ty *str_field(string_ty *str, int sep, int nth);

/**
* \brief
*   convert tables of strings
*
* The slow_to_fast function is used to convert tables for normal
* C strings into tables of reference countest strings.  Use amlost
* exclusively by the fmtgen-generated sources.
*
* \return
*   void
*/
void slow_to_fast(char **, string_ty **, size_t);

/**
* \brief
*   format text
*
* The str_format function is used to create a new string by interpreting
* the \a fmt string.  All formats understood by the ANSI C printf(3)
* are understodd by this function (but probably not your favorite
* proprietary extension).  In addition the '%S' specifier expects a <i>
* string_ty * </i> argument.
*
* \param fmt
*   The format string to be interpreted when constructing the
*   return value.
*
* \return
*   a pointer to a string in dynamic memory.  Use str_free() when
*   finished with.    The contents of the structure pointed to <b>shall
*   not</b> be altered.
*/
string_ty *str_format(const char *fmt, ...);

/**
* \brief
*   format text
*
* The str_vformat function is used to create a new string by interpreting
* the \a fmt string.  All formats understood by the ANSI C printf(3)
* are understodd by this function (but probably not your favorite
* proprietary extension).  In addition the '%S' specifier expects a <i>
* string_ty * </i> argument.
*
* \param fmt
*   The format string to be interpreted when constructing the
*   return value.
* \param ap
*   Where to obtain additional arguments required by the \a fmt string.
*
* \return
*   a pointer to a string in dynamic memory.  Use str_free() when
*   finished with.    The contents of the structure pointed to <b>shall
*   not</b> be altered.
*/
string_ty *str_vformat(const char *fmt, va_list ap);

/**
* \brief
*   test string equality
*
* The str_equal function is used to test to see if two strings are
* exactly the same.
*
* \param str1
*   A string to be compared.  Will not be modified.
* \param str2
*   A string to be compared.  Will not be modified.
*
* \note
*   Users shall always write code as if they did not know that a
*   string equality test is a pointer equality test.
*
* \return
*   Non-zero if the strings are equal,
*   zero if the strings are unequal.
*/
int str_equal(string_ty *str1, string_ty *str2);

/**
* \brief
*   test string equality
* \see
*   str_equal()
*
* The str_equal macro is used to accellerate string equality tests.
* Users shall always write code as if they did not know that a string
* equality test is a pointer  equality test.
*/
#define str_equal(s1, s2) ((s1) == (s2))

/**
* \brief
*   regular expression match
*
* The str_re_match function is used to test for a regular expression
* match.
*
* \param pattern
*   The regular expression pattern to be matched against (excluding
*   the slashes).  Will not be modified.
* \param candidate
*   The string to be tested, to see if it matches the \a pattern.
*   Will not be modified.
* \param callback
*   A pointer to an error message function to be called if there is
*   something wrong with the pattern.  If this pointer is NULL,
*   it will not be called.
*
* \return
*   Positive if there is a match, zero if there is not,
*   negative if an error occurred (usually, a broken \a pattern string).
*/
int str_re_match(string_ty *pattern, string_ty *candidate,
void (*callback)(const char *));

/**
* \brief
*   regular expression substitute
*
* The str_re_substitute function is used to performa a regular
* expression match of the \a actual string against the \a lhs (the
* pattern) and then substitute into the \a rhs string.
*
* \param lhs
*   The left hand side (the regular expression).
*   Will not be modified.
* \param rhs
*   The right hand side (the replacement).
*   Will not be modified.
* \param actual
*   The string to be matched and replaced.    Will not be modified
*   (the operation is <b>not</b> performed <i>in situ</i>).
* \param callback
*   A pointer to an error message function to be called if there is
*   something wrong with the pattern.  If this pointer is NULL,
*   it will not be called.
* \param count
*   The maximum number of times to match the expression agains the
*   string (zero means infinite).
*
* \return
*   a pointer to a string in dynamic memory.  Use str_free() when
*   finished with.    The contents of the structure pointed to <b>shall
*   not</b> be altered.  Returns NULL if there was an error.
*/
string_ty *str_re_substitute(string_ty *lhs, string_ty *rhs, string_ty *actual,
void (*callback)(const char *), int count_);

/**
* \brief
*   quote shell meta-characters
*
* The str_quote_shell function is used to create a new string which
* quotes the shell meta-characters in the input string.
*
* \param str
*   The string to be converted.  Will not be modified (the operation
*   is <b>not</b> performed <i>in situ</i>).
*
* \return
*   a pointer to a string in dynamic memory.  Use str_free() when
*   finished with.    The contents of the structure pointed to <b>shall
*   not</b> be altered.
*/
string_ty *str_quote_shell(string_ty *str);

/**
* \brief
*   remove excess white space
*
* The str_trim function is used to remove white space from the beginning
* and end of the string, and replace all other runs of one or more
* white space characters with a single space.
*
* \param str
*   The string to be converted.  Will not be modified (the operation
*   is <b>not</b> performed <i>in situ</i>).
*
* \return
*   a pointer to a string in dynamic memory.  Use str_free() when
*   finished with.    The contents of the structure pointed to <b>shall
*   not</b> be altered.
*/
string_ty *str_trim(string_ty *str);

/**
* \brief
*   check is valid
*
* The str_validate function is used to confirm that the given string
* pointer, \a str, points to a valid string.
* Usually used for debugging, often in assert()s.
*
* \param str
*   The string to be validated.  Willnot be modified.
*
* \return
*   Non-zero if valid, zero if invalid.
*/
int str_validate(string_ty *);

/**
* \brief
*   look for a leading prefix
*
* The str_leading_prefix function is used to test whether the \a needle
* argument is a leading prefix of the \a haystack argument.
*
* \param haystack
*   The large string which allegedly contains the \a needle.
* \param needle
*   The substring to be tested for.
*
* \return
*   Non-zero if is a leadinf prefix, zero if not.
*/