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