rice 4.3.3 → 4.6.0

data/rice/cpp_api/Array.hpp

@@ -0,0 +1,209 @@
+#ifndef Rice__Array__hpp_
+#define Rice__Array__hpp_
+
+#include <iterator>
+#include <memory>
+
+namespace Rice
+{
+  //! A wrapper for the ruby Array class.
+  /*! This class provides a C++-style interface to ruby's Array class and
+   *  its associated rb_ary_* functions.
+   *  Example:
+   *  \code
+   *    Array a;
+   *    a.push(String("some string"));
+   *    a.push(42);
+   *  \endcode
+   */
+  class Array
+    : public Builtin_Object<T_ARRAY>
+  {
+  public:
+    //! Construct a new array
+    Array();
+
+    //! Construct a new array with specified size
+    Array(long capacity);
+
+    //! Wrap an existing array
+    /*! \param v a ruby object, which must be of type T_ARRAY.
+     */
+    Array(Object v);
+
+    //! Wrap an existing array
+    /*! \param v a ruby object, which must be of type T_ARRAY.
+     */
+    Array(VALUE v);
+
+    //! Construct an array from a sequence.
+    /*! \param begin an iterator to the beginning of the sequence.
+     *  \param end an iterator to the end of the sequence.
+     */
+    template<typename Iter_T>
+    Array(Iter_T begin, Iter_T end);
+
+    //! Construct an Array from a C array.
+    /*! \param a a C array of type T and size n.
+     */
+    template<typename T, long n>
+    Array(T const (&a)[n]);
+
+  public:
+    //! Return the size of the array.
+    long size() const;
+
+    //! Return the element at the given index.
+    /*! \param index The index of the desired element.  The index may be
+     *  negative, to indicate an offset from the end of the array.  If the
+     *  index is out of bounds, this function has undefined behavior.
+     *  \return the element at the given index.
+     */
+    Object operator[](long index) const;
+
+    //! Converts a Ruby Array into a C++ array where the elements are
+    //! contiguous. This is similar to a std::vector, but instead a
+    //! std::unique_ptr<T> is returned. This allows the calling code to
+    //! pass ownership to its callers if needed (for exmaple, From_Ruby<T>#convert)
+    //! Note this method is designed convenience, not for speed or efficieny.
+    //! C++ APIs that take large chunks of memory should not be passed Ruby Arrrays.
+    //! \return std::unique_ptr that is owned by the caller.
+    template<typename T>
+    String pack();
+
+    // Join elements together
+    String join(const char* separator);
+
+  private:
+    //! A helper class so array[index]=value can work.
+    class Proxy;
+
+  public:
+    //! Return a reference to the element at the given index.
+    /*! \param index The index of the desired element.  The index may be
+     *  negative, to indicate an offset from the end of the array.  If the
+     *  index is out of bounds, this function has undefined behavior.
+     *  \return the element at the given index.
+     */
+    Proxy operator[](long index);
+
+    //! Push an element onto the end of the array
+    /*! \param v an object to push onto the array.
+     *  \return the object which was pushed onto the array.
+     */
+    template<typename T>
+    Object push(T obj);
+
+    //! Pop an element from the end of the array
+    /*! \return the object which was popped from the array, or Qnil if
+     *  the array was empty.
+     */
+    Object pop();
+
+    //! Unshift an element onto the beginning of the array
+    /*! \param v an object to unshift onto the array.
+     *  \return the object which was unshifted onto the array.
+     */
+    template<typename T>
+    Object unshift(T const& obj);
+
+    //! Shift an element from the beginning of the array
+    /*! \return the object which was shifted from the array.
+     */
+    Object shift();
+
+  private:
+    template<typename Array_Ptr_T, typename Value_T>
+    class Iterator;
+
+    long position_of(long index) const;
+
+  public:
+    //! An iterator.
+    typedef Iterator<Array*, Proxy> iterator;
+
+    //! A const iterator.
+    typedef Iterator<Array const*, Object> const_iterator;
+
+    //! Return an iterator to the beginning of the array.
+    iterator begin();
+
+    //! Return a const iterator to the beginning of the array.
+    const_iterator begin() const;
+
+    //! Return an iterator to the end of the array.
+    iterator end();
+
+    //! Return a const iterator to the end of the array.
+    const_iterator end() const;
+
+    //! Return the content of the array as a std::vector
+    template<typename T>
+    std::vector<T> to_vector();
+  };
+
+  //! A helper class so array[index]=value can work.
+  class Array::Proxy
+  {
+  public:
+    //! Construct a new Proxy
+    Proxy(Array array, long index);
+
+    //! Implicit conversions
+    operator Object() const;
+
+    //! Explicit conversion to VALUE.
+    VALUE value() const;
+
+    //! Assignment operator.
+    template<typename T>
+    Object operator=(T const& value);
+
+  private:
+    Array array_;
+    long index_;
+  };
+
+  //! A helper class for implementing iterators for a Array.
+  // TODO: This really should be a random-access iterator.
+  template<typename Array_Ptr_T, typename Value_T>
+  class Array::Iterator
+  {
+  public:
+    using iterator_category = std::forward_iterator_tag;
+    using value_type = Value_T;
+    using difference_type = long;
+    using pointer = Object*;
+    using reference = Value_T&;
+
+    Iterator(Array_Ptr_T array, long index);
+
+    template<typename Array_Ptr_T_, typename Value_T_>
+    Iterator(Iterator<Array_Ptr_T_, Value_T_> const& rhs);
+
+    template<typename Array_Ptr_T_, typename Value_T_>
+    Iterator& operator=(Iterator<Array_Ptr_T_, Value_T_> const& rhs);
+
+    Iterator& operator++();
+    Iterator operator++(int);
+    Value_T operator*();
+    Object* operator->();
+
+    template<typename Array_Ptr_T_, typename Value_T_>
+    bool operator==(Iterator<Array_Ptr_T_, Value_T_> const& rhs) const;
+
+    template<typename Array_Ptr_T_, typename Value_T_>
+    bool operator!=(Iterator<Array_Ptr_T_, Value_T_> const& rhs) const;
+
+    Array_Ptr_T array() const;
+    long index() const;
+
+  private:
+    Array_Ptr_T array_;
+    long index_;
+
+    Object tmp_;
+  };
+} // namespace Rice
+
+#endif // Rice__Array__hpp_

data/rice/cpp_api/Array.ipp

@@ -0,0 +1,304 @@
+#ifndef Rice__Array__ipp_
+#define Rice__Array__ipp_
+
+namespace Rice
+{
+  inline Array::Array() : Builtin_Object<T_ARRAY>(detail::protect(rb_ary_new))
+  {
+  }
+
+  inline Array::Array(long capacity) : Builtin_Object<T_ARRAY>(detail::protect(rb_ary_new_capa, capacity))
+  {
+  }
+
+  inline Array::Array(Object v) : Builtin_Object<T_ARRAY>(v)
+  {
+  }
+
+  inline Array::Array(VALUE v) : Builtin_Object<T_ARRAY>(v)
+  {
+  }
+
+  template<typename Iter_T>
+  inline Array::Array(Iter_T it, Iter_T end) : Builtin_Object<T_ARRAY>(detail::protect(rb_ary_new))
+  {
+    for (; it != end; ++it)
+    {
+      push(*it);
+    }
+  }
+
+  template<typename T, long n>
+  inline Array::Array(T const (&a)[n]) : Builtin_Object<T_ARRAY>(detail::protect(rb_ary_new))
+  {
+    for (long j = 0; j < n; ++j)
+    {
+      push(a[j]);
+    }
+  }
+
+  inline long Array::size() const
+  {
+    return RARRAY_LEN(this->value());
+  }
+
+  inline String Array::join(const char* separator)
+  {
+    return this->call("join", separator);
+  }
+
+  template<typename T>
+  String Array::pack()
+  {
+    // Use .c_str so that the stl.hpp header is not required
+    return this->call("pack", detail::RubyType<T>::packTemplate.c_str());
+  }
+
+  inline Object Array::operator[](long index) const
+  {
+    return detail::protect(rb_ary_entry, value(), position_of(index));
+  }
+
+  inline Array::Proxy Array::operator[](long index)
+  {
+    return Proxy(*this, position_of(index));
+  }
+
+  template<typename T>
+  inline Object Array::push(T obj)
+  {
+    return detail::protect(rb_ary_push, value(), detail::To_Ruby<T>().convert(std::forward<T>(obj)));
+  }
+
+  inline Object Array::pop()
+  {
+    return detail::protect(rb_ary_pop, value());
+  }
+
+  template<typename T>
+  inline Object Array::unshift(T const& obj)
+  {
+    return detail::protect(rb_ary_unshift, value(), detail::To_Ruby<T>().convert(obj));
+  }
+
+  inline Object Array::shift()
+  {
+    return detail::protect(rb_ary_shift, value());
+  }
+
+  inline long Array::position_of(long index) const
+  {
+    if (index < 0)
+    {
+      return size() + index;
+    }
+    else
+    {
+      return static_cast<long>(index);
+    }
+  }
+
+  template<typename T>
+  std::vector<T> Array::to_vector()
+  {
+    std::vector<T> result;
+
+    long size = this->size();
+    result.reserve(size);
+
+    detail::From_Ruby<T> fromRuby;
+    for (long i = 0; i < size; i++)
+    {
+      VALUE element = detail::protect(rb_ary_entry, this->value(), i);
+      result.push_back(fromRuby.convert(element));
+    }
+
+    return result;
+  }
+
+  inline Array::Proxy::Proxy(Array array, long index)
+    : array_(array)
+    , index_(index)
+  {
+  }
+
+  inline VALUE Array::Proxy::value() const
+  {
+    return detail::protect(rb_ary_entry, array_.value(), index_);
+  }
+
+  inline Array::Proxy::operator Object() const
+  {
+    return Object(this->value());
+  }
+
+  template<typename T>
+  Object Array::Proxy::operator=(T const& value)
+  {
+    Object o = detail::To_Ruby<T>().convert(value);
+    detail::protect(rb_ary_store, array_.value(), index_, o.value());
+    return o;
+  }
+
+  template<typename Array_Ptr_T, typename Value_T>
+  inline Array::Iterator<Array_Ptr_T, Value_T>::Iterator(Array_Ptr_T array, long index) :
+    array_(array), index_(index)
+  {
+  }
+
+  template<typename Array_Ptr_T, typename Value_T>
+  template<typename Array_Ptr_T_, typename Value_T_>
+  inline
+    Array::Iterator<Array_Ptr_T, Value_T>::Iterator(Iterator<Array_Ptr_T_, Value_T_> const& rhs) :
+      array_(rhs.array()) , index_(rhs.index()), tmp_()
+  {
+  }
+
+  template<typename Array_Ptr_T, typename Value_T>
+  template<typename Array_Ptr_T_, typename Value_T_>
+  inline Array::Iterator<Array_Ptr_T, Value_T>& Array::Iterator<Array_Ptr_T, Value_T>::operator=(Iterator<Array_Ptr_T_, Value_T_> const& rhs)
+  {
+    array_ = rhs.array_;
+    index_ = rhs.index_;
+    return *this;
+  }
+
+  template<typename Array_Ptr_T, typename Value_T>
+  inline Array::Iterator<Array_Ptr_T, Value_T>& Array::Iterator<Array_Ptr_T, Value_T>::operator++()
+  {
+    ++index_;
+    return *this;
+  }
+
+  template<typename Array_Ptr_T, typename Value_T>
+  inline Array::Iterator<Array_Ptr_T, Value_T> Array::Iterator<Array_Ptr_T, Value_T>::operator++(int)
+  {
+    Array copy(*this);
+    ++(*this);
+    return *this;
+  }
+
+  template<typename Array_Ptr_T, typename Value_T>
+  inline Value_T Array::Iterator<Array_Ptr_T, Value_T>::operator*()
+  {
+    return (*array_)[index_];
+  }
+
+  template<typename Array_Ptr_T, typename Value_T>
+  inline Object* Array::Iterator<Array_Ptr_T, Value_T>::operator->()
+  {
+    tmp_ = (*array_)[index_];
+    return &tmp_;
+  }
+
+  template<typename Array_Ptr_T, typename Value_T>
+  template<typename Array_Ptr_T_, typename Value_T_>
+  inline bool Array::Iterator<Array_Ptr_T, Value_T>::operator==(Iterator<Array_Ptr_T_, Value_T_> const& rhs) const
+  {
+    return array_->value() == rhs.array_->value() && index_ == rhs.index_;
+  }
+
+  template<typename Array_Ptr_T, typename Value_T>
+  template<typename Array_Ptr_T_, typename Value_T_>
+  inline bool Array::Iterator<Array_Ptr_T, Value_T>::operator!=(Iterator<Array_Ptr_T_, Value_T_> const& rhs) const
+  {
+    return !(*this == rhs);
+  }
+
+  template<typename Array_Ptr_T, typename Value_T>
+  Array_Ptr_T Array::Iterator<Array_Ptr_T, Value_T>::array() const
+  {
+    return array_;
+  }
+
+  template<typename Array_Ptr_T, typename Value_T>
+  long Array::Iterator<Array_Ptr_T, Value_T>::index() const
+  {
+    return index_;
+  }
+
+  inline Array::iterator Array::begin()
+  {
+    return iterator(this, 0);
+  }
+
+  inline Array::const_iterator Array::begin() const
+  {
+    return const_iterator(this, 0);
+  }
+
+  inline Array::iterator Array::end()
+  {
+    return iterator(this, size());
+  }
+
+  inline Array::const_iterator Array::end() const
+  {
+    return const_iterator(this, size());
+  }
+}
+
+namespace Rice::detail
+{
+  template<>
+  struct Type<Array>
+  {
+    static bool verify()
+    {
+      return true;
+    }
+  };
+
+  template<>
+  class To_Ruby<Array>
+  {
+  public:
+    VALUE convert(Array const& x)
+    {
+      return x.value();
+    }
+  };
+
+  template<>
+  class To_Ruby<Array&>
+  {
+  public:
+    VALUE convert(Array const& x)
+    {
+      return x.value();
+    }
+  };
+
+  template<>
+  class To_Ruby<Array*>
+  {
+  public:
+    VALUE convert(Array const* x)
+    {
+      return x->value();
+    }
+  };
+
+  template<>
+  class From_Ruby<Array>
+  {
+  public:
+    Convertible is_convertible(VALUE value)
+    {
+      switch (rb_type(value))
+      {
+        case RUBY_T_ARRAY:
+          return Convertible::Exact;
+          break;
+        default:
+          return Convertible::None;
+      }
+    }
+
+    Array convert(VALUE value)
+    {
+      return Array(value);
+    }
+  };
+}
+#endif // Rice__Array__ipp_

data/rice/cpp_api/Builtin_Object.hpp

@@ -0,0 +1,31 @@
+#ifndef Rice__Builtin_Object__hpp_
+#define Rice__Builtin_Object__hpp_
+
+namespace Rice
+{
+  //! A smartpointer-like wrapper for Ruby builtin objects.
+  /*! A builtin object is one of Ruby's internal types, e.g. RArray or
+   *  RString.  Every builtin type structure has a corresponding integer
+   *  type number (e.g T_ARRAY for RArray or T_STRING for RString).  This
+   *  class is a wrapper for those types of objects, primarily useful as a
+   *  base class for other wrapper classes like Array and Hash.
+   */
+  template<int Builtin_Type>
+  class Builtin_Object
+    : public Object
+  {
+  public:
+    //! Wrap an already allocated Ruby object.
+    /*! Checks to see if the object is an object of type Builtin_Type; a
+     *  C++ exception is thrown if this is not the case.
+     *  \param value the object to be wrapped.
+     */
+    Builtin_Object(Object value);
+
+    RObject& operator*() const; //!< Return a reference to obj_
+    RObject* operator->() const; //!< Return a pointer to obj_
+    RObject* get() const;       //!< Return a pointer to obj_
+  };
+} // namespace Rice
+
+#endif // Rice__Builtin_Object__hpp_

data/rice/cpp_api/Builtin_Object.ipp

@@ -0,0 +1,37 @@
+#include <algorithm>
+
+namespace Rice
+{
+  namespace detail
+  {
+    inline VALUE check_type(Object value, int type)
+    {
+      detail::protect(rb_check_type, value.value(), type);
+      return Qnil;
+    }
+  }
+
+  template<int Builtin_Type>
+  inline Builtin_Object<Builtin_Type>::Builtin_Object(Object value) : Object(value)
+  {
+    detail::check_type(value, Builtin_Type);
+  }
+
+  template<int Builtin_Type>
+  inline RObject& Builtin_Object<Builtin_Type>::operator*() const
+  {
+    return *ROBJECT(this->value());
+  }
+
+  template<int Builtin_Type>
+  inline RObject* Builtin_Object<Builtin_Type>::operator->() const
+  {
+    return ROBJECT(this->value());
+  }
+
+  template<int Builtin_Type>
+  inline RObject* Builtin_Object<Builtin_Type>::get() const
+  {
+    return ROBJECT(this->value());
+  }
+} // namespace Rice

data/rice/cpp_api/Class.hpp

@@ -0,0 +1,70 @@
+#ifndef Rice__Class__hpp_
+#define Rice__Class__hpp_
+
+/*!
+ *  \example inheritance/animals.cpp
+ *  \example callbacks/sample_callbacks.cpp
+ */
+
+namespace Rice
+{
+  //! A helper for defining a Class and its methods.
+  /*! This class provides a C++-style interface to ruby's Class class and
+   *  for defining methods on that class.
+   */
+  class Class: public Module
+  {
+  public:
+    //! Default construct a new class wrapper and initialize it to
+    //! rb_cObject.
+    Class() = default;
+
+    //! Construct a new class wrapper from a ruby object of type T_CLASS.
+    Class(VALUE v);
+
+    //! Disallow creation of an instance from Ruby code.
+    /*! Undefines the singleton method allocate (or new, if using a
+     *  version of ruby prior to 1.7) and the instance method initialize.
+     */
+    Class & undef_creation_funcs();
+
+    // Create a new instance
+    template<typename ...Arg_Ts>
+    Object create(Arg_Ts ...args);
+
+    //! Class name
+    /*! \return std::string.
+     */
+    const std::string name() const;
+
+    //! Base class name - does not include any parent modules
+    /*! \return std::string.
+     */
+    const std::string base_name() const;
+
+#include "shared_methods.hpp"
+  };
+
+  //! Define a new class in the namespace given by module.
+  /*! \param module the Module in which to define the class.
+   *  \param name the name of the class.
+   *  \param superclass the base class to use.
+   *  \return the new class.
+   */
+  Class define_class_under(Object parent, char const * name, const Class& superclass = rb_cObject);
+  Class define_class_under(Object parent, Identifier id, const Class& superclass = rb_cObject);
+
+  //! Define a new class in the default namespace.
+  /*! \param name the name of the class.
+   *  \param superclass the base class to use.
+   *  \return the new class.
+   */
+  Class define_class(char const * name, const Class& superclass = rb_cObject);
+
+  //! Create a new anonymous class.
+  /*! \return the new class.
+   */
+  Class anonymous_class();
+} // namespace Rice
+
+#endif // Rice__Class__hpp_