Rev 7 | Blame | Compare with Previous | Last modification | View Log | RSS feed
/*
* Copyright (c) 2002-2006 The TenDRA Project <http://www.tendra.org/>.
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions are met:
*
* 1. Redistributions of source code must retain the above copyright notice,
* this list of conditions and the following disclaimer.
* 2. Redistributions in binary form must reproduce the above copyright notice,
* this list of conditions and the following disclaimer in the documentation
* and/or other materials provided with the distribution.
* 3. Neither the name of The TenDRA Project nor the names of its contributors
* may be used to endorse or promote products derived from this software
* without specific, prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS
* IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
* THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
* PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR
* CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
* EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
* PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
* OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
* WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
* OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
* ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*
* $Id$
*/
/*
Crown Copyright (c) 1997
This TenDRA(r) Computer Program is subject to Copyright
owned by the United Kingdom Secretary of State for Defence
acting through the Defence Evaluation and Research Agency
(DERA). It is made available to Recipients with a
royalty-free licence for its use, reproduction, transfer
to other parties and amendment for any purpose not excluding
product development provided that any such use et cetera
shall be deemed to be acceptance of the following conditions:-
(1) Its Recipients shall ensure that this Notice is
reproduced upon any copies or amended versions of it;
(2) Any amended version of it shall be clearly marked to
show both the nature of and the organisation responsible
for the relevant amendment or amendments;
(3) Its onward transfer from a recipient to another
party shall be deemed to be that party's acceptance of
these conditions;
(4) DERA gives no warranty or assurance as to its
quality or suitability for any purpose and DERA accepts
no liability whatsoever in relation to any use to which
it may be put.
*/
/**** dstring.h --- String manipulation.
*
** Author: Steve Folkes <smf@hermes.mod.uk>
*
**** Commentary:
*
***=== INTRODUCTION =========================================================
*
* This file specifies the interface to a string manipulation facility. There
* are two types of strings supported: nstrings (strings are stored as a
* length, and a vector of characters), and dstrings which are only of use
* when it is necessary to append characters to a string one at a time with
* reasonable efficiency.
*
* Null pointers are not valid as nstrings or dstrings. Passing a null pointer
* as the argument to a function will have an undefined effect (on many
* machines the program will abort, but this is not guaranteed).
*
***=== TYPES ================================================================
*
** Type: NStringT
** Type: NStringP
** Repr: <private>
*
* This is the nstring type. These strings may contain null characters.
*
** Type: DStringT
** Type: DStringP
** Repr: <private>
*
* This is the dstring type. It is only for appending characters and C
* strings to. Once it has been completely initialised, it should be
* converted to one of the other string types.
*
***=== FUNCTIONS ============================================================
*
** Function: void nstring_init(NStringP nstring)
** Exceptions:
*
* This function initialises the specified nstring to be an empty nstring.
*
** Function: void nstring_init_length(NStringP nstring, unsigned length)
** Exceptions: XX_dalloc_no_memory
*
* This function initialises the specified nstring to be an nstring of the
* specified length. The initial contents are unspecified.
*
** Function: void nstring_assign(NStringP to, NStringP from)
** Exceptions:
*
* This function assigns the from nstring to the to nstring. The from nstring
* should not be used afterwards, without reinitialising it.
*
** Function: void nstring_copy_cstring(NStringP nstring, CStringP cstring)
** Exceptions: XX_dalloc_no_memory
*
* This function initialises the specified nstring from the content of the
* specified cstring.
*
** Function: void nstring_insert_cstring(NStringP nstring, CStringP cstring)
** Exceptions:
*
* This function inserts the specified cstring into the specified nstring.
* Sufficient characters are copied to fill up the nstring.
*
** Function: void nstring_copy(NStringP to, NStringP from)
** Exceptions: XX_dalloc_no_memory
*
* This function copies the specified from nstring into the specified to
* nstring.
*
** Function: CStringP nstring_to_cstring(NStringP nstring)
** Exceptions: XX_dalloc_no_memory
*
* This function returns a dynamically allocated cstring copy of the specified
* nstring. If the nstring contains null characters, then the characters
* after the first null will be ignored in the cstring (although they will
* still be part of it).
*
** Function: unsigned nstring_hash_value(NStringP nstring)
** Exceptions:
*
* This function returns the hash value associated with the specified nstring.
* This value is guaranteed to be identical for all nstrings with the same
* content.
*
** Function: unsigned nstring_length(NStringP nstring)
** Exceptions:
*
* This function returns the length of the specified nstring.
*
** Function: CStringP nstring_contents(NStringP nstring)
** Exceptions:
*
* This function returns the contents of the specified nstring.
*
** Function: CmpT nstring_compare(NStringP nstring1, NStringP nstring2)
** Exceptions:
*
* This function returns ``CMP_LT'', ``CMP_EQ'', or ``CMP_GT'', depending on
* whether the content of nstring1 is lexicographically less than, equal to,
* or greater than the content of nstring2.
*
** Function: BoolT nstring_equal(NStringP nstring1, NStringP nstring2)
** Exceptions:
*
* This function returns true if the specified nstrings have the same content,
* and false otherwise.
*
** Function: BoolT nstring_ci_equal(NStringP nstring1, NStringP nstring2)
** Exceptions:
*
* This function returns true if the specified nstrings have the same content
* (ignoring differences in case), and false otherwise.
*
** Function: BoolT nstring_contains(NStringP nstring, char c)
** Exceptions:
*
* This function returns true if the specified nstring contains the specified
* character, and false otherwise.
*
** Function: BoolT nstring_is_prefix(NStringP nstring1, NStringP nstring2)
** Exceptions:
*
* This function returns true if the second nstring is a prefix of the first
* nstring, and false otherwise.
*
** Function: void nstring_destroy(NStringP nstring)
** Exceptions:
*
* This function deallocates the contents of the specified nstring.
*
** Function: void write_nstring(OStreamP stream, NStringP nstring)
** Exceptions: XX_dalloc_no_memory, XX_ostream_write_error
*
* This function writes the content of the specified nstring to the specified
* ostream.
*
** Function: void dstring_init(DStringP dstring)
** Exceptions: XX_dalloc_no_memory
*
* This function initialises the specified dstring to be an empty dstring.
*
** Function: unsigned dstring_length(DStringP dstring)
** Exceptions:
*
* This function returns the length of the specified dstring.
*
** Function: void dstring_append_char(DStringP dstring, char c)
** Exceptions: XX_dalloc_no_memory
*
* This function appends the specified character to the specified dstring.
*
** Function: void dstring_append_cstring(DStringP dstring, CStringP cstring
** Exceptions: XX_dalloc_no_memory
*
* This function appends the content of the specified cstring to the specified
* dstring.
*
** Function: void dstring_append_nstring(DStringP dstring, NStringP nstring
** Exceptions: XX_dalloc_no_memory
*
* This function appends the content of the specified nstring to the specified
* dstring.
*
** Function: BoolT dstring_last_char_equal(DStringP dstring, char c)
** Exceptions:
*
* This function returns true if the last character of the specified dstring
* is the same as the specified character, and false otherwise. If the
* dstring is empty, then false is always returned.
*
** Function: void dstring_to_nstring(DStringP dstring, NStringP nstring_ref)
** Exceptions: XX_dalloc_no_memory
*
* This function copies the content of the specified dstring into the
* specified nstring.
*
** Functions: CStringP dstring_to_cstring(DStringP dstring)
** Exceptions: XX_dalloc_no_memory
*
* This function copies the content of the specified dstring into a
* dynamically allocated cstring, and returns it.
*
** Function: CStringP dstring_destroy_to_cstring(DStringP dstring)
** Exceptions: XX_dalloc_no_memory
*
* This function does the equivalent of a call to ``dstring_to_cstring''
* followed by a call to ``dstring_destroy''. It returns a cstring that is
* normally the internal cstring of the dstring (if there isn't enough room
* for a null character at the end, then the cstring will need to be
* reallocated).
*
** Function: void dstring_destroy(DStringP dstring)
** Exceptions:
*
* This function deallocates the contents of the specified dstring.
*
**** Change log:
* $Log: dstring.h,v $
* Revision 1.1.1.1 1998/01/17 15:57:17 release
* First version to be checked into rolling release.
*
* Revision 1.2 1994/12/12 11:44:35 smf
* Performing changes for 'CR94_178.sid+tld-update' - bringing in line with
* OSSG C Coding Standards.
*
* Revision 1.1.1.1 1994/07/25 16:05:49 smf
* Initial import of library shared files.
*
**/
/****************************************************************************/
#ifndef H_DSTRING
#define H_DSTRING
#include "os-interface.h"
#include "cstring.h"
#include "dalloc.h"
#include "ostream.h"
/*--------------------------------------------------------------------------*/
typedef struct NStringT {
unsigned length;
CStringP contents;
} NStringT, *NStringP;
typedef struct DStringT {
unsigned length;
unsigned max_length;
CStringP contents;
} DStringT, *DStringP;
/*--------------------------------------------------------------------------*/
extern void nstring_init
(NStringP);
extern void nstring_init_length
(NStringP, unsigned);
extern void nstring_assign
(NStringP, NStringP);
extern void nstring_copy_cstring
(NStringP, CStringP);
extern void nstring_insert_cstring
(NStringP, CStringP);
extern void nstring_copy
(NStringP, NStringP);
extern CStringP nstring_to_cstring
(NStringP);
extern unsigned nstring_hash_value
(NStringP);
extern unsigned nstring_length
(NStringP);
extern CStringP nstring_contents
(NStringP);
extern CmpT nstring_compare
(NStringP, NStringP);
extern BoolT nstring_equal
(NStringP, NStringP);
extern BoolT nstring_ci_equal
(NStringP, NStringP);
extern BoolT nstring_contains
(NStringP, char);
extern BoolT nstring_is_prefix
(NStringP, NStringP);
extern void nstring_destroy
(NStringP);
extern void write_nstring
(OStreamP, NStringP);
extern void dstring_init
(DStringP);
extern unsigned dstring_length
(DStringP);
extern void dstring_append_char
(DStringP, char);
extern void dstring_append_cstring
(DStringP, CStringP);
extern void dstring_append_nstring
(DStringP, NStringP);
extern BoolT dstring_last_char_equal
(DStringP, char);
extern void dstring_to_nstring
(DStringP, NStringP);
extern CStringP dstring_to_cstring
(DStringP);
extern CStringP dstring_destroy_to_cstring
(DStringP);
extern void dstring_destroy
(DStringP);
/*--------------------------------------------------------------------------*/
#ifdef FS_FAST
#define nstring_length(s) ((s)->length)
#define nstring_contents(s) ((s)->contents)
#define dstring_length(s) ((s)->length)
#endif /* defined (FS_FAST) */
#endif /* !defined (H_DSTRING) */
/*
* Local variables(smf):
* eval: (include::add-path-entry "../os-interface" "../generated")
* end:
**/