String.h 3.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105
  1. /* vim: set expandtab ts=4 sw=4: */
  2. /*
  3. * You may redistribute this program and/or modify it under the terms of
  4. * the GNU General Public License as published by the Free Software Foundation,
  5. * either version 3 of the License, or (at your option) any later version.
  6. *
  7. * This program is distributed in the hope that it will be useful,
  8. * but WITHOUT ANY WARRANTY; without even the implied warranty of
  9. * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  10. * GNU General Public License for more details.
  11. *
  12. * You should have received a copy of the GNU General Public License
  13. * along with this program. If not, see <http://www.gnu.org/licenses/>.
  14. */
  15. #ifndef String_H
  16. #define String_H
  17. #include "benc/Object.h"
  18. #include "memory/Allocator.h"
  19. #include "util/CString.h"
  20. #include "util/Linker.h"
  21. Linker_require("benc/String.c")
  22. #include <stdbool.h>
  23. #include <stddef.h> // NULL
  24. /**
  25. * Create a new bencoded string from a C null terminated string.
  26. * This implementation will make a copy of the string into the memory provided by the allocator.
  27. *
  28. * @param bytes the beginning of a memory location containing the string to use.
  29. * @param allocator a means of getting the memory to store the string object.
  30. * @return a bencoded string.
  31. */
  32. String* String_new(const char* bytes, struct Allocator* allocator);
  33. /**
  34. * Create a new bencoded constant string on the stack.
  35. */
  36. #define String_CONST(x) (&(String) { .bytes = x, .len = CString_strlen(x) })
  37. /** For use outside of functions with compile time constant strings. */
  38. #define String_CONST_SO(x) (&(String) { .bytes = x, .len = sizeof(x) - 1 })
  39. #define String_OBJ(x) (&(Object) { .type = Object_STRING, .as.string = x })
  40. /**
  41. * Create a new bencoded string from a set of bytes.
  42. * This implementation will make a copy of the string into the memory provided by the allocator.
  43. *
  44. * @param bytes the beginning of a memory location containing thre string to use.
  45. if NULL then this will make a new string of null characters.
  46. * @param length the number of bytes to use from the location.
  47. * @param allocator a means of getting the memory to store the string object.
  48. * @return a bencoded string.
  49. */
  50. String* String_newBinary(const char* bytes, unsigned long length, struct Allocator* allocator);
  51. #define String_clone(string, alloc) \
  52. ((string) ? String_newBinary(string->bytes, string->len, alloc) : NULL)
  53. /**
  54. * Create a new bencoded string from a format and arguments.
  55. * EG: String_printf("this is on line number %d!", allocator, __LINE__);
  56. *
  57. * @param allocator a means of getting the memory to store the string object.
  58. * @param format standard printf formatting.
  59. * @params arguments to the printf() function.
  60. * @return a bencoded string.
  61. */
  62. String* String_printf(struct Allocator* allocator, const char* format, ...);
  63. #ifdef va_start
  64. /**
  65. * Same as String_printf() except the arguments are passed as a va_list.
  66. * Only enabled if stdarg.h is included before String.h.
  67. */
  68. String* String_vprintf(struct Allocator* allocator, const char* format, va_list args);
  69. #endif
  70. /**
  71. * Compare 2 bencoded strings.
  72. * If the first differing character is numerically smaller for input a then
  73. * a negative number is returned, if the first differing character is numerically
  74. * smaller for input b then a positive number. If all characters in a and b are
  75. * the same then the difference in length (a->len - b->len) is returned.
  76. * If a is NULL and b is not NULL then a negative is returned, if b is NULL and a
  77. * not NULL then a positive is returned, if both NULL then 0.
  78. *
  79. * @param a the first string to compare.
  80. * @param b the second string to compare.
  81. * @return the output from comparison, 0 if and only if they are equal.
  82. */
  83. int String_compare(const String* a, const String* b);
  84. /**
  85. * Will return true if and only if the String_compare() would return 0.
  86. *
  87. * @param a the first string to compare.
  88. * @param b the second string to compare.
  89. * @return !(String_compare(a, b))
  90. */
  91. int String_equals(const String* a, const String* b);
  92. #endif