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]	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]	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]

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]

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