163 строки
6.4 KiB
Tcl
163 строки
6.4 KiB
Tcl
\function{SLmake_string}
|
|
\synopsis{Duplicate a string}
|
|
\usage{char *SLmake_string (char *s)}
|
|
\description
|
|
The \var{SLmake_string} function creates a new copy of the string
|
|
\var{s}, via \var{malloc}, and returns it. Upon failure it returns
|
|
\var{NULL}. Since the resulting string is malloced, it should be
|
|
freed when nolonger needed via a call to either \var{free} or
|
|
\var{SLfree}.
|
|
\notes
|
|
\var{SLmake_string} should not be confused with the function
|
|
\var{SLang_create_slstring}, which performs a similar function.
|
|
\seealso{SLmake_nstring, SLfree, SLmalloc, SLang_create_slstring}
|
|
\done
|
|
|
|
\function{SLmake_nstring}
|
|
\synopsis{Duplicate a substring}
|
|
\usage{char *SLmake_nstring (char *s, unsigned int n)}
|
|
\description
|
|
This function is like \var{SLmake_string} except that it creates a
|
|
null terminated string formed from the first \var{n} characters of
|
|
\var{s}. Upon failure, it returns \var{NULL}, otherwise it returns
|
|
the new string. When nolonger needed, the returned string should be
|
|
freed with \var{SLfree}.
|
|
\seealso{SLmake_string, SLfree, SLang_create_nslstring}
|
|
\done
|
|
|
|
\function{SLang_create_nslstring}
|
|
\synopsis{Created a hashed substring}
|
|
\usage{char *SLang_create_nslstring (char *s, unsigned int n)}
|
|
\description
|
|
\var{SLang_create_nslstring} is like \var{SLang_create_slstring}
|
|
except that only the first \var{n} characters of \var{s} are used to
|
|
create the hashed string. Upon error, it returns \var{NULL}, otherwise it
|
|
returns the hashed substring. Such a string must be freed by the
|
|
function \var{SLang_free_slstring}.
|
|
\notes
|
|
Do not use \var{free} or \var{SLfree} to free the string returned by
|
|
\var{SLang_create_slstring} or \var{SLang_create_nslstring}. Also
|
|
it is important that no attempt is made to modify the hashed string
|
|
returned by either of these functions. If one needs to modify a
|
|
string, the functions \var{SLmake_string} or \var{SLmake_nstring}
|
|
should be used instead.
|
|
\seealso{SLang_free_slstring, SLang_create_slstring, SLmake_nstring}
|
|
\done
|
|
|
|
\function{SLang_create_slstring}
|
|
\synopsis{Create a hashed string}
|
|
\usage{char *SLang_create_slstring (char *s)}
|
|
\description
|
|
The \var{SLang_create_slstring} creates a copy of \var{s} and
|
|
returns it as a hashed string. Upon error, the function returns
|
|
\var{NULL}, otherwise it returns the hashed string. Such a string
|
|
must only be freed via the \var{SLang_free_slstring} function.
|
|
\notes
|
|
Do not use \var{free} or \var{SLfree} to free the string returned by
|
|
\var{SLang_create_slstring} or \var{SLang_create_nslstring}. Also
|
|
it is important that no attempt is made to modify the hashed string
|
|
returned by either of these functions. If one needs to modify a
|
|
string, the functions \var{SLmake_string} or \var{SLmake_nstring}
|
|
should be used instead.
|
|
\seealso{SLang_free_slstring, SLang_create_nslstring, SLmake_string}
|
|
\done
|
|
|
|
\function{SLang_free_slstring}
|
|
\synopsis{Free a hashed string}
|
|
\usage{void SLang_free_slstring (char *s)}
|
|
\description
|
|
The \var{SLang_free_slstring} function is used to free a hashed
|
|
string such as one returned by \var{SLang_create_slstring},
|
|
\var{SLang_create_nslstring}, or \var{SLang_create_static_slstring}.
|
|
If \var{s} is \var{NULL}, the routine does nothing.
|
|
\seealso{SLang_create_slstring, SLang_create_nslstring, SLang_create_static_slstring}
|
|
\done
|
|
|
|
\function{SLang_concat_slstrings}
|
|
\synopsis{Concatenate two strings to produce a hashed string}
|
|
\usage{char *SLang_concat_slstrings (char *a, char *b)}
|
|
\description
|
|
The \var{SLang_concat_slstrings} function concatenates two strings,
|
|
\var{a} and \var{b}, and returns the result as a hashed string.
|
|
Upon failure, \var{NULL} is returned.
|
|
\notes
|
|
A hashed string can only be freed using \var{SLang_free_slstring}.
|
|
Never use \var{free} or \var{SLfree} to free a hashed string,
|
|
otherwise memory corruption will result.
|
|
\seealso{SLang_free_slstring, SLang_create_slstring}
|
|
\done
|
|
|
|
\function{SLang_create_static_slstring}
|
|
\synopsis{Create a hashed string}
|
|
\usage{char *SLang_create_static_slstring (char *s_literal)}
|
|
\description
|
|
The \var{SLang_create_static_slstring} creates a hashed string from
|
|
the string literal \var{s_literal} and returns the result. Upon
|
|
failure it returns \var{NULL}.
|
|
\example
|
|
#v+
|
|
char *create_hello (void)
|
|
{
|
|
return SLang_create_static_slstring ("hello");
|
|
}
|
|
#v-
|
|
\notes
|
|
This function should only be used with string literals.
|
|
\seealso{SLang_create_slstring, SLang_create_nslstring}
|
|
\done
|
|
|
|
\function{SLmalloc}
|
|
\synopsis{Allocate some memory}
|
|
\usage{char *SLmalloc (unsigned int nbytes)}
|
|
\description
|
|
This function uses \var{malloc} to allocate \var{nbytes} of memory.
|
|
Upon error it returns \var{NULL}; otherwise it returns a pointer to
|
|
the allocated memory. One should use \var{SLfree} to free the
|
|
memory after use.
|
|
\seealso{SLfree, SLrealloc, SLcalloc}
|
|
\done
|
|
|
|
\function{SLcalloc}
|
|
\synopsis{Allocate some memory}
|
|
\usage{char *SLcalloc (unsigned int num_elem, unsigned int elem_size)}
|
|
\description
|
|
This function uses \var{calloc} to allocate memory for
|
|
\var{num_elem} objects with each of size \var{elem_size} and returns
|
|
the result. In addition, the newly allocated memory is zeroed.
|
|
Upon error it returns \var{NULL}; otherwise it returns a pointer to
|
|
the allocated memory. One should use \var{SLfree} to free the
|
|
memory after use.
|
|
\seealso{SLmalloc, SLrealloc, SLfree}
|
|
\done
|
|
|
|
\function{SLfree}
|
|
\synopsis{Free some allocated memory}
|
|
\usage{void SLfree (char *ptr)}
|
|
\description
|
|
The \var{SLfree} function deallocates the memory specified by
|
|
\var{ptr}, which may be \var{NULL} in which case the function does
|
|
nothing.
|
|
\notes
|
|
Never use this function to free a hashed string returned by one of
|
|
the family of \var{slstring} functions, e.g.,
|
|
\var{SLang_pop_slstring}.
|
|
\seealso{SLmalloc, SLcalloc, SLrealloc, SLmake_string}
|
|
\done
|
|
|
|
\function{SLrealloc}
|
|
\synopsis{Resize a dynamic memory block}
|
|
\usage{char *SLrealloc (char *ptr, unsigned int new_size)}
|
|
\description
|
|
The \var{SLrealloc} uses the \var{realloc} function to resize the
|
|
memory block specified by \var{ptr} to the new size \var{new_size}.
|
|
If \var{ptr} is \var{NULL}, the function call is equivalent to
|
|
\exmp{SLmalloc(new_size)}. Similarly, if \var{new_size} is zero,
|
|
the function call is equivalent to \var{SLfree(ptr)}.
|
|
|
|
If the function fails, or if \var{new_size} is zero, \var{NULL} is
|
|
returned. Otherwise a pointer is returned to the (possibly moved)
|
|
new block of memory.
|
|
\seealso{SLfree, SLmalloc, SLcalloc}
|
|
\done
|
|
|