Move str and c_str to the fmt namespace and document the API.

doc/format.rst

@@ -19,81 +19,9 @@ String Formatting
 .. doxygenclass:: format::StringRef
    :members:
 
-.. ifconfig:: False
-
-   .. class:: Formatter
-
-      In addition, the :class:`Formatter` defines a number of methods that are
-      intended to be replaced by subclasses:
-
-      .. method:: parse(format_string)
-
-         Loop over the format_string and return an iterable of tuples
-         (*literal_text*, *field_name*, *format_spec*, *conversion*).  This is used
-         by :meth:`vformat` to break the string into either literal text, or
-         replacement fields.
-
-         The values in the tuple conceptually represent a span of literal text
-         followed by a single replacement field.  If there is no literal text
-         (which can happen if two replacement fields occur consecutively), then
-         *literal_text* will be a zero-length string.  If there is no replacement
-         field, then the values of *field_name*, *format_spec* and *conversion*
-         will be ``None``.
-
-      .. method:: get_field(field_name, args, kwargs)
-
-         Given *field_name* as returned by :meth:`parse` (see above), convert it to
-         an object to be formatted.  Returns a tuple (obj, used_key).  The default
-         version takes strings of the form defined in :pep:`3101`, such as
-         "0[name]" or "label.title".  *args* and *kwargs* are as passed in to
-         :meth:`vformat`.  The return value *used_key* has the same meaning as the
-         *key* parameter to :meth:`get_value`.
-
-      .. method:: get_value(key, args, kwargs)
-
-         Retrieve a given field value.  The *key* argument will be either an
-         integer or a string.  If it is an integer, it represents the index of the
-         positional argument in *args*; if it is a string, then it represents a
-         named argument in *kwargs*.
-
-         The *args* parameter is set to the list of positional arguments to
-         :meth:`vformat`, and the *kwargs* parameter is set to the dictionary of
-         keyword arguments.
-
-         For compound field names, these functions are only called for the first
-         component of the field name; Subsequent components are handled through
-         normal attribute and indexing operations.
-
-         So for example, the field expression '0.name' would cause
-         :meth:`get_value` to be called with a *key* argument of 0.  The ``name``
-         attribute will be looked up after :meth:`get_value` returns by calling the
-         built-in :func:`getattr` function.
-
-         If the index or keyword refers to an item that does not exist, then an
-         :exc:`IndexError` or :exc:`KeyError` should be raised.
-
-      .. method:: check_unused_args(used_args, args, kwargs)
-
-         Implement checking for unused arguments if desired.  The arguments to this
-         function is the set of all argument keys that were actually referred to in
-         the format string (integers for positional arguments, and strings for
-         named arguments), and a reference to the *args* and *kwargs* that was
-         passed to vformat.  The set of unused args can be calculated from these
-         parameters.  :meth:`check_unused_args` is assumed to raise an exception if
-         the check fails.
-
-      .. method:: format_field(value, format_spec)
-
-         :meth:`format_field` simply calls the global :func:`format` built-in.  The
-         method is provided so that subclasses can override it.
-
-      .. method:: convert_field(value, conversion)
-
-         Converts the value (returned by :meth:`get_field`) given a conversion type
-         (as in the tuple returned by the :meth:`parse` method).  The default
-         version understands 's' (str), 'r' (repr) and 'a' (ascii) conversion
-         types.
+.. doxygenfunction:: format::str
 
+.. doxygenfunction:: format::c_str
 
 .. _formatstrings: