feat: migrate /cpp/language/functions from cppref

Author: Sudrut

src/content/docs/cpp/language/functions.mdx

@@ -0,0 +1,56 @@
+---
+title: Functions
+cppdoc:
+  keys: ["cpp.lang.functions"]
+---
+
+import { Revision, RevisionBlock } from "@components/revision";
+import DocLink from "@components/DocLink.astro";
+import Missing from "@components/Missing.astro";
+
+Functions are C++ entities that associate a sequence of <DocLink src="/cpp/language/statements">statements</DocLink> (a _function body_) with a _name_ and a list of zero or more _function parameters_.
+
+```cpp
+// function name: "isodd"
+// parameter list has one parameter, with name "n" and type int
+// the return type is bool
+bool isodd(int n) { // the body of the function begins
+  return n % 2;
+}                   // the body of the function ends
+```
+
+When a function is invoked, e.g. in a <DocLink src="/cpp/language/operator_other">function-call expression</DocLink>, the parameters are initialized from the arguments (either provided at the place of call or <DocLink src="/cpp/language/default_arguments">defaulted</DocLink>) and the statements in the function body are executed. If the <DocLink src="/cpp/language/function">parameter list</DocLink> ends with `...`, extra arguments can be supplied to the function, such a function is called <DocLink src="/cpp/language/variadic_arguments">variadic function</DocLink>.
+
+```cpp
+int main() {
+  for (int arg : {-3, -2, -1, 0, 1, 2, 3})
+    std::cout << isodd(arg) << ' '; // isodd called 7 times, each
+                                    // time n is copy-initialized from arg
+}
+```
+
+<DocLink src="/cpp/language/unqualified_lookup">Unqualified</DocLink> function names in function-call expressions are looked up with an extra set of rules called <DocLink src="/cpp/language/adl">"argument-dependent lookup" (ADL)</DocLink>.
+
+A function can terminate by <DocLink src="/cpp/language/return">returning</DocLink> or by <DocLink src="/cpp/language/throw">throwing</DocLink> an <DocLink src="/cpp/language/exceptions">exception</DocLink>.
+
+<RevisionBlock since="C++20">
+  A function may be a <DocLink src="/cpp/language/coroutines">coroutine</DocLink>, in which case it can suspend execution to be resumed later.
+</RevisionBlock>
+
+A <DocLink src="/cpp/language/function">function declaration</DocLink> may appear in any scope, but a <DocLink src="/cpp/language/function">function definition</DocLink> may only appear in namespace scope or, for <DocLink src="/cpp/language/member_functions">member</DocLink> and <DocLink src="/cpp/language/friend">friend</DocLink> functions, in class scope. A function that is declared in a class body without a friend specifier is a class member function. Such functions have many additional properties, see <DocLink src="/cpp/language/member_functions">member functions</DocLink> for details.
+
+Functions are not objects: there are no arrays of functions and functions cannot be passed by value or returned from other functions. Pointers and references to functions (except for the <DocLink src="/cpp/language/main_function">main function</DocLink> <Revision since="C++20">and <DocLink src="/cpp/language/extending_std">most standard library functions</DocLink></Revision>) are allowed, and may be used where these functions themselves cannot. Therefore we say these functions are "addressable".
+
+Each function has a type, which consists of the function's return type, the types of all parameters (after array-to-pointer and function-to-pointer transformations, see <DocLink src="/cpp/language/function">parameter list</DocLink>) <Revision since="C++17">, whether the function is <DocLink src="/cpp/language/noexcept_spec">noexcept</DocLink> or not</Revision>, and, for non-static member functions, cv-qualification <Revision since="C++11">and ref-qualification</Revision>. Function types also have <DocLink src="/cpp/language/language_linkage">language linkage</DocLink>. There are no cv-qualified function types (not to be confused with the types of <DocLink src="/cpp/language/language_linkage">cv-qualified functions</DocLink> such as `int f() const;` or functions returning <DocLink src="/cpp/language/cv">cv-qualified types</DocLink>, such as `std::string const f();`). Any cv-qualifier is ignored if it is added to an alias for a function type.
+
+Multiple functions in the same scope may have the same name, as long as their parameter lists and, for non-static member functions, cv<Revision since="C++11">/ref</Revision>-qualifications are different. This is known as <DocLink src="/cpp/language/overload_resolution">function overloading</DocLink>. Function declarations that differ only in the return type <Revision since="C++17">and the noexcept specification</Revision> cannot be overloaded. The <DocLink src="/cpp/language/overloaded_address">address of an overloaded function</DocLink> is determined differently.
+
+<RevisionBlock since="C++11">
+  C++ implements [anonymous functions](https://en.wikipedia.org/wiki/anonymous_function) using <DocLink src="/cpp/language/lambda">lambda-expressions</DocLink>.
+</RevisionBlock>
+
+## Function objects
+
+Besides function lvalues, the function call expression supports pointers to functions, and any value of class type that overloads the function-call operator or is convertible to function pointer <Revision since="C++11">(including <DocLink src="/cpp/language/lambda">lambda-expressions</DocLink>)</Revision>. Together, these types are known as <Missing>FunctionObjects</Missing>, and they are used ubiquitously through the C++ standard library, see for example, usages of <Missing>BinaryPredicate</Missing> and <Missing>Compare</Missing>.
+
+The standard library also provides a number of predefined <Missing>function object templates</Missing> as well as the methods to compose new ones (including <Missing>std::less</Missing><Revision since="C++11">, <Missing>std::mem_fn</Missing>, <Missing>std::bind</Missing>, <Missing>std::function</Missing></Revision><Revision since="C++17">, <Missing>std::not_fn</Missing></Revision><Revision since="C++20">, <Missing>std::bind_front</Missing></Revision><Revision since="C++23">, std::bind_back, std::move_only_function</Revision><Revision since="C++26">, std::copyable_function, and std::function_ref</Revision>).