[clangd] Standard library mapping: prefer "primary" versions of functions over variants.

[sammccall]

Add note about skipping variants, and mention the weird begin/end case.

[kadircet]

LG

clangd/StdSymbolMap.inc

 SYMBOL(StrictTotallyOrderedWith, std::, <concepts>)
 SYMBOL(StrictWeakOrder, std::, <concepts>)
 SYMBOL(Swappable, std::, <concepts>)
 SYMBOL(SwappableWith, std::, <concepts>)
 SYMBOL(UniformRandomBitGenerator, std::, <random>)
 SYMBOL(UnsignedIntegral, std::, <concepts>)
 SYMBOL(_Exit, std::, <cstdlib>)
 SYMBOL(accumulate, std::, <numeric>)
+SYMBOL(acos, std::, <cmath>)
+SYMBOL(acosh, std::, <cmath>)
 SYMBOL(add_const, std::, <type_traits>)
 SYMBOL(add_const_t, std::, <type_traits>)
 SYMBOL(add_cv, std::, <type_traits>)
 SYMBOL(add_cv_t, std::, <type_traits>)
 SYMBOL(add_lvalue_reference, std::, <type_traits>)
 SYMBOL(add_lvalue_reference_t, std::, <type_traits>)
 SYMBOL(add_pointer, std::, <type_traits>)
 SYMBOL(add_pointer_t, std::, <type_traits>)

 SYMBOL(allocator_traits, std::, <memory>)
 SYMBOL(any, std::, <any>)
 SYMBOL(any_of, std::, <algorithm>)
 SYMBOL(apply, std::, <tuple>)
 SYMBOL(arg, std::, <complex>)
 SYMBOL(array, std::, <array>)
 SYMBOL(as_const, std::, <utility>)
 SYMBOL(asctime, std::, <ctime>)
+SYMBOL(asin, std::, <cmath>)
+SYMBOL(asinh, std::, <cmath>)
 SYMBOL(async, std::, <future>)
 SYMBOL(at_quick_exit, std::, <cstdlib>)
+SYMBOL(atan, std::, <cmath>)
+SYMBOL(atan2, std::, <cmath>)
+SYMBOL(atanh, std::, <cmath>)
 SYMBOL(atexit, std::, <cstdlib>)
 SYMBOL(atof, std::, <cstdlib>)
 SYMBOL(atoi, std::, <cstdlib>)
 SYMBOL(atol, std::, <cstdlib>)
 SYMBOL(atoll, std::, <cstdlib>)
 SYMBOL(atomic_compare_exchange_strong, std::, <atomic>)
 SYMBOL(atomic_compare_exchange_strong_explicit, std::, <atomic>)
 SYMBOL(atomic_compare_exchange_weak, std::, <atomic>)

 SYMBOL(conjunction_v, std::, <type_traits>)
 SYMBOL(const_pointer_cast, std::, <memory>)
 SYMBOL(contract_violation, std::, <contract>)
 SYMBOL(copy, std::, <algorithm>)
 SYMBOL(copy_backward, std::, <algorithm>)
 SYMBOL(copy_if, std::, <algorithm>)
 SYMBOL(copy_n, std::, <algorithm>)
 SYMBOL(copysign, std::, <cmath>)
+SYMBOL(cos, std::, <cmath>)
+SYMBOL(cosh, std::, <cmath>)
 SYMBOL(count, std::, <algorithm>)
 SYMBOL(count_if, std::, <algorithm>)
 SYMBOL(cout, std::, <iostream>)
 SYMBOL(crbegin, std::, <iterator>)
 SYMBOL(cref, std::, <functional>)
 SYMBOL(cregex_iterator, std::, <regex>)
 SYMBOL(cregex_token_iterator, std::, <regex>)
 SYMBOL(crend, std::, <iterator>)

 SYMBOL(error_code, std::, <system_error>)
 SYMBOL(error_condition, std::, <system_error>)
 SYMBOL(exa, std::, <ratio>)
 SYMBOL(exception, std::, <exception>)
 SYMBOL(exception_ptr, std::, <exception>)
 SYMBOL(exchange, std::, <utility>)
 SYMBOL(exclusive_scan, std::, <numeric>)
 SYMBOL(exit, std::, <cstdlib>)
+SYMBOL(exp, std::, <cmath>)
 SYMBOL(exp2, std::, <cmath>)
 SYMBOL(expm1, std::, <cmath>)
 SYMBOL(exponential_distribution, std::, <random>)
 SYMBOL(extent, std::, <type_traits>)
 SYMBOL(extent_v, std::, <type_traits>)
 SYMBOL(extreme_value_distribution, std::, <random>)
 SYMBOL(false_type, std::, <type_traits>)
 SYMBOL(fclose, std::, <cstdio>)

 SYMBOL(is_union, std::, <type_traits>)
 SYMBOL(is_union_v, std::, <type_traits>)
 SYMBOL(is_unsigned, std::, <type_traits>)
 SYMBOL(is_unsigned_v, std::, <type_traits>)
 SYMBOL(is_void, std::, <type_traits>)
 SYMBOL(is_void_v, std::, <type_traits>)
 SYMBOL(is_volatile, std::, <type_traits>)
 SYMBOL(is_volatile_v, std::, <type_traits>)
+SYMBOL(isalnum, std::, <cctype>)
+SYMBOL(isalpha, std::, <cctype>)
+SYMBOL(isblank, std::, <cctype>)
+SYMBOL(iscntrl, std::, <cctype>)
+SYMBOL(isdigit, std::, <cctype>)
 SYMBOL(isfinite, std::, <cmath>)
+SYMBOL(isgraph, std::, <cctype>)
 SYMBOL(isgreater, std::, <cmath>)
 SYMBOL(isgreaterequal, std::, <cmath>)
 SYMBOL(isinf, std::, <cmath>)
 SYMBOL(isless, std::, <cmath>)
 SYMBOL(islessequal, std::, <cmath>)
 SYMBOL(islessgreater, std::, <cmath>)
+SYMBOL(islower, std::, <cctype>)
 SYMBOL(isnan, std::, <cmath>)
 SYMBOL(isnormal, std::, <cmath>)
 SYMBOL(ispow2, std::, <bit>)
+SYMBOL(isprint, std::, <cctype>)
+SYMBOL(ispunct, std::, <cctype>)
+SYMBOL(isspace, std::, <cctype>)
 SYMBOL(istream_iterator, std::, <iterator>)
 SYMBOL(istreambuf_iterator, std::, <iterator>)
 SYMBOL(istringstream, std::, <sstream>)
 SYMBOL(isunordered, std::, <cmath>)
+SYMBOL(isupper, std::, <cctype>)
 SYMBOL(iswalnum, std::, <cwctype>)
 SYMBOL(iswalpha, std::, <cwctype>)
 SYMBOL(iswblank, std::, <cwctype>)
 SYMBOL(iswcntrl, std::, <cwctype>)
 SYMBOL(iswctype, std::, <cwctype>)
 SYMBOL(iswdigit, std::, <cwctype>)
 SYMBOL(iswgraph, std::, <cwctype>)
 SYMBOL(iswlower, std::, <cwctype>)
 SYMBOL(iswprint, std::, <cwctype>)
 SYMBOL(iswpunct, std::, <cwctype>)
 SYMBOL(iswspace, std::, <cwctype>)
 SYMBOL(iswupper, std::, <cwctype>)
 SYMBOL(iswxdigit, std::, <cwctype>)
+SYMBOL(isxdigit, std::, <cctype>)
 SYMBOL(iter_swap, std::, <algorithm>)
 SYMBOL(iterator, std::, <iterator>)
 SYMBOL(iterator_traits, std::, <iterator>)
 SYMBOL(jmp_buf, std::, <csetjmp>)
 SYMBOL(kill_dependency, std::, <atomic>)
 SYMBOL(kilo, std::, <ratio>)
 SYMBOL(launch, std::, <future>)
 SYMBOL(launder, std::, <new>)

 SYMBOL(list, std::, <list>)
 SYMBOL(llrint, std::, <cmath>)
 SYMBOL(llround, std::, <cmath>)
 SYMBOL(locale, std::, <locale>)
 SYMBOL(localeconv, std::, <clocale>)
 SYMBOL(localtime, std::, <ctime>)
 SYMBOL(lock, std::, <mutex>)
 SYMBOL(lock_guard, std::, <mutex>)
+SYMBOL(log, std::, <cmath>)
+SYMBOL(log10, std::, <cmath>)
 SYMBOL(log1p, std::, <cmath>)
 SYMBOL(log2, std::, <cmath>)
 SYMBOL(log2p1, std::, <bit>)
 SYMBOL(logb, std::, <cmath>)
 SYMBOL(logic_error, std::, <stdexcept>)
 SYMBOL(logical_and, std::, <functional>)
 SYMBOL(logical_not, std::, <functional>)
 SYMBOL(logical_or, std::, <functional>)

 SYMBOL(piecewise_linear_distribution, std::, <random>)
 SYMBOL(plus, std::, <functional>)
 SYMBOL(pointer_safety, std::, <memory>)
 SYMBOL(pointer_traits, std::, <memory>)
 SYMBOL(poisson_distribution, std::, <random>)
 SYMBOL(polar, std::, <complex>)
 SYMBOL(polymorphic_allocator, std::, <memory_resource>)
 SYMBOL(pop_heap, std::, <algorithm>)
+SYMBOL(pow, std::, <cmath>)
 SYMBOL(prev, std::, <iterator>)
 SYMBOL(prev_permutation, std::, <algorithm>)
 SYMBOL(printf, std::, <cstdio>)
 SYMBOL(priority_queue, std::, <queue>)
 SYMBOL(proj, std::, <complex>)
 SYMBOL(promise, std::, <future>)
 SYMBOL(ptrdiff_t, std::, <cstddef>)
 SYMBOL(push_heap, std::, <algorithm>)

 SYMBOL(regex_iterator, std::, <regex>)
 SYMBOL(regex_match, std::, <regex>)
 SYMBOL(regex_replace, std::, <regex>)
 SYMBOL(regex_search, std::, <regex>)
 SYMBOL(regex_token_iterator, std::, <regex>)
 SYMBOL(regex_traits, std::, <regex>)
 SYMBOL(reinterpret_pointer_cast, std::, <memory>)
 SYMBOL(remainder, std::, <cmath>)
+SYMBOL(remove, std::, <cstdio>)
 SYMBOL(remove_all_extents, std::, <type_traits>)
 SYMBOL(remove_all_extents_t, std::, <type_traits>)
 SYMBOL(remove_const, std::, <type_traits>)
 SYMBOL(remove_const_t, std::, <type_traits>)
 SYMBOL(remove_copy, std::, <algorithm>)
 SYMBOL(remove_copy_if, std::, <algorithm>)
 SYMBOL(remove_cv, std::, <type_traits>)
 SYMBOL(remove_cv_t, std::, <type_traits>)

 SYMBOL(showbase, std::, <ios>)
 SYMBOL(showpoint, std::, <ios>)
 SYMBOL(showpos, std::, <ios>)
 SYMBOL(shuffle, std::, <algorithm>)
 SYMBOL(shuffle_order_engine, std::, <random>)
 SYMBOL(sig_atomic_t, std::, <csignal>)
 SYMBOL(signal, std::, <csignal>)
 SYMBOL(signbit, std::, <cmath>)
+SYMBOL(sin, std::, <cmath>)
+SYMBOL(sinh, std::, <cmath>)
 SYMBOL(size, std::, <iterator>)
 SYMBOL(skipws, std::, <ios>)
 SYMBOL(slice, std::, <valarray>)
 SYMBOL(slice_array, std::, <valarray>)
 SYMBOL(smatch, std::, <regex>)
 SYMBOL(snprintf, std::, <cstdio>)
 SYMBOL(sort, std::, <algorithm>)
 SYMBOL(sort_heap, std::, <algorithm>)
 SYMBOL(span, std::, <span>)
 SYMBOL(sprintf, std::, <cstdio>)
+SYMBOL(sqrt, std::, <cmath>)
 SYMBOL(srand, std::, <cstdlib>)
 SYMBOL(sregex_iterator, std::, <regex>)
 SYMBOL(sregex_token_iterator, std::, <regex>)
 SYMBOL(sscanf, std::, <cstdio>)
 SYMBOL(ssub_match, std::, <regex>)
 SYMBOL(stable_partition, std::, <algorithm>)
 SYMBOL(stable_sort, std::, <algorithm>)
 SYMBOL(stack, std::, <stack>)

 SYMBOL(subtract_with_carry_engine, std::, <random>)
 SYMBOL(swap_ranges, std::, <algorithm>)
 SYMBOL(swprintf, std::, <cwchar>)
 SYMBOL(swscanf, std::, <cwchar>)
 SYMBOL(syncbuf, std::, <syncstream>)
 SYMBOL(system, std::, <cstdlib>)
 SYMBOL(system_category, std::, <system_error>)
 SYMBOL(system_error, std::, <system_error>)
+SYMBOL(tan, std::, <cmath>)
+SYMBOL(tanh, std::, <cmath>)
 SYMBOL(tera, std::, <ratio>)
 SYMBOL(terminate, std::, <exception>)
 SYMBOL(terminate_handler, std::, <exception>)
 SYMBOL(tgamma, std::, <cmath>)
 SYMBOL(thread, std::, <thread>)
 SYMBOL(throw_with_nested, std::, <exception>)
 SYMBOL(tie, std::, <tuple>)
 SYMBOL(time, std::, <ctime>)
 SYMBOL(time_base, std::, <locale>)
 SYMBOL(time_get, std::, <locale>)
 SYMBOL(time_get_byname, std::, <locale>)
 SYMBOL(time_put, std::, <locale>)
 SYMBOL(time_put_byname, std::, <locale>)
 SYMBOL(time_t, std::, <ctime>)
 SYMBOL(timed_mutex, std::, <mutex>)
 SYMBOL(timespec, std::, <ctime>)
 SYMBOL(timespec_get, std::, <ctime>)
 SYMBOL(tm, std::, <ctime>)
 SYMBOL(tmpfile, std::, <cstdio>)
 SYMBOL(tmpnam, std::, <cstdio>)
 SYMBOL(to_address, std::, <memory>)
 SYMBOL(to_chars, std::, <charconv>)
 SYMBOL(to_integer, std::, <cstddef>)
 SYMBOL(to_string, std::, <string>)
+SYMBOL(tolower, std::, <cctype>)
+SYMBOL(toupper, std::, <cctype>)
 SYMBOL(towctrans, std::, <cwctype>)
 SYMBOL(towlower, std::, <cwctype>)
 SYMBOL(towupper, std::, <cwctype>)
 SYMBOL(transform, std::, <algorithm>)
 SYMBOL(transform_exclusive_scan, std::, <numeric>)
 SYMBOL(transform_inclusive_scan, std::, <numeric>)
 SYMBOL(transform_reduce, std::, <numeric>)
 SYMBOL(true_type, std::, <type_traits>)

 SYMBOL(unitbuf, std::, <ios>)
 SYMBOL(unordered_map, std::, <unordered_map>)
 SYMBOL(unordered_multimap, std::, <unordered_map>)
 SYMBOL(unordered_multiset, std::, <unordered_set>)
 SYMBOL(unordered_set, std::, <unordered_set>)
 SYMBOL(upper_bound, std::, <algorithm>)
 SYMBOL(uppercase, std::, <ios>)
 SYMBOL(use_facet, std::, <locale>)
+SYMBOL(uses_allocator, std::, <memory>)
 SYMBOL(uses_allocator_v, std::, <memory>)
 SYMBOL(va_list, std::, <cstdarg>)
 SYMBOL(valarray, std::, <valarray>)
 SYMBOL(variant, std::, <variant>)
 SYMBOL(variant_alternative, std::, <variant>)
 SYMBOL(variant_alternative_t, std::, <variant>)
 SYMBOL(variant_npos, std::, <variant>)
 SYMBOL(variant_size, std::, <variant>)

clangd/include-mapping/gen_std.py

Usage:
   2. Download cppreference offline HTML files (e.g. html_book_20181028.zip) at
        https://en.cppreference.com/w/Cppreference:Archives
   3. Unzip the zip file from step 2 to directory </cppreference>, you should
      get a "reference" directory in </cppreference>
   4. Run the command:
        gen_std.py -cppreference </cppreference/reference> > StdSymbolMap.inc
 """
 
-from bs4 import BeautifulSoup
+from bs4 import BeautifulSoup, NavigableString
 
 import argparse
 import collections
 import datetime
 import multiprocessing
 import os
 import signal
 import sys

 def ParseIndexPage(index_page_html):
   """Parse index page.
   The index page lists all std symbols and hrefs to their detailed pages
   (which contain the defined header). An example:
 
   <a href="abs.html" title="abs"><tt>abs()</tt></a> (int) <br>
   <a href="acos.html" title="acos"><tt>acos()</tt></a> <br>
 
-  Returns a list of tuple (symbol_name, relative_path_to_symbol_page).
+  Returns a list of tuple (symbol_name, relative_path_to_symbol_page, variant).
   """
   symbols = []
   soup = BeautifulSoup(index_page_html, "html.parser")
   for symbol_href in soup.select("a[title]"):
+    # Ignore annotated symbols like "acos<>() (std::complex)".
+    # These tend to be overloads, and we the primary is more useful.
+    # This accidentally accepts begin/end despite the (iterator) caption: the
+    # (since C++11) note is first. They are good symbols, so the bug is unfixed.
+    caption = symbol_href.next_sibling
+    variant = isinstance(caption, NavigableString) and "(" in caption
     symbol_tt = symbol_href.find("tt")
     if symbol_tt:
       symbols.append((symbol_tt.text.rstrip("<>()"), # strip any trailing <>()
-                      symbol_href["href"]))
+                      symbol_href["href"], variant))
   return symbols
 
 class Symbol:
 
   def __init__(self, name, namespace, headers):
     # unqualifed symbol name, e.g. "move"
     self.name = name
     # namespace of the symbol (with trailing "::"), e.g. "std::"
def GetSymbols(pool, root_dir, index_page_name, namespace):
   #   1. Parse index page which lists all symbols to get symbol
   #      name (unqualified name) and its href link to the symbol page which
   #      contains the defined header.
   #   2. Parse the symbol page to get the defined header.
   index_page_path = os.path.join(root_dir, index_page_name)
   with open(index_page_path, "r") as f:
     # Read each symbol page in parallel.
     results = [] # (symbol_name, promise of [header...])
-    for symbol_name, symbol_page_path in ParseIndexPage(f.read()):
+    for symbol_name, symbol_page_path, variant in ParseIndexPage(f.read()):
+      # Variant symbols (e.g. the std::locale version of isalpha) add ambiguity.
+      # FIXME: use these as a fallback rather than ignoring entirely.
+      if variant:
+        continue
       path = os.path.join(root_dir, symbol_page_path)
       results.append((symbol_name,
                       pool.apply_async(ReadSymbolPage, (path, symbol_name))))
 
     # Build map from symbol name to a set of headers.
     symbol_headers = collections.defaultdict(set)
     for symbol_name, lazy_headers in results:
       symbol_headers[symbol_name].update(lazy_headers.get())

clangd/include-mapping/test.py

  <a href="complex/abs.html" title="abs"><tt>abs&lt;&gt;()</tt></a> (std::complex) <br>
  <a href="acos.html" title="acos"><tt>acos()</tt></a> <br>
  <a href="acosh.html" title="acosh"><tt>acosh()</tt></a> <span class="t-mark-rev">(since C++11)</span> <br>
  <a href="as_bytes.html" title="as bytes"><tt>as_bytes&lt;&gt;()</tt></a> <span class="t-mark-rev t-since-cxx20">(since C++20)</span> <br>
  """
 
     actual = ParseIndexPage(html)
     expected = [
-      ("abs", "abs.html"),
-      ("abs", "complex/abs.html"),
-      ("acos", "acos.html"),
-      ("acosh", "acosh.html"),
-      ("as_bytes", "as_bytes.html"),
+      ("abs", "abs.html", True),
+      ("abs", "complex/abs.html", True),
+      ("acos", "acos.html", False),
+      ("acosh", "acosh.html", False),
+      ("as_bytes", "as_bytes.html", False),
     ]
     self.assertEqual(len(actual), len(expected))
     for i in range(0, len(actual)):
       self.assertEqual(expected[i][0], actual[i][0])
       self.assertTrue(actual[i][1].endswith(expected[i][1]))
+      self.assertEqual(expected[i][2], actual[i][2])
 
 
   def testParseSymbolPage_SingleHeader(self):
     # Defined in header <cmath>
     html = """
  <table class="t-dcl-begin"><tbody>
   <tr class="t-dsc-header">
   <td> <div>Defined in header <code><a href="cmath.html" title="cmath">&lt;cmath&gt;</a></code>