Home Libraries Author Links

Abstract Data Type StmDstr
[Dvec: Dynamic Vectors and Character Strings]

Collaboration diagram for Abstract Data Type StmDstr:

Detailed Description

StmDstr is an abstract data type for dynamic character strings.

A StmDstr object realizes a character string of concepually arbitrary length. It is created by one of the functions stmDstrSave(), stmDstrResize(), stmDstrIns(), stmDstrChIns(), stmDstrApp(), stmDstrChApp(), stmDstrPrintf() and stmFgetDstr(). Elements of such a dynamic character string can be accessed exactly like normal character strings, that is to say the ith character of a dynamic character string dstr of length len is dstr [i] or * (dstr + i) and it is guaranteed that dest [len] is the null character.

Dynamic character strings cannot be obtained by other means as by the functions mentioned above and as they are implemented as dynamic char vectors, they have to be deallocated by stmDvecFree().


Constants for stmFgetDstr

Constants for stmFgetDstr().

For readibility reasons the following constants should be used as values of the parameters noNl and overWrite of stmFgetDstr().

#define StmFgdPreserveNl   StmFalse
 noNl == StmFalse
#define StmFgdStripNl   StmTrue
 noNl == StmTrue
#define StmFgdAppend   StmFalse
 overWrite == StmFalse
#define StmFgdNew   StmTrue
 overWrite == StmTrue

Functions

char * stmDstrSave (const char *str, int len)
 Creation of a new dynamic string.
int stmDstrLen (const char *dstr)
 Return the length of the dynamic string dstr.
char * stmDstrResize (char *dstr, int len)
 Resize the dynamic string dstr.
char * stmDstrDel (char *dstr, unsigned start, unsigned count)
 Delete characters of the dynamic string dstr.
char * stmDstrIns (char *dstr, unsigned start, const char *str, unsigned count)
 Insert characters into the dynamic string dstr.
char * stmDstrChIns (char *dstr, unsigned start, char ch)
 Insert one character into the dynamic string dstr.
char * stmDstrApp (char *dstr, const char *str, unsigned count)
 Append characters to the dynamic string dstr.
char * stmDstrChApp (char *dstr, char ch)
 Append one character to the dynamic string dstr.
char * stmDstrReplace (char *dstr, unsigned start, unsigned rcount, const char *str, unsigned count)
 Replace a part of the dynamic string dstr.
char * stmDstrPrintf (char *dstr, const char *format,...)
 Copy arguments according with format to the dynamic string dstr.
char * stmDstrVfprintf (char *dstr, const char *format, va_list arg)
 Copy arguments according with format to the dynamic string dstr.
char * stmFgetDstr (FILE *fp, char *dstr, StmBool noNl, StmBool overWrite)
 Copy one line from the stream fp to the dynamic string dstr.


Define Documentation

#define StmFgdPreserveNl   StmFalse

noNl == StmFalse

Definition at line 566 of file dvec.h.

#define StmFgdStripNl   StmTrue

noNl == StmTrue

Examples:
matchtst.c.

Definition at line 567 of file dvec.h.

#define StmFgdAppend   StmFalse

overWrite == StmFalse

Definition at line 568 of file dvec.h.

#define StmFgdNew   StmTrue

overWrite == StmTrue

Examples:
matchtst.c.

Definition at line 569 of file dvec.h.


Function Documentation

char* stmDstrSave ( const char *  str,
int  len 
)

Creation of a new dynamic string.

The function stmDstrSave allocates a dynamic string of length len and initializes it with the first len characters of the string str. If str is the NULL pointer, nevertheless space for a dynamic string of length len is allocated and the len characters are initialized with NULL bytes. If len is 0, it is assumed that str is a NULL terminated string and a dynamic string of its length is allocated.

On success a pointer to the allocated string is returned. On error the NULL pointer is returned, and the variable errno reflects the error's cause.

Examples:
cuglify.c.

Referenced by newfile().

int stmDstrLen ( const char *  dstr  ) 

Return the length of the dynamic string dstr.

The function stmDstrLen returns the length of the dynamic string dstr. If dstr is the NULL pointer, 0 is returned, and on error (for example, if dstr does not point to a valid dynamic string) -1 is returned.

Examples:
cuglify.c.

Referenced by readline().

char* stmDstrResize ( char *  dstr,
int  len 
)

Resize the dynamic string dstr.

The function stmDstrResize adjusts the length of the dynamic string dstr to len. If len is less than the current string length, the string is shortened, if it is greater, NULL characters are appended. If dstr is the NULL pointer, a new string is allocated.

On success a char pointer to the 0th element of the (possibly relocated) string is returned. On error the NULL pointer is returned and the varable errno reflects the error's cause. On return the original pointer dstr is invalid.

char* stmDstrDel ( char *  dstr,
unsigned  start,
unsigned  count 
)

Delete characters of the dynamic string dstr.

The function stmDstrDel deletes, beginning at the character position start, count characters of the dynamic string dvec. Trailing characters are moved count index positions in direction to the beginning of the string. If count is 0, all characters beginning with character position start to the end of the string are deleted. On error, or if dstr is the NULL pointer, the NULL pointer is returned, else a char pointer to the 0th character of the (possibly relocated) string. On return the original pointer dstr is invalid.

On error the variable errno reflects the error's cause.

Examples:
cuglify.c, and matchtst.c.

Referenced by cnlout(), commout(), flushout(), gatherout(), mkCtrl(), out(), pout(), and readline().

char* stmDstrIns ( char *  dstr,
unsigned  start,
const char *  str,
unsigned  count 
)

Insert characters into the dynamic string dstr.

The function stmDstrIns copies, beginning at character position start, len - start characters of the dynamic string dstr of length len n character positions towards the string's rear end prolongating the string by n characters. The value len - start must not be negative. If str is the NULL pointer or if count is greater than 0, count is the number n of character positions. Otherwise, that is to say, if str is not the NULL pointer but count is 0, it is assumed that str points to a NULL terminated string whose length determines the number n of character positions. If str is not the NULL pointer, then the first n characters of the string str are copied to the n characters of string dstr beginning at character position start. Else the

                            min (n, len - \a start)
characters beginning at character position start remain unchanged and the
                            max (0, n - len + \a start)
characters folowing them are initialized with 0 characters. If dstr is the NULL pointer and start is 0, a new dynamic string is allocated. Either none of the characters to be copied to dstr shall be originated in dstr or else all these characters shall stem from dstr.

On success a char pointer to the 0th character of the (possibly relocated) dynamic string is returned. On error the NULL pointer is returned and the variable errno reflects the error's cause. On return the original pointer dstr is invalid.

char* stmDstrChIns ( char *  dstr,
unsigned  start,
char  ch 
)

Insert one character into the dynamic string dstr.

The function stmDstrChIns inserts the character ch into the dynamic string dstr at character position start. If dstr is the NULL pointer and start is 0, a new dynamic string is allocated. All original characters from beginning at character position start are moved one character position towards the rear end of the string.

On success a char pointer to the 0th character of the (possibly relocated) dynamic string is returned. On error the NULL pointer is returned and the variable errno reflects the error's cause. On return the original pointer dstr is invalid.

char* stmDstrApp ( char *  dstr,
const char *  str,
unsigned  count 
)

Append characters to the dynamic string dstr.

The function stmDstrApp extends the length of the dynamic string dstr by a number n of characters. If str is the NULL pointer, or if count is greater than 0, count determines the number n of characters. Otherwise, that is to say if str is not the NULL pointer but count is 0, it is assumed that str points to a dynamic string whose length determines the number n of characters. If str is not the NULL pointer, then the first n characters of the string str are copied to the appended characters of dstr. Else these characters are initialized with 0 bytes. If dstr is the NULL pointer, a new dynamic string of length n is allocated. Either none of the characters to be copied to dstr shall be originated in dstr or else all these characters shall stem from dstr.

On success a char pointer to the 0th character of the (possibly relocated) dynamic string is returned. On error the NULL pointer is returned and the variable errno reflects the error's cause. On return the original pointer dstr is invalid.

Examples:
cuglify.c.

Referenced by cnlout(), and gatherout().

char* stmDstrChApp ( char *  dstr,
char  ch 
)

Append one character to the dynamic string dstr.

The function stmDstrChApp appends the character ch to the dynamic string dstr increasing its length by 1. If dstr is the NULL pointer, a new dynamic string is allocated.

On success a char pointer to the 0th character of the (possibly relocated) dynamic string is returned. On error the NULL pointer is returned and the variable errno reflects the error's cause. On return the original pointer dstr is invalid.

Examples:
cuglify.c.

Referenced by readline().

char* stmDstrReplace ( char *  dstr,
unsigned  start,
unsigned  rcount,
const char *  str,
unsigned  count 
)

Replace a part of the dynamic string dstr.

The function stmDstrReplace replaces the part of length rcount, beginning at character position start, of the dynamic string dstr with the count characters of str determined as in stmDstrIns(). If dstr is the NULL pointer and start and rcount are 0, a new dynamic string is allocated. Either none of the characters to be copied to dstr shall be originated in dstr or else all these characters shall stem from dstr.

On success a char pointer to the 0th character of the (possibly relocated) dynamic string is returned. On error the NULL pointer is returned and the variable errno reflects the error's cause. On return the original pointer dstr is invalid.

char* stmDstrPrintf ( char *  dstr,
const char *  format,
  ... 
)

Copy arguments according with format to the dynamic string dstr.

The function stmDstrPrintf has the same semantics as the ANSI C function sprintf with the difference that the target string dstr is a dynamic string. If it is the NULL pointer, a new dynamic string is created, else dstr is deleted before printing to it. Also differing from the ANSI C function sprintf, the return value is not the number of characters printed, but a char pointer to the 0th character of the (possibly relocated) dynamic target string.

On error the NULL pointer is returned and the variable errno reflects the error's cause. On return the original pointer dstr is invalid.

char* stmDstrVfprintf ( char *  dstr,
const char *  format,
va_list  arg 
)

Copy arguments according with format to the dynamic string dstr.

The function stmDstrPrintf has the same semantics as the ANSI C function vsprintf with the difference that the target string dstr is a dynamic string. If it is the NULL pointer, a new dynamic string is created, else dstr is deleted before printing to it. Also differing from the ANSI C function sprintf, the return value is not the number of characters printed, but a char pointer to the 0th character of the (possibly relocated) dynamic target string.

On error the NULL pointer is returned and the variable errno reflects the error's cause. On return the original pointer dstr is invalid.

char* stmFgetDstr ( FILE *  fp,
char *  dstr,
StmBool  noNl,
StmBool  overWrite 
)

Copy one line from the stream fp to the dynamic string dstr.

The function stmFgetDstr reads a line from the stream referred to by fp and writes it to the dynamic string dvec. If dvec is the NULL pointer, a new dynamic string is allocated. If the parameter noNl is StmTrue, a newline character terminating the line is replaced by a null character, else not. If the parameter overWrite is StmTrue, the dynamic string dstr is deleted before printing to it, else the line is appended to it.

If a line has been read sucessfully, a char pointer to the 0th character of the (possibly relocated) dynamic string is returned and the original pointer dstr is invalid. Otherwise either the end of file is reached, or a file or other error has occurred. Then the NULL pointer is returned. On return with the NULL pointer

                        feof (fp) != 0
denotes end of file and
                        ferror (fp) != 0
denotes a file error. If a file error occurred, dstr remains valid. If on return with the NULL pointer none of the above conditions is fulfilled, another error occurred (for instance not enough memory). Also in this case the original pointer dstr is invalid.

On error the variable errno reflects the error's cause.

Examples:
matchtst.c.


© Copyright Tom Michaelis 2002-2007

Distributed under the SysToMath Software License (See the accompanying file license.txt or a copy at www.SysToMath.com).