LayOut C API

- Main Page
- Related Pages
- Data Structures
- Files

- Data Structures
- Data Structure Index
- Data Fields

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
Related Functions
SUStringRef Struct Reference

Stores a Unicode string for use as output string parameters in the API. More...

`#include <unicodestring.h>`

## Related Functions
(Note that these are not member functions.)
SU_RESULT | SUStringCreate (SUStringRef *out_string_ref)
| Creates an empty string. More...
SU_RESULT | SUStringCreateFromUTF8 (SUStringRef *out_string_ref, const char *char_array)
| Creates a string from a UTF-8 string. More...
SU_RESULT | SUStringCreateFromUTF16 (SUStringRef *out_string_ref, const unichar *char_array)
| Creates a string from a UTF-16 string. More...
SU_RESULT | SUStringRelease (SUStringRef *string_ref)
| Deletes a string object. More...
SU_RESULT | SUStringGetUTF8Length (SUStringRef string_ref, size_t *out_length)
| Get the number of 8-bit characters required to store this string. More...
SU_RESULT | SUStringGetUTF16Length (SUStringRef string_ref, size_t *out_length)
| Get the number of 16-bit characters required to store this string. More...
SU_RESULT | SUStringSetUTF8 (SUStringRef string_ref, const char *char_array)
| Sets the value of a string from a NULL-terminated UTF-8 character array. More...
SU_RESULT | SUStringSetUTF16 (SUStringRef string_ref, const unichar *char_array)
| Sets the value of a string from a NULL-terminated UTF-16 character array. More...
SU_RESULT | SUStringGetUTF8 (SUStringRef string_ref, size_t char_array_length, char *out_char_array, size_t *out_number_of_chars_copied)
| Writes the contents of the string into the provided character array. More...
SU_RESULT | SUStringGetUTF16 (SUStringRef string_ref, size_t char_array_length, unichar *out_char_array, size_t *out_number_of_chars_copied)
| Writes the contents of the string into the provided wide character array. More...
SU_RESULT | SUStringTrimLeft (SUStringRef string_ref)
| Trim leading white spaces from the string. More...
SU_RESULT | SUStringTrimRight (SUStringRef string_ref)
| Trim tailing white spaces from the string. More...
SU_RESULT | SUStringCompare (SUStringRef a, SUStringRef b, int *result)
| Compares two strings. More...

## Detailed Description

Stores a Unicode string for use as output string parameters in the API.

## Friends And Related Function Documentation

SU_RESULT SUStringCompare | ( | SUStringRef | a,
|  | SUStringRef | b,
|  | int * | result
| ) |  |
| related

Compares two strings.

Since
  SketchUp 2017, API 5.0

Parameters

  [in] | a | The first string object.
  [in] | b | The second string object.
  [out] | result | The comparison result. 0 for equal, -1 for less than, 1 for greater than.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if string_a or string_b do not refer to a valid string
  - SU_ERROR_NULL_POINTER_OUTPUT if result is NULL

SU_RESULT SUStringCreate | ( | SUStringRef * | out_string_ref | ) |
| related

Creates an empty string.

Constructs a string and initializes it to "", an empty string. You must use SUStringRelease() on this string object to free its memory.

Parameters

  [out] | out_string_ref | The string object to be created.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_NULL_POINTER_OUTPUT if `out_string_ref` is `NULL`
  - SU_ERROR_OVERWRITE_VALID if *`out_string_ref` does not refer to an invalid object

SU_RESULT SUStringCreateFromUTF16 | ( | SUStringRef * | out_string_ref,
|  | const unichar * | char_array
| ) |  |
| related

Creates a string from a UTF-16 string.

Constructs a string and initializes it to a copy of the provided string, which is provided by a 0 (`NULL`) terminated array of 16-bit characters. This string is interpreted as UTF-16. You must use SUStringRelease() on this string object to free its memory.

Parameters

  [out] | out_string_ref | The string object to be created
  [in] | char_array | A NULL-terminated UTF-16 string that initializes the string

Returns
  - SU_ERROR_NONE on Success
  - SU_ERROR_NULL_POINTER_INPUT if `char_array` is `NULL`
  - SU_ERROR_NULL_POINTER_OUTPUT if `out_string_ref` is `NULL`
  - SU_ERROR_OVERWRITE_VALID if *`out_string_ref` does not refer to an invalid object

SU_RESULT SUStringCreateFromUTF8 | ( | SUStringRef * | out_string_ref,
|  | const char * | char_array
| ) |  |
| related

Creates a string from a UTF-8 string.

Constructs a string and initializes it to a copy of the provided string, which is provided by a `'\0'` (`NULL`) terminated array of 8-bit characters. This string is interpreted as UTF-8. You must use SUStringRelease() on this string object to free its memory.

Parameters

  [out] | out_string_ref | The string object to be created
  [in] | char_array | A NULL-terminated UTF-8 (or ASCII) string that initializes the string.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_NULL_POINTER_INPUT if `char_array` is `NULL`
  - SU_ERROR_NULL_POINTER_OUTPUT if `out_string_ref` is `NULL`
  - SU_ERROR_OVERWRITE_VALID if *`out_string_ref` does not refer to an invalid object

SU_RESULT SUStringGetUTF16 | ( | SUStringRef | string_ref,
|  | size_t | char_array_length,
|  | unichar * | out_char_array,
|  | size_t * | out_number_of_chars_copied
| ) |  |
| related

Writes the contents of the string into the provided wide character array.

This function does not allocate memory. You must provide an array of sufficient length to get the entire string. The output string will be NULL terminated.

Parameters

  [in] | string_ref | The string object.
  [in] | char_array_length | The length of the given character array.
  [out] | out_char_array | The character array to be filled in.
  [out] | out_number_of_chars_copied | The number of characters returned.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if string_ref does not refer to a valid string
  - SU_ERROR_NULL_POINTER_OUTPUT : out_char_array or out_number_of_chars_copied is NULL

SU_RESULT SUStringGetUTF16Length | ( | SUStringRef | string_ref,
|  | size_t * | out_length
| ) |  |
| related

Get the number of 16-bit characters required to store this string.

Gives you the length of the string when encoded in UTF-16. This may be larger than the number of glyphs when multiple values are required. This value does not include the space for a 0 (`NULL`) terminator value at the end of the string. It is a good idea when using this function with SUStringGetUTF16() to add one to `out_length`.

Parameters

  [in] | string_ref | The string object.
  [out] | out_length | The length returned.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if `string_ref` does not refer to a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if `out_length` is `NULL`

SU_RESULT SUStringGetUTF8 | ( | SUStringRef | string_ref,
|  | size_t | char_array_length,
|  | char * | out_char_array,
|  | size_t * | out_number_of_chars_copied
| ) |  |
| related

Writes the contents of the string into the provided character array.

This function does not allocate memory. You must provide an array of sufficient length to get the entire string. The output string will be `NULL` terminated.

Parameters

  [in] | string_ref | The string object.
  [in] | char_array_length | The length of the given character array.
  [out] | out_char_array | The character array to be filled in.
  [out] | out_number_of_chars_copied | The number of characters returned.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if `string_ref` does not refer to a valid string
  - SU_ERROR_NULL_POINTER_OUTPUT : `out_char_array` or `out_number_of_chars_copied` is `NULL`

SU_RESULT SUStringGetUTF8Length | ( | SUStringRef | string_ref,
|  | size_t * | out_length
| ) |  |
| related

Get the number of 8-bit characters required to store this string.

Gives you the length of the string when encoded in UTF-8. This may be larger than the number of glyphs when multiple bytes are required. This value does not include the space for a '\0' (`NULL`) terminator value at the end of the string. It is a good idea when using this function with SUStringGetUTF8() to add one to `out_length`.

Parameters

  [in] | string_ref | The string object.
  [out] | out_length | The length returned.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if `string_ref` does not refer to a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if `out_length` is `NULL`

SU_RESULT SUStringRelease | ( | SUStringRef * | string_ref | ) |
| related

Deletes a string object.

You must use SUStringRelease() when a SUStringRef object is no longer in use. *string_ref is deleted and the reference is made invalid. (Calling SUIsInvalid(*string_ref) would evaluate true.)

Parameters

  [in,out] | string_ref | The string object to be deleted.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_NULL_POINTER_INPUT if `string_ref` is `NULL`
  - SU_ERROR_INVALID_INPUT if *`string_ref` does not refer to a valid object

SU_RESULT SUStringSetUTF16 | ( | SUStringRef | string_ref,
|  | const unichar * | char_array
| ) |  |
| related

Sets the value of a string from a NULL-terminated UTF-16 character array.

Parameters

  [in,out] | string_ref | The string object.
  [in] | char_array | The character array to be set.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if `string_ref` does not refer to a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if `char_array` is `NULL`

SU_RESULT SUStringSetUTF8 | ( | SUStringRef | string_ref,
|  | const char * | char_array
| ) |  |
| related

Sets the value of a string from a NULL-terminated UTF-8 character array.

Parameters

  [in,out] | string_ref | The string object.
  [in] | char_array | The character array to be set.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if `string_ref` does not refer to a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if `char_array` is `NULL`

SU_RESULT SUStringTrimLeft | ( | SUStringRef | string_ref | ) |
| related

Trim leading white spaces from the string.

Since
  SketchUp 2017, API 5.0

Parameters

  [in,out] | string_ref | The string object.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if string_ref does not refer to a valid string

SU_RESULT SUStringTrimRight | ( | SUStringRef | string_ref | ) |
| related

Trim tailing white spaces from the string.

Since
  SketchUp 2017, API 5.0

Parameters

  [in,out] | string_ref | The string object.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if string_ref does not refer to a valid string

The documentation for this struct was generated from the following file:

- SketchUpAPI/unicodestring.h