chiark - git - mdw - mLib/blob - man/str.3

   1 .\" -*-nroff-*-
   2 .de VS
   3 .sp 1
   4 .in +5n
   5 .ft B
   6 .nf
   7 ..
   8 .de VE
   9 .ft R
  10 .in -5n
  11 .sp 1
  12 .fi
  13 ..
  14 .TH str 3mLib "20 June 1999" mLib
  15 .SH NAME
  16 str \- small string utilities
  17 .SH SYNOPSIS
  18 .nf
  19 .B "#include <mLib/str.h>"
  20
  21 .BI "char *str_getword(char **" pp );
  22 .BI "size_t str_split(char *" p ", char *" v "[], size_t " c ", char **" rest );
  23 .BI "void str_sanitize(char *" d ", const char *" p ", size_t " sz );
  24 .fi
  25 .SH DESCRIPTION
  26 The header file
  27 .B <mLib/str.h>
  28 contains a few small utility functions for manipulating null-terminated
  29 strings.
  30 .PP
  31 The function
  32 .B str_getword
  33 extracts the next whitespace-delimited word from a string.  The
  34 function's argument,
  35 .IR pp ,
  36 is the address of a pointer into the string: this pointer is updated by
  37 .B str_getword
  38 so that it can extract the following word on the next call and so on.
  39 The return value is the address of the next word, appropriately null
  40 terminated.  A null pointer is returned if the entire remainder of the
  41 string is whitespace.  Note that
  42 .B str_getword
  43 modifies the string as it goes, to null-terminate the individual words.
  44 .PP
  45 The function
  46 .B str_split
  47 divides a string into whitespace-separated words.  The arguments are as
  48 follows:
  49 .TP
  50 .I p
  51 The address of the string to split.  The string is modified by having
  52 null terminators written after each word extracted.
  53 .TP
  54 .I v
  55 The address of an array of pointers to characters.  This array will be
  56 filled in by
  57 .BR str_split :
  58 the first entry will point to the first word extracted from the string,
  59 and so on.  If there aren't enough words in the string, the remaining
  60 array elements are filled with null pointers.
  61 .TP
  62 .I c
  63 The maxmimum number of words to extract; also, the number of elements in
  64 the array
  65 .IR v .
  66 .TP
  67 .I rest
  68 The address of a pointer in which to store the address of the remainder
  69 of the string.  Leading whitespace is removed from the remainder before
  70 storing.  If the remainder string is empty, a null pointer is stored
  71 instead.  If
  72 .I rest
  73 is null, the remainder pointer is discarded.
  74 .PP
  75 The return value of
  76 .B str_split
  77 is the number of words extracted from the input string.
  78 .PP
  79 The function
  80 .B str_sanitize
  81 copies at most
  82 .I sz \- 1
  83 characters from the string
  84 .I p
  85 to
  86 .IR d .
  87 The result string is null terminated.  Any nonprinting characters in
  88 .I p
  89 are replaced by an underscore
  90 .RB ` _ '
  91 when written to
  92 .IR d .
  93 .SH EXAMPLES
  94 Given the code
  95 .VS
  96 char p[] = " alpha  beta gamma   delta ";
  97 char *v[3];
  98 size_t n;
  99 char *q;
 100
 101 n = str_split(p, v, 3, &q);
 102 .VE
 103 following the call to
 104 .BR str_split ,
 105 .B n
 106 will have the value 3,
 107 .B v[0]
 108 will point to
 109 .RB ` alpha ',
 110 .B v[1]
 111 will point to
 112 .RB ` beta ',
 113 .B v[2]
 114 will point to
 115 .RB ` gamma '
 116 and
 117 .B rest
 118 will point to
 119 .RB ` delta\  '
 120 (note the trailing space).
 121 .PP
 122 Similarly, given the string
 123 .B """\ alpha\ \ beta\ """
 124 instead,
 125 .B n
 126 will be assigned the value 2,
 127 .B v[0]
 128 and
 129 .B v[1]
 130 will have the same values as last time, and
 131 .B v[2]
 132 and
 133 .B rest
 134 will be null.
 135 .SH AUTHOR
 136 Mark Wooding, <mdw@nsict.org>