String library
string operators
- STRCopy
- copy a string to another place
- STRCopySafe
- copy a string to another place, as much as possible
- STRLength
- get the length of a string
- STRAppend
- append a string to another string
- STRAppendSafe
- append a string to another string, as much as possible
- STRCompareCD
- compare two strings, Case Dependant (CD)
- STRCompareCI
- compare two strings, Case Independant (CI)
- STRSameCD
- see if two strings are the same CD, faster than compare
- STRSameCI
- see if two strings are the same CI, faster than compare
- STRSearchCD
- search first occurence of on string in another, CD
- STRSearchCI
- search first occurence of on string in another, CD
- STRUpper
- convert a string to upper case
- STRLower
- convert a string to lower case
- STRBreak
- break a string up into a list of pointers to strings
e.g. STRBreak(params,&argv) !!
- STRDuplicate
- duplicate a string
conversion routines
- STRFormatGet
- get data (in variables) using format string
- STRFormatPut
- convert any kind of info to a string
- STRFormatPutSafe
- Safe version of STRFormatPut.
In this routine, the length of the string to be filled
in has to be passed.
standard function
because it is used so often, we have also provided this standard routine.
It does not follow the standard rules for parameter passing and returning
as it returns the length of the string (and not an error).
However, this routine can almost be considered as a builtin function (like
sizeof).
- strlen
- return the length of the string
Format strings :
STRFormatGet
The format string may contain :
- whitespace (' ','\t','\v','\n','\r'). These match with a run of
whitespace characters (this run can be zero length).
- ordinary characters (not '%') which have to match the next
character.
- conversion specifications, which start with a '%', an optional
assignment suppresion character ('*'), an optional number specifying
the maximum field width, and optional 'h', 'l' or 'L' indicating
the with of the target, and a conversion character.
When a '*' is present, then no assignment to an argument is made (and
no argument is needed). An input field is a string of non-whitespace
characters, it extends either to the next whitespace character, or
until the field width is exhausted (or an unrecognized character is
encountered).
The conversion character indicates the interpretation of the input
field. The corresponding argument must be a pointer. If the conversion
character of an integer is preceded by a 'h', the argument is taken as
a pointer to short rather than int, or long instead of int (for 'l').
Conversion characters are :
- char - argument type, input data
- d
- int *; decimal integer
- i
- int *; integer, the integer may be octal (leading '0') or hex
(leading '0x' or '0X')
- o
- int *; octal integer, with or without leading '0'
- u
- unsigned int *; unsigned decimal
- x
- int *; hex integer, with or without '0x' or '0X'
- c
- char *; The next input characters are placed in the indicated
array, up to the number given in the field width, the default
is 1. No terminating '\0' is added !
- s
- char *; read a string of non-whitespace chars (not quoted). A
terminating '\0' will be added. The array pointed to should be
large enough
- e,f,g
- double *; reads a floating point number, which can include a
sign, decimal point and exponent.
- p
- void **; reads a pointer value.
- n
- int *; writes into the argument the number of characters read
so far from the string. Does not increment the count. No chars
from the string are matched.
- [..]
- char *; matches the longest non-empty string of input characters
from the set between brackets. A '\0' is added. [^]..] includes
']' in the set.
- [^..]
- char *; matches the longest non-empty string of input characters
not from the set between brackets. A '\0' is added. [^]..]
includes ']' in the set.
- %
- matches witha '%', no assignment is made.
STRFormatPut and STRFormatPutSafe
The format contains ordinary characters, which are copied to the
string, and conversion specifications, which start with a % character,
and end with a conversion character. In between there may be (in the
order as given here)
- flags (in any order)
- '-'
- indicate left adjustment of the argument in the field
- '+'
- the number will always be printed with a sign
- ' '
- a space will be prefixed when no sign present
- '0'
- zero padding for numeric conversions
- '#'
- alternate output, for o '0' is prefixed, for x and X '0x'
or '0X' is prefixed to non-zero result. For e, E, f, g, G
the output will always contain a decimal point, for g and G
trailing zeros will not be removed.
- a number, indicating the minimum field width. The converted
argument will be printed in a field at least this wide, and wider
if necessary. When the converted argument has fewer characters than
the width, it will be padded on the left (or right in case of left
adjustment). The padding character is normally space, but is 0 if
the zero padding flag is present.
- a period, to seperate the field width from the precision.
- a number, the precision, which specifies the minimum number of
characters to print from a string, or the number of digits after
the decimal point for e, E, f, or the number of significant digits
for g, G conversions, or minimum number of digits to print for an
integer (leading zeros will be added to get the necessary width).
- a length modifier, h, l or L, indicating that the argument is to
be printed as a short ('h'), a long ('l'), or long double ('L').
Width or precision or both may be specified as '*', in which case
the value is calculated by converting the next argument(s), which
must be int.
If an unrecognized character is encountered, it is put in the
string.
Conversion characters are (char - argument type, converted to) :
- d,i
- int; signed decimal
- o
- int; unsigned octal (without leading zero)
- x,X
- int; usigned hex, without '0x', lower case for x, upper for X
- u
- int; unsigned decimal
- c
- int; single character
- s
- char *; characters from the string are printed until a '\0' is
encountered, or the number of chars indicated by precision printed.
- f
- double; decimal notation of the form [-]mmm.ddd, where the number
of d's is given by the precision. The default precision is 6 (or
14 when 'L' is used). A precision of 0 suppresses the decimal point.
- e,E
- double; decimal notation of the form [-]m.dddesxx, where the number
of d's is given by the precision. The default precision is 6 (or
14 when 'L' is used). A precision of 0 suppresses the decimal point.
The e is lower case for 'e', upper for 'E'. The s is the sign of
the exponent.
- g,G
- double; %e or %E is used when the exponent is less than -4 or
greater than or equal to the precision. Otherwise %f is used.
Trailing zeros and trailing decimal point are not printed.
- p
- void *; print as a pointer (hex)
- n
- int *; the number of characters written so far by this call is
filled into the argument. No argument is converted.
- %
- no argument is converted, put '%' in the string.