[libc][docs] Add doc for libc string functions

[michaelrj]

Summary

This patch adds a document describing the status of the string functions
in LLVM-libc.

[jeffbailey]

Thanks for doing this! I do want to pull all of the impllemented/unimplemented functions into a list like the C++ folks have it, but this is nice to have.

It would also be nice to check to see if the _s functions are still being considered for removal and include that information here. http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1967.htm

[gchatelet]

libc/docs/strings.rst

34–40

Outside of Google EXEgesis mostly refers to llvm-exegesis. It is not really connected to string functions (even though it's been developed by the same people).
Maybe call the section Primary memory function without description and leave the TODO assigned to me (omitting the exegesis word).

44

In this document, the Designed and Implemented columns are always equal. Maybe there is more value in telling which architectures are actually implemented ?

103

Maybe this should go into an Additional Functions section?

[michaelrj]

addressed comments.

libc/docs/strings.rst

44

Most of these string functions are completely platform independent, since they work on individual bytes at a time, so giving all of them architecture specific statuses feels redundant. On the other hand, the memory functions and the conversion functions do have possible platform differences, so tracking them could be helpful. I think the biggest problem is that all of these functions already have versions for all of our supported platforms, so no matter how we slice it the table will just say "Done" everywhere, except for the functions that we haven't started.

103

I like them here because it puts them before the functions that aren't implemented yet.

[sivachandra]

libc/docs/strings.rst

44

Perhaps a more useful way to present this is to just say whether an implementation is available or not. So, just one column Available under which you say YES if available, nothing if not. You can potentially add a Notes column in future to add additional notes if required. For a reader not involved in the development, that something has been designed or not does not help much. A person interested in contributing can engage on discourse et al to gather more information.

[gchatelet]

libc/docs/strings.rst

44

Yep in that case a single column is enough.

[michaelrj]

address comments and add performance information

[michaelrj]

add more specifics on performance comparison

[sivachandra]

Still LGTM with the suggested inline fix.

libc/docs/strings.rst

85

s/Designed/Available everywhere?

[tschuett]

In D123645#3452505, @sivachandra wrote:

Still LGTM with the suggested inline fix.

Did you say something about endianness? Or is it X86 + aarch64 only?

[michaelrj]

address final comments

libc/docs/strings.rst

85

I went with Available over Available Everywhere since it allows for specifying which platforms it is available on if that's not everywhere.

[sivachandra]

libc/docs/strings.rst

85

Ah, I didn't quite understand when @tschuett made that comment. I did not intend to suggest replacing "Designed" with "Available everywhere" but was trying to say the "Designed" should be replaced with "Available" everywhere relevant.

libc/docs/index.rst

.. toctree::
     ground_truth_specification
     header_generation
     implementation_standard
     api_test
     layering
     mechanics_of_public_api
     redirectors
     source_layout
+    strings

libc/docs/strings.rst

+=============================
+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
+---------------------
+
+EXEgesis Raw Memory Functions
+=============================
+
+These functions were developed by the EXEgesis team and have been
+open sourced via LLVM libc.
+
+.. TODO(gchatelet): add details about the exegesis memory functions.
+
+
+=============  ========  ===========
+Function_Name  Designed  Implemented
+=============  ========  ===========
+bzero          DONE      DONE
+bcmp           DONE      DONE
+memcpy         DONE      DONE
+memset         DONE      DONE
+memcmp         DONE      DONE
+memmove        DONE      DONE
+=============  ========  ===========
+
+
+Other Raw Memory Functions
+==========================
+
+=============  ========  ===========
+Function_Name  Designed  Implemented
+=============  ========  ===========
+memchr         DONE      DONE
+memrchr        DONE      DONE
+memccpy        DONE      DONE
+mempcpy        DONE      DONE
+=============  ========  ===========
+
+String Memory Functions
+=======================
+
+=============  ========  ===========
+Function_Name  Designed  Implemented
+=============  ========  ===========
+stpcpy         DONE      DONE
+stpncpy        DONE      DONE
+strcpy         DONE      DONE
+strncpy        DONE      DONE
+strcat         DONE      DONE
+strncat        DONE      DONE
+strdup         DONE      DONE
+strndup        DONE      DONE
+=============  ========  ===========
+
+String Examination Functions
+============================
+
+=============  ========  ===========
+Function_Name  Designed  Implemented
+=============  ========  ===========
+strlen         DONE      DONE
+strnlen        DONE      DONE
+strcmp         DONE      DONE
+strncmp        DONE      DONE
+strchr         DONE      DONE
+strrchr        DONE      DONE
+strspn         DONE      DONE
+strcspn        DONE      DONE
+strpbrk        DONE      DONE
+strstr         DONE      DONE
+strtok         DONE      DONE
+strtok_r       DONE      DONE
+=============  ========  ===========
+
+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.
+
+.. TODO(michaelrj): add details about string to float conversion design and implementation.
+
+
+=============  ========  ===========
+Function_Name  Designed  Implemented
+=============  ========  ===========
+atof           DONE      DONE
+atoi           DONE      DONE
+atol           DONE      DONE
+atoll          DONE      DONE
+strtol         DONE      DONE
+strtoll        DONE      DONE
+strtoul        DONE      DONE
+strtoull       DONE      DONE
+strtof         DONE      DONE
+strtod         DONE      DONE
+strtold        DONE      DONE
+strtoimax      DONE      DONE
+strtoumax      DONE      DONE
+=============  ========  ===========
+
+String Error Functions
+======================
+
+=============  ========  ===========
+Function_Name  Designed  Implemented
+=============  ========  ===========
+strerror
+strerror_s
+strerrorlen_s
+=============  ========  ===========
+
+Localized String Functions
+==========================
+
+These functions require locale.h, which is currently deprioritised.
+
+=============  ========  ===========
+Function_Name  Designed  Implemented
+=============  ========  ===========
+strcoll
+strxfrm
+=============  ========  ===========
+
+---------------------------
+\<name\>_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. For this and other
+reasons, these functions are currently deprioritised.