## Class template basic_string_literal

boost::log::basic_string_literal — String literal wrapper.

## Synopsis

    // In header: <boost/log/utility/string_literal_fwd.hpp>

    template<typename CharT, typename TraitsT>
    class basic_string_literal {
    public:

      // public member functions
      basic_string_literal() noexcept;
      template<typename T, size_type LenV> basic_string_literal(T(&)) noexcept;
      basic_string_literal(basic_string_literal const &) noexcept;
      this_type & operator=(this_type const &) noexcept;
      template<typename T, size_type LenV> this_type & operator=(T(&)) noexcept;
      bool operator==(this_type const &) const noexcept;
      bool operator==(const_pointer) const noexcept;
      bool operator==(string_type const &) const noexcept;
      bool operator!=(this_type const &) const noexcept;
      bool operator!=(const_pointer) const noexcept;
      bool operator!=(string_type const &) const noexcept;
      bool operator<(this_type const &) const noexcept;
      bool operator<(const_pointer) const noexcept;
      bool operator<(string_type const &) const noexcept;
      bool operator<=(this_type const &) const noexcept;
      bool operator<=(const_pointer) const noexcept;
      bool operator<=(string_type const &) const noexcept;
      bool operator>(this_type const &) const noexcept;
      bool operator>(const_pointer) const noexcept;
      bool operator>(string_type const &) const noexcept;
      bool operator>=(this_type const &) const noexcept;
      bool operator>=(const_pointer) const noexcept;
      bool operator>=(string_type const &) const noexcept;
      const_reference operator[](size_type) const noexcept;
      const_reference at(size_type) const;
      const_pointer c_str() const noexcept;
      const_pointer data() const noexcept;
      size_type size() const noexcept;
      size_type length() const noexcept;
      bool empty() const noexcept;
      const_iterator begin() const noexcept;
      const_iterator end() const noexcept;
      const_reverse_iterator rbegin() const noexcept;
      const_reverse_iterator rend() const noexcept;
      string_type str() const;
      void clear() noexcept;
      void swap(this_type &) noexcept;
      this_type & assign(this_type const &) noexcept;
      template<typename T, size_type LenV> this_type & assign(T(&)) noexcept;
      size_type copy(value_type *, size_type, size_type = 0) const;
      int compare(size_type, size_type, const_pointer, size_type) const;
      int compare(size_type, size_type, const_pointer) const noexcept;
      int compare(size_type, size_type, this_type const &) const noexcept;
      int compare(const_pointer, size_type) const noexcept;
      int compare(const_pointer) const noexcept;
      int compare(this_type const &) const noexcept;
    };

## Description

The `basic_string_literal` is a thin wrapper around a constant string literal. It provides interface similar to STL strings, but because of read-only nature of string literals, lacks ability to modify string contents. However, `basic_string_literal` objects can be assigned to and cleared.

The main advantage of this class comparing to other string classes is that it doesn't dynamically allocate memory and therefore is fast, thin and exception safe.

### `basic_string_literal` public member functions

1.     basic_string_literal() noexcept;

   Constructor

   Postconditions: | `empty() == true`

2.     template<typename T, size_type LenV> basic_string_literal(T(&) p) noexcept;

   Constructor from a string literal

   Parameters: |
   `p` | A zero-terminated constant sequence of characters
   Postconditions: | `*this == p`

3.     basic_string_literal(basic_string_literal const & that) noexcept;

   Copy constructor

   Parameters: |
   `that` | Source literal to copy string from
   Postconditions: | `*this == that`

4.     this_type & operator=(this_type const & that) noexcept;

   Assignment operator

   Parameters: |
   `that` | Source literal to copy string from
   Postconditions: | `*this == that`

5.     template<typename T, size_type LenV> this_type & operator=(T(&) p) noexcept;

   Assignment from a string literal

   Parameters: |
   `p` | A zero-terminated constant sequence of characters
   Postconditions: | `*this == p`

6.     bool operator==(this_type const & that) const noexcept;

   Lexicographical comparison (equality)

   Parameters: |
   `that` | Comparand
   Returns: | `true` if the comparand string equals to this string, `false` otherwise

7.     bool operator==(const_pointer str) const noexcept;

   Lexicographical comparison (equality)

   Parameters: |
   `str` | Comparand. Must point to a zero-terminated sequence of characters, must not be NULL.
   Returns: | `true` if the comparand string equals to this string, `false` otherwise

8.     bool operator==(string_type const & that) const noexcept;

   Lexicographical comparison (equality)

   Parameters: |
   `that` | Comparand
   Returns: | `true` if the comparand string equals to this string, `false` otherwise

9.     bool operator!=(this_type const & that) const noexcept;

   Lexicographical comparison (inequality)

   Parameters: |
   `that` | Comparand
   Returns: | `true` if the comparand string is not equal to this string, `false` otherwise

10.     bool operator!=(const_pointer str) const noexcept;

    Lexicographical comparison (inequality)

    Parameters: |
    `str` | Comparand. Must point to a zero-terminated sequence of characters, must not be NULL.
    Returns: | `true` if the comparand string is not equal to this string, `false` otherwise

11.     bool operator!=(string_type const & that) const noexcept;

    Lexicographical comparison (inequality)

    Parameters: |
    `that` | Comparand
    Returns: | `true` if the comparand string is not equal to this string, `false` otherwise

12.     bool operator<(this_type const & that) const noexcept;

    Lexicographical comparison (less ordering)

    Parameters: |
    `that` | Comparand
    Returns: | `true` if this string is less than the comparand, `false` otherwise

13.     bool operator<(const_pointer str) const noexcept;

    Lexicographical comparison (less ordering)

    Parameters: |
    `str` | Comparand. Must point to a zero-terminated sequence of characters, must not be NULL.
    Returns: | `true` if this string is less than the comparand, `false` otherwise

14.     bool operator<(string_type const & that) const noexcept;

    Lexicographical comparison (less ordering)

    Parameters: |
    `that` | Comparand
    Returns: | `true` if this string is less than the comparand, `false` otherwise

15.     bool operator<=(this_type const & that) const noexcept;

    Lexicographical comparison (less or equal ordering)

    Parameters: |
    `that` | Comparand
    Returns: | `true` if this string is less or equal to the comparand, `false` otherwise

16.     bool operator<=(const_pointer str) const noexcept;

    Lexicographical comparison (less or equal ordering)

    Parameters: |
    `str` | Comparand. Must point to a zero-terminated sequence of characters, must not be NULL.
    Returns: | `true` if this string is less or equal to the comparand, `false` otherwise

17.     bool operator<=(string_type const & that) const noexcept;

    Lexicographical comparison (less or equal ordering)

    Parameters: |
    `that` | Comparand
    Returns: | `true` if this string is less or equal to the comparand, `false` otherwise

18.     bool operator>(this_type const & that) const noexcept;

    Lexicographical comparison (greater ordering)

    Parameters: |
    `that` | Comparand
    Returns: | `true` if this string is greater than the comparand, `false` otherwise

19.     bool operator>(const_pointer str) const noexcept;

    Lexicographical comparison (greater ordering)

    Parameters: |
    `str` | Comparand. Must point to a zero-terminated sequence of characters, must not be NULL.
    Returns: | `true` if this string is greater than the comparand, `false` otherwise

20.     bool operator>(string_type const & that) const noexcept;

    Lexicographical comparison (greater ordering)

    Parameters: |
    `that` | Comparand
    Returns: | `true` if this string is greater than the comparand, `false` otherwise

21.     bool operator>=(this_type const & that) const noexcept;

    Lexicographical comparison (greater or equal ordering)

    Parameters: |
    `that` | Comparand
    Returns: | `true` if this string is greater or equal to the comparand, `false` otherwise

22.     bool operator>=(const_pointer str) const noexcept;

    Lexicographical comparison (greater or qual ordering)

    Parameters: |
    `str` | Comparand. Must point to a zero-terminated sequence of characters, must not be NULL.
    Returns: | `true` if this string is greater or equal to the comparand, `false` otherwise

23.     bool operator>=(string_type const & that) const noexcept;

    Lexicographical comparison (greater or equal ordering)

    Parameters: |
    `that` | Comparand
    Returns: | `true` if this string is greater or equal to the comparand, `false` otherwise

24.     const_reference operator[](size_type i) const noexcept;

    Subscript operator

    Parameters: |
    `i` | Requested character index
    Requires: | `i < size()`
    Returns: | Constant reference to the requested character

25.     const_reference at(size_type i) const;

    Checked subscript

    Throws: An `std::exception`-based exception if index i is out of string boundaries

    Parameters: |
    `i` | Requested character index
    Returns: | Constant reference to the requested character

26.     const_pointer c_str() const noexcept;

    Returns: | Pointer to the beginning of the literal

27.     const_pointer data() const noexcept;

    Returns: | Pointer to the beginning of the literal

28.     size_type size() const noexcept;

    Returns: | Length of the literal

29.     size_type length() const noexcept;

    Returns: | Length of the literal

30.     bool empty() const noexcept;

    Returns: | `true` if the literal is an empty string, `false` otherwise

31.     const_iterator begin() const noexcept;

    Returns: | Iterator that points to the first character of the literal

32.     const_iterator end() const noexcept;

    Returns: | Iterator that points after the last character of the literal

33.     const_reverse_iterator rbegin() const noexcept;

    Returns: | Reverse iterator that points to the last character of the literal

34.     const_reverse_iterator rend() const noexcept;

    Returns: | Reverse iterator that points before the first character of the literal

35.     string_type str() const;

    Returns: | STL string constructed from the literal

36.     void clear() noexcept;

    The method clears the literal

    Postconditions: | `empty() == true`

37.     void swap(this_type & that) noexcept;

    The method swaps two literals

38.     this_type & assign(this_type const & that) noexcept;

    Assignment from another literal

    Parameters: |
    `that` | Source literal to copy string from
    Postconditions: | `*this == that`

39.     template<typename T, size_type LenV> this_type & assign(T(&) p) noexcept;

    Assignment from another literal

    Parameters: |
    `p` | A zero-terminated constant sequence of characters
    Postconditions: | `*this == p`

40.     size_type copy(value_type * str, size_type n, size_type pos = 0) const;

    The method copies the literal or its portion to an external buffer

    Throws: An `std::exception`-based exception if pos is out of range.

    Parameters: |
    `str` | Pointer to the external buffer beginning. Must not be NULL. The buffer must have enough capacity to accommodate the requested number of characters.
    `n` | Maximum number of characters to copy
    `pos` | Starting position to start copying from
    Requires: | `pos <= size()`
    Returns: | Number of characters copied

41.     int compare(size_type pos, size_type n, const_pointer str, size_type len) const;

    Lexicographically compares the argument string to a part of this string

    Throws: An `std::exception`-based exception if pos is out of range.

    Parameters: |
    `pos` | Starting position within this string to perform comparison to
    `n` | Length of the substring of this string to perform comparison to
    `str` | Comparand. Must point to a sequence of characters, must not be NULL.
    `len` | Number of characters in the sequence str.
    Requires: | `pos <= size()`
    Returns: | Zero if the comparand equals this string, a negative value if this string is less than the comparand, a positive value if this string is greater than the comparand.

42.     int compare(size_type pos, size_type n, const_pointer str) const noexcept;

    Lexicographically compares the argument string to a part of this string

    Throws: An `std::exception`-based exception if pos is out of range.

    Parameters: |
    `pos` | Starting position within this string to perform comparison to
    `n` | Length of the substring of this string to perform comparison to
    `str` | Comparand. Must point to a zero-terminated sequence of characters, must not be NULL.
    Requires: | `pos <= size()`
    Returns: | Zero if the comparand equals this string, a negative value if this string is less than the comparand, a positive value if this string is greater than the comparand.

43.     int compare(size_type pos, size_type n, this_type const & that) const noexcept;

    Lexicographically compares the argument string literal to a part of this string

    Throws: An `std::exception`-based exception if pos is out of range.

    Parameters: |
    `pos` | Starting position within this string to perform comparison to
    `n` | Length of the substring of this string to perform comparison to
    `that` | Comparand
    Requires: | `pos <= size()`
    Returns: | Zero if the comparand equals this string, a negative value if this string is less than the comparand, a positive value if this string is greater than the comparand.

44.     int compare(const_pointer str, size_type len) const noexcept;

    Lexicographically compares the argument string to this string

    Parameters: |
    `str` | Comparand. Must point to a sequence of characters, must not be NULL.
    `len` | Number of characters in the sequence str.
    Returns: | Zero if the comparand equals this string, a negative value if this string is less than the comparand, a positive value if this string is greater than the comparand.

45.     int compare(const_pointer str) const noexcept;

    Lexicographically compares the argument string to this string

    Parameters: |
    `str` | Comparand. Must point to a zero-terminated sequence of characters, must not be NULL.
    Returns: | Zero if the comparand equals this string, a negative value if this string is less than the comparand, a positive value if this string is greater than the comparand.

46.     int compare(this_type const & that) const noexcept;

    Lexicographically compares the argument string to this string

    Parameters: |
    `that` | Comparand
    Returns: | Zero if the comparand equals this string, a negative value if this string is less than the comparand, a positive value if this string is greater than the comparand.