{The S-Lang C Library Reference}: String and Memory Allocation Functions

Next Previous Contents

## 9. String and Memory Allocation Functions

## 9.1 SLmake_string

Synopsis

  Duplicate a string

Usage

  `char *SLmake_string (char *s)`

Description

  The `SLmake_string` function creates a new copy of the string `s`, via `malloc`, and returns it. Upon failure it returns `NULL`. Since the resulting string is malloced, it should be freed when nolonger needed via a call to either `free` or `SLfree`.

Notes

  `SLmake_string` should not be confused with the function `SLang_create_slstring`, which performs a similar function.

See Also

  `SLmake_nstring, SLfree, SLmalloc, SLang_create_slstring`

## 9.2 SLmake_nstring

Synopsis

  Duplicate a substring

Usage

  `char *SLmake_nstring (char *s, unsigned int n)`

Description

  This function is like `SLmake_nstring` except that it creates a null terminated string formed from the first `n` characters of `s`. Upon failure, it returns `NULL`, otherwise it returns the new string. When nolonger needed, the returned string should be freed with either `free` or `SLfree`.

See Also

  `SLmake_nstring, SLfree, SLang_create_nslstring`

## 9.3 SLang_create_nslstring

Synopsis

  Created a hashed substring

Usage

  `char *SLang_create_nslstring (char *s, unsigned int n)`

Description

  `SLang_create_nslstring` is like `SLang_create_slstring` except that only the first `n` characters of `s` are used to perform the string. Upon error, it returns `NULL`, otherwise it returns the hashed substring. Such a string must be freed by the function `SLang_free_slstring`.

Notes

  Do not use `free` or `SLfree` to free the string returned by `SLang_create_slstring` or `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 `SLmake_string` or `SLmake_nstring` should be used instead.

See Also

  `SLang_free_slstring, SLang_create_slstring, SLmake_nstring`

## 9.4 SLang_create_slstring

Synopsis

  Create a hashed string

Usage

  `char *SLang_create_slstring (char *s)`

Description

  The `SLang_create_slstring` creates a copy of `s` and returns it as a hashed string. Upon error, the function returns `NULL`, otherwise it returns the hashed string. Such a string must only be freed via the `SLang_free_slstring` function.

Notes

  Do not use `free` or `SLfree` to free the string returned by `SLang_create_slstring` or `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 `SLmake_string` or `SLmake_nstring` should be used instead.

See Also

  `SLang_free_slstring, SLang_create_nslstring, SLmake_string`

## 9.5 SLang_free_slstring

Synopsis

  Free a hashed string

Usage

  `void SLang_free_slstring (char *s)`

Description

  The `SLang_free_slstring` function is used to free a hashed string such as one returned by `SLang_create_slstring`, `SLang_create_nslstring`, or `SLang_create_static_slstring`. If `s` is `NULL`, the routine does nothing.

See Also

  `SLang_create_slstring, SLang_create_nslstring, SLang_create_static_slstring`

## 9.6 SLang_concat_slstrings

Synopsis

  Concatenate two strings to produce a hashed string

Usage

  `char *SLang_concat_slstrings (char *a, char *b)`

Description

  The `SLang_concat_slstrings` function concatenates two strings, `a` and `b`, and returns the result as a hashed string. Upon failure, `NULL` is returned.

Notes

  A hashed string can only be freed using `SLang_free_slstring`. Never use either `free` or `SLfree` to free a hashed string, otherwise memory corruption will result.

See Also

  `SLang_free_slstring, SLang_create_slstring`

## 9.7 SLang_create_static_slstring

Synopsis

  Create a hashed string

Usage

  `char *SLang_create_static_slstring (char *s_literal)`

Description

  The `SLang_create_static_slstring` creates a hashed string from the string literal `s_literal` and returns the result. Upon failure it returns `NULL`.

Example

  > `

  >          char *create_hello (void)
  >          {
  >             return SLang_create_static_slstring ("hello");
  >          }

  > `

Notes

  This function should only be used with string literals.

See Also

  `SLang_create_slstring, SLang_create_nslstring`

## 9.8 SLmalloc

Synopsis

  Allocate some memory

Usage

  `char *SLmalloc (unsigned int nbytes)`

Description

  This function uses `malloc` to allocate `nbytes` of memory. Upon error it returns `NULL`; otherwise it returns a pointer to the allocated memory. One should use `SLfree` to free the memory after used.

See Also

  `SLfree, SLrealloc, SLcalloc`

## 9.9 SLcalloc

Synopsis

  Allocate some memory

Usage

  `char *SLcalloc (unsigned int num_elem, unsigned int elem_size)`

Description

  This function uses `calloc` to allocate memory for `num_elem` objects with each of size `elem_size` and returns the result. In addition, the newly allocated memory is zeroed. Upon error it returns `NULL`; otherwise it returns a pointer to the allocated memory. One should use `SLfree` to free the memory after used.

See Also

  `SLmalloc, SLrealloc, SLfree`

## 9.10 SLfree

Synopsis

  Free some allocated memory

Usage

  `void SLfree (char *ptr)`

Description

  The `SLfree` function uses `free` to deallocate the memory specified by `ptr`, which may be `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 `slstring` functions, e.g., `SLang_pop_slstring`.

See Also

  `SLmalloc, SLcalloc, SLrealloc, SLmake_string`

## 9.11 SLrealloc

Synopsis

  Resize a dynamic memory block

Usage

  `char *SLrealloc (char *ptr, unsigned int new_size)`

Description

  The `SLrealloc` uses the `realloc` function to resize the memory block specified by `ptr` to the new size `new_size`. If `ptr` is `NULL`, the function call is equivalent to `SLmalloc(new_size)`. Similarly, if `new_size` is zero, the function call is equivalent to `SLfree(ptr)`.

  If the function fails, or if `new_size` is zero, `NULL` is returned. Otherwise a pointer is returned to the (possibly moved) new block of memory.

See Also

  `SLfree, SLmalloc, SLcalloc`

Next Previous Contents