.. Licensed to the Apache Software Foundation (ASF) under one
   or more contributor license agreements.  See the NOTICE file
   distributed with this work for additional information
   regarding copyright ownership.  The ASF licenses this file
   to you under the Apache License, Version 2.0 (the
   "License"); you may not use this file except in compliance
   with the License.  You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing,
   software distributed under the License is distributed on an
   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
   KIND, either express or implied.  See the License for the
   specific language governing permissions and limitations
   under the License.

.. include:: ../../common.defs

.. default-domain:: cpp

MemSpan
*******

Synopsis
========

.. code-block:: cpp

    #include <ts/MemSpan.h>

:class:`MemSpan` is a view on a contiguous section of writeable memory. A view does not own the memory
and neither allocates nor de-allocates. The memory in the view is always owned by some other container
and it is the responsibility of the code to make sure the lifetime of the view is no more than that
of the owning container [#vector]_.


Description
===========

A :class:`MemSpan` is generally constructed on either an array or an allocated buffer. This allows
the buffer to be passed around with intrinsic length information. The buffer can also be treated as
an array of varying types, which makes working with serialized data much easier.

Reference
=========

.. class:: MemSpan

   A span of writable memory. Because this is a chunk of memory, conceptually delimited by start and
   end pointers, the sizing type is :code:`ptrdiff_t` so that all of the sizing is consistent with
   differences between pointers. The memory is owned by some other object and that object must
   maintain the memory as long as the span references it.

   .. function:: MemSpan(void * ptr, ptrdiff_t size)

      Construct a view starting at :arg:`ptr` for :arg:`size` bytes.

   .. function:: void * data()  const

      Return a pointer to the first byte of the span.

   .. function:: ptrdiff_t size() const

      Return the size of the span.

   .. function:: bool operator == (MemSpan const& that) const

      Check the equality of two spans, which are equal if they contain the same number of bytes of the same values.

   .. function:: bool is_same(MemSpan const& that) const

      Check if :arg:`that` is the same span as :arg:`this`, that is the spans contain the exact same bytes.

   .. function:: template < typename V > V at(ptrdiff_t n) const

      Return a value of type :arg:`V` as if the span were are array of type :arg:`V`.

   .. function:: template < typename V > V * ptr(ptrdiff_t n) const

      Return a pointer to a value of type :arg:`V` as if the span were are array of type :arg:`V`.

   .. function:: MemSpan prefix(ptrdiff_t n) const

      Return a new instance that contains the first :arg:`n` bytes of the current span. If :arg:`n`
      is larger than the number of bytes in the span, only that many bytes are returned.

   .. function:: MemSpan& remove_prefix(ptrdiff_t n)

      Remove the first :arg:`n` bytes of the span. If :arg:`n` is more than the number of bytes in
      the span the result is an empty span. A reference to the instance is returned.

.. rubric:: Footnotes

.. [#vector]

   Strong caution must be used with containers such as :code:`std::vector` or :code:`std::string`
   because the lifetime of the memory can be much less than the lifetime of the container. In
   particular, adding or removing any element from a :code:`std::vector` can cause a re-allocation,
   invalidating any view of the original memory. In general views should be treated like iterators,
   suitable for passing to nested function calls but not for storing.