Starboard Module Reference: string.h

Defines functions for interacting with c-style strings.

Functions

SbStringAToI

Description

Parses a string into a base-10 integer. This is a shorthand replacement for atoi.

Declaration

static SB_C_INLINE int SbStringAToI(const char* value) {
  // NOLINTNEXTLINE(readability/casting)
  return (int)SbStringParseSignedInteger(value, NULL, 10);
}

Parameters

Parameters
const char*
value
The string to be converted.

SbStringAToL

Description

Parses a string into a base-10, long integer. This is a shorthand replacement for atol.

Declaration

static SB_C_INLINE long SbStringAToL(const char* value) {
  // NOLINTNEXTLINE(readability/casting)
  return SbStringParseSignedInteger(value, NULL, 10);
}

Parameters

Parameters
const char*
value
The string to be converted. NOLINTNEXTLINE(runtime/int)

SbStringCompare

Description

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.

Declaration and definitions

SB_EXPORT int SbStringCompare(const char* string1,
                              const char* string2,
                              size_t count);

#include "starboard/string.h"

int SbStringCompare(const char* /*string1*/,
                    const char* /*string2*/,
                    size_t /*count*/) {
  return 0;
}

Parameters

Parameters
const char*
string1
The first 8-bit character string to compare.
const char*
string2
The second 8-bit character string to compare.
size_t
count
The number of characters to compare.

SbStringCompareAll

Description

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.

Declaration and definitions

SB_EXPORT int SbStringCompareAll(const char* string1, const char* string2);

#include "starboard/string.h"

int SbStringCompareAll(const char* /*string1*/, const char* /*string2*/) {
  return 0;
}

Parameters

Parameters
const char*
string1
The first 8-bit character string to compare.
const char*
string2
The second 8-bit character string to compare.

SbStringCompareNoCase

Description

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.

Declaration and definitions

SB_EXPORT int SbStringCompareNoCase(const char* string1, const char* string2);

#include "starboard/string.h"

int SbStringCompareNoCase(const char* /*string1*/, const char* /*string2*/) {
  return 0;
}

Parameters

Parameters
const char*
string1
The first string to compare.
const char*
string2
The second string to compare.

SbStringCompareNoCaseN

Description

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.

Declaration and definitions

SB_EXPORT int SbStringCompareNoCaseN(const char* string1,
                                     const char* string2,
                                     size_t count);

#include "starboard/string.h"

int SbStringCompareNoCaseN(const char* /*string1*/,
                           const char* /*string2*/,
                           size_t /*count*/) {
  return 0;
}

Parameters

Parameters
const char*
string1
The first string to compare.
const char*
string2
The second string to compare.
size_t
count
The number of characters to compare.

SbStringCompareWide

Description

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.

Declaration and definitions

SB_EXPORT int SbStringCompareWide(const wchar_t* string1,
                                  const wchar_t* string2,
                                  size_t count);

#include "starboard/string.h"

int SbStringCompareWide(const wchar_t* /*string1*/,
                        const wchar_t* /*string2*/,
                        size_t /*count*/) {
  return 0;
}

Parameters

Parameters
const wchar_t*
string1
The first 16-bit character string to compare.
const wchar_t*
string2
The second 16-bit character string to compare.
size_t
count
The number of characters to compare.

SbStringConcat

Description

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.

Declaration and definitions

SB_EXPORT int SbStringConcat(char* out_destination,
                             const char* source,
                             int destination_size);

#include "starboard/string.h"

int SbStringConcat(char* /*out_destination*/,
                   const char* /*source*/,
                   int /*destination_size*/) {
  return 0;
}

Parameters

Parameters
char*
out_destination
The string to which the source string is appended.
const char*
source
The string to be appended to the destination string.
int
destination_size
The amount of storage space available for the concatenated string.

SbStringConcatUnsafe

Description

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.

Declaration

static SB_C_INLINE int SbStringConcatUnsafe(char* out_destination,
                                            const char* source) {
  return SbStringConcat(out_destination, source, INT_MAX);
}

Parameters

Parameters
char*
out_destination
The string to which the source string is appended.
const char*
source
The string to be appended to the destination string.

SbStringConcatWide

Description

Identical to SbStringCat, but for wide characters.

Declaration and definitions

SB_EXPORT int SbStringConcatWide(wchar_t* out_destination,
                                 const wchar_t* source,
                                 int destination_size);

#include "starboard/string.h"

int SbStringConcatWide(wchar_t* /*out_destination*/,
                       const wchar_t* /*source*/,
                       int /*destination_size*/) {
  return 0;
}

Parameters

Parameters
wchar_t*
out_destination
The string to which the source string is appended.
const wchar_t*
source
The string to be appended to the destination string.
int
destination_size
The amount of storage space available for the concatenated string.

SbStringCopy

Description

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.

Declaration and definitions

SB_EXPORT int SbStringCopy(char* out_destination,
                           const char* source,
                           int destination_size);

#include "starboard/string.h"

int SbStringCopy(char* /*out_destination*/,
                 const char* /*source*/,
                 int /*destination_size*/) {
  return 0;
}

Parameters

Parameters
char*
out_destination
The location to which the string is copied.
const char*
source
The string to be copied.
int
destination_size
The amount of the source string to copy.

SbStringCopyUnsafe

Description

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.

Declaration

static SB_C_INLINE char* SbStringCopyUnsafe(char* out_destination,
                                            const char* source) {
  SbStringCopy(out_destination, source, INT_MAX);
  return out_destination;
}

Parameters

Parameters
char*
out_destination
The location to which the string is copied.
const char*
source
The string to be copied.

SbStringCopyWide

Description

Identical to SbStringCopy, but for wide characters.

Declaration and definitions

SB_EXPORT int SbStringCopyWide(wchar_t* out_destination,
                               const wchar_t* source,
                               int destination_size);

#include "starboard/string.h"

int SbStringCopyWide(wchar_t* /*out_destination*/,
                     const wchar_t* /*source*/,
                     int /*destination_size*/) {
  return 0;
}

Parameters

Parameters
wchar_t*
out_destination
The location to which the string is copied.
const wchar_t*
source
The string to be copied.
int
destination_size
The amount of the source string to copy.

SbStringDuplicate

Description

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.

Declaration and definitions

SB_EXPORT char* SbStringDuplicate(const char* source);

#include "starboard/string.h"

char* SbStringDuplicate(const char* /*source*/) {
  return NULL;
}

Parameters

Parameters
const char*
source
The string to be copied.

SbStringFindCharacter

Description

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.

Declaration and definitions

SB_EXPORT const char* SbStringFindCharacter(const char* str, char character);

#include "starboard/string.h"

const char* SbStringFindCharacter(const char* /*str*/, char /*character*/) {
  return NULL;
}

Parameters

Parameters
const char*
str
The string to search for the character.
char
character
The character to find in the string.

SbStringFindLastCharacter

Description

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.

Declaration and definitions

SB_EXPORT const char* SbStringFindLastCharacter(const char* str,
                                                char character);

#include "starboard/string.h"

const char* SbStringFindLastCharacter(const char* /*str*/, char /*character*/) {
  return NULL;
}

Parameters

Parameters
const char*
str
The string to search for the character.
char
character
The character to find in the string.

SbStringFindString

Description

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.

Declaration and definitions

SB_EXPORT const char* SbStringFindString(const char* str1, const char* str2);

#include "starboard/string.h"

const char* SbStringFindString(const char* /*str1*/, const char* /*str2*/) {
  return NULL;
}

Parameters

Parameters
const char*
str1
The string in which to search for the presence of str2.
const char*
str2
The string to locate in str1.

SbStringFormat

Description

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.

Declaration and definitions

SB_EXPORT int SbStringFormat(char* out_buffer,
                             size_t buffer_size,
                             const char* format,
                             va_list arguments) SB_PRINTF_FORMAT(3, 0);

#include "starboard/string.h"

int SbStringFormat(char* /*out_buffer*/,
                   size_t /*buffer_size*/,
                   const char* /*format*/,
                   va_list /*arguments*/) {
  return 0;
}

Parameters

Parameters
char*
out_buffer
The location where the formatted string is stored.
size_t
buffer_size
The size of out_buffer.
const char*
format
A string that specifies how the data should be formatted.
va_list
arguments
Variable arguments used in the string.

SbStringFormatF

Declaration

static SB_C_INLINE int SbStringFormatF(char* out_buffer,
                                       size_t buffer_size,
                                       const char* format,
                                       ...) {
  va_list arguments;
  va_start(arguments, format);
  int result = SbStringFormat(out_buffer, buffer_size, format, arguments);
  va_end(arguments);
  return result;
}

Parameters

Parameters
char*
out_buffer
size_t
buffer_size
const char*
format

...

SbStringFormatUnsafeF

Declaration

static SB_C_INLINE int SbStringFormatUnsafeF(char* out_buffer,
                                             const char* format,
                                             ...) {
  va_list arguments;
  va_start(arguments, format);
  int result = SbStringFormat(out_buffer, UINT_MAX, format, arguments);
  va_end(arguments);
  return result;
}

Parameters

Parameters
char*
out_buffer
const char*
format

...

SbStringFormatWide

Description

This function is identical to SbStringFormat, but is for wide characters. It is meant to be a drop-in replacement for vswprintf.

Declaration and definitions

SB_EXPORT int SbStringFormatWide(wchar_t* out_buffer,
                                 size_t buffer_size,
                                 const wchar_t* format,
                                 va_list arguments);

#include "starboard/string.h"

int SbStringFormatWide(wchar_t* /*out_buffer*/,
                       size_t /*buffer_size*/,
                       const wchar_t* /*format*/,
                       va_list /*arguments*/) {
  return 0;
}

Parameters

Parameters
wchar_t*
out_buffer
The location where the formatted string is stored.
size_t
buffer_size
The size of out_buffer.
const wchar_t*
format
A string that specifies how the data should be formatted.
va_list
arguments
Variable arguments used in the string.

SbStringFormatWideF

Description

An inline wrapper of SbStringFormatWide that converts from ellipsis to va_args.

Declaration

static SB_C_INLINE int SbStringFormatWideF(wchar_t* out_buffer,
                                           size_t buffer_size,
                                           const wchar_t* format,
                                           ...) {
  va_list arguments;
  va_start(arguments, format);
  int result = SbStringFormatWide(out_buffer, buffer_size, format, arguments);
  va_end(arguments);
  return result;
}

Parameters

Parameters
wchar_t*
out_buffer
The location where the formatted string is stored.
size_t
buffer_size
The size of out_buffer.
const wchar_t*
format
A string that specifies how the data should be formatted.

...
Arguments used in the string.

SbStringGetLength

Description

Returns the length, in characters, of str.

Declaration and definitions

SB_EXPORT size_t SbStringGetLength(const char* str);

#include "starboard/string.h"

size_t SbStringGetLength(const char* /*str*/) {
  return static_cast<size_t>(0);
}

Parameters

Parameters
const char*
str
A zero-terminated ASCII string.

SbStringGetLengthWide

Description

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.

Declaration and definitions

SB_EXPORT size_t SbStringGetLengthWide(const wchar_t* str);

#include "starboard/string.h"

size_t SbStringGetLengthWide(const wchar_t* /*str*/) {
  return static_cast<size_t>(0);
}

Parameters

Parameters
const wchar_t*
str
A zero-terminated ASCII string.

SbStringParseDouble

Description

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.

Declaration and definitions

SB_EXPORT double SbStringParseDouble(const char* start, char** out_end);

#include "starboard/string.h"

double SbStringParseDouble(const char* start, char** out_end) {
  if (out_end != NULL)
    *out_end = NULL;
  return 0.0;
}

Parameters

Parameters
const char*
start
The string that begins with the number to be converted.
char**
out_end
If provided, the function places a pointer to the end of the consumed portion of the string into out_end.

SbStringParseSignedInteger

Description

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.

Declaration and definitions

SB_EXPORT long SbStringParseSignedInteger(const char* start,
                                          char** out_end,
                                          int base);

#include "starboard/string.h"

// NOLINTNEXTLINE(runtime/int)
long SbStringParseSignedInteger(const char* /*start*/,
                                char** /*out_end*/,
                                int /*base*/) {
  return 0L;
}

Parameters

Parameters
const char*
start
The string that begins with the number to be converted.
char**
out_end
If provided, the function places a pointer to the end of the consumed portion of the string into out_end.
int
base
The base into which the number will be converted. The value must be between 2 and 36, inclusive. NOLINTNEXTLINE(runtime/int)

SbStringParseUInt64

Description

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.

Declaration

SB_EXPORT uint64_t SbStringParseUInt64(const char* start,
                                       char** out_end,
                                       int base);

Parameters

Parameters
const char*
start
The string that begins with the number to be converted.
char**
out_end
If provided, the function places a pointer to the end of the consumed portion of the string into out_end.
int
base
The base into which the number will be converted. The value must be between 2 and 36, inclusive.

SbStringParseUnsignedInteger

Description

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.

Declaration and definitions

SB_EXPORT unsigned long SbStringParseUnsignedInteger(const char* start,
                                                     char** out_end,
                                                     int base);

#include "starboard/string.h"

// NOLINTNEXTLINE(runtime/int)
unsigned long SbStringParseUnsignedInteger(const char* /*start*/,
                                           char** /*out_end*/,
                                           int /*base*/) {
  return 0UL;
}

Parameters

Parameters
const char*
start
The string that begins with the number to be converted.
char**
out_end
If provided, the function places a pointer to the end of the consumed portion of the string into out_end.
int
base
The base into which the number will be converted. The value must be between 2 and 36, inclusive. NOLINTNEXTLINE(runtime/int)

SbStringScan

Description

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.

Declaration and definitions

SB_EXPORT int SbStringScan(const char* buffer,
                           const char* pattern,
                           va_list arguments);

#include "starboard/string.h"

int SbStringScan(const char* /*buffer*/,
                 const char* /*pattern*/,
                 va_list /*arguments*/) {
  return 0;
}

Parameters

Parameters
const char*
buffer
The string to scan for the pattern.
const char*
pattern
The string to search for in buffer.
va_list
arguments
Values matching pattern that were extracted from buffer.

SbStringScanF

Description

An inline wrapper of SbStringScan that converts from ellipsis to va_args. This function is meant to be a drop-in replacement for sscanf.

Declaration

static SB_C_INLINE int SbStringScanF(const char* buffer,
                                     const char* pattern,
                                     ...) {
  va_list arguments;
  va_start(arguments, pattern);
  int result = SbStringScan(buffer, pattern, arguments);
  va_end(arguments);
  return result;
}

Parameters

Parameters
const char*
buffer
The string to scan for the pattern.
const char*
pattern
The string to search for in buffer.

...
Values matching pattern that were extracted from buffer.