string.h - Engine C API Reference

string.h
  1. #pragma once
  3. #include "allocator.h"
  4. #include "assert.h"
  6. #include "array.h"
  8. #include <string.h>
  9. #include <stdlib.h>
  10. #include <limits.h>
  12. namespace stingray_plugin_foundation {
  14. template <class T> class Vector;
  16. // ----------------------------------------------------------------------
  17. // Functions that extend the normal ANSI C string interface.
  18. // ----------------------------------------------------------------------
  20. // Returns the length of the string a 32-bit number (unsigned rather
  21. // than size_t).
  22. inline unsigned strlen32(const char *s);
  24. // Returns the length of the string a 32-bit number (unsigned rather
  25. // than size_t).
  26. inline unsigned strlenw32(const wchar_t *s);
  28. // Returns true if strings s1 and s2 are identical.
  29. inline bool strequal(const char *s1, const char *s2);
  31. // Returns true if strings s1 and s2 are identical when ignoring case.
  32. // Only ascii characters (A-Z) are considered when comparing case.
  33. bool strequali(const char *s1, const char *s2);
  35. // Returns true if string s is empty.
  36. inline bool strempty(const char *s);
  38. // Converts s to an integer and returns the result.
  39. inline int to_int(const char *s);
  41. // Converts s to an unsigned and returns the result.
  42. inline unsigned to_unsigned(const char *s);
  44. // Converts s to a float and returns the result.
  45. inline float to_float(const char *s);
  47. // Converts s to an integer and returns the result.
  48. inline int to_int(const char *s, bool &error);
  50. // Converts s to an unsigned and returns the result.
  51. inline unsigned to_unsigned(const char *s, bool &error);
  53. // Converts s to a float and returns the result.
  54. inline float to_float(const char *s, bool &error);
  56. // ----------------------------------------------------------------------
  58. // A thin wrapper around a const char * that just adds a == operator for string
  59. // comparison. Note especially that it doesn't make a copy of the string. The
  60. // original string pointer must be valid as long as this class is used.
  61. //
  62. // Typically, this class is used to make string comparisons easier to read
  63. // and prevent mistakes. An example:
  64. //
  65. //  ConstString s(p)
  66. //      if (s == "open")
  67. //          ...
  68. class ConstString
  69. {
  70. public:
  71.     // ConstString that wraps the empty string.
  72.     ConstString() : s("") {}
  74.     // ConstString that wraps the specified string.
  75.     ConstString(const char *s_) : s(s_) {}
  77.     // Returns the raw string pointer.
  78.     const char *c_str() const {return s;}
  80.     // Returns true if the string is empty.
  81.     bool empty() const {return *s == 0;}
  83.     // Returns the length of the string
  84.     unsigned size() const {return strlen32(s);}
  86.     const char *s;
  87. };
  89. // Comparison operators for ConstString.
  90. inline bool operator==(const ConstString &s1, const char *s2) {return strcmp(s1.s, s2) ==  0;}
  91. inline bool operator==(const char *s1, const ConstString &s2) {return strcmp(s1, s2.s) ==  0;}
  92. inline bool operator==(const ConstString &s1, const ConstString &s2) {return strcmp(s1.s, s2.s) == 0;}
  93. inline bool operator!=(const ConstString &s1, const char *s2) {return strcmp(s1.s, s2) !=  0;}
  94. inline bool operator!=(const char *s1, const ConstString &s2) {return strcmp(s1, s2.s) !=  0;}
  95. inline bool operator!=(const ConstString &s1, const ConstString &s2) {return strcmp(s1.s, s2.s) != 0;}
  96. inline bool operator<(const ConstString &s1, const char *s2) {return strcmp(s1.s, s2) <  0;}
  97. inline bool operator<(const char *s1, const ConstString &s2) {return strcmp(s1, s2.s) <  0;}
  98. inline bool operator<(const ConstString &s1, const ConstString &s2) {return strcmp(s1.s, s2.s) < 0;}
  100. // ----------------------------------------------------------------------
  102. // Class that represents a dynamic string -- a string whose content can be modified.
  103. // This class is basically just a thin wrapper around an Array<char> buffer that stores
  104. // the content of the string.
  105. class DynamicString
  106. {
  107. public:
  108.     ALLOCATOR_AWARE;
  110.     // Creates a new dynamic string using the specified allocator.
  111.     DynamicString(Allocator &a) : _buffer(a) {}
  113.     // Creates a new dynamic string initialized from s.
  114.     DynamicString(Allocator &a, const char *s) : _buffer(a) { unsigned length = s ? strlen32(s) : 0;  if (length > 0) { _buffer.resize(length + 1);  memmove(_buffer.begin(), s, _buffer.size()); } }
  116.     // Creates a new dynamic string initialized from the first n characters of s.
  117.     DynamicString(Allocator &a, const char *s, unsigned n) : _buffer(a) { if (n > 0) { _buffer.resize(n + 1);  memmove(_buffer.begin(), s, n); _buffer[n] = 0; } }
  119.     // Copy constructor
  120.     DynamicString(const DynamicString &o) : _buffer(o._buffer) {}
  122.     // Assignment.
  123.     void operator=(const char *s) { unsigned length = strlen32(s); if (length > 0) { _buffer.resize(length + 1); memmove(_buffer.begin(), s, _buffer.size()); } else _buffer.clear(); }
  125.     // Assigns the characters from ds to this string. Does not change the allocator.
  126.     void operator=(const DynamicString &ds) { _buffer = ds._buffer; }
  128.     // Returns the size/length of the string. The size does not include the terminating zero.
  129.     unsigned size() const {return _buffer.empty() ? 0 : _buffer.size() - 1;}
  131.     // Returns true if the string is empty.
  132.     bool empty() const {return size() == 0;}
  134.     // Returns the C-string held by this dynamic string.
  135.     char *c_str() { return _buffer.empty() ? empty_string() : _buffer.begin(); }
  136.     const char *c_str() const {return _buffer.empty() ? empty_string() : _buffer.begin();}
  138.     // Returns a pointer to the terminating zero at the end of C-string.
  139.     char *end() { return _buffer.empty() ? c_str() : _buffer.end() - 1; }
  140.     const char *end() const { return _buffer.empty() ? c_str() : _buffer.end() - 1; }
  142.     // Accesses characters in the string.
  143.     char &operator[](unsigned i) { return c_str()[i];}
  144.     const char &operator[](unsigned i) const { return c_str()[i]; }
  146.     // Resizes the string to the specified size (size does not include terminating zero).
  147.     void resize(unsigned size) { bool empty = _buffer.empty(); _buffer.resize(size + 1); if (empty) _buffer[0] = '\0'; _buffer[size] = '\0'; }
  149.     // Extends the string with the specified number of bytes.
  150.     void extend(unsigned bytes) {resize(size() + bytes);}
  152.     // Clears the memory and sets this string to the empty string.
  153.     void clear() { _buffer.clear(); }
  155.     // Returns the allocator of the string.
  156.     Allocator &allocator() const {return _buffer.allocator();}
  158.     // Swaps the contents efficiently.
  159.     void swap(DynamicString &other);
  161.     // Serializes the string to the stream
  162.     template <class STREAM> void serialize(STREAM &s) {
  163.         unsigned sz = size();
  164.         s & sz;
  165.         if (sz != size())
  166.             resize(sz);
  168.         if (sz != 0) {
  169.             if (s.is_output())
  170.                 s.write(_buffer.begin(), sz);
  171.             else
  172.                 s.read(_buffer.begin(), sz);
  173.         }
  174.     }
  176.     Array<char> &buffer() { if (_buffer.empty()) _buffer.push_back(0); return _buffer; }
  177.     private:
  178.         // Raw access to the string buffer.
  179.         Array<char> _buffer;
  180.         static char *empty_string() { static char c = '\0'; return &c; }
  181. };
  183. // Comparison operators
  184. inline bool operator==(const DynamicString &s1, const char *s2) {return strcmp(s1.c_str(), s2) ==  0;}
  185. inline bool operator==(const char *s1, const DynamicString &s2) {return strcmp(s1, s2.c_str()) ==  0;}
  186. inline bool operator==(const DynamicString &s1, const DynamicString &s2) {return strcmp(s1.c_str(), s2.c_str()) == 0;}
  187. inline bool operator!=(const DynamicString &s1, const char *s2) {return strcmp(s1.c_str(), s2) !=  0;}
  188. inline bool operator!=(const char *s1, const DynamicString &s2) {return strcmp(s1, s2.c_str()) !=  0;}
  189. inline bool operator!=(const DynamicString &s1, const DynamicString &s2) {return strcmp(s1.c_str(), s2.c_str()) != 0;}
  190. inline bool operator<(const DynamicString &s1, const char *s2) {return strcmp(s1.c_str(), s2) <  0;}
  191. inline bool operator<(const char *s1, const DynamicString &s2) {return strcmp(s1, s2.c_str()) <  0;}
  192. inline bool operator<(const DynamicString &s1, const DynamicString &s2) {return strcmp(s1.c_str(), s2.c_str()) < 0;}
  194. // Appends `s` to the end of `str`.
  195. inline void append(DynamicString &str, const char *s);
  197. // Appends `c` to the end of `str`.
  198. inline void append(DynamicString &str, char c);
  200. // Appends `len` characters beginning from `s` to the end of `str`.
  201. inline void append(DynamicString &str, const char *s, unsigned len);
  203. // Inserts `s` in front of any characters in `str`.
  204. inline void prefix(DynamicString &str, const char *s);
  206. // ----------------------------------------------------------------------
  208. // Namespace for string operations.
  209. namespace string {
  211.     const unsigned npos = UINT_MAX;
  213.     // Returns true if c is a whitespace character.
  214.     bool is_whitespace(char c);
  216.     // Returns the index of the first occurrence of `c` in
  217.     // `s` or `npos` if not found.
  218.     unsigned find(const char *s, char c);
  220.     // Returns the index of the last occurrence of `c` in
  221.     // `s` or `npos` if not found.
  222.     unsigned find_last(const char *s, char c);
  224.     // Returns the index of the first occurrence of `substring` in
  225.     // `s` or `npos` if not found.
  226.     unsigned find(const char *s, const char *substring);
  228.     // Returns the index of the last occurrence of `substring` in
  229.     // `s` or `npos` if not found.
  230.     unsigned find_last(const char *s, const char *substring);
  232.     // Returns true if `s` contains `substring`.
  233.     bool contains(const char *s, const char *substring);
  235.     // Splits the string `s` on the first instance of `split_on` and stores the
  236.     // results in `first` and `second`. If `split_on` is not found, `first`
  237.     // will get the entire string.
  238.     void split(const char *s, const char *split_on, DynamicString &first, DynamicString &second);
  240.     // Splits the string `s` on all instances of `split_on` and stores the
  241.     // results in `result`
  242.     void split(const char *s, const char *split_by, Vector<DynamicString> &result);
  244.     enum SkipEmpty { SKIP_EMPTY, DONT_SKIP_EMPTY };
  245.     // Joins each string in `strings` into a single string separated by `separator` and stores the result in `result`.
  246.     void join(const DynamicString* strings, unsigned num_strings, const char* separator, DynamicString& result, SkipEmpty skip_empty = DONT_SKIP_EMPTY);
  248.     // Returns a pointer to a string with n spaces for indentation purposes. If n > 200 a string with 200 spaces
  249.     // will be returned.
  250.     const char *spaces(int n);
  252.     // Returns true if s is a lowercase string.
  253.     bool is_lowercase(const char *s);
  255.     // Replaces the character range (start, start+size) in the string s with the
  256.     // replacement rep.
  257.     void replace(DynamicString &s, unsigned start, unsigned size, const char *rep);
  259.     // Replaces the occurances of the string `find` with the replacement `rep` and returns the number of successful replacements made.
  260.     unsigned replace_all(DynamicString &s, const char *find, const char *rep);
  262.     // In-place converts the string to lower case
  263.     void to_lower_case(char *s);
  265.     // In-place converts the string to upper case
  266.     void to_upper_case(char *s);
  268.     // Converts from camel case to underscore representation.
  269.     DynamicString from_camel_case(const char *s, Allocator &a);
  271.     // Returns the string with the character stripped out.
  272.     DynamicString strip(const char *s, char c, Allocator &a);
  274.     // Trims whitespace from the start and end of the string and returns the result.
  275.     DynamicString trim(const char *s, Allocator &a);
  277.     // Returns a substring of s starting at start and of length.
  278.     DynamicString substring(const char *s, unsigned start, unsigned length, Allocator &a);
  280.     // Returns true if `str` contains `c`.
  281.     bool in_string(const char *str, char c);
  283.     // Returns true if `str` only contains characters in `allowed`.
  284.     bool consists_of(const char *str, const char *allowed);
  286.     // Returns true if `str` begins with `begins`.
  287.     bool begins_with(const char *str, const char *begins);
  289.     // Returns true if `str` ends with `ends`.
  290.     bool ends_with(const char *str, const char *ends);
  291.     bool ends_with(const wchar_t *str, const wchar_t *ends);
  293.     // Returns a copy of the string `str` allocated with the allocator `a`.
  294.     char* copy(const char *str, Allocator& a);
  296.     // Copies src to dest. Truncates the copy if necessary so that more than
  297.     // `dest_size` bytes are never written to `dest`. Always terminates
  298.     // dest with a \0 character. Utf-8 characters are guaranteed to not get
  299.     // truncated in the middle of a multibyte character.
  300.     void copy(char *dest, const char *src, unsigned dest_size);
  301.     void copy(wchar_t *dest, const wchar_t *src, unsigned dest_size);
  303.     // Appends `src` to the end of `dest`. Truncates `dest` if necessary so that
  304.     // more than `dest_size` bytes are never written to `dest`. Always terminates
  305.     // dest with a \0 character. Utf-8 characters are guaranteed to not get
  306.     // truncated in the middle of a multibyte character.
  307.     void append(char *dest, const char *src, unsigned dest_size);
  308.     void append(wchar_t *dest, const wchar_t *src, unsigned dest_size);
  310.     #ifdef DEVELOPMENT
  311.         // Returns a string allocated by `a` representing a typcial hex_view of the `data`.
  312.         // (Such as shown by a memory debugger, for instance.)
  313.         // `columns` is the number of columns of hex values in the view.
  314.         // If `ascii_column` is true a column that shows ascii representation is included.
  315.         DynamicString hex_view(Allocator &a, const char *data, unsigned size, unsigned columns = 16, bool ascii_column = true);
  316.     #endif
  318. } // namespace string
  320. }
  322. #include "string.inl"
Please send us your comment about this page