| --- |
| layout: doc |
| title: "Starboard Module Reference: string.h" |
| --- |
| |
| Defines functions for interacting with c-style strings. |
| |
| ## Functions ## |
| |
| ### SbStringAToI ### |
| |
| Parses a string into a base-10 integer. This is a shorthand replacement for |
| `atoi`. |
| |
| `value`: The string to be converted. |
| |
| #### Declaration #### |
| |
| ``` |
| static int SbStringAToI(const char *value) |
| ``` |
| |
| ### SbStringAToL ### |
| |
| Parses a string into a base-10, long integer. This is a shorthand replacement |
| for `atol`. |
| |
| `value`: The string to be converted. NOLINTNEXTLINE(runtime/int) |
| |
| #### Declaration #### |
| |
| ``` |
| static long SbStringAToL(const char *value) |
| ``` |
| |
| ### SbStringCompare ### |
| |
| Compares the first `count` characters of two 8-bit character strings. The return |
| value is: |
| |
| * `< 0` if `string1` is ASCII-betically lower than `string2`. |
| |
| * `0` if the two strings are equal. |
| |
| * `> 0` if `string1` is ASCII-betically higher than `string2`. |
| |
| This function is meant to be a drop-in replacement for `strncmp`. |
| |
| `string1`: The first 8-bit character string to compare. `string2`: The second |
| 8-bit character string to compare. `count`: The number of characters to compare. |
| |
| #### Declaration #### |
| |
| ``` |
| int SbStringCompare(const char *string1, const char *string2, size_t count) |
| ``` |
| |
| ### SbStringCompareAll ### |
| |
| Compares two entire 8-bit character strings. The return value is: |
| |
| * `< 0` if `string1` is ASCII-betically lower than `string2`. |
| |
| * `0` if the two strings are equal. |
| |
| * `> 0` if `string1` is ASCII-betically higher than `string2`. |
| |
| This function is meant to be a drop-in replacement for `strcmp`. |
| |
| `string1`: The first 8-bit character string to compare. `string2`: The second |
| 8-bit character string to compare. |
| |
| #### Declaration #### |
| |
| ``` |
| int SbStringCompareAll(const char *string1, const char *string2) |
| ``` |
| |
| ### SbStringCompareNoCase ### |
| |
| Compares two strings, ignoring differences in case. The return value is: |
| |
| * `< 0` if `string1` is ASCII-betically lower than `string2`. |
| |
| * `0` if the two strings are equal. |
| |
| * `> 0` if `string1` is ASCII-betically higher than `string2`. |
| |
| This function is meant to be a drop-in replacement for `strcasecmp`. |
| |
| `string1`: The first string to compare. `string2`: The second string to compare. |
| |
| #### Declaration #### |
| |
| ``` |
| int SbStringCompareNoCase(const char *string1, const char *string2) |
| ``` |
| |
| ### SbStringCompareNoCaseN ### |
| |
| Compares the first `count` characters of two strings, ignoring differences in |
| case. The return value is: |
| |
| * `< 0` if `string1` is ASCII-betically lower than `string2`. |
| |
| * `0` if the two strings are equal. |
| |
| * `> 0` if `string1` is ASCII-betically higher than `string2`. |
| |
| This function is meant to be a drop-in replacement for `strncasecmp`. |
| |
| `string1`: The first string to compare. `string2`: The second string to compare. |
| `count`: The number of characters to compare. |
| |
| #### Declaration #### |
| |
| ``` |
| int SbStringCompareNoCaseN(const char *string1, const char *string2, size_t count) |
| ``` |
| |
| ### SbStringCompareWide ### |
| |
| Compares the first `count` characters of two 16-bit character strings. The |
| return value is: |
| |
| * `< 0` if `string1` is ASCII-betically lower than `string2`. |
| |
| * `0` if the two strings are equal. |
| |
| * `> 0` if `string1` is ASCII-betically higher than `string2`. |
| |
| This function is meant to be a drop-in replacement for `wcsncmp`. |
| |
| `string1`: The first 16-bit character string to compare.weird `string2`: The |
| second 16-bit character string to compare. `count`: The number of characters to |
| compare. |
| |
| #### Declaration #### |
| |
| ``` |
| int SbStringCompareWide(const wchar_t *string1, const wchar_t *string2, size_t count) |
| ``` |
| |
| ### SbStringConcat ### |
| |
| Appends `source` to `out_destination` as long as `out_destination` has enough |
| storage space to hold the concatenated string. |
| |
| This function is meant to be a drop-in replacement for `strlcat`. Also note that |
| this function's signature is NOT compatible with `strncat`. |
| |
| `out_destination`: The string to which the `source` string is appended. |
| `source`: The string to be appended to the destination string. |
| `destination_size`: The amount of storage space available for the concatenated |
| string. |
| |
| #### Declaration #### |
| |
| ``` |
| int SbStringConcat(char *out_destination, const char *source, int destination_size) |
| ``` |
| |
| ### SbStringConcatUnsafe ### |
| |
| An inline wrapper for an unsafe SbStringConcat that assumes that the |
| `out_destination` provides enough storage space for the concatenated string. |
| Note that this function's signature is NOT compatible with `strcat`. |
| |
| `out_destination`: The string to which the `source` string is appended. |
| `source`: The string to be appended to the destination string. |
| |
| #### Declaration #### |
| |
| ``` |
| static int SbStringConcatUnsafe(char *out_destination, const char *source) |
| ``` |
| |
| ### SbStringConcatWide ### |
| |
| Identical to SbStringCat, but for wide characters. |
| |
| `out_destination`: The string to which the `source` string is appended. |
| `source`: The string to be appended to the destination string. |
| `destination_size`: The amount of storage space available for the concatenated |
| string. |
| |
| #### Declaration #### |
| |
| ``` |
| int SbStringConcatWide(wchar_t *out_destination, const wchar_t *source, int destination_size) |
| ``` |
| |
| ### SbStringCopy ### |
| |
| Copies as much of a `source` string as possible and null-terminates it, given |
| that `destination_size` characters of storage are available. This function is |
| meant to be a drop-in replacement for `strlcpy`. |
| |
| The return value specifies the length of `source`. |
| |
| `out_destination`: The location to which the string is copied. `source`: The |
| string to be copied. `destination_size`: The amount of the source string to |
| copy. |
| |
| #### Declaration #### |
| |
| ``` |
| int SbStringCopy(char *out_destination, const char *source, int destination_size) |
| ``` |
| |
| ### SbStringCopyUnsafe ### |
| |
| An inline wrapper for an unsafe SbStringCopy that assumes that the destination |
| provides enough storage space for the entire string. The return value is a |
| pointer to the destination string. This function is meant to be a drop-in |
| replacement for `strcpy`. |
| |
| `out_destination`: The location to which the string is copied. `source`: The |
| string to be copied. |
| |
| #### Declaration #### |
| |
| ``` |
| static char* SbStringCopyUnsafe(char *out_destination, const char *source) |
| ``` |
| |
| ### SbStringCopyWide ### |
| |
| Identical to SbStringCopy, but for wide characters. |
| |
| `out_destination`: The location to which the string is copied. `source`: The |
| string to be copied. `destination_size`: The amount of the source string to |
| copy. |
| |
| #### Declaration #### |
| |
| ``` |
| int SbStringCopyWide(wchar_t *out_destination, const wchar_t *source, int destination_size) |
| ``` |
| |
| ### SbStringDuplicate ### |
| |
| Copies `source` into a buffer that is allocated by this function and that can be |
| freed with SbMemoryDeallocate. This function is meant to be a drop-in |
| replacement for `strdup`. |
| |
| `source`: The string to be copied. |
| |
| #### Declaration #### |
| |
| ``` |
| char* SbStringDuplicate(const char *source) |
| ``` |
| |
| ### SbStringFindCharacter ### |
| |
| Finds the first occurrence of a `character` in `str`. The return value is a |
| pointer to the found character in the given string or `NULL` if the character is |
| not found. Note that this function's signature does NOT match that of the |
| `strchr` function. |
| |
| `str`: The string to search for the character. `character`: The character to |
| find in the string. |
| |
| #### Declaration #### |
| |
| ``` |
| const char* SbStringFindCharacter(const char *str, char character) |
| ``` |
| |
| ### SbStringFindLastCharacter ### |
| |
| Finds the last occurrence of a specified character in a string. The return value |
| is a pointer to the found character in the given string or `NULL` if the |
| character is not found. Note that this function's signature does NOT match that |
| of the `strrchr` function. |
| |
| `str`: The string to search for the character. `character`: The character to |
| find in the string. |
| |
| #### Declaration #### |
| |
| ``` |
| const char* SbStringFindLastCharacter(const char *str, char character) |
| ``` |
| |
| ### SbStringFindString ### |
| |
| Finds the first occurrence of `str2` in `str1`. The return value is a pointer to |
| the beginning of the found string or `NULL` if the string is not found. This |
| function is meant to be a drop-in replacement for `strstr`. |
| |
| `str1`: The string in which to search for the presence of `str2`. `str2`: The |
| string to locate in `str1`. |
| |
| #### Declaration #### |
| |
| ``` |
| const char* SbStringFindString(const char *str1, const char *str2) |
| ``` |
| |
| ### SbStringFormat ### |
| |
| Produces a string formatted with `format` and `arguments`, placing as much of |
| the result that will fit into `out_buffer`. The return value specifies the |
| number of characters that the format would produce if `buffer_size` were |
| infinite. |
| |
| This function is meant to be a drop-in replacement for `vsnprintf`. |
| |
| `out_buffer`: The location where the formatted string is stored. `buffer_size`: |
| The size of `out_buffer`. `format`: A string that specifies how the data should |
| be formatted. `arguments`: Variable arguments used in the string. |
| |
| #### Declaration #### |
| |
| ``` |
| int SbStringFormat(char *out_buffer, size_t buffer_size, const char *format, va_list arguments) SB_PRINTF_FORMAT(3 |
| ``` |
| |
| ### SbStringFormatF ### |
| |
| An inline wrapper of SbStringFormat that converts from ellipsis to va_args. This |
| function is meant to be a drop-in replacement for `snprintf`. |
| |
| `out_buffer`: The location where the formatted string is stored. `buffer_size`: |
| The size of `out_buffer`. `format`: A string that specifies how the data should |
| be formatted. `...`: Arguments used in the string. |
| |
| #### Declaration #### |
| |
| ``` |
| int static int static int SbStringFormatF(char *out_buffer, size_t buffer_size, const char *format,...) SB_PRINTF_FORMAT(3 |
| ``` |
| |
| ### SbStringFormatUnsafeF ### |
| |
| An inline wrapper of SbStringFormat that is meant to be a drop-in replacement |
| for the unsafe but commonly used `sprintf`. |
| |
| `out_buffer`: The location where the formatted string is stored. `format`: A |
| string that specifies how the data should be formatted. `...`: Arguments used in |
| the string. |
| |
| #### Declaration #### |
| |
| ``` |
| static int static int SbStringFormatUnsafeF(char *out_buffer, const char *format,...) SB_PRINTF_FORMAT(2 |
| ``` |
| |
| ### SbStringFormatWide ### |
| |
| This function is identical to SbStringFormat, but is for wide characters. It is |
| meant to be a drop-in replacement for `vswprintf`. |
| |
| `out_buffer`: The location where the formatted string is stored. `buffer_size`: |
| The size of `out_buffer`. `format`: A string that specifies how the data should |
| be formatted. `arguments`: Variable arguments used in the string. |
| |
| #### Declaration #### |
| |
| ``` |
| int SbStringFormatWide(wchar_t *out_buffer, size_t buffer_size, const wchar_t *format, va_list arguments) |
| ``` |
| |
| ### SbStringFormatWideF ### |
| |
| An inline wrapper of SbStringFormatWide that converts from ellipsis to |
| `va_args`. |
| |
| `out_buffer`: The location where the formatted string is stored. `buffer_size`: |
| The size of `out_buffer`. `format`: A string that specifies how the data should |
| be formatted. `...`: Arguments used in the string. |
| |
| #### Declaration #### |
| |
| ``` |
| static int SbStringFormatWideF(wchar_t *out_buffer, size_t buffer_size, const wchar_t *format,...) |
| ``` |
| |
| ### SbStringGetLength ### |
| |
| Returns the length, in characters, of `str`. |
| |
| `str`: A zero-terminated ASCII string. |
| |
| #### Declaration #### |
| |
| ``` |
| size_t SbStringGetLength(const char *str) |
| ``` |
| |
| ### SbStringGetLengthWide ### |
| |
| Returns the length of a wide character string. (This function is the same as |
| SbStringGetLength, but for a string comprised of wide characters.) This function |
| assumes that there are no multi-element characters. |
| |
| `str`: A zero-terminated ASCII string. |
| |
| #### Declaration #### |
| |
| ``` |
| size_t SbStringGetLengthWide(const wchar_t *str) |
| ``` |
| |
| ### SbStringParseDouble ### |
| |
| Extracts a string that represents an integer from the beginning of `start` into |
| a double. |
| |
| This function is meant to be a drop-in replacement for `strtod`, except that it |
| is explicitly declared to return a double. |
| |
| `start`: The string that begins with the number to be converted. `out_end`: If |
| provided, the function places a pointer to the end of the consumed portion of |
| the string into `out_end`. |
| |
| #### Declaration #### |
| |
| ``` |
| double SbStringParseDouble(const char *start, char **out_end) |
| ``` |
| |
| ### SbStringParseSignedInteger ### |
| |
| Extracts a string that represents an integer from the beginning of `start` into |
| a signed integer in the given `base`. This function is meant to be a drop-in |
| replacement for `strtol`. |
| |
| `start`: The string that begins with the number to be converted. `out_end`: If |
| provided, the function places a pointer to the end of the consumed portion of |
| the string into `out_end`. `base`: The base into which the number will be |
| converted. The value must be between `2` and `36`, inclusive. |
| NOLINTNEXTLINE(runtime/int) |
| |
| #### Declaration #### |
| |
| ``` |
| long SbStringParseSignedInteger(const char *start, char **out_end, int base) |
| ``` |
| |
| ### SbStringParseUInt64 ### |
| |
| Extracts a string that represents an integer from the beginning of `start` into |
| an unsigned 64-bit integer in the given `base`. |
| |
| This function is meant to be a drop-in replacement for `strtoull`, except that |
| it is explicitly declared to return `uint64_t`. |
| |
| `start`: The string that begins with the number to be converted. `out_end`: If |
| provided, the function places a pointer to the end of the consumed portion of |
| the string into `out_end`. `base`: The base into which the number will be |
| converted. The value must be between `2` and `36`, inclusive. |
| |
| #### Declaration #### |
| |
| ``` |
| uint64_t SbStringParseUInt64(const char *start, char **out_end, int base) |
| ``` |
| |
| ### SbStringParseUnsignedInteger ### |
| |
| Extracts a string that represents an integer from the beginning of `start` into |
| an unsigned integer in the given `base`. This function is meant to be a drop-in |
| replacement for `strtoul`. |
| |
| `start`: The string that begins with the number to be converted. `out_end`: If |
| provided, the function places a pointer to the end of the consumed portion of |
| the string into `out_end`. `base`: The base into which the number will be |
| converted. The value must be between `2` and `36`, inclusive. |
| NOLINTNEXTLINE(runtime/int) |
| |
| #### Declaration #### |
| |
| ``` |
| unsigned long SbStringParseUnsignedInteger(const char *start, char **out_end, int base) |
| ``` |
| |
| ### SbStringScan ### |
| |
| Scans `buffer` for `pattern`, placing the extracted values in `arguments`. The |
| return value specifies the number of successfully matched items, which may be |
| `0`. |
| |
| This function is meant to be a drop-in replacement for `vsscanf`. |
| |
| `buffer`: The string to scan for the pattern. `pattern`: The string to search |
| for in `buffer`. `arguments`: Values matching `pattern` that were extracted from |
| `buffer`. |
| |
| #### Declaration #### |
| |
| ``` |
| int SbStringScan(const char *buffer, const char *pattern, va_list arguments) |
| ``` |
| |
| ### SbStringScanF ### |
| |
| An inline wrapper of SbStringScan that converts from ellipsis to `va_args`. This |
| function is meant to be a drop-in replacement for `sscanf`. `buffer`: The string |
| to scan for the pattern. `pattern`: The string to search for in `buffer`. `...`: |
| Values matching `pattern` that were extracted from `buffer`. |
| |
| #### Declaration #### |
| |
| ``` |
| static int SbStringScanF(const char *buffer, const char *pattern,...) |
| ``` |
| |