Cockpit-cpp/ZjServer/thirdparty/mysql/include/mysqlx/devapi/common.h

/*
 * Copyright (c) 2015, 2018, Oracle and/or its affiliates. All rights reserved.
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License, version 2.0, as
 * published by the Free Software Foundation.
 *
 * This program is also distributed with certain software (including
 * but not limited to OpenSSL) that is licensed under separate terms,
 * as designated in a particular file or component or in included license
 * documentation.  The authors of MySQL hereby grant you an
 * additional permission to link the program and your derivative works
 * with the separately licensed software that they have included with
 * MySQL.
 *
 * Without limiting anything contained in the foregoing, this file,
 * which is part of MySQL Connector/C++, is also subject to the
 * Universal FOSS Exception, version 1.0, a copy of which can be found at
 * http://oss.oracle.com/licenses/universal-foss-exception.
 *
 * This program is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 * See the GNU General Public License, version 2.0, for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software Foundation, Inc.,
 * 51 Franklin St, Fifth Floor, Boston, MA 02110-1301  USA
 */

#ifndef MYSQLX_COMMON_H
#define MYSQLX_COMMON_H


#include "../common.h"

#include <string>
#include <stdexcept>
#include <ostream>
#include <memory>
#include <forward_list>
#include <string.h>  // for memcpy
#include <utility>   // std::move etc

namespace cdk {
namespace foundation {

class bytes;
class string;

}}  // cdk::foundation


namespace mysqlx {

using std::out_of_range;

using common::byte;
class Value;


/**
  A wrapper around std::wstring that can perform
  conversions from/to different character encodings
  used by MySQL.

  Currently only utf-8 encoding is supported.

  @ingroup devapi_aux
*/

class string : public std::wstring
{

  struct Impl
  {
    PUBLIC_API static std::string to_utf8(const string&);
    PUBLIC_API static void from_utf8(string&, const std::string&);
  };

public:

  string() {}

  string(const wchar_t *other)
  {
    if (other)
      assign(other);
  }
  string(const std::wstring &other) : std::wstring(other) {}
  string(std::wstring &&other) : std::wstring(std::move(other)) {}

  // TODO: make utf8 conversions explicit

  string(const char *other)
  {
    if (!other)
      return;
    std::string utf8(other);
    Impl::from_utf8(*this, utf8);
  }

  string(const std::string &other)
  {
    Impl::from_utf8(*this, other);
  }

  string(const common::Value&);
  string(const Value &val);

  // conversion to utf-8

  operator std::string() const
  {
    return Impl::to_utf8(*this);
  }

};


inline
string::string(const common::Value &val)
{
  switch (val.get_type())
  {
  case common::Value::STRING:
    Impl::from_utf8(*this, val.get_string());
    return;

  default:
    assign(val.get_wstring());
  }
}


inline
std::ostream& operator<<(std::ostream &out, const string &str)
{
  const std::string utf8(str);
  out << utf8;
  return out;
}


typedef unsigned long col_count_t;
typedef unsigned long row_count_t;


/**
  Class representing a region of memory holding raw bytes.

  Method `begin()` returns pointer to the first byte in the
  region, `end()` to one past the last byte in the region.

  @note An instance of `bytes` does not store the bytes -
  it merely describes a region of memory and is equivalent
  to a pair of pointers. It is very cheap to copy `bytes` and
  pass them by value.

  @note This class extends std::pair<byte *, size_t> to make
  it consistent with how memory regions are described by
  std::get_temporary_buffer(). It is also possible to initialize
  a `bytes` instance by buffer returned from
  std::get_temporary_buffer(), as follows:

    bytes buf = std::get_temporary_buffer<byte>(size);

  @ingroup devapi_aux
*/

class bytes : public std::pair<const byte*, size_t>
{

public:

  bytes(const byte *beg_, const byte *end_)
    : pair(beg_, end_ - beg_)
  {}

  bytes(const byte *beg, size_t len) : pair(beg, len)
  {}

  bytes(const char *str) : pair((const byte*)str, 0)
  {
    if (nullptr != str)
      second = strlen(str);
  }

  bytes(std::pair<const byte*, size_t> buf) : pair(buf)
  {}

  bytes() : pair(nullptr, 0)
  {}

  bytes(const bytes &) = default;

  virtual const byte* begin() const { return first; }
  virtual const byte* end() const { return first + second; }

  size_t length() const { return second; }
  size_t size() const { return length(); }

  class Access;
  friend Access;
};


/**
  Base class for connector errors.

  @internal
  TODO: Derive from std::system_error and introduce proper
  error codes.
  @endinternal

  @ingroup devapi
*/

// TODO: Make it header-only class somehow...

DLL_WARNINGS_PUSH

class PUBLIC_API Error : public common::Error
{

  DLL_WARNINGS_POP

public:

  Error(const char *msg)
    : common::Error(msg)
  {}
};



#define CATCH_AND_WRAP \
  catch (const ::mysqlx::Error&) { throw; }       \
  catch (const std::out_of_range&) { throw; }     \
  catch (const std::exception &e)                 \
  { throw ::mysqlx::Error(e.what()); }            \
  catch (const char *e)                           \
  { throw ::mysqlx::Error(e); }                   \
  catch (...)                                     \
  { throw ::mysqlx::Error("Unknown exception"); } \


inline
void throw_error(const char *msg)
{
  throw ::mysqlx::Error(msg);
}


/*
  Infrastructure for type-agnostic handling of lists
  ==================================================

  Template internal::List_initializer<> defined below is used to return lists
  of values from public API method so that user can store this list in
  a container of his choice. The only requirement is that the container instance
  should be constructible from two iterators defining a range of elements
  (such constructors exists for standard STL containers, for example).

  Thus, given a public API method foo() which returns a List_initializer<> for
  lists of elements of type X, user can do the following:

     My_container cont = foo();

  The container will be constructed as if this code was executed:

     My_container cont = My_container(begin, end);

  where begin and end are STL iterators defining a range of elements of type X.
  This is implemented by defining templated conversion operator.

  Apart from initializing containers, values of List_initializer<> type can
  be iterated using a range loop:

    for(X &el : foo()) { ... }

  Otherwise, user should not be able to use List_initializer<> values directly.
*/

namespace internal {

/*
  Iterator template.

  It defines an STL input iterator which is implemented using an
  implementation object of some type Impl. It is assumed that Impl
  has the following methods:

   void iterator_start() - puts iterator in "before begin" position;
   bool iterator_next() - moves iterator to next position, returns
                          false if it was not possible;
   Value_type iterator_get() - gets current value.

   An implementation object must be passed to iterator constructor. Iterator
   stores only a pointer to this implementation (so it must exist as long as
   iterator is used).
*/

template<
  typename Impl,
  typename T          = typename std::iterator_traits<Impl>::value_type,
  typename Distance   = typename std::iterator_traits<T*>::difference_type,
  typename Pointer    = typename std::iterator_traits<T*>::pointer,
  typename Reference  = typename std::iterator_traits<T*>::reference
>
struct Iterator
  : std::iterator < std::input_iterator_tag, T, Distance, Pointer, Reference >
{
protected:

  typename std::remove_reference<Impl>::type *m_impl = NULL;
  bool m_at_end = false;

public:

  Iterator(Impl& impl)
    : m_impl(&impl)
  {
    m_impl->iterator_start();
    m_at_end = !m_impl->iterator_next();
  }

  Iterator()
    : m_at_end(true)
  {}

  bool operator !=(const Iterator &other) const
  {
    /*
      Compares only if both iterators are at the end
      of the sequence.
    */
    return !(m_at_end && other.m_at_end);
  }

  Iterator& operator++()
  {
    try {
      if (m_impl && !m_at_end)
        m_at_end = !m_impl->iterator_next();
      return *this;
    }
    CATCH_AND_WRAP
  }

  T operator*() const
  {
    if (!m_impl || m_at_end)
      THROW("Attempt to dereference null iterator");

    try {
      return m_impl->iterator_get();
    }
    CATCH_AND_WRAP
  }

  friend Impl;
};


/*
  List_initializer object can be used to initialize a container of
  arbitrary type U with list of items taken from a source object.

  It is assumed that the source object type Source defines iterator
  type and that std::begin/end() return iterators to the beginning
  and end of the sequence. The container type U is assumed to have
  a constructor from begin/end iterator.

  List_iterator defines begin/end() methods, so it is possible to
  iterate over the sequence without storing it in any container.
*/

template <class Source>
class List_initializer
{
protected:

  Source m_src;

  friend Source;

public:

  typedef typename std::remove_reference<Source>::type::iterator iterator;

  /*
    Arguments given to the constructor are passed to the internal
    m_src object.
  */

  template <typename... Ty>
  List_initializer(Ty&&... args)
    : m_src(std::forward<Ty>(args)...)
  {}

  /*
    Narrow the set of types for which this template is instantiated
    to avoid ambiguous conversion errors. It is important to disallow
    conversion to std::initializer_list<> because this conversion path
    is considered when assigning to STL containers.
  */

  template <
    typename U
    , typename std::is_constructible<
        U, const iterator&, const iterator&
      >::type* = nullptr
    , typename std::enable_if<
        ! std::is_same< U, std::initializer_list<typename U::value_type> >::value
      >::type* = nullptr
  >
  operator U()
  {
    try {
      return U(std::begin(m_src), std::end(m_src));
    }
    CATCH_AND_WRAP
  }

  iterator begin()
  {
    try {
      return std::begin(m_src);
    }
    CATCH_AND_WRAP
  }

  iterator end() const
  {
    try {
      return std::end(m_src);
    }
    CATCH_AND_WRAP
  }

};


template <typename T>
struct iterator_traits
{
  using value_type = typename std::remove_reference<T>::type;
  using difference_type
    = typename std::iterator_traits<value_type*>::difference_type;
  using pointer
    = typename std::iterator_traits<value_type*>::pointer;
  using reference
    = typename std::iterator_traits<value_type*>::reference;
};


/*
  This helper template adapts class Impl to be used as a source for
  List_initializer<> template.

  Class Impl should be suitable for the Iterator<> template which is used to
  build iterators required by List_initializer<>. That is, Impl should
  implement iterator_start(), iteratore_next() etc (see Iterator<>).
*/

template<
  typename Impl,
  typename Value_type = typename Impl::Value,
  typename Distance   = typename iterator_traits<Value_type>::difference_type,
  typename Pointer    = typename iterator_traits<Value_type>::pointer,
  typename Reference  = typename iterator_traits<Value_type>::reference
>
class List_source
{
protected:

  Impl m_impl;

public:

  template <typename... Ty>
  List_source(Ty&&... args)
    : m_impl(std::forward<Ty>(args)...)
  {}

  using iterator = Iterator<Impl, Value_type, Distance, Pointer, Reference>;

  iterator begin()
  {
    return iterator(m_impl);
  }

  iterator end() const
  {
    return iterator();
  }
};


/*
  A template used to adapt an object of class Impl that represents an array of
  values accessed via operator[] to be used as source for List_initializer<>
  template. This template uses instance of Impl to implement the iterator
  methods iterator_start(), so that it can be used with Iterator<> template.
*/

template <typename Impl, typename Value_type = typename Impl::Value>
class Array_src_impl
{
protected:

  Impl m_impl;
  size_t m_pos = 0;
  bool   m_at_begin = true;

public:

  template <typename... Ty>
  Array_src_impl(Ty&&... args)
    : m_impl(std::forward<Ty>(args)...)
  {}

  void iterator_start()
  {
    m_pos = 0;
    m_at_begin = true;
  }

  bool iterator_next()
  {
    if (m_at_begin)
      m_at_begin = false;
    else
      m_pos++;
    return m_pos < size();
  }

  Value_type iterator_get()
  {
    return operator[](m_pos);
  }

  Value_type operator[](size_t pos)
  {
    return m_impl[pos];
  }

  size_t size() const
  {
    return m_impl.size();
  }
};


/*
  This template adapts an object of type Impl holding an array of values as
  a source for List_initializer<> template. It combines List_source<> and
  Array_src_impl<> adapters.
*/

template<
  typename Impl,
  typename Value_type = typename Impl::Value,
  typename Distance   = typename iterator_traits<Value_type>::difference_type,
  typename Pointer    = typename iterator_traits<Value_type>::pointer,
  typename Reference  = typename iterator_traits<Value_type>::reference
>
class Array_source
  : public List_source<
      Array_src_impl<Impl, Value_type>,
      Value_type,
      Distance,
      Pointer,
      Reference
    >
{
  using Base = List_source<
      Array_src_impl<Impl, Value_type>,
      Value_type,
      Distance,
      Pointer,
      Reference
  >;

  using Base::m_impl;

public:

  using
  List_source<
      Array_src_impl<Impl, Value_type>,
      Value_type,
      Distance,
      Pointer,
      Reference
  >::List_source;

  Value_type operator[](size_t pos)
  {
    return m_impl[pos];
  }

  size_t size() const
  {
    return m_impl.size();
  }
};

}


/*
  Infrastructure for handling variable argument lists
  ===================================================

  See documentation of Args_processor<> template.
*/

namespace internal {

/*
  Type trait which checks if std::begin()/end() work on objects of given
  class C, so that it can be used as a range to iterate over.

  TODO: Make it work also with user-defined begin()/end() functions.
  TODO: Make it work with plain C arrays. For example:

      int vals[] = { 1, 2, 3 }
      process_args(data, vals)
*/

template <class C>
class is_range
{
  /*
    Note: This overload is taken into account only if std::begin(X) and
    std::end(X) expressions are valid.
  */
  template <class X>
  static std::true_type
  test(
    decltype(std::begin(*((X*)nullptr)))*,
    decltype(std::end(*((X*)nullptr)))*
  );

  template <class X>
  static std::false_type test(...);

public:

  static const bool value = std::is_same<
    std::true_type,
    decltype(test<C>(nullptr, nullptr))
  >::value;
};


/*
  Class template to be used for uniform processing of variable argument lists
  in public API methods. This template handles the cases where arguments
  are specified directly as a list:

    method(arg1, arg2, ..., argN)

  or they are taken from a container such as std::list:

    method(container)

  or they are taken from a range of items described by two iterators:

    method(begin, end)

  A class B that is using this template to define a varargs method 'foo'
  should define it as follows:

    template <typename... T>
    X foo(T... args)
    {
      Args_processor<B>::process_args(m_impl, args...);
      return ...;
    }

  Process_args() is a static method of Args_processor<> and therefore
  additional context data is passed to it as the first argument. By default
  this context is a pointer to internal implementation object, as defined
  by the base class B. The process_args() methods does all the necessary
  processing of the variable argument list, passing the resulting items
  one-by-one to B::process_one() method. Base class B must define this
  static method, which takes the context and one data item as arguments.
  B::process_one() method can have overloads that handle different types
  of data items.

  See devapi/detail/crud.h for usage examples.
*/

template <class Base, class D = typename Base::Impl*>
class Args_processor
{
public:

  /*
    Check if item of type T can be passed to Base::process_one()
  */

  template <typename T>
  class can_process
  {
    template <typename X>
    static std::true_type
    test(decltype(Base::process_one(*(D*)nullptr,*(X*)nullptr))*);

    template <typename X>
    static std::false_type test(...);

  public:

    static const bool value
      = std::is_same< std::true_type, decltype(test<T>(nullptr)) >::value;
  };

public:

  /*
    Process items from a container.
  */

  template <
    typename C,
    typename std::enable_if<is_range<C>::value>::type* = nullptr,
    typename std::enable_if<!can_process<C>::value>::type* = nullptr
  >
  static void process_args(D data, C container)
  {
    // TODO: use (const) reference to avoid copying instances?
    for (auto el : container)
    {
      Base::process_one(data, el);
    }
  }

  /*
    If process_args(data, a, b) is called and a,b are of the same type It
    which can not be passed to Base::process_one() then we assume that a and
    b are iterators that describe a range of elements to process.
  */

  template <
    typename It,
    typename std::enable_if<!can_process<It>::value>::type* = nullptr
  >
  static void process_args(D data, const It &begin, const It &end)
  {
    for (It it = begin; it != end; ++it)
    {
      Base::process_one(data, *it);
    }
  }

  /*
    Process elements given as a varargs list.
  */

  template <
    typename T,
    typename... R,
    typename std::enable_if<can_process<T>::value>::type* = nullptr
  >
  static void process_args(D data, T first, R&&... rest)
  {
    process_args1(data, first, std::forward<R>(rest)...);
  }

private:

  template <
    typename T,
    typename... R,
    typename std::enable_if<can_process<T>::value>::type* = nullptr
  >
  static void process_args1(D data, T first, R&&... rest)
  {
    Base::process_one(data, first);
    process_args1(data, std::forward<R>(rest)...);
  }

  static void process_args1(D)
  {}

};

}  // internal namespace


}  // mysqlx


#endif