LayOut C API
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
Functions
unicodestring.h File Reference
#include <SketchUpAPI/defs.h>
#include <stddef.h>

Go to the source code of this file.

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

Function Documentation

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

Compares two strings.

Since
SketchUp 2017, API 5.0
Parameters
[in]aThe first string object.
[in]bThe second string object.
[out]resultThe comparison result. 0 for equal, -1 for less than, 1 for greater than.
Returns
SU_RESULT SUStringCreate ( SUStringRef out_string_ref)

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_refThe string object to be created.
Returns
SU_RESULT SUStringCreateFromUTF16 ( SUStringRef out_string_ref,
const unichar char_array 
)

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_refThe string object to be created
[in]char_arrayA null-terminated UTF-16 string that initializes the string
Returns
SU_RESULT SUStringCreateFromUTF8 ( SUStringRef out_string_ref,
const char *  char_array 
)

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_refThe string object to be created
[in]char_arrayA null-terminated UTF-8 (or ASCII) string that initializes the string.
Returns
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.

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_refThe string object.
[in]char_array_lengthThe length of the given character array.
[out]out_char_arrayThe character array to be filled in.
[out]out_number_of_chars_copiedThe number of characters returned.
Returns
SU_RESULT SUStringGetUTF16Length ( SUStringRef  string_ref,
size_t *  out_length 
)

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_refThe string object.
[out]out_lengthThe length returned.
Returns
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.

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_refThe string object.
[in]char_array_lengthThe length of the given character array.
[out]out_char_arrayThe character array to be filled in.
[out]out_number_of_chars_copiedThe number of characters returned.
Returns
SU_RESULT SUStringGetUTF8Length ( SUStringRef  string_ref,
size_t *  out_length 
)

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_refThe string object.
[out]out_lengthThe length returned.
Returns
SU_RESULT SUStringRelease ( SUStringRef string_ref)

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_refThe string object to be deleted.
Returns
SU_RESULT SUStringSetUTF16 ( SUStringRef  string_ref,
const unichar char_array 
)

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

Parameters
[in]string_refThe string object.
[in]char_arrayThe character array to be set.
Returns
SU_RESULT SUStringSetUTF8 ( SUStringRef  string_ref,
const char *  char_array 
)

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

Parameters
[in]string_refThe string object.
[in]char_arrayThe character array to be set.
Returns
SU_RESULT SUStringTrimLeft ( SUStringRef  string_ref)

Trim leading white spaces from the string.

Since
SketchUp 2017, API 5.0
Parameters
[in]string_refThe string object.
Returns
SU_RESULT SUStringTrimRight ( SUStringRef  string_ref)

Trim tailing white spaces from the string.

Since
SketchUp 2017, API 5.0
Parameters
[in]string_refThe string object.
Returns