## Class object_name

boost::log::ipc::object_name — A system object name class.

## Synopsis

    // In header: <boost/log/utility/ipc/object_name.hpp>

    class object_name {
    public:

      // Name scopes.
      enum scope { global, user, session, process_group };

      // public member functions
      object_name() noexcept;
      object_name(object_name &&) noexcept;
      object_name(object_name const &);
      object_name(scope, const char *);
      object_name(scope, std::string const &);
      object_name & operator=(object_name &&) noexcept;
      object_name & operator=(object_name const &);
      bool empty() const noexcept;
      std::size_t size() const noexcept;
      const char * c_str() const noexcept;
      void swap(object_name &) noexcept;

      // public static functions
      static object_name from_native(const char *);
      static object_name from_native(std::string const &);

      // friend functions
      void swap(object_name &, object_name &) noexcept;
      std::string to_string(object_name const &);
      bool operator==(object_name const &, object_name const &) noexcept;
      bool operator!=(object_name const &, object_name const &) noexcept;
      bool operator<(object_name const &, object_name const &) noexcept;
      bool operator>(object_name const &, object_name const &) noexcept;
      bool operator<=(object_name const &, object_name const &) noexcept;
      bool operator>=(object_name const &, object_name const &) noexcept;
      template<typename CharT, typename TraitsT>
        std::basic_ostream< CharT, TraitsT > &
        operator<<(std::basic_ostream< CharT, TraitsT > &, object_name const &);
    };

## Description

In order to identify a system-wide object such as a shared memory segment or a named synchronization primitive the object has to be given a name. The format of the name is specific to the operating system and the `object_name` class provides an abstraction for names of objects. It also provides means for scoping, which allows to avoid name clashes between different processes.

The object name is a UTF-8 encoded string. The portable object name should consist of the following characters:

    A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
    a b c d e f g h i j k l m n o p q r s t u v w x y z
    0 1 2 3 4 5 6 7 8 9 . _ -

| Note
The character set corresponds to the POSIX Portable Filename Character Set (http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html#tag_03_278).

Use of other characters may result in non-portable system-specific behavior.

The name can have one of the following scopes:

- `global` - objects within this scope are visible to any process on the system. In order to use this scope the process may need to have extended privileges. This scope is not available for Windows Store applications.

- `user` - objects within this scope can be opened by processes running under the same user as the current process.

- `session` - objects within this scope are visible to processes within the session of the current process. The definition of a session may vary between operating systems. On POSIX, a session is typically a group of processes attached to a single virtual terminal device. On Windows a session is started when a user logs into the system. There is also a separate session for Windows services.

- `process_group` - objects within this scope are visible to processes within the process group of the current process. Currently, on Windows all processes running in the current session are considered members of the same process group. This may change in future.

The scopes are not overlapping. For instance, if an object is created in the global scope, the object cannot be opened with the same name but in user's scope.

Note that name scoping is not a security feature. On some systems any process on the system has technical capability to open objects within any scope. The scope is only used to help avoid name clashes between processes using `object_name` to identify objects.

### `object_name` public member functions

1.     object_name() noexcept;

   Default constructor. The method creates an empty object name.

   Postconditions: | `empty() == true`

2.     object_name(object_name && that) noexcept;

   Move constructor.

3.     object_name(object_name const & that);

   Copy constructor.

4.     object_name(scope ns, const char * str);

   Constructor from the object name

   Parameters: |
   `ns` | The scope of the object name
   `str` | The object name, must not be NULL.

5.     object_name(scope ns, std::string const & str);

   Constructor from the object name

   Parameters: |
   `ns` | The scope of the object name
   `str` | The object name

6.     object_name & operator=(object_name && that) noexcept;

   Move assignment

7.     object_name & operator=(object_name const & that);

   Copy assignment

8.     bool empty() const noexcept;

   Returns `true` if the object name is empty

9.     std::size_t size() const noexcept;

   Returns length of the name, in bytes

10.     const char * c_str() const noexcept;

    Returns the name string

11.     void swap(object_name & that) noexcept;

    Swaps the object name with another object name

### `object_name` public static functions

1.     static object_name from_native(const char * str);

   Constructor from the native string.

   Parameters: |
   `str` | The object name string, must not be `NULL`. The string format is specific to the operating system.

2.     static object_name from_native(std::string const & str);

   Constructor from the native string.

   Parameters: |
   `str` | The object name string. The string format is specific to the operating system.

### `object_name` friend functions

1.     void swap(object_name & left, object_name & right) noexcept;

   Swaps two object names

2.     std::string to_string(object_name const & name);

   Returns string representation of the object name

3.     bool operator==(object_name const & left, object_name const & right) noexcept;

   Equality operator

4.     bool operator!=(object_name const & left, object_name const & right) noexcept;

   Inequality operator

5.     bool operator<(object_name const & left, object_name const & right) noexcept;

   Less operator

6.     bool operator>(object_name const & left, object_name const & right) noexcept;

   Greater operator

7.     bool operator<=(object_name const & left, object_name const & right) noexcept;

   Less or equal operator

8.     bool operator>=(object_name const & left, object_name const & right) noexcept;

   Greater or equal operator

9.     template<typename CharT, typename TraitsT>
         std::basic_ostream< CharT, TraitsT > &
         operator<<(std::basic_ostream< CharT, TraitsT > & strm,
                    object_name const & name);

   Stream ouput operator