# KIM String Reference Documentation

## Functions

- kim_error kim_string_create_for_last_error (kim_string *out_string, kim_error in_error)
    Get a text description of an error suitable for display to the user.
- kim_error kim_string_copy (kim_string *out_string, const kim_string in_string)
    Copy a string.
- kim_error kim_string_compare (kim_string in_string, kim_string in_compare_to_string, kim_comparison *out_comparison)
    Compare two strings.
- void kim_string_free (kim_string *io_string)
    Free memory associated with a string.

## Function Documentation

kim_error kim_string_create_for_last_error | ( | kim_string * | out_string,
|  | kim_error | in_error |
| ) |  |  |

Get a text description of an error suitable for display to the user.

Parameters:

  | out_string | On success, a human-readable UTF-8 string describing the error representedby in_error. Must be freed with kim_string_free().
  | in_error | an error code. Used to verify that the correct error string will be returned (see note below).

Returns:
  On success, KIM_NO_ERROR.

Note:
  This API is implemented using thread local storage. It should be called immediately after a KIM API returns an error code so that the correct string is returned. The returned copy may then be held by the caller until needed. If in_error does not match the last saved error KIM may return a less descriptive string.

kim_error kim_string_copy | ( | kim_string * | out_string,
|  | const kim_string | in_string |
| ) |  |  |

Copy a string.

Parameters:

  | out_string | on exit, a new string object which is a copy of in_string. Must be freed with kim_string_free().
  | in_string | the string to copy.

Returns:
  On success, KIM_NO_ERROR. On failure, an error code representing the failure.

kim_error kim_string_compare | ( | kim_string | in_string,
|  | kim_string | in_compare_to_string,
|  | kim_comparison * | out_comparison |
| ) |  |  |

Compare two strings.

Parameters:

  | in_string | a string.
  | in_compare_to_string | a string to be compared to in_string.
  | out_comparison | on exit, a comparison result indicating whether in_string is greater than, less than or equal to in_compare_to_string.

Returns:
  On success, KIM_NO_ERROR. On failure, an error code representing the failure.

void kim_string_free | ( | kim_string * | io_string | ) |

Free memory associated with a string.

Parameters:

  | io_string | a string to be freed. Set to NULL on exit.