libc/docs/strings.rst

   1 ================
   2 String Functions
   3 ================
   4
   5 .. include:: check.rst
   6
   7 ---------------
   8 Source location
   9 ---------------
  10
  11 -   The main source for string functions is located at:
  12     ``libc/src/string``.
  13
  14 -   The source for string conversion functions is located at:
  15     ``libc/src/stdlib`` and
  16     ``libc/src/__support``.
  17
  18 -   The tests are located at:
  19     ``libc/test/src/string``,
  20     ``libc/test/src/stdlib``, and
  21     ``libc/test/src/__support``
  22     respectively.
  23
  24 ---------------------
  25 Implementation Status
  26 ---------------------
  27
  28 Primary memory functions
  29 ========================
  30
  31 .. TODO(gchatelet): add details about the memory functions.
  32
  33
  34 =============  =========
  35 Function Name  Available
  36 =============  =========
  37 bzero          |check|
  38 bcmp           |check|
  39 bcopy          |check|
  40 memcpy         |check|
  41 memset         |check|
  42 memcmp         |check|
  43 memmove        |check|
  44 =============  =========
  45
  46
  47 Other Raw Memory Functions
  48 ==========================
  49
  50 =============  =========
  51 Function Name  Available
  52 =============  =========
  53 memchr         |check|
  54 memrchr        |check|
  55 memccpy        |check|
  56 mempcpy        |check|
  57 =============  =========
  58
  59 String Memory Functions
  60 =======================
  61
  62 =============  =========
  63 Function Name  Available
  64 =============  =========
  65 stpcpy         |check|
  66 stpncpy        |check|
  67 strcpy         |check|
  68 strncpy        |check|
  69 strcat         |check|
  70 strncat        |check|
  71 strdup         |check|
  72 strndup        |check|
  73 =============  =========
  74
  75 String Examination Functions
  76 ============================
  77
  78 =============  =========
  79 Function Name  Available
  80 =============  =========
  81 strlen         |check|
  82 strnlen        |check|
  83 strcmp         |check|
  84 strncmp        |check|
  85 strchr         |check|
  86 strrchr        |check|
  87 strspn         |check|
  88 strcspn        |check|
  89 strpbrk        |check|
  90 strstr         |check|
  91 strtok         |check|
  92 strtok_r       |check|
  93 =============  =========
  94
  95 String Conversion Functions
  96 ============================
  97
  98 These functions are not in strings.h, but are still primarily string
  99 functions, and are therefore tracked along with the rest of the string
 100 functions.
 101
 102 The String to float functions were implemented using the Eisel-Lemire algorithm
 103 (read more about the algorithm here: `The Eisel-Lemire ParseNumberF64 Algorithm
 104 <https://nigeltao.github.io/blog/2020/eisel-lemire.html>`_). This improved
 105 the performance of string to float and double, and allowed it to complete this
 106 comprehensive test 15% faster than glibc: `Parse Number FXX Test Data
 107 <https://github.com/nigeltao/parse-number-fxx-test-data>`_. The test was done
 108 with LLVM-libc built on 2022-04-14 and Debian GLibc version 2.33-6. The targets
 109 ``libc_str_to_float_comparison_test`` and
 110 ``libc_system_str_to_float_comparison_test`` were built and run on the test data
 111 10 times each, skipping the first run since it was an outlier.
 112
 113
 114 =============  =========
 115 Function Name  Available
 116 =============  =========
 117 atof           |check|
 118 atoi           |check|
 119 atol           |check|
 120 atoll          |check|
 121 strtol         |check|
 122 strtoll        |check|
 123 strtoul        |check|
 124 strtoull       |check|
 125 strtof         |check|
 126 strtod         |check|
 127 strtold        |check|
 128 strtoimax      |check|
 129 strtoumax      |check|
 130 =============  =========
 131
 132 String Error Functions
 133 ======================
 134
 135 =============  =========
 136 Function Name  Available
 137 =============  =========
 138 strerror
 139 strerror_s
 140 strerrorlen_s
 141 =============  =========
 142
 143 Localized String Functions
 144 ==========================
 145
 146 These functions require locale.h, and will be added when locale support is
 147 implemented in LLVM-libc.
 148
 149 =============  =========
 150 Function Name  Available
 151 =============  =========
 152 strcoll
 153 strxfrm
 154 =============  =========
 155
 156 ---------------------------
 157 \<name\>_s String Functions
 158 ---------------------------
 159
 160 Many String functions have an equivalent _s version, which is intended to be
 161 more secure and safe than the previous standard. These functions add runtime
 162 error detection and overflow protection. While they can be seen as an
 163 improvement, adoption remains relatively low among users. In addition, they are
 164 being considered for removal, see
 165 `Field Experience With Annex K — Bounds Checking Interfaces
 166 <http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1967.htm>`_. For these reasons,
 167 there is no ongoing work to implement them.