caio/clang-p2996
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[libc][docs] split "String Functions" into string.h, strings.h, stdlib.h, and inttypes.h (#118860)

Browse Source 
bcmp, bcopy, and bzero should be moved from libc/src/string/ to
lib/src/strings/ in order for docgen to use existing conventions to find
whether we implement a function or not.

We should add support to docgen for mentioning glibc extensions (mempcpy) or
extensions from other libcs.
This commit is contained in:
Nick Desaulniers
2024-12-10 12:59:46 -08:00
committed by GitHub
parent 04269ea0e4
commit 02e39a13c3
9 changed files with 851 additions and 161 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
libc/docs/headers/index.rst
View File

@@ -10,6 +10,7 @@ Implementation Status
errno
fenv
float
inttypes
locale
math/index.rst
search
@@ -17,6 +18,8 @@ Implementation Status
signal
stdbit
stdio
stdlib
string
strings
threads
time

42
libc/docs/headers/inttypes.rst Normal file
View File

@@ -0,0 +1,42 @@
.. include:: ../check.rst
==========
inttypes.h
==========
Functions
=========
.. list-table::
:widths: auto
:align: center
:header-rows: 1
* - Function
- Implemented
- C23 Standard Section
- POSIX.1-2024 Standard Section
* - imaxabs
- |check|
- 7.8.2.1
-
* - imaxdiv
- |check|
- 7.8.2.2
-
* - strtoimax
- |check|
- 7.8.2.3
-
* - strtoumax
- |check|
- 7.8.2.3
-
* - wcstoimax
-
- 7.8.2.4
-
* - wcstoumax
-
- 7.8.2.4
-

255
libc/docs/headers/stdlib.rst Normal file
View File

@@ -0,0 +1,255 @@
.. include:: ../check.rst
========
stdlib.h
========
Macros
======
.. list-table::
:widths: auto
:align: center
:header-rows: 1
* - Macro
- Implemented
- C23 Standard Section
- POSIX.1-2024 Standard Section
* - EXIT_FAILURE
- |check|
- 7.24
-
* - EXIT_SUCCESS
- |check|
- 7.24
-
* - MB_CUR_MAX
- |check|
- 7.24
-
* - RAND_MAX
- |check|
- 7.24
-
* - __STDC_VERSION_STDLIB_H__
-
- 7.24
-
Functions
=========
.. list-table::
:widths: auto
:align: center
:header-rows: 1
* - Function
- Implemented
- C23 Standard Section
- POSIX.1-2024 Standard Section
* - _Exit
- |check|
- 7.24.4.5
-
* - abort
- |check|
- 7.24.4.1
-
* - abs
- |check|
- 7.24.6.1
-
* - aligned_alloc
- |check|
- 7.24.3.1
-
* - at_quick_exit
- |check|
- 7.24.4.3
-
* - atexit
- |check|
- 7.24.4.2
-
* - atof
- |check|
- 7.24.1.1
-
* - atoi
- |check|
- 7.24.1.2
-
* - atol
- |check|
- 7.24.1.2
-
* - atoll
- |check|
- 7.24.1.2
-
* - bsearch
- |check|
- 7.24.5.1
-
* - calloc
- |check|
- 7.24.3.2
-
* - div
- |check|
- 7.24.6.2
-
* - exit
- |check|
- 7.24.4.4
-
* - free
- |check|
- 7.24.3.3
-
* - free_aligned_sized
-
- 7.24.3.5
-
* - free_sized
-
- 7.24.3.4
-
* - getenv
- |check|
- 7.24.4.6
-
* - labs
- |check|
- 7.24.6.1
-
* - ldiv
- |check|
- 7.24.6.2
-
* - llabs
- |check|
- 7.24.6.1
-
* - lldiv
- |check|
- 7.24.6.2
-
* - malloc
- |check|
- 7.24.3.6
-
* - mblen
-
- 7.24.7.1
-
* - mbstowcs
-
- 7.24.8.1
-
* - mbtowc
-
- 7.24.7.2
-
* - memalignment
-
- 7.24.9.1
-
* - qsort
- |check|
- 7.24.5.2
-
* - quick_exit
- |check|
- 7.24.4.7
-
* - rand
- |check|
- 7.24.2.1
-
* - realloc
- |check|
- 7.24.3.7
-
* - srand
- |check|
- 7.24.2.2
-
* - strfromd
- |check|
- 7.24.1.3
-
* - strfromd128
-
- 7.24.1.4
-
* - strfromd32
-
- 7.24.1.4
-
* - strfromd64
-
- 7.24.1.4
-
* - strfromf
- |check|
- 7.24.1.3
-
* - strfroml
- |check|
- 7.24.1.3
-
* - strtod
- |check|
- 7.24.1.5
-
* - strtod128
-
- 7.24.1.6
-
* - strtod32
-
- 7.24.1.6
-
* - strtod64
-
- 7.24.1.6
-
* - strtof
- |check|
- 7.24.1.5
-
* - strtol
- |check|
- 7.24.1.7
-
* - strtold
- |check|
- 7.24.1.5
-
* - strtoll
- |check|
- 7.24.1.7
-
* - strtoul
- |check|
- 7.24.1.7
-
* - strtoull
- |check|
- 7.24.1.7
-
* - system
- |check|
- 7.24.4.8
-
* - wcstombs
-
- 7.24.8.2
-
* - wctomb
-
- 7.24.7.3
-

155
libc/docs/headers/string.rst Normal file
View File

@@ -0,0 +1,155 @@
.. include:: ../check.rst
========
string.h
========
Macros
======
.. list-table::
:widths: auto
:align: center
:header-rows: 1
* - Macro
- Implemented
- C23 Standard Section
- POSIX.1-2024 Standard Section
* - __STDC_VERSION_STRING_H__
-
- 7.26.1
-
Functions
=========
.. list-table::
:widths: auto
:align: center
:header-rows: 1
* - Function
- Implemented
- C23 Standard Section
- POSIX.1-2024 Standard Section
* - memccpy
- |check|
- 7.26.2.2
-
* - memchr
- |check|
- 7.26.5.2
-
* - memcmp
- |check|
- 7.26.4.1
-
* - memcpy
- |check|
- 7.26.2.1
-
* - memmove
- |check|
- 7.26.2.3
-
* - mempcpy
- |check|
- TODO: glibc extension
-
* - memset
- |check|
- 7.26.6.1
-
* - memset_explicit
- |check|
- 7.26.6.2
-
* - stpcpy
- |check|
-
- https://pubs.opengroup.org/onlinepubs/9799919799/functions/stpcpy.html
* - stpncpy
- |check|
-
- https://pubs.opengroup.org/onlinepubs/9799919799/functions/stpncpy.html
* - strcat
- |check|
- 7.26.3.1
-
* - strchr
- |check|
- 7.26.5.3
-
* - strcmp
- |check|
- 7.26.4.2
-
* - strcoll
- |check|
- 7.26.4.3
-
* - strcpy
- |check|
- 7.26.2.4
-
* - strcspn
- |check|
- 7.26.5.4
-
* - strdup
- |check|
- 7.26.2.6
-
* - strerror
- |check|
- 7.26.6.3
-
* - strlen
- |check|
- 7.26.6.4
-
* - strncat
- |check|
- 7.26.3.2
-
* - strncmp
- |check|
- 7.26.4.4
-
* - strncpy
- |check|
- 7.26.2.5
-
* - strndup
- |check|
- 7.26.2.7
-
* - strpbrk
- |check|
- 7.26.5.5
-
* - strrchr
- |check|
- 7.26.5.6
-
* - strspn
- |check|
- 7.26.5.7
-
* - strstr
- |check|
- 7.26.5.8
-
* - strtok
- |check|
- 7.26.5.9
-
* - strtok_r
- |check|
-
- https://pubs.opengroup.org/onlinepubs/9799919799/functions/strtok_r.html
* - strxfrm
- |check|
- 7.26.4.5
-

222
libc/docs/headers/strings.rst
View File

@@ -1,166 +1,66 @@
================
String Functions
================
.. include:: ../check.rst
---------------
Source location
---------------
=========
strings.h
=========
- The main source for string functions is located at:
``libc/src/string``.
Functions
=========
- The source for string conversion functions is located at:
``libc/src/stdlib`` and
``libc/src/__support``.
.. list-table::
:widths: auto
:align: center
:header-rows: 1
- 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 Available
============= =========
bzero |check|
bcmp |check|
bcopy |check|
memcpy |check|
memset |check|
memcmp |check|
memmove |check|
============= =========
Other Raw Memory Functions
==========================
============= =========
Function Name Available
============= =========
memchr |check|
memrchr |check|
memccpy |check|
mempcpy |check|
============= =========
String Memory Functions
=======================
============= =========
Function Name Available
============= =========
stpcpy |check|
stpncpy |check|
strcpy |check|
strncpy |check|
strcat |check|
strncat |check|
strdup |check|
strndup |check|
============= =========
String Examination Functions
============================
============= =========
Function Name Available
============= =========
strlen |check|
strnlen |check|
strcmp |check|
strncmp |check|
strchr |check|
strrchr |check|
strspn |check|
strcspn |check|
strpbrk |check|
strstr |check|
strtok |check|
strtok_r |check|
============= =========
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
<https://nigeltao.github.io/blog/2020/eisel-lemire.html>`_). 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
<https://github.com/nigeltao/parse-number-fxx-test-data>`_. The test was done
with LLVM-libc built on 2022-04-14 and Debian GLibc version 2.33-6. The targets
``libc_str_to_float_comparison_test`` and
``libc_system_str_to_float_comparison_test`` were built and run on the test data
10 times each, skipping the first run since it was an outlier.
============= =========
Function Name Available
============= =========
atof |check|
atoi |check|
atol |check|
atoll |check|
strtol |check|
strtoll |check|
strtoul |check|
strtoull |check|
strtof |check|
strtod |check|
strtold |check|
strtoimax |check|
strtoumax |check|
============= =========
String Error Functions
======================
============= =========
Function Name Available
============= =========
strerror |check|
strerror_r |check|
============= =========
Localized String Functions
==========================
These functions require locale.h, and will be finished when locale support is
implemented in LLVM-libc.
============= =========
Function Name Available
============= =========
strcoll Partially
strxfrm Partially
============= =========
---------------------------
\<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. In addition, they are
being considered for removal, see
`Field Experience With Annex K — Bounds Checking Interfaces
<http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1967.htm>`_. For these reasons,
there is no ongoing work to implement them.
* - Function
- Implemented
- C23 Standard Section
- POSIX.1-2024 Standard Section
* - bcmp
- |check|
-
- removed in POSIX.1-2008
* - bcopy
- |check|
-
- removed in POSIX.1-2008
* - bzero
- |check|
-
- removed in POSIX.1-2008
* - ffs
-
-
- https://pubs.opengroup.org/onlinepubs/9799919799/functions/ffs.html
* - ffsl
-
-
- https://pubs.opengroup.org/onlinepubs/9799919799/functions/ffsl.html
* - ffsll
-
-
- https://pubs.opengroup.org/onlinepubs/9799919799/functions/ffsll.html
* - index
- |check|
-
- removed in POSIX.1-2008
* - rindex
- |check|
-
- removed in POSIX.1-2008
* - strcasecmp
- |check|
-
- https://pubs.opengroup.org/onlinepubs/9799919799/functions/strncasecmp.html
* - strcasecmp_l
-
-
- https://pubs.opengroup.org/onlinepubs/9799919799/functions/strncasecmp.html
* - strncasecmp
- |check|
-
- https://pubs.opengroup.org/onlinepubs/9799919799/functions/strncasecmp.html
* - strncasecmp_l
-
-
- https://pubs.opengroup.org/onlinepubs/9799919799/functions/strncasecmp.html

22
libc/utils/docgen/inttypes.json Normal file
View File

@@ -0,0 +1,22 @@
{
"functions": {
"imaxabs": {
"c-definition": "7.8.2.1"
},
"imaxdiv": {
"c-definition": "7.8.2.2"
},
"strtoimax": {
"c-definition": "7.8.2.3"
},
"strtoumax": {
"c-definition": "7.8.2.3"
},
"wcstoimax": {
"c-definition": "7.8.2.4"
},
"wcstoumax": {
"c-definition": "7.8.2.4"
}
}
}

174
libc/utils/docgen/stdlib.json Normal file
View File

@@ -0,0 +1,174 @@
{
"macros": {
"__STDC_VERSION_STDLIB_H__": {
"c-definition": "7.24"
},
"EXIT_FAILURE": {
"c-definition": "7.24"
},
"EXIT_SUCCESS": {
"c-definition": "7.24"
},
"RAND_MAX": {
"c-definition": "7.24"
},
"MB_CUR_MAX": {
"c-definition": "7.24"
}
},
"functions": {
"atof": {
"c-definition": "7.24.1.1"
},
"atoi": {
"c-definition": "7.24.1.2"
},
"atol": {
"c-definition": "7.24.1.2"
},
"atoll": {
"c-definition": "7.24.1.2"
},
"strfromd": {
"c-definition": "7.24.1.3"
},
"strfromf": {
"c-definition": "7.24.1.3"
},
"strfroml": {
"c-definition": "7.24.1.3"
},
"strfromd32": {
"c-definition": "7.24.1.4"
},
"strfromd64": {
"c-definition": "7.24.1.4"
},
"strfromd128": {
"c-definition": "7.24.1.4"
},
"strtod": {
"c-definition": "7.24.1.5"
},
"strtof": {
"c-definition": "7.24.1.5"
},
"strtold": {
"c-definition": "7.24.1.5"
},
"strtod32": {
"c-definition": "7.24.1.6"
},
"strtod64": {
"c-definition": "7.24.1.6"
},
"strtod128": {
"c-definition": "7.24.1.6"
},
"strtol": {
"c-definition": "7.24.1.7"
},
"strtoll": {
"c-definition": "7.24.1.7"
},
"strtoul": {
"c-definition": "7.24.1.7"
},
"strtoull": {
"c-definition": "7.24.1.7"
},
"rand": {
"c-definition": "7.24.2.1"
},
"srand": {
"c-definition": "7.24.2.2"
},
"aligned_alloc": {
"c-definition": "7.24.3.1"
},
"calloc": {
"c-definition": "7.24.3.2"
},
"free": {
"c-definition": "7.24.3.3"
},
"free_sized": {
"c-definition": "7.24.3.4"
},
"free_aligned_sized": {
"c-definition": "7.24.3.5"
},
"malloc": {
"c-definition": "7.24.3.6"
},
"realloc": {
"c-definition": "7.24.3.7"
},
"abort": {
"c-definition": "7.24.4.1"
},
"atexit": {
"c-definition": "7.24.4.2"
},
"at_quick_exit": {
"c-definition": "7.24.4.3"
},
"exit": {
"c-definition": "7.24.4.4"
},
"_Exit": {
"c-definition": "7.24.4.5"
},
"getenv": {
"c-definition": "7.24.4.6"
},
"quick_exit": {
"c-definition": "7.24.4.7"
},
"system": {
"c-definition": "7.24.4.8"
},
"bsearch": {
"c-definition": "7.24.5.1"
},
"qsort": {
"c-definition": "7.24.5.2"
},
"abs": {
"c-definition": "7.24.6.1"
},
"labs": {
"c-definition": "7.24.6.1"
},
"llabs": {
"c-definition": "7.24.6.1"
},
"div": {
"c-definition": "7.24.6.2"
},
"ldiv": {
"c-definition": "7.24.6.2"
},
"lldiv": {
"c-definition": "7.24.6.2"
},
"mblen": {
"c-definition": "7.24.7.1"
},
"mbtowc": {
"c-definition": "7.24.7.2"
},
"wctomb": {
"c-definition": "7.24.7.3"
},
"mbstowcs": {
"c-definition": "7.24.8.1"
},
"wcstombs": {
"c-definition": "7.24.8.2"
},
"memalignment": {
"c-definition": "7.24.9.1"
}
}
}

99
libc/utils/docgen/string.json Normal file
View File

@@ -0,0 +1,99 @@
{
"macros": {
"__STDC_VERSION_STRING_H__": {
"c-definition": "7.26.1"
}
},
"functions": {
"memcpy": {
"c-definition": "7.26.2.1"
},
"memccpy": {
"c-definition": "7.26.2.2"
},
"mempcpy": {
"c-definition": "TODO: glibc extension"
},
"memmove": {
"c-definition": "7.26.2.3"
},
"strcpy": {
"c-definition": "7.26.2.4"
},
"strncpy": {
"c-definition": "7.26.2.5"
},
"stpcpy": {
"posix-definition": "https://pubs.opengroup.org/onlinepubs/9799919799/functions/stpcpy.html"
},
"stpncpy": {
"posix-definition": "https://pubs.opengroup.org/onlinepubs/9799919799/functions/stpncpy.html"
},
"strdup": {
"c-definition": "7.26.2.6"
},
"strndup": {
"c-definition": "7.26.2.7"
},
"strcat": {
"c-definition": "7.26.3.1"
},
"strncat": {
"c-definition": "7.26.3.2"
},
"memcmp": {
"c-definition": "7.26.4.1"
},
"strcmp": {
"c-definition": "7.26.4.2"
},
"strcoll": {
"c-definition": "7.26.4.3"
},
"strncmp": {
"c-definition": "7.26.4.4"
},
"strxfrm": {
"c-definition": "7.26.4.5"
},
"memchr": {
"c-definition": "7.26.5.2"
},
"strchr": {
"c-definition": "7.26.5.3"
},
"strcspn": {
"c-definition": "7.26.5.4"
},
"strpbrk": {
"c-definition": "7.26.5.5"
},
"strrchr": {
"c-definition": "7.26.5.6"
},
"strspn": {
"c-definition": "7.26.5.7"
},
"strstr": {
"c-definition": "7.26.5.8"
},
"strtok": {
"c-definition": "7.26.5.9"
},
"strtok_r": {
"posix-definition": "https://pubs.opengroup.org/onlinepubs/9799919799/functions/strtok_r.html"
},
"memset": {
"c-definition": "7.26.6.1"
},
"memset_explicit": {
"c-definition": "7.26.6.2"
},
"strerror": {
"c-definition": "7.26.6.3"
},
"strlen": {
"c-definition": "7.26.6.4"
}
}
}

40
libc/utils/docgen/strings.json Normal file
View File

@@ -0,0 +1,40 @@
{
"functions": {
"bzero": {
"posix-definition": "removed in POSIX.1-2008"
},
"bcmp": {
"posix-definition": "removed in POSIX.1-2008"
},
"bcopy": {
"posix-definition": "removed in POSIX.1-2008"
},
"ffs": {
"posix-definition": "https://pubs.opengroup.org/onlinepubs/9799919799/functions/ffs.html"
},
"ffsl": {
"posix-definition": "https://pubs.opengroup.org/onlinepubs/9799919799/functions/ffsl.html"
},
"ffsll": {
"posix-definition": "https://pubs.opengroup.org/onlinepubs/9799919799/functions/ffsll.html"
},
"index": {
"posix-definition": "removed in POSIX.1-2008"
},
"rindex": {
"posix-definition": "removed in POSIX.1-2008"
},
"strcasecmp": {
"posix-definition": "https://pubs.opengroup.org/onlinepubs/9799919799/functions/strncasecmp.html"
},
"strcasecmp_l": {
"posix-definition": "https://pubs.opengroup.org/onlinepubs/9799919799/functions/strncasecmp.html"
},
"strncasecmp": {
"posix-definition": "https://pubs.opengroup.org/onlinepubs/9799919799/functions/strncasecmp.html"
},
"strncasecmp_l": {
"posix-definition": "https://pubs.opengroup.org/onlinepubs/9799919799/functions/strncasecmp.html"
}
}
}