1\function{SLmake_string}
2\synopsis{Duplicate a string}
3\usage{char *SLmake_string (char *s)}
4\description
5  The \var{SLmake_string} function creates a new copy of the string
6  \var{s}, via \var{malloc}, and returns it.  Upon failure it returns
7  \var{NULL}.  Since the resulting string is malloced, it should be
8  freed when nolonger needed via a call to either \var{free} or
9  \var{SLfree}.
10\notes
11  \var{SLmake_string} should not be confused with the function
12  \var{SLang_create_slstring}, which performs a similar function.
13\seealso{SLmake_nstring, SLfree, SLmalloc, SLang_create_slstring}
14\done
15
16\function{SLmake_nstring}
17\synopsis{Duplicate a substring}
18\usage{char *SLmake_nstring (char *s, unsigned int n)}
19\description
20  This function is like \var{SLmake_string} except that it creates a
21  null terminated string formed from the first \var{n} characters of
22  \var{s}.  Upon failure, it returns \var{NULL}, otherwise it returns
23  the new string.  When nolonger needed, the returned string should be
24  freed with \var{SLfree}.
25\seealso{SLmake_string, SLfree, SLang_create_nslstring}
26\done
27
28\function{SLang_create_nslstring}
29\synopsis{Created a hashed substring}
30\usage{char *SLang_create_nslstring (char *s, unsigned int n)}
31\description
32  \var{SLang_create_nslstring} is like \var{SLang_create_slstring}
33  except that only the first \var{n} characters of \var{s} are used to
34  create the hashed string.  Upon error, it returns \var{NULL}, otherwise it
35  returns the hashed substring.  Such a string must be freed by the
36  function \var{SLang_free_slstring}.
37\notes
38  Do not use \var{free} or \var{SLfree} to free the string returned by
39  \var{SLang_create_slstring} or \var{SLang_create_nslstring}.  Also
40  it is important that no attempt is made to modify the hashed string
41  returned by either of these functions.  If one needs to modify a
42  string, the functions \var{SLmake_string} or \var{SLmake_nstring}
43  should be used instead.
44\seealso{SLang_free_slstring, SLang_create_slstring, SLmake_nstring}
45\done
46
47\function{SLang_create_slstring}
48\synopsis{Create a hashed string}
49\usage{char *SLang_create_slstring (char *s)}
50\description
51  The \var{SLang_create_slstring} creates a copy of \var{s} and
52  returns it as a hashed string.  Upon error, the function returns
53  \var{NULL}, otherwise it returns the hashed string.  Such a string
54  must only be freed via the \var{SLang_free_slstring} function.
55\notes
56  Do not use \var{free} or \var{SLfree} to free the string returned by
57  \var{SLang_create_slstring} or \var{SLang_create_nslstring}.  Also
58  it is important that no attempt is made to modify the hashed string
59  returned by either of these functions.  If one needs to modify a
60  string, the functions \var{SLmake_string} or \var{SLmake_nstring}
61  should be used instead.
62\seealso{SLang_free_slstring, SLang_create_nslstring, SLmake_string}
63\done
64
65\function{SLang_free_slstring}
66\synopsis{Free a hashed string}
67\usage{void SLang_free_slstring (char *s)}
68\description
69  The \var{SLang_free_slstring} function is used to free a hashed
70  string such as one returned by \var{SLang_create_slstring},
71  \var{SLang_create_nslstring}, or \var{SLang_create_static_slstring}.
72  If \var{s} is \var{NULL}, the routine does nothing.
73\seealso{SLang_create_slstring, SLang_create_nslstring, SLang_create_static_slstring}
74\done
75
76\function{SLang_concat_slstrings}
77\synopsis{Concatenate two strings to produce a hashed string}
78\usage{char *SLang_concat_slstrings (char *a, char *b)}
79\description
80  The \var{SLang_concat_slstrings} function concatenates two strings,
81  \var{a} and \var{b}, and returns the result as a hashed string.
82  Upon failure, \var{NULL} is returned.
83\notes
84  A hashed string can only be freed using \var{SLang_free_slstring}.
85  Never use \var{free} or \var{SLfree} to free a hashed string,
86  otherwise memory corruption will result.
87\seealso{SLang_free_slstring, SLang_create_slstring}
88\done
89
90\function{SLang_create_static_slstring}
91\synopsis{Create a hashed string}
92\usage{char *SLang_create_static_slstring (char *s_literal)}
93\description
94  The \var{SLang_create_static_slstring} creates a hashed string from
95  the string literal \var{s_literal} and returns the result.  Upon
96  failure it returns \var{NULL}.
97\example
98#v+
99     char *create_hello (void)
100     {
101        return SLang_create_static_slstring ("hello");
102     }
103#v-
104\notes
105  This function should only be used with string literals.
106\seealso{SLang_create_slstring, SLang_create_nslstring}
107\done
108
109\function{SLmalloc}
110\synopsis{Allocate some memory}
111\usage{char *SLmalloc (unsigned int nbytes)}
112\description
113  This function uses \var{malloc} to allocate \var{nbytes} of memory.
114  Upon error it returns \var{NULL}; otherwise it returns a pointer to
115  the allocated memory.  One should use \var{SLfree} to free the
116  memory after use.
117\seealso{SLfree, SLrealloc, SLcalloc}
118\done
119
120\function{SLcalloc}
121\synopsis{Allocate some memory}
122\usage{char *SLcalloc (unsigned int num_elem, unsigned int elem_size)}
123\description
124  This function uses \var{calloc} to allocate memory for
125  \var{num_elem} objects with each of size \var{elem_size} and returns
126  the result.  In addition, the newly allocated memory is zeroed.
127  Upon error it returns \var{NULL}; otherwise it returns a pointer to
128  the allocated memory.  One should use \var{SLfree} to free the
129  memory after use.
130\seealso{SLmalloc, SLrealloc, SLfree}
131\done
132
133\function{SLfree}
134\synopsis{Free some allocated memory}
135\usage{void SLfree (char *ptr)}
136\description
137  The \var{SLfree} function deallocates the memory specified by
138  \var{ptr}, which may be \var{NULL} in which case the function does
139  nothing.
140\notes
141  Never use this function to free a hashed string returned by one of
142  the family of \var{slstring} functions, e.g.,
143  \var{SLang_pop_slstring}.
144\seealso{SLmalloc, SLcalloc, SLrealloc, SLmake_string}
145\done
146
147\function{SLrealloc}
148\synopsis{Resize a dynamic memory block}
149\usage{char *SLrealloc (char *ptr, unsigned int new_size)}
150\description
151  The \var{SLrealloc} uses the \var{realloc} function to resize the
152  memory block specified by \var{ptr} to the new size \var{new_size}.
153  If \var{ptr} is \var{NULL}, the function call is equivalent to
154  \exmp{SLmalloc(new_size)}.  Similarly, if \var{new_size} is zero,
155  the function call is equivalent to \var{SLfree(ptr)}.
156
157  If the function fails, or if \var{new_size} is zero, \var{NULL} is
158  returned.  Otherwise a pointer is returned to the (possibly moved)
159  new block of memory.
160\seealso{SLfree, SLmalloc, SLcalloc}
161\done
162
163