This is an automated email from the ASF dual-hosted git repository. amc pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/trafficserver.git
The following commit(s) were added to refs/heads/master by this push: new e4aa18e Doc: Add internal documenation for ts::string_view. e4aa18e is described below commit e4aa18e3337929bb1c9dc4272f369c86a1325c61 Author: Alan M. Carroll <a...@apache.org> AuthorDate: Fri Feb 16 17:12:42 2018 -0600 Doc: Add internal documenation for ts::string_view. --- .../internal-libraries/index.en.rst | 3 +- .../internal-libraries/string_view.en.rst | 65 ++++++++++++++++++++++ 2 files changed, 67 insertions(+), 1 deletion(-) diff --git a/doc/developer-guide/internal-libraries/index.en.rst b/doc/developer-guide/internal-libraries/index.en.rst index 1b6cd1e..1e569e3 100644 --- a/doc/developer-guide/internal-libraries/index.en.rst +++ b/doc/developer-guide/internal-libraries/index.en.rst @@ -26,7 +26,8 @@ Here we document various internal libraries whose use is encouraged by |ATS| development team. .. toctree:: - :maxdepth: 2 + :maxdepth: 1 + string_view.en memview.en scalar.en diff --git a/doc/developer-guide/internal-libraries/string_view.en.rst b/doc/developer-guide/internal-libraries/string_view.en.rst new file mode 100644 index 0000000..911dd23 --- /dev/null +++ b/doc/developer-guide/internal-libraries/string_view.en.rst @@ -0,0 +1,65 @@ +.. 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 + +ts::string_view +*************** + +Synopsis +======== + +:code:`#include <ts/string_view.h>` + +.. class:: string_view + +This is an internal implementation of `std::string_view +<https://en.cppreference.com/w/cpp/header/string_view>`__. This was done because +:code:`std::string_view` is part of the C++17 standard and therefore cannot be assumed in our +supported compilers (which are currently only C++11). + +Description +=========== + +:class:`string_view` provides a read only view into memory allocated elsewhere and is handy for when +passing around pieces of memory, such as pieces of an HTTP header. It is essentially a pointer and a +length and a quick glance at our internal API will provide numerous places this kind of data is +passed. + +This implementation is intended to be as similar as possible to the standard version to avoid +transition difficulties if / when we upgrade to C++17. For this reason no additional features, +regardless of how useful we might find them, have been or will be added to this class. + +The only known difference at this time is the literal operator is :code:`""_sv` instead of +:code:`""sv` as it is for :code:`std::string_view`. The reason is a compiler limitation which does +not allow non-compiler headers to define literal operators without a leading ``_``. The use would be + +.. code-block:: cpp + + ts::string_view ts_v = "A literal string"_sv; // ts::string_view + std::string_view std_v = "A literal string"sv; // std::string_view + +If you discover any other differences, that is a bug in our implementation and should be fixed. + +For a class that provides a much richer set of text manipulation methods, see :class:`TextView` +which is a subclass of :class:`string_view`. + +There is no shortage of additional reference material available, beyond the basic description noted +above, which serves to describe the API and usage of this class, and duplicating it here would serve +no purpose. -- To stop receiving notification emails like this one, please contact a...@apache.org.