| // Copyright 2015 Google Inc. All Rights Reserved. |
| // |
| // Licensed under the Apache License, Version 2.0 (the "License"); |
| // you may not use this file except in compliance with the License. |
| // You may obtain a copy of the License at |
| // |
| // http://www.apache.org/licenses/LICENSE-2.0 |
| // |
| // Unless required by applicable law or agreed to in writing, software |
| // distributed under the License is distributed on an "AS IS" BASIS, |
| // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| // See the License for the specific language governing permissions and |
| // limitations under the License. |
| |
| // Functions for interacting with c-style strings. |
| |
| #ifndef STARBOARD_STRING_H_ |
| #define STARBOARD_STRING_H_ |
| |
| #include <stdarg.h> |
| |
| #include "starboard/configuration.h" |
| #include "starboard/export.h" |
| #include "starboard/types.h" |
| |
| #ifdef __cplusplus |
| extern "C" { |
| #endif |
| |
| // Returns the length, in characters, of |str|, a zero-terminated ASCII string. |
| SB_EXPORT size_t SbStringGetLength(const char* str); |
| |
| // Same as SbStringGetLength but for wide characters. This assumes that there |
| // are no multi-element characters. |
| SB_EXPORT size_t SbStringGetLengthWide(const wchar_t* str); |
| |
| // Copies as much |source| as possible into |out_destination| and |
| // null-terminates it, given that it has |destination_size| characters of |
| // storage available. Returns the length of |source|. Meant to be a drop-in |
| // replacement for strlcpy |
| SB_EXPORT int SbStringCopy(char* out_destination, |
| const char* source, |
| int destination_size); |
| |
| // Inline wrapper for an unsafe SbStringCopy that assumes |out_destination| is |
| // big enough. Meant to be a drop-in replacement for strcpy. |
| static SB_C_INLINE char* SbStringCopyUnsafe(char* out_destination, |
| const char* source) { |
| SbStringCopy(out_destination, source, INT_MAX); |
| return out_destination; |
| } |
| |
| // Same as SbStringCopy but for wide characters. |
| SB_EXPORT int SbStringCopyWide(wchar_t* out_destination, |
| const wchar_t* source, |
| int destination_size); |
| |
| // Concatenates |source| onto the end of |out_destination|, presuming it has |
| // |destination_size| total characters of storage available. Returns |
| // length of |source|. Meant to be a drop-in replacement for strlcpy |
| // Note: This function's signature is NOT compatible with strncat |
| SB_EXPORT int SbStringConcat(char* out_destination, |
| const char* source, |
| int destination_size); |
| |
| // Inline wrapper for an unsafe SbStringConcat that assumes |out_destination| is |
| // big enough. |
| // Note: This function's signature is NOT compatible with strcat. |
| static SB_C_INLINE int SbStringConcatUnsafe(char* out_destination, |
| const char* source) { |
| return SbStringConcat(out_destination, source, INT_MAX); |
| } |
| |
| // Same as SbStringConcat but for wide characters. |
| SB_EXPORT int SbStringConcatWide(wchar_t* out_destination, |
| const wchar_t* source, |
| int destination_size); |
| |
| // Copies the string |source| into a buffer allocated by this function that can |
| // be freed with SbMemoryFree. Meant to be a drop-in replacement for strdup. |
| SB_EXPORT char* SbStringDuplicate(const char* source); |
| |
| // Finds the first occurrence of |character| in |str|, returning a pointer to |
| // the found character in the given string, or NULL if not found. |
| // NOTE: The function signature of this function does NOT match the function |
| // strchr. |
| SB_EXPORT const char* SbStringFindCharacter(const char* str, char character); |
| |
| // Finds the last occurrence of |character| in |str|, returning a pointer to the |
| // found character in the given string, or NULL if not found. |
| // NOTE: The function signature of this function does NOT match the function |
| // strrchr. |
| SB_EXPORT const char* SbStringFindLastCharacter(const char* str, |
| char character); |
| |
| // Finds the first occurrence of |str2| in |str1|, returning a pointer to the |
| // beginning of the found occurrencein |str1|, or NULL if not found. Meant to |
| // be a drop-in replacement for strstr. |
| SB_EXPORT const char* SbStringFindString(const char* str1, const char* str2); |
| |
| // Compares |string1| and |string2|, ignoring differences in case. Returns < 0 |
| // if |string1| is ASCII-betically lower than |string2|, 0 if they are equal, |
| // and > 0 if |string1| is ASCII-betically higher than |string2|. Meant to be a |
| // drop-in replacement for strcasecmp. |
| SB_EXPORT int SbStringCompareNoCase(const char* string1, const char* string2); |
| |
| // Compares the first |count| characters of |string1| and |string2|, ignoring |
| // differences in case. Returns < 0 if |string1| is ASCII-betically lower than |
| // |string2|, 0 if they are equal, and > 0 if |string1| is ASCII-betically |
| // higher than |string2|. Meant to be a drop-in replacement for strncasecmp. |
| SB_EXPORT int SbStringCompareNoCaseN(const char* string1, |
| const char* string2, |
| size_t count); |
| |
| // Formats the given |format| and |arguments|, placing as much of the result |
| // will fit in |out_buffer|, whose size is specified by |buffer_size|. Returns |
| // the number of characters the format would produce if |buffer_size| was |
| // infinite. Meant to be a drop-in replacement for vsnprintf. |
| SB_EXPORT int SbStringFormat(char* out_buffer, |
| size_t buffer_size, |
| const char* format, |
| va_list arguments) SB_PRINTF_FORMAT(3, 0); |
| |
| // Inline wrapper of SbStringFormat to convert from ellipsis to va_args. |
| // Meant to be a drop-in replacement for snprintf. |
| static SB_C_INLINE int SbStringFormatF(char* out_buffer, |
| size_t buffer_size, |
| const char* format, |
| ...) SB_PRINTF_FORMAT(3, 4); |
| 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; |
| } |
| |
| // Inline wrapper of SbStringFormat to be a drop-in replacement for the unsafe |
| // but commonly used sprintf. |
| static SB_C_INLINE int SbStringFormatUnsafeF(char* out_buffer, |
| const char* format, |
| ...) SB_PRINTF_FORMAT(2, 3); |
| 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; |
| } |
| |
| // Same as SbStringFormat, but for wide characters. Meant to be a drop-in |
| // replacement for vswprintf. |
| SB_EXPORT int SbStringFormatWide(wchar_t* out_buffer, |
| size_t buffer_size, |
| const wchar_t* format, |
| va_list arguments); |
| |
| // Inline wrapper of SbStringFormatWide to convert from ellipsis to va_args. |
| 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; |
| } |
| |
| // Compares the first |count| characters of |string1| and |string2|, which are |
| // 16-bit character strings. Returns < 0 if |string1| is ASCII-betically lower |
| // than |string2|, 0 if they are equal, and > 0 if |string1| is ASCII-betically |
| // higher than |string2|. Meant to be a drop-in replacement of wcsncmp. |
| SB_EXPORT int SbStringCompareWide(const wchar_t* string1, |
| const wchar_t* string2, |
| size_t count); |
| |
| // Compares the first |count| characters of |string1| and |string2|, which are |
| // 8-bit character strings. Returns < 0 if |string1| is ASCII-betically lower |
| // than |string2|, 0 if they are equal, and > 0 if |string1| is ASCII-betically |
| // higher than |string2|. Meant to be a drop-in replacement of strncmp. |
| SB_EXPORT int SbStringCompare(const char* string1, |
| const char* string2, |
| size_t count); |
| |
| // Compares all the characters of |string1| and |string2|, which are 8-bit |
| // character strings, up to their natural termination. Returns < 0 if |string1| |
| // is ASCII-betically lower than |string2|, 0 if they are equal, and > 0 if |
| // |string1| is ASCII-betically higher than |string2|. Meant to be a drop-in |
| // replacement of strcmp. |
| SB_EXPORT int SbStringCompareAll(const char* string1, const char* string2); |
| |
| // Scans |buffer| for |pattern|, placing the extracted values in |arguments|. |
| // Returns the number of successfully matched items, which may be zero. Meant to |
| // be a drop-in replacement for vsscanf. |
| SB_EXPORT int SbStringScan(const char* buffer, |
| const char* pattern, |
| va_list arguments); |
| |
| // Inline wrapper of SbStringScan to convert from ellipsis to va_args. Meant to |
| // be a drop-in replacement for sscanf. |
| 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; |
| } |
| |
| // Parses a string at the beginning of |start| into a signed integer in the |
| // given |base|. It will place the pointer to the end of the consumed portion |
| // of the string in |out_end|, if it is provided. Meant to be a drop-in |
| // replacement for strtol. |
| // NOLINTNEXTLINE(runtime/int) |
| SB_EXPORT long SbStringParseSignedInteger(const char* start, |
| char** out_end, |
| int base); |
| |
| // Shorthand replacement for atoi. Parses |value| into a base-10 int. |
| static SB_C_INLINE int SbStringAToI(const char* value) { |
| // NOLINTNEXTLINE(readability/casting) |
| return (int)SbStringParseSignedInteger(value, NULL, 10); |
| } |
| |
| // Shorthand replacement for atol. Parses |value| into a base-10 int. |
| // NOLINTNEXTLINE(runtime/int) |
| static SB_C_INLINE long SbStringAToL(const char* value) { |
| // NOLINTNEXTLINE(readability/casting) |
| return SbStringParseSignedInteger(value, NULL, 10); |
| } |
| |
| // Parses a string at the beginning of |start| into a unsigned integer in the |
| // given |base|. It will place the pointer to the end of the consumed portion |
| // of the string in |out_end|, if it is provided. Meant to be a drop-in |
| // replacement for strtoul. |
| // NOLINTNEXTLINE(runtime/int) |
| SB_EXPORT unsigned long SbStringParseUnsignedInteger(const char* start, |
| char** out_end, |
| int base); |
| |
| // Parses a string at the beginning of |start| into a unsigned 64-bit integer in |
| // the given |base|. It will place the pointer to the end of the consumed |
| // portion of the string in |out_end|, if it is provided. Meant to be a drop-in |
| // replacement for strtoull, but explicity declared to return uint64_t. |
| SB_EXPORT uint64_t SbStringParseUInt64(const char* start, |
| char** out_end, |
| int base); |
| |
| // Parses a string at the beginning of |start| into a double. |
| // It will place the pointer to the end of the consumed |
| // portion of the string in |out_end|, if it is provided. Meant to be a drop-in |
| // replacement for strtod, but explicity declared to return double. |
| SB_EXPORT double SbStringParseDouble(const char* start, char** out_end); |
| |
| #ifdef __cplusplus |
| } // extern "C" |
| #endif |
| |
| #endif // STARBOARD_STRING_H_ |