stream.h

00001 // Tencent is pleased to support the open source community by making RapidJSON available.
00002 // 
00003 // Copyright (C) 2015 THL A29 Limited, a Tencent company, and Milo Yip. All rights reserved.
00004 //
00005 // Licensed under the MIT License (the "License"); you may not use this file except
00006 // in compliance with the License. You may obtain a copy of the License at
00007 //
00008 // http://opensource.org/licenses/MIT
00009 //
00010 // Unless required by applicable law or agreed to in writing, software distributed 
00011 // under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR 
00012 // CONDITIONS OF ANY KIND, either express or implied. See the License for the 
00013 // specific language governing permissions and limitations under the License.
00014 
00015 #include "rapidjson.h"
00016 
00017 #ifndef RAPIDJSON_STREAM_H_
00018 #define RAPIDJSON_STREAM_H_
00019 
00020 #include "encodings.h"
00021 
00022 RAPIDJSON_NAMESPACE_BEGIN
00023 
00024 ///////////////////////////////////////////////////////////////////////////////
00025 //  Stream
00026 
00027 /*! \class rapidjson::Stream
00028     \brief Concept for reading and writing characters.
00029 
00030     For read-only stream, no need to implement PutBegin(), Put(), Flush() and PutEnd().
00031 
00032     For write-only stream, only need to implement Put() and Flush().
00033 
00034 \code
00035 concept Stream {
00036     typename Ch;    //!< Character type of the stream.
00037 
00038     //! Read the current character from stream without moving the read cursor.
00039     Ch Peek() const;
00040 
00041     //! Read the current character from stream and moving the read cursor to next character.
00042     Ch Take();
00043 
00044     //! Get the current read cursor.
00045     //! \return Number of characters read from start.
00046     size_t Tell();
00047 
00048     //! Begin writing operation at the current read pointer.
00049     //! \return The begin writer pointer.
00050     Ch* PutBegin();
00051 
00052     //! Write a character.
00053     void Put(Ch c);
00054 
00055     //! Flush the buffer.
00056     void Flush();
00057 
00058     //! End the writing operation.
00059     //! \param begin The begin write pointer returned by PutBegin().
00060     //! \return Number of characters written.
00061     size_t PutEnd(Ch* begin);
00062 }
00063 \endcode
00064 */
00065 
00066 //! Provides additional information for stream.
00067 /*!
00068     By using traits pattern, this type provides a default configuration for stream.
00069     For custom stream, this type can be specialized for other configuration.
00070     See TEST(Reader, CustomStringStream) in readertest.cpp for example.
00071 */
00072 template<typename Stream>
00073 struct StreamTraits {
00074     //! Whether to make local copy of stream for optimization during parsing.
00075     /*!
00076         By default, for safety, streams do not use local copy optimization.
00077         Stream that can be copied fast should specialize this, like StreamTraits<StringStream>.
00078     */
00079     enum { copyOptimization = 0 };
00080 };
00081 
00082 //! Reserve n characters for writing to a stream.
00083 template<typename Stream>
00084 inline void PutReserve(Stream& stream, size_t count) {
00085     (void)stream;
00086     (void)count;
00087 }
00088 
00089 //! Write character to a stream, presuming buffer is reserved.
00090 template<typename Stream>
00091 inline void PutUnsafe(Stream& stream, typename Stream::Ch c) {
00092     stream.Put(c);
00093 }
00094 
00095 //! Put N copies of a character to a stream.
00096 template<typename Stream, typename Ch>
00097 inline void PutN(Stream& stream, Ch c, size_t n) {
00098     PutReserve(stream, n);
00099     for (size_t i = 0; i < n; i++)
00100         PutUnsafe(stream, c);
00101 }
00102 
00103 ///////////////////////////////////////////////////////////////////////////////
00104 // StringStream
00105 
00106 //! Read-only string stream.
00107 /*! \note implements Stream concept
00108 */
00109 template <typename Encoding>
00110 struct GenericStringStream {
00111     typedef typename Encoding::Ch Ch;
00112 
00113     GenericStringStream(const Ch *src) : src_(src), head_(src) {}
00114 
00115     Ch Peek() const { return *src_; }
00116     Ch Take() { return *src_++; }
00117     size_t Tell() const { return static_cast<size_t>(src_ - head_); }
00118 
00119     Ch* PutBegin() { RAPIDJSON_ASSERT(false); return 0; }
00120     void Put(Ch) { RAPIDJSON_ASSERT(false); }
00121     void Flush() { RAPIDJSON_ASSERT(false); }
00122     size_t PutEnd(Ch*) { RAPIDJSON_ASSERT(false); return 0; }
00123 
00124     const Ch* src_;     //!< Current read position.
00125     const Ch* head_;    //!< Original head of the string.
00126 };
00127 
00128 template <typename Encoding>
00129 struct StreamTraits<GenericStringStream<Encoding> > {
00130     enum { copyOptimization = 1 };
00131 };
00132 
00133 //! String stream with UTF8 encoding.
00134 typedef GenericStringStream<UTF8<> > StringStream;
00135 
00136 ///////////////////////////////////////////////////////////////////////////////
00137 // InsituStringStream
00138 
00139 //! A read-write string stream.
00140 /*! This string stream is particularly designed for in-situ parsing.
00141     \note implements Stream concept
00142 */
00143 template <typename Encoding>
00144 struct GenericInsituStringStream {
00145     typedef typename Encoding::Ch Ch;
00146 
00147     GenericInsituStringStream(Ch *src) : src_(src), dst_(0), head_(src) {}
00148 
00149     // Read
00150     Ch Peek() { return *src_; }
00151     Ch Take() { return *src_++; }
00152     size_t Tell() { return static_cast<size_t>(src_ - head_); }
00153 
00154     // Write
00155     void Put(Ch c) { RAPIDJSON_ASSERT(dst_ != 0); *dst_++ = c; }
00156 
00157     Ch* PutBegin() { return dst_ = src_; }
00158     size_t PutEnd(Ch* begin) { return static_cast<size_t>(dst_ - begin); }
00159     void Flush() {}
00160 
00161     Ch* Push(size_t count) { Ch* begin = dst_; dst_ += count; return begin; }
00162     void Pop(size_t count) { dst_ -= count; }
00163 
00164     Ch* src_;
00165     Ch* dst_;
00166     Ch* head_;
00167 };
00168 
00169 template <typename Encoding>
00170 struct StreamTraits<GenericInsituStringStream<Encoding> > {
00171     enum { copyOptimization = 1 };
00172 };
00173 
00174 //! Insitu string stream with UTF8 encoding.
00175 typedef GenericInsituStringStream<UTF8<> > InsituStringStream;
00176 
00177 RAPIDJSON_NAMESPACE_END
00178 
00179 #endif // RAPIDJSON_STREAM_H_