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       |check|
 139 strerror_r     |check|
 140 =============  =========
 141
 142 Localized String Functions
 143 ==========================
 144
 145 These functions require locale.h, and will be finished when locale support is
 146 implemented in LLVM-libc.
 147
 148 =============  =========
 149 Function Name  Available
 150 =============  =========
 151 strcoll        Partially
 152 strxfrm        Partially
 153 =============  =========
 154
 155 ---------------------------
 156 \<name\>_s String Functions
 157 ---------------------------
 158
 159 Many String functions have an equivalent _s version, which is intended to be
 160 more secure and safe than the previous standard. These functions add runtime
 161 error detection and overflow protection. While they can be seen as an
 162 improvement, adoption remains relatively low among users. In addition, they are
 163 being considered for removal, see
 164 `Field Experience With Annex K — Bounds Checking Interfaces
 165 <http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1967.htm>`_. For these reasons,
 166 there is no ongoing work to implement them.