diff --git a/libc/docs/index.rst b/libc/docs/index.rst --- a/libc/docs/index.rst +++ b/libc/docs/index.rst @@ -82,3 +82,4 @@ mechanics_of_public_api redirectors source_layout + strings diff --git a/libc/docs/strings.rst b/libc/docs/strings.rst new file mode 100644 --- /dev/null +++ b/libc/docs/strings.rst @@ -0,0 +1,168 @@ +============================= +String Functions in LLVM-libc +============================= + +------- +Summary +------- + +This site tracks the status of the implementation of string functions in LLVM +Libc. This includes a few extra functions that are not in string.h, such as +functions converting strings to numbers. + +--------------- +Source location +--------------- + +- The main source for string functions is located at: + ``libc/src/string``. + +- The source for string conversion functions is located at: + ``libc/src/stdlib`` and + ``libc/src/__support``. + +- The tests are located at: + ``libc/test/src/string``, + ``libc/test/src/stdlib``, and + ``libc/test/src/__support`` + respectively. + +--------------------- +Implementation Status +--------------------- + +Primary memory functions +======================== + +.. TODO(gchatelet): add details about the memory functions. + + +============= ======== +Function Name Designed +============= ======== +bzero YES +bcmp YES +memcpy YES +memset YES +memcmp YES +memmove YES +============= ======== + + +Other Raw Memory Functions +========================== + +============= ======== +Function Name Designed +============= ======== +memchr YES +memrchr YES +memccpy YES +mempcpy YES +============= ======== + +String Memory Functions +======================= + +============= ======== +Function Name Designed +============= ======== +stpcpy YES +stpncpy YES +strcpy YES +strncpy YES +strcat YES +strncat YES +strdup YES +strndup YES +============= ======== + +String Examination Functions +============================ + +============= ======== +Function Name Designed +============= ======== +strlen YES +strnlen YES +strcmp YES +strncmp YES +strchr YES +strrchr YES +strspn YES +strcspn YES +strpbrk YES +strstr YES +strtok YES +strtok_r YES +============= ======== + +String Conversion Functions +============================ + +These functions are not in strings.h, but are still primarily string +functions, and are therefore tracked along with the rest of the string +functions. + +The String to float functions were implemented using the Eisel-Lemire algorithm +(read more about the algorithm here: `The Eisel-Lemire ParseNumberF64 Algorithm +`_). This improved +the performance of string to float and double, and allowed it to complete this +comprehensive test 15% faster than glibc: `Parse Number FXX Test Data +`_. + + +============= ======== +Function Name Designed +============= ======== +atof YES +atoi YES +atol YES +atoll YES +strtol YES +strtoll YES +strtoul YES +strtoull YES +strtof YES +strtod YES +strtold YES +strtoimax YES +strtoumax YES +============= ======== + +String Error Functions +====================== + +============= ======== +Function Name Designed +============= ======== +strerror +strerror_s +strerrorlen_s +============= ======== + +Localized String Functions +========================== + +These functions require locale.h, and will be added when locale support is +implemented in LLVM-libc. + +============= ======== +Function Name Designed +============= ======== +strcoll +strxfrm +============= ======== + +--------------------------- +\_s String Functions +--------------------------- + +Many String functions have an equivalent _s version, which is intended to be +more secure and safe than the previous standard. These functions add runtime +error detection and overflow protection. While they can be seen as an +improvement, adoption remains relatively low among users. In addition, they are +being considered for removal, see +`Field Experience With Annex K — Bounds Checking Interfaces +`_. For these reasons, +there is no ongoing work to implement them.