Rev 2 | Go to most recent revision | Blame | Compare with Previous | Last modification | View Log | RSS feed
/*
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
* PROTO_S ((NStringP nstring))
** Exceptions:
*
* This function initialises the specified nstring to be an empty nstring.
*
** Function: void nstring_init_length
* PROTO_S ((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
* PROTO_S ((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
* PROTO_S ((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
* PROTO_S ((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
* PROTO_S ((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
* PROTO_S ((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
* PROTO_S ((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
* PROTO_S ((NStringP nstring))
** Exceptions:
*
* This function returns the length of the specified nstring.
*
** Function: CStringP nstring_contents
* PROTO_S ((NStringP nstring))
** Exceptions:
*
* This function returns the contents of the specified nstring.
*
** Function: CmpT nstring_compare
* PROTO_S ((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
* PROTO_S ((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
* PROTO_S ((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
* PROTO_S ((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
* PROTO_S ((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
* PROTO_S ((NStringP nstring))
** Exceptions:
*
* This function deallocates the contents of the specified nstring.
*
** Function: void write_nstring
* PROTO_S ((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
* PROTO_S ((DStringP dstring))
** Exceptions: XX_dalloc_no_memory
*
* This function initialises the specified dstring to be an empty dstring.
*
** Function: unsigned dstring_length
* PROTO_S ((DStringP dstring))
** Exceptions:
*
* This function returns the length of the specified dstring.
*
** Function: void dstring_append_char
* PROTO_S ((DStringP dstring, char c))
** Exceptions: XX_dalloc_no_memory
*
* This function appends the specified character to the specified dstring.
*
** Function: void dstring_append_cstring
* PROTO_S ((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
* PROTO_S ((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
* PROTO_S ((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
* PROTO_S ((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
* PROTO_S ((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
* PROTO_S ((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
* PROTO_S ((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:45 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
PROTO_S ((NStringP));
extern void nstring_init_length
PROTO_S ((NStringP, unsigned));
extern void nstring_assign
PROTO_S ((NStringP, NStringP));
extern void nstring_copy_cstring
PROTO_S ((NStringP, CStringP));
extern void nstring_insert_cstring
PROTO_S ((NStringP, CStringP));
extern void nstring_copy
PROTO_S ((NStringP, NStringP));
extern CStringP nstring_to_cstring
PROTO_S ((NStringP));
extern unsigned nstring_hash_value
PROTO_S ((NStringP));
extern unsigned nstring_length
PROTO_S ((NStringP));
extern CStringP nstring_contents
PROTO_S ((NStringP));
extern CmpT nstring_compare
PROTO_S ((NStringP, NStringP));
extern BoolT nstring_equal
PROTO_S ((NStringP, NStringP));
extern BoolT nstring_ci_equal
PROTO_S ((NStringP, NStringP));
extern BoolT nstring_contains
PROTO_S ((NStringP, char));
extern BoolT nstring_is_prefix
PROTO_S ((NStringP, NStringP));
extern void nstring_destroy
PROTO_S ((NStringP));
extern void write_nstring
PROTO_S ((OStreamP, NStringP));
extern void dstring_init
PROTO_S ((DStringP));
extern unsigned dstring_length
PROTO_S ((DStringP));
extern void dstring_append_char
PROTO_S ((DStringP, char));
extern void dstring_append_cstring
PROTO_S ((DStringP, CStringP));
extern void dstring_append_nstring
PROTO_S ((DStringP, NStringP));
extern BoolT dstring_last_char_equal
PROTO_S ((DStringP, char));
extern void dstring_to_nstring
PROTO_S ((DStringP, NStringP));
extern CStringP dstring_to_cstring
PROTO_S ((DStringP));
extern CStringP dstring_destroy_to_cstring
PROTO_S ((DStringP));
extern void dstring_destroy
PROTO_S ((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:
**/