ceph/src/boost/libs/python/doc/reference/slice.qbk

   1 [section boost/python/slice.hpp]
   2 [section Introduction]
   3 Exposes a [link concepts.objectwrapper.typewrapper_concept_requirements TypeWrapper] for the Python [@http://www.python.org/doc/2.3.3/api/slice-objects.html `slice`] type.
   4 [endsect]
   5 [section Class `slice`]
   6 Exposes the extended slicing protocol by wrapping the built-in slice type. The semantics of the constructors and member functions defined below can be fully understood by reading the [link concepts.objectwrapper.typewrapper_concept_requirements TypeWrapper] concept definition. Since `slice` is publicly derived from [link object_wrappers.boost_python_object_hpp.class_object `object`], the public `object` interface applies to `slice` instances as well.
   7 ``
   8 namespace boost { namespace python
   9 {
  10   class slice : public object
  11   {
  12    public:
  13       slice(); // create an empty slice, equivalent to [::]
  14
  15       template <typename Int1, typename Int2>
  16       slice(Int1 start, Int2 stop);
  17
  18       template <typename Int1, typename Int2, typename Int3>
  19       slice(Int1 start, Int2 stop, Int3 step);
  20
  21       // Access the parameters this slice was created with.
  22       object start();
  23       object stop();
  24       object step();
  25
  26       // The return type of slice::get_indices()
  27       template <typename RandomAccessIterator>
  28       struct range
  29       {
  30           RandomAccessIterator start;
  31           RandomAccessIterator stop;
  32           int step;
  33       };
  34
  35       template <typename RandomAccessIterator>
  36       range<RandomAccessIterator>
  37       get_indices(
  38           RandomAccessIterator const& begin,
  39           RandomAccessIterator const& end);
  40   };
  41 }}
  42 ``
  43 [endsect]
  44 [section Class `slice` constructors]
  45 ``slice();``
  46 [variablelist
  47 [[Effects][constructs a slice with default stop, start, and step values.  Equivalent to the slice object created as part of the Python expression `base[::]`.]]
  48 [[Throws][nothing]]
  49 ]
  50 ``
  51 template <typename Int1, typename Int2>
  52 slice(Int1 start, Int2 stop);
  53 ``
  54 [variablelist
  55 [[Requires][`start`, `stop`, and `step` are of type `slice_nil` or convertible to type `object`.]]
  56 [[Effects][constructs a new slice with default step value and the provided start and stop values.  Equivalent to the slice object created by the built-in Python function `slice(start,stop)`, or as part of the Python expression `base[start:stop]`.]]
  57 [[Throws][`error_already_set` and sets a Python TypeError exception if no conversion is possible from the arguments to type object.]]
  58 ]
  59 ``
  60 template <typename Int1, typename Int2, typename Int3>
  61 slice(Int1 start, Int2 stop, Int3 step);
  62 ``
  63 [variablelist
  64 [[Requires][`start`, `stop`, and `step` are `slice_nil` or convertible to type `object`.]]
  65 [[Effects][constructs a new slice with start stop and step values.  Equivalent to the slice object created by the built-in Python function `slice(start,stop,step)`, or as part of the Python expression `base[start:stop:step]`.]]
  66 [[Throws][`error_already_set` and sets a Python TypeError exception if no conversion is possible from the arguments to type object.]]
  67 ]
  68 [endsect]
  69 [section Class `slice` observer functions]
  70 ``
  71 object slice::start() const;
  72 object slice::stop() const;
  73 object slice::step() const;
  74 ``
  75 [variablelist
  76 [[Effects][None]]
  77 [[Throws][nothing]]
  78 [[Returns][the parameter that the slice was created with. If the parameter was omitted or `slice_nil` was used when the slice was created, than that parameter will be a reference to `PyNone` and compare equal to a default-constructed object.  In principal, any object may be used when creating a slice object, but in practice they are usually integers.]]
  79 ]
  80 ``
  81 template <typename RandomAccessIterator>
  82 slice::range<RandomAccessIterator>
  83 slice::get_indices(
  84     RandomAccessIterator const& begin,
  85     RandomAccessIterator const& end) const;
  86 ``
  87 [variablelist
  88 [[Arguments][A pair of STL-conforming Random Access Iterators that form a half-open range.]]
  89 [[Effects][Create a RandomAccessIterator pair that defines a fully-closed range within the `[begin,end)` range of its arguments.  This function translates this slice's indices while accounting for the effects of any PyNone or negative indices, and non-singular step sizes.]]
  90 [[Returns][a `slice::range` that has been initialized with a non-zero value of step and a pair of RandomAccessIterators that point within the range of this functions arguments and define a closed interval.]]
  91 [[Throws][Raises a Python TypeError exception if any of this slice's arguments are neither references to PyNone nor convertible to int.  Throws `std::invalid_argument` if the resulting range would be empty.  You should always wrap calls to `slice::get_indices()` within `try { ...; } catch (std::invalid_argument) {}` to handle this case and take appropriate action.]]
  92 [[Rationale][closed-interval: If an open interval were used, then for step size other than 1, the required state for the end iterator would point beyond the one-past-the-end position or before the beginning of the specified range.
  93 exceptions on empty slice: It is impossible to define a closed interval over an empty range, so some other form of error checking would have to be used to prevent undefined behavior. In the case where the exception is not caught, it will simply be translated to Python by the default exception handling mechanisms. ]]
  94 ]
  95 [endsect]
  96 [section Example]
  97 ``
  98 using namespace boost::python;
  99
 100 // Perform an extended slice of a Python list.
 101 // Warning: extended slicing was not supported for built-in types prior
 102 // to Python 2.3
 103 list odd_elements(list l)
 104 {
 105     return l[slice(_,_,2)];
 106 }
 107
 108 // Perform a multidimensional extended slice of a Numeric.array
 109 numeric::array even_columns(numeric::array arr)
 110 {
 111     // select every other column, starting with the second, of a 2-D array.
 112     // Equivalent to "return arr[:, 1::2]" in Python.
 113     return arr[make_tuple( slice(), slice(1,_,2))];
 114 }
 115
 116 // Perform a summation over a slice of a std::vector.
 117 double partial_sum(std::vector<double> const& Foo, const slice index)
 118 {
 119     slice::range<std::vector<double>::const_iterator> bounds;
 120     try {
 121         bounds = index.get_indices<>(Foo.begin(), Foo.end());
 122     }
 123     catch (std::invalid_argument) {
 124         return 0.0;
 125     }
 126     double sum = 0.0;
 127     while (bounds.start != bounds.stop) {
 128         sum += *bounds.start;
 129         std::advance( bounds.start, bounds.step);
 130     }
 131     sum += *bounds.start;
 132     return sum;
 133 }
 134 ``
 135 [endsect]
 136 [endsect]