.. note::
- Prefer to use ``SmallVectorImpl<T>`` as a parameter type.
+ Prefer to use ``ArrayRef<T>`` or ``SmallVectorImpl<T>`` as a parameter type.
- In APIs that don't care about the "small size" (most?), prefer to use
- the ``SmallVectorImpl<T>`` class, which is basically just the "vector
- header" (and methods) without the elements allocated after it. Note that
- ``SmallVector<T, N>`` inherits from ``SmallVectorImpl<T>`` so the
- conversion is implicit and costs nothing. E.g.
+ It's rarely appropriate to use ``SmallVector<T, N>`` as a parameter type.
+ If an API only reads from the vector, it should use :ref:`ArrayRef
+ <dss_arrayref>`. Even if an API updates the vector the "small size" is
+ unlikely to be relevant; such an API should use the ``SmallVectorImpl<T>``
+ class, which is the "vector header" (and methods) without the elements
+ allocated after it. Note that ``SmallVector<T, N>`` inherits from
+ ``SmallVectorImpl<T>`` so the conversion is implicit and costs nothing. E.g.
.. code-block:: c++
- // BAD: Clients cannot pass e.g. SmallVector<Foo, 4>.
+ // DISCOURAGED: Clients cannot pass e.g. raw arrays.
+ hardcodedContiguousStorage(const SmallVectorImpl<Foo> &In);
+ // ENCOURAGED: Clients can pass any contiguous storage of Foo.
+ allowsAnyContiguousStorage(ArrayRef<Foo> In);
+
+ void someFunc1() {
+ Foo Vec[] = { /* ... */ };
+ hardcodedContiguousStorage(Vec); // Error.
+ allowsAnyContiguousStorage(Vec); // Works.
+ }
+
+ // DISCOURAGED: Clients cannot pass e.g. SmallVector<Foo, 8>.
hardcodedSmallSize(SmallVector<Foo, 2> &Out);
- // GOOD: Clients can pass any SmallVector<Foo, N>.
+ // ENCOURAGED: Clients can pass any SmallVector<Foo, N>.
allowsAnySmallSize(SmallVectorImpl<Foo> &Out);
- void someFunc() {
+ void someFunc2() {
SmallVector<Foo, 8> Vec;
hardcodedSmallSize(Vec); // Error.
allowsAnySmallSize(Vec); // Works.
}
- Even though it has "``Impl``" in the name, this is so widely used that
- it really isn't "private to the implementation" anymore. A name like
- ``SmallVectorHeader`` would be more appropriate.
+ Even though it has "``Impl``" in the name, SmallVectorImpl is widely used
+ and is no longer "private to the implementation". A name like
+ ``SmallVectorHeader`` might be more appropriate.
.. _dss_vector: