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