Network event record/replay
authorkrollin@apple.com <krollin@apple.com@268f45cc-cd09-0410-ab3c-d52691b4dbfc>
Thu, 8 Dec 2016 00:44:19 +0000 (00:44 +0000)
committerkrollin@apple.com <krollin@apple.com@268f45cc-cd09-0410-ab3c-d52691b4dbfc>
Thu, 8 Dec 2016 00:44:19 +0000 (00:44 +0000)
https://bugs.webkit.org/show_bug.cgi?id=164527
<rdar://problem/29168157>

Reviewed by Alex Christensen.

Source/WebCore:

Export parseURLEncodedForm.

No new tests -- no functionality added, changed, or removed.

* platform/URLParser.h:

Source/WebKit2:

Add WebKit2/NetworkProcess/capture/* for recording the network events
that occur when loading a page and for replaying them later. Update
NetworkLoad to invoke capture facilities. Add preferences for enabling
record or replay.

* CMakeLists.txt:
* NetworkProcess/NetworkLoad.cpp:
(WebKit::NetworkLoad::NetworkLoad):
(WebKit::NetworkLoad::initializeForRecord):
(WebKit::NetworkLoad::initializeForReplay):
(WebKit::NetworkLoad::initialize):
(WebKit::NetworkLoad::setDefersLoading):
(WebKit::NetworkLoad::continueWillSendRequest):
(WebKit::NetworkLoad::sharedWillSendRedirectedRequest):
(WebKit::NetworkLoad::notifyDidReceiveResponse):
(WebKit::NetworkLoad::didReceiveData):
(WebKit::NetworkLoad::didCompleteWithError):
* NetworkProcess/NetworkLoad.h:
* NetworkProcess/NetworkProcess.cpp:
(WebKit::NetworkProcess::initializeNetworkProcess):
(WebKit::NetworkProcess::terminate):
* NetworkProcess/NetworkProcessCreationParameters.cpp:
(WebKit::NetworkProcessCreationParameters::encode):
(WebKit::NetworkProcessCreationParameters::decode):
* NetworkProcess/NetworkProcessCreationParameters.h:
* NetworkProcess/capture/NetworkCaptureEvent.cpp: Added.
(WebKit::NetworkCapture::copyHeaders):
(WebKit::NetworkCapture::KeyValuePair::KeyValuePair):
(WebKit::NetworkCapture::ResourceRequest::ResourceRequest):
(WebKit::NetworkCapture::ResourceRequest::operator WebCore::ResourceRequest):
(WebKit::NetworkCapture::ResourceResponse::ResourceResponse):
(WebKit::NetworkCapture::ResourceResponse::operator WebCore::ResourceResponse):
(WebKit::NetworkCapture::ResourceError::ResourceError):
(WebKit::NetworkCapture::ResourceError::operator WebCore::ResourceError):
(WebKit::NetworkCapture::JSONCoder::encode):
(WebKit::NetworkCapture::JSONCoder::decode):
(WebKit::NetworkCapture::JSONCoder<String>::encode):
(WebKit::NetworkCapture::JSONCoder<String>::decode):
(WebKit::NetworkCapture::JSONCoder<CaptureTimeType>::encode):
(WebKit::NetworkCapture::JSONCoder<CaptureTimeType>::decode):
(WebKit::NetworkCapture::JSONCoder<KeyValuePair>::encode):
(WebKit::NetworkCapture::JSONCoder<KeyValuePair>::decode):
(WebKit::NetworkCapture::JSONCoder<Vector<T>>::encode):
(WebKit::NetworkCapture::JSONCoder<Vector<T>>::decode):
(WebKit::NetworkCapture::JSONCoder<ResourceRequest>::encode):
(WebKit::NetworkCapture::JSONCoder<ResourceRequest>::decode):
(WebKit::NetworkCapture::JSONCoder<ResourceResponse>::encode):
(WebKit::NetworkCapture::JSONCoder<ResourceResponse>::decode):
(WebKit::NetworkCapture::JSONCoder<ResourceError>::encode):
(WebKit::NetworkCapture::JSONCoder<ResourceError>::decode):
(WebKit::NetworkCapture::JSONCoder<WebCore::SharedBuffer>::encode):
(WebKit::NetworkCapture::JSONCoder<WebCore::SharedBuffer>::decode):
(WebKit::NetworkCapture::JSONCoder<RequestSentEvent>::encode):
(WebKit::NetworkCapture::JSONCoder<RequestSentEvent>::decode):
(WebKit::NetworkCapture::JSONCoder<ResponseReceivedEvent>::encode):
(WebKit::NetworkCapture::JSONCoder<ResponseReceivedEvent>::decode):
(WebKit::NetworkCapture::JSONCoder<RedirectReceivedEvent>::encode):
(WebKit::NetworkCapture::JSONCoder<RedirectReceivedEvent>::decode):
(WebKit::NetworkCapture::JSONCoder<RedirectSentEvent>::encode):
(WebKit::NetworkCapture::JSONCoder<RedirectSentEvent>::decode):
(WebKit::NetworkCapture::JSONCoder<DataReceivedEvent>::encode):
(WebKit::NetworkCapture::JSONCoder<DataReceivedEvent>::decode):
(WebKit::NetworkCapture::JSONCoder<FinishedEvent>::encode):
(WebKit::NetworkCapture::JSONCoder<FinishedEvent>::decode):
(WebKit::NetworkCapture::eventToString):
(WebKit::NetworkCapture::stringToEvent):
* NetworkProcess/capture/NetworkCaptureEvent.h: Added.
(WebKit::NetworkCapture::TimedEvent::TimedEvent):
* NetworkProcess/capture/NetworkCaptureLogging.h: Added.
* NetworkProcess/capture/NetworkCaptureManager.cpp: Added.
(WebKit::NetworkCapture::Manager::singleton):
(WebKit::NetworkCapture::Manager::initialize):
(WebKit::NetworkCapture::Manager::terminate):
(WebKit::NetworkCapture::Manager::findMatch):
(WebKit::NetworkCapture::Manager::findExactMatch):
(WebKit::NetworkCapture::Manager::findBestFuzzyMatch):
(WebKit::NetworkCapture::Manager::fuzzyMatchURLs):
(WebKit::NetworkCapture::Manager::loadResources):
(WebKit::NetworkCapture::Manager::reportLoadPath):
(WebKit::NetworkCapture::Manager::reportRecordPath):
(WebKit::NetworkCapture::Manager::reportReplayPath):
(WebKit::NetworkCapture::Manager::requestToPath):
(WebKit::NetworkCapture::Manager::stringToHash):
(WebKit::NetworkCapture::Manager::hashToPath):
(WebKit::NetworkCapture::Manager::logRecordedResource):
(WebKit::NetworkCapture::Manager::logLoadedResource):
(WebKit::NetworkCapture::Manager::logPlayedBackResource):
(WebKit::NetworkCapture::Manager::ensureFileHandle):
(WebKit::NetworkCapture::Manager::openCacheFile):
(WebKit::NetworkCapture::Manager::readFile):
(WebKit::NetworkCapture::Manager::getLine):
(WebKit::NetworkCapture::Manager::getWord):
(WebKit::NetworkCapture::Manager::printToFile):
* NetworkProcess/capture/NetworkCaptureManager.h: Added.
(WebKit::NetworkCapture::Manager::isRecording):
(WebKit::NetworkCapture::Manager::isReplaying):
(WebKit::NetworkCapture::Manager::mode):
* NetworkProcess/capture/NetworkCaptureRecorder.cpp: Added.
(WebKit::NetworkCapture::Recorder::recordRequestSent):
(WebKit::NetworkCapture::Recorder::recordResponseReceived):
(WebKit::NetworkCapture::Recorder::recordRedirectReceived):
(WebKit::NetworkCapture::Recorder::recordRedirectSent):
(WebKit::NetworkCapture::Recorder::recordDataReceived):
(WebKit::NetworkCapture::Recorder::recordFinish):
(WebKit::NetworkCapture::Recorder::writeEvents):
* NetworkProcess/capture/NetworkCaptureRecorder.h: Added.
(WebKit::NetworkCapture::Recorder::recordEvent):
* NetworkProcess/capture/NetworkCaptureReplayer.cpp: Added.
(WebKit::NetworkCapture::Replayer::replayResource):
* NetworkProcess/capture/NetworkCaptureReplayer.h: Added.
* NetworkProcess/capture/NetworkCaptureResource.cpp: Added.
(WebKit::NetworkCapture::Resource::Resource):
(WebKit::NetworkCapture::Resource::url):
(WebKit::NetworkCapture::Resource::baseURL):
(WebKit::NetworkCapture::Resource::queryParameters):
(WebKit::NetworkCapture::Resource::eventStream):
(WebKit::NetworkCapture::Resource::EventStream::EventStream):
(WebKit::NetworkCapture::Resource::EventStream::nextEvent):
* NetworkProcess/capture/NetworkCaptureResource.h: Added.
* NetworkProcess/capture/NetworkCaptureTypes.h: Added.
(WebKit::NetworkCapture::TypeHolder::forEachTypeImpl):
(WebKit::NetworkCapture::TypeHolder::forEachType):
* NetworkProcess/capture/NetworkDataTaskReplay.cpp: Added.
(WebKit::NetworkCapture::NetworkDataTaskReplay::NetworkDataTaskReplay):
(WebKit::NetworkCapture::NetworkDataTaskReplay::~NetworkDataTaskReplay):
(WebKit::NetworkCapture::NetworkDataTaskReplay::resume):
(WebKit::NetworkCapture::NetworkDataTaskReplay::suspend):
(WebKit::NetworkCapture::NetworkDataTaskReplay::cancel):
(WebKit::NetworkCapture::NetworkDataTaskReplay::complete):
(WebKit::NetworkCapture::NetworkDataTaskReplay::invalidateAndCancel):
(WebKit::NetworkCapture::NetworkDataTaskReplay::enqueueEventHandler):
(WebKit::NetworkCapture::NetworkDataTaskReplay::replayRequestSent):
(WebKit::NetworkCapture::NetworkDataTaskReplay::replayResponseReceived):
(WebKit::NetworkCapture::NetworkDataTaskReplay::replayRedirectReceived):
(WebKit::NetworkCapture::NetworkDataTaskReplay::replayRedirectSent):
(WebKit::NetworkCapture::NetworkDataTaskReplay::replayDataReceived):
(WebKit::NetworkCapture::NetworkDataTaskReplay::replayFinished):
(WebKit::NetworkCapture::NetworkDataTaskReplay::didReceiveResponse):
(WebKit::NetworkCapture::NetworkDataTaskReplay::didFinish):
* NetworkProcess/capture/NetworkDataTaskReplay.h: Added.
(WebKit::NetworkCapture::NetworkDataTaskReplay::create):
* NetworkProcess/capture/json.hpp: Added.
* UIProcess/Cocoa/WebProcessPoolCocoa.mm:
(WebKit::WebProcessPool::platformInitializeNetworkProcess):
* WebKit2.xcodeproj/project.pbxproj:
* config.h:

git-svn-id: https://svn.webkit.org/repository/webkit/trunk@209498 268f45cc-cd09-0410-ab3c-d52691b4dbfc

27 files changed:
Source/WebCore/ChangeLog
Source/WebCore/platform/URLParser.h
Source/WebKit2/CMakeLists.txt
Source/WebKit2/ChangeLog
Source/WebKit2/NetworkProcess/NetworkLoad.cpp
Source/WebKit2/NetworkProcess/NetworkLoad.h
Source/WebKit2/NetworkProcess/NetworkProcess.cpp
Source/WebKit2/NetworkProcess/NetworkProcessCreationParameters.cpp
Source/WebKit2/NetworkProcess/NetworkProcessCreationParameters.h
Source/WebKit2/NetworkProcess/capture/NetworkCaptureEvent.cpp [new file with mode: 0644]
Source/WebKit2/NetworkProcess/capture/NetworkCaptureEvent.h [new file with mode: 0644]
Source/WebKit2/NetworkProcess/capture/NetworkCaptureLogging.h [new file with mode: 0644]
Source/WebKit2/NetworkProcess/capture/NetworkCaptureManager.cpp [new file with mode: 0644]
Source/WebKit2/NetworkProcess/capture/NetworkCaptureManager.h [new file with mode: 0644]
Source/WebKit2/NetworkProcess/capture/NetworkCaptureRecorder.cpp [new file with mode: 0644]
Source/WebKit2/NetworkProcess/capture/NetworkCaptureRecorder.h [new file with mode: 0644]
Source/WebKit2/NetworkProcess/capture/NetworkCaptureReplayer.cpp [new file with mode: 0644]
Source/WebKit2/NetworkProcess/capture/NetworkCaptureReplayer.h [new file with mode: 0644]
Source/WebKit2/NetworkProcess/capture/NetworkCaptureResource.cpp [new file with mode: 0644]
Source/WebKit2/NetworkProcess/capture/NetworkCaptureResource.h [new file with mode: 0644]
Source/WebKit2/NetworkProcess/capture/NetworkCaptureTypes.h [new file with mode: 0644]
Source/WebKit2/NetworkProcess/capture/NetworkDataTaskReplay.cpp [new file with mode: 0644]
Source/WebKit2/NetworkProcess/capture/NetworkDataTaskReplay.h [new file with mode: 0644]
Source/WebKit2/NetworkProcess/capture/json.hpp [new file with mode: 0644]
Source/WebKit2/UIProcess/Cocoa/WebProcessPoolCocoa.mm
Source/WebKit2/WebKit2.xcodeproj/project.pbxproj
Source/WebKit2/config.h

index b243ee1..ed2fbb8 100644 (file)
@@ -1,3 +1,17 @@
+2016-12-07  Keith Rollin  <krollin@apple.com>
+
+        Network event record/replay
+        https://bugs.webkit.org/show_bug.cgi?id=164527
+        <rdar://problem/29168157>
+
+        Reviewed by Alex Christensen.
+
+        Export parseURLEncodedForm.
+
+        No new tests -- no functionality added, changed, or removed.
+
+        * platform/URLParser.h:
+
 2016-12-07  Dave Hyatt  <hyatt@apple.com>
 
         [CSS Parser] Consolidate string/ident/url serialization functions
index 864eacd..78e0e19 100644 (file)
@@ -47,7 +47,7 @@ public:
     WEBCORE_EXPORT static void setEnabled(bool);
     
     typedef Vector<std::pair<String, String>> URLEncodedForm;
-    static URLEncodedForm parseURLEncodedForm(StringView);
+    WEBCORE_EXPORT static URLEncodedForm parseURLEncodedForm(StringView);
     static String serialize(const URLEncodedForm&);
 
     static const UIDNA& internationalDomainNameTranscoder();
index a99a01e..c44f4aa 100644 (file)
@@ -208,6 +208,13 @@ set(NetworkProcess_COMMON_SOURCES
     NetworkProcess/cache/NetworkCacheSubresourcesEntry.cpp
     NetworkProcess/cache/NetworkCacheStatistics.cpp
     NetworkProcess/cache/NetworkCacheStorage.cpp
+
+    NetworkProcess/capture/NetworkCaptureEvent.cpp
+    NetworkProcess/capture/NetworkCaptureManager.cpp
+    NetworkProcess/capture/NetworkCaptureRecorder.cpp
+    NetworkProcess/capture/NetworkCaptureReplayer.cpp
+    NetworkProcess/capture/NetworkCaptureResource.cpp
+    NetworkProcess/capture/NetworkDataTaskReplay.cpp
 )
 
 set(WebKit2_SOURCES
index 98875c2..1d44b8a 100644 (file)
@@ -1,3 +1,158 @@
+2016-12-07  Keith Rollin  <krollin@apple.com>
+
+        Network event record/replay
+        https://bugs.webkit.org/show_bug.cgi?id=164527
+        <rdar://problem/29168157>
+
+        Reviewed by Alex Christensen.
+
+        Add WebKit2/NetworkProcess/capture/* for recording the network events
+        that occur when loading a page and for replaying them later. Update
+        NetworkLoad to invoke capture facilities. Add preferences for enabling
+        record or replay.
+
+        * CMakeLists.txt:
+        * NetworkProcess/NetworkLoad.cpp:
+        (WebKit::NetworkLoad::NetworkLoad):
+        (WebKit::NetworkLoad::initializeForRecord):
+        (WebKit::NetworkLoad::initializeForReplay):
+        (WebKit::NetworkLoad::initialize):
+        (WebKit::NetworkLoad::setDefersLoading):
+        (WebKit::NetworkLoad::continueWillSendRequest):
+        (WebKit::NetworkLoad::sharedWillSendRedirectedRequest):
+        (WebKit::NetworkLoad::notifyDidReceiveResponse):
+        (WebKit::NetworkLoad::didReceiveData):
+        (WebKit::NetworkLoad::didCompleteWithError):
+        * NetworkProcess/NetworkLoad.h:
+        * NetworkProcess/NetworkProcess.cpp:
+        (WebKit::NetworkProcess::initializeNetworkProcess):
+        (WebKit::NetworkProcess::terminate):
+        * NetworkProcess/NetworkProcessCreationParameters.cpp:
+        (WebKit::NetworkProcessCreationParameters::encode):
+        (WebKit::NetworkProcessCreationParameters::decode):
+        * NetworkProcess/NetworkProcessCreationParameters.h:
+        * NetworkProcess/capture/NetworkCaptureEvent.cpp: Added.
+        (WebKit::NetworkCapture::copyHeaders):
+        (WebKit::NetworkCapture::KeyValuePair::KeyValuePair):
+        (WebKit::NetworkCapture::ResourceRequest::ResourceRequest):
+        (WebKit::NetworkCapture::ResourceRequest::operator WebCore::ResourceRequest):
+        (WebKit::NetworkCapture::ResourceResponse::ResourceResponse):
+        (WebKit::NetworkCapture::ResourceResponse::operator WebCore::ResourceResponse):
+        (WebKit::NetworkCapture::ResourceError::ResourceError):
+        (WebKit::NetworkCapture::ResourceError::operator WebCore::ResourceError):
+        (WebKit::NetworkCapture::JSONCoder::encode):
+        (WebKit::NetworkCapture::JSONCoder::decode):
+        (WebKit::NetworkCapture::JSONCoder<String>::encode):
+        (WebKit::NetworkCapture::JSONCoder<String>::decode):
+        (WebKit::NetworkCapture::JSONCoder<CaptureTimeType>::encode):
+        (WebKit::NetworkCapture::JSONCoder<CaptureTimeType>::decode):
+        (WebKit::NetworkCapture::JSONCoder<KeyValuePair>::encode):
+        (WebKit::NetworkCapture::JSONCoder<KeyValuePair>::decode):
+        (WebKit::NetworkCapture::JSONCoder<Vector<T>>::encode):
+        (WebKit::NetworkCapture::JSONCoder<Vector<T>>::decode):
+        (WebKit::NetworkCapture::JSONCoder<ResourceRequest>::encode):
+        (WebKit::NetworkCapture::JSONCoder<ResourceRequest>::decode):
+        (WebKit::NetworkCapture::JSONCoder<ResourceResponse>::encode):
+        (WebKit::NetworkCapture::JSONCoder<ResourceResponse>::decode):
+        (WebKit::NetworkCapture::JSONCoder<ResourceError>::encode):
+        (WebKit::NetworkCapture::JSONCoder<ResourceError>::decode):
+        (WebKit::NetworkCapture::JSONCoder<WebCore::SharedBuffer>::encode):
+        (WebKit::NetworkCapture::JSONCoder<WebCore::SharedBuffer>::decode):
+        (WebKit::NetworkCapture::JSONCoder<RequestSentEvent>::encode):
+        (WebKit::NetworkCapture::JSONCoder<RequestSentEvent>::decode):
+        (WebKit::NetworkCapture::JSONCoder<ResponseReceivedEvent>::encode):
+        (WebKit::NetworkCapture::JSONCoder<ResponseReceivedEvent>::decode):
+        (WebKit::NetworkCapture::JSONCoder<RedirectReceivedEvent>::encode):
+        (WebKit::NetworkCapture::JSONCoder<RedirectReceivedEvent>::decode):
+        (WebKit::NetworkCapture::JSONCoder<RedirectSentEvent>::encode):
+        (WebKit::NetworkCapture::JSONCoder<RedirectSentEvent>::decode):
+        (WebKit::NetworkCapture::JSONCoder<DataReceivedEvent>::encode):
+        (WebKit::NetworkCapture::JSONCoder<DataReceivedEvent>::decode):
+        (WebKit::NetworkCapture::JSONCoder<FinishedEvent>::encode):
+        (WebKit::NetworkCapture::JSONCoder<FinishedEvent>::decode):
+        (WebKit::NetworkCapture::eventToString):
+        (WebKit::NetworkCapture::stringToEvent):
+        * NetworkProcess/capture/NetworkCaptureEvent.h: Added.
+        (WebKit::NetworkCapture::TimedEvent::TimedEvent):
+        * NetworkProcess/capture/NetworkCaptureLogging.h: Added.
+        * NetworkProcess/capture/NetworkCaptureManager.cpp: Added.
+        (WebKit::NetworkCapture::Manager::singleton):
+        (WebKit::NetworkCapture::Manager::initialize):
+        (WebKit::NetworkCapture::Manager::terminate):
+        (WebKit::NetworkCapture::Manager::findMatch):
+        (WebKit::NetworkCapture::Manager::findExactMatch):
+        (WebKit::NetworkCapture::Manager::findBestFuzzyMatch):
+        (WebKit::NetworkCapture::Manager::fuzzyMatchURLs):
+        (WebKit::NetworkCapture::Manager::loadResources):
+        (WebKit::NetworkCapture::Manager::reportLoadPath):
+        (WebKit::NetworkCapture::Manager::reportRecordPath):
+        (WebKit::NetworkCapture::Manager::reportReplayPath):
+        (WebKit::NetworkCapture::Manager::requestToPath):
+        (WebKit::NetworkCapture::Manager::stringToHash):
+        (WebKit::NetworkCapture::Manager::hashToPath):
+        (WebKit::NetworkCapture::Manager::logRecordedResource):
+        (WebKit::NetworkCapture::Manager::logLoadedResource):
+        (WebKit::NetworkCapture::Manager::logPlayedBackResource):
+        (WebKit::NetworkCapture::Manager::ensureFileHandle):
+        (WebKit::NetworkCapture::Manager::openCacheFile):
+        (WebKit::NetworkCapture::Manager::readFile):
+        (WebKit::NetworkCapture::Manager::getLine):
+        (WebKit::NetworkCapture::Manager::getWord):
+        (WebKit::NetworkCapture::Manager::printToFile):
+        * NetworkProcess/capture/NetworkCaptureManager.h: Added.
+        (WebKit::NetworkCapture::Manager::isRecording):
+        (WebKit::NetworkCapture::Manager::isReplaying):
+        (WebKit::NetworkCapture::Manager::mode):
+        * NetworkProcess/capture/NetworkCaptureRecorder.cpp: Added.
+        (WebKit::NetworkCapture::Recorder::recordRequestSent):
+        (WebKit::NetworkCapture::Recorder::recordResponseReceived):
+        (WebKit::NetworkCapture::Recorder::recordRedirectReceived):
+        (WebKit::NetworkCapture::Recorder::recordRedirectSent):
+        (WebKit::NetworkCapture::Recorder::recordDataReceived):
+        (WebKit::NetworkCapture::Recorder::recordFinish):
+        (WebKit::NetworkCapture::Recorder::writeEvents):
+        * NetworkProcess/capture/NetworkCaptureRecorder.h: Added.
+        (WebKit::NetworkCapture::Recorder::recordEvent):
+        * NetworkProcess/capture/NetworkCaptureReplayer.cpp: Added.
+        (WebKit::NetworkCapture::Replayer::replayResource):
+        * NetworkProcess/capture/NetworkCaptureReplayer.h: Added.
+        * NetworkProcess/capture/NetworkCaptureResource.cpp: Added.
+        (WebKit::NetworkCapture::Resource::Resource):
+        (WebKit::NetworkCapture::Resource::url):
+        (WebKit::NetworkCapture::Resource::baseURL):
+        (WebKit::NetworkCapture::Resource::queryParameters):
+        (WebKit::NetworkCapture::Resource::eventStream):
+        (WebKit::NetworkCapture::Resource::EventStream::EventStream):
+        (WebKit::NetworkCapture::Resource::EventStream::nextEvent):
+        * NetworkProcess/capture/NetworkCaptureResource.h: Added.
+        * NetworkProcess/capture/NetworkCaptureTypes.h: Added.
+        (WebKit::NetworkCapture::TypeHolder::forEachTypeImpl):
+        (WebKit::NetworkCapture::TypeHolder::forEachType):
+        * NetworkProcess/capture/NetworkDataTaskReplay.cpp: Added.
+        (WebKit::NetworkCapture::NetworkDataTaskReplay::NetworkDataTaskReplay):
+        (WebKit::NetworkCapture::NetworkDataTaskReplay::~NetworkDataTaskReplay):
+        (WebKit::NetworkCapture::NetworkDataTaskReplay::resume):
+        (WebKit::NetworkCapture::NetworkDataTaskReplay::suspend):
+        (WebKit::NetworkCapture::NetworkDataTaskReplay::cancel):
+        (WebKit::NetworkCapture::NetworkDataTaskReplay::complete):
+        (WebKit::NetworkCapture::NetworkDataTaskReplay::invalidateAndCancel):
+        (WebKit::NetworkCapture::NetworkDataTaskReplay::enqueueEventHandler):
+        (WebKit::NetworkCapture::NetworkDataTaskReplay::replayRequestSent):
+        (WebKit::NetworkCapture::NetworkDataTaskReplay::replayResponseReceived):
+        (WebKit::NetworkCapture::NetworkDataTaskReplay::replayRedirectReceived):
+        (WebKit::NetworkCapture::NetworkDataTaskReplay::replayRedirectSent):
+        (WebKit::NetworkCapture::NetworkDataTaskReplay::replayDataReceived):
+        (WebKit::NetworkCapture::NetworkDataTaskReplay::replayFinished):
+        (WebKit::NetworkCapture::NetworkDataTaskReplay::didReceiveResponse):
+        (WebKit::NetworkCapture::NetworkDataTaskReplay::didFinish):
+        * NetworkProcess/capture/NetworkDataTaskReplay.h: Added.
+        (WebKit::NetworkCapture::NetworkDataTaskReplay::create):
+        * NetworkProcess/capture/json.hpp: Added.
+        * UIProcess/Cocoa/WebProcessPoolCocoa.mm:
+        (WebKit::WebProcessPool::platformInitializeNetworkProcess):
+        * WebKit2.xcodeproj/project.pbxproj:
+        * config.h:
+
 2016-12-07  Anders Carlsson  <andersca@apple.com>
 
         Fix build.
index 517f845..1c3e281 100644 (file)
 #include "NetworkDataTaskCocoa.h"
 #endif
 
+#if ENABLE(NETWORK_CAPTURE)
+#include "NetworkCaptureManager.h"
+#endif
+
 namespace WebKit {
 
 using namespace WebCore;
@@ -67,6 +71,45 @@ NetworkLoad::NetworkLoad(NetworkLoadClient& client, NetworkLoadParameters&& para
     , m_parameters(WTFMove(parameters))
     , m_currentRequest(m_parameters.request)
 {
+#if ENABLE(NETWORK_CAPTURE)
+    switch (NetworkCapture::Manager::singleton().mode()) {
+    case NetworkCapture::Manager::RecordReplayMode::Record:
+        initializeForRecord(networkSession);
+        break;
+    case NetworkCapture::Manager::RecordReplayMode::Replay:
+        initializeForReplay(networkSession);
+        break;
+    case NetworkCapture::Manager::RecordReplayMode::Disabled:
+        initialize(networkSession);
+        break;
+    }
+#else
+    initialize(networkSession);
+#endif
+}
+
+#if ENABLE(NETWORK_CAPTURE)
+void NetworkLoad::initializeForRecord(NetworkSession& networkSession)
+{
+    m_recorder = std::make_unique<NetworkCapture::Recorder>();
+    m_task = NetworkDataTask::create(networkSession, *this, m_parameters);
+    if (!m_parameters.defersLoading) {
+        m_task->resume();
+        m_recorder->recordRequestSent(m_parameters.request);
+    }
+}
+
+void NetworkLoad::initializeForReplay(NetworkSession& networkSession)
+{
+    m_replayer = std::make_unique<NetworkCapture::Replayer>();
+    m_task = m_replayer->replayResource(networkSession, *this, m_parameters);
+    if (!m_parameters.defersLoading)
+        m_task->resume();
+}
+#endif
+
+void NetworkLoad::initialize(NetworkSession& networkSession)
+{
     m_task = NetworkDataTask::create(networkSession, *this, m_parameters);
     if (!m_parameters.defersLoading)
         m_task->resume();
@@ -113,8 +156,13 @@ void NetworkLoad::setDefersLoading(bool defers)
     if (m_task) {
         if (defers)
             m_task->suspend();
-        else
+        else {
             m_task->resume();
+#if ENABLE(NETWORK_CAPTURE)
+            if (m_recorder)
+                m_recorder->recordRequestSent(m_parameters.request);
+#endif
+        }
     }
 #else
     if (m_handle)
@@ -142,6 +190,11 @@ void NetworkLoad::continueWillSendRequest(WebCore::ResourceRequest&& newRequest)
     m_currentRequest.updateFromDelegatePreservingOldProperties(newRequest);
 #endif
 
+#if ENABLE(NETWORK_CAPTURE)
+    if (m_recorder)
+        m_recorder->recordRedirectSent(newRequest);
+#endif
+
 #if USE(NETWORK_SESSION)
     auto redirectCompletionHandler = std::exchange(m_redirectCompletionHandler, nullptr);
     ASSERT(redirectCompletionHandler);
@@ -194,6 +247,11 @@ void NetworkLoad::sharedWillSendRedirectedRequest(ResourceRequest&& request, Res
     ASSERT(!redirectResponse.isNull());
     ASSERT(RunLoop::isMain());
 
+#if ENABLE(NETWORK_CAPTURE)
+    if (m_recorder)
+        m_recorder->recordRedirectReceived(request, redirectResponse);
+#endif
+
     auto oldRequest = WTFMove(m_currentRequest);
     m_currentRequest = request;
     m_client.get().willSendRedirectedRequest(WTFMove(oldRequest), WTFMove(request), WTFMove(redirectResponse));
@@ -324,6 +382,11 @@ void NetworkLoad::notifyDidReceiveResponse(ResourceResponse&& response, Response
 {
     ASSERT(isMainThread());
 
+#if ENABLE(NETWORK_CAPTURE)
+    if (m_recorder)
+        m_recorder->recordResponseReceived(response);
+#endif
+
     if (sharedDidReceiveResponse(WTFMove(response)) == NetworkLoadClient::ShouldContinueDidReceiveResponse::No) {
         m_responseCompletionHandler = WTFMove(completionHandler);
         return;
@@ -335,6 +398,11 @@ void NetworkLoad::didReceiveData(Ref<SharedBuffer>&& buffer)
 {
     ASSERT(!m_throttle);
 
+#if ENABLE(NETWORK_CAPTURE)
+    if (m_recorder)
+        m_recorder->recordDataReceived(buffer.get());
+#endif
+
     // FIXME: This should be the encoded data length, not the decoded data length.
     auto size = buffer->size();
     m_client.get().didReceiveBuffer(WTFMove(buffer), size);
@@ -344,6 +412,11 @@ void NetworkLoad::didCompleteWithError(const ResourceError& error)
 {
     ASSERT(!m_throttle);
 
+#if ENABLE(NETWORK_CAPTURE)
+    if (m_recorder)
+        m_recorder->recordFinish(error);
+#endif
+
     if (error.isNull())
         m_client.get().didFinishLoading(WTF::monotonicallyIncreasingTime());
     else
index 766bd50..b252a0c 100644 (file)
 #include <WebCore/AuthenticationChallenge.h>
 #endif
 
+#if ENABLE(NETWORK_CAPTURE)
+#include "NetworkCaptureRecorder.h"
+#include "NetworkCaptureReplayer.h"
+#endif
+
 namespace WebKit {
 
 class NetworkLoad final :
@@ -95,6 +100,14 @@ public:
 #endif
 
 private:
+#if USE(NETWORK_SESSION)
+#if ENABLE(NETWORK_CAPTURE)
+    void initializeForRecord(NetworkSession&);
+    void initializeForReplay(NetworkSession&);
+#endif
+    void initialize(NetworkSession&);
+#endif
+
     NetworkLoadClient::ShouldContinueDidReceiveResponse sharedDidReceiveResponse(WebCore::ResourceResponse&&);
     void sharedWillSendRedirectedRequest(WebCore::ResourceRequest&&, WebCore::ResourceResponse&&);
 
@@ -151,6 +164,11 @@ private:
 #endif
 
     WebCore::ResourceRequest m_currentRequest; // Updated on redirects.
+
+#if ENABLE(NETWORK_CAPTURE)
+    std::unique_ptr<NetworkCapture::Recorder> m_recorder;
+    std::unique_ptr<NetworkCapture::Replayer> m_replayer;
+#endif
 };
 
 } // namespace WebKit
index 61f9876..ffaf7db 100644 (file)
 #include "NetworkCacheCoders.h"
 #endif
 
+#if ENABLE(NETWORK_CAPTURE)
+#include "NetworkCaptureManager.h"
+#endif
+
 #if PLATFORM(COCOA)
 #include "NetworkSessionCocoa.h"
 #endif
@@ -222,6 +226,12 @@ void NetworkProcess::initializeNetworkProcess(NetworkProcessCreationParameters&&
         memoryPressureHandler.install();
     }
 
+#if ENABLE(NETWORK_CAPTURE)
+    NetworkCapture::Manager::singleton().initialize(
+        parameters.recordReplayMode,
+        parameters.recordReplayCacheLocation);
+#endif
+
     m_diskCacheIsDisabledForTesting = parameters.shouldUseTestingNetworkSession;
 
     m_diskCacheSizeOverride = parameters.diskCacheSizeOverride;
@@ -596,6 +606,10 @@ void NetworkProcess::logDiagnosticMessageWithValue(uint64_t webPageID, const Str
 
 void NetworkProcess::terminate()
 {
+#if ENABLE(NETWORK_CAPTURE)
+    NetworkCapture::Manager::singleton().terminate();
+#endif
+
     platformTerminate();
     ChildProcess::terminate();
 }
index bd7ab54..099a3a4 100644 (file)
@@ -93,6 +93,10 @@ void NetworkProcessCreationParameters::encode(IPC::Encoder& encoder) const
 #if OS(LINUX)
     encoder << memoryPressureMonitorHandle;
 #endif
+#if ENABLE(NETWORK_CAPTURE)
+    encoder << recordReplayMode;
+    encoder << recordReplayCacheLocation;
+#endif
 }
 
 bool NetworkProcessCreationParameters::decode(IPC::Decoder& decoder, NetworkProcessCreationParameters& result)
@@ -188,6 +192,13 @@ bool NetworkProcessCreationParameters::decode(IPC::Decoder& decoder, NetworkProc
         return false;
 #endif
 
+#if ENABLE(NETWORK_CAPTURE)
+    if (!decoder.decode(result.recordReplayMode))
+        return false;
+    if (!decoder.decode(result.recordReplayCacheLocation))
+        return false;
+#endif
+
     return true;
 }
 
index f4569c9..330e3ba 100644 (file)
@@ -106,6 +106,11 @@ struct NetworkProcessCreationParameters {
 #if OS(LINUX)
     IPC::Attachment memoryPressureMonitorHandle;
 #endif
+
+#if ENABLE(NETWORK_CAPTURE)
+    String recordReplayMode;
+    String recordReplayCacheLocation;
+#endif
 };
 
 } // namespace WebKit
diff --git a/Source/WebKit2/NetworkProcess/capture/NetworkCaptureEvent.cpp b/Source/WebKit2/NetworkProcess/capture/NetworkCaptureEvent.cpp
new file mode 100644 (file)
index 0000000..9508ba7
--- /dev/null
@@ -0,0 +1,505 @@
+/*
+ * Copyright (C) 2016 Apple Inc. All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ * 1. Redistributions of source code must retain the above copyright
+ *    notice, this list of conditions and the following disclaimer.
+ * 2. Redistributions in binary form must reproduce the above copyright
+ *    notice, this list of conditions and the following disclaimer in the
+ *    documentation and/or other materials provided with the distribution.
+ *
+ * THIS SOFTWARE IS PROVIDED BY APPLE INC. AND ITS CONTRIBUTORS ``AS IS''
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+ * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+ * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL APPLE INC. OR ITS CONTRIBUTORS
+ * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
+ * THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+#include "config.h"
+#include "NetworkCaptureEvent.h"
+
+#if ENABLE(NETWORK_CAPTURE)
+
+
+#include "NetworkCaptureLogging.h"
+#include "json.hpp"
+#include <WebCore/ResourceError.h>
+#include <WebCore/ResourceRequest.h>
+#include <WebCore/ResourceResponse.h>
+#include <WebCore/URLParser.h>
+#include <wtf/Assertions.h>
+#include <wtf/Brigand.h>
+#include <wtf/text/Base64.h>
+
+namespace WebKit {
+namespace NetworkCapture {
+
+const char RequestSentEvent::typeName[] = "RequestSentEvent";
+const char ResponseReceivedEvent::typeName[] = "ResponseReceivedEvent";
+const char RedirectReceivedEvent::typeName[] = "RedirectReceivedEvent";
+const char RedirectSentEvent::typeName[] = "RedirectSentEvent";
+const char DataReceivedEvent::typeName[] = "DataReceivedEvent";
+const char FinishedEvent::typeName[] = "FinishedEvent";
+
+static Headers copyHeaders(const WebCore::HTTPHeaderMap& httpHeaders)
+{
+    Headers headers;
+    for (const auto& header : httpHeaders)
+        headers.append(std::make_pair(header.key, header.value));
+    return headers;
+}
+
+// ----------
+
+Request::Request(String&& url, String&& referrer, int policy, String&& method, Headers&& headers)
+    : url(WTFMove(url))
+    , referrer(WTFMove(referrer))
+    , policy(WTFMove(policy))
+    , method(WTFMove(method))
+    , headers(WTFMove(headers))
+{
+}
+
+Request::Request(const WebCore::ResourceRequest& request)
+    : url(request.url().string())
+    , referrer(request.httpReferrer())
+    , policy(static_cast<int>(request.cachePolicy()))
+    , method(request.httpMethod())
+    , headers(copyHeaders(request.httpHeaderFields()))
+{
+}
+
+Request::operator WebCore::ResourceRequest() const
+{
+    WebCore::URLParser parser(url);
+    WebCore::ResourceRequest request(parser.result(), referrer, static_cast<WebCore::ResourceRequestCachePolicy>(policy));
+    request.setHTTPMethod(method);
+
+    for (const auto& header : headers)
+        request.setHTTPHeaderField(header.first, header.second);
+
+    return request;
+}
+
+// ----------
+
+Response::Response(String&& url, String&& mimeType, long long expectedLength, String&& textEncodingName, String&& version, int status, String&& reason, Headers&& headers)
+    : url(WTFMove(url))
+    , mimeType(WTFMove(mimeType))
+    , expectedLength(WTFMove(expectedLength))
+    , textEncodingName(WTFMove(textEncodingName))
+    , status(WTFMove(status))
+    , reason(WTFMove(reason))
+    , headers(WTFMove(headers))
+{
+}
+
+Response::Response(const WebCore::ResourceResponse& response)
+    : url(response.url())
+    , mimeType(response.mimeType())
+    , expectedLength(response.expectedContentLength())
+    , textEncodingName(response.textEncodingName())
+    , version(response.httpVersion())
+    , status(response.httpStatusCode())
+    , reason(response.httpStatusText())
+    , headers(copyHeaders(response.httpHeaderFields()))
+{
+}
+
+Response::operator WebCore::ResourceResponse() const
+{
+    WebCore::URLParser parser(url);
+    WebCore::ResourceResponse response(parser.result(), mimeType, expectedLength, textEncodingName);
+    response.setHTTPVersion(version);
+    response.setHTTPStatusCode(status);
+    response.setHTTPStatusText(reason);
+
+    for (const auto& header : headers)
+        response.setHTTPHeaderField(header.first, header.second);
+
+    return response;
+}
+
+// ----------
+
+Error::Error(String&& domain, String&& failingURL, String&& localizedDescription, int errorCode, int type)
+    : domain(WTFMove(domain))
+    , failingURL(WTFMove(failingURL))
+    , localizedDescription(WTFMove(localizedDescription))
+    , errorCode(WTFMove(errorCode))
+    , type(WTFMove(type))
+{
+}
+
+Error::Error(const WebCore::ResourceError& error)
+    : domain(error.domain())
+    , failingURL(error.failingURL())
+    , localizedDescription(error.localizedDescription())
+    , errorCode(error.errorCode())
+    , type(static_cast<int>(error.type()))
+{
+}
+
+Error::operator WebCore::ResourceError() const
+{
+    WebCore::URLParser parser(failingURL);
+    WebCore::ResourceError error(domain, errorCode, parser.result(), localizedDescription, static_cast<WebCore::ResourceError::Type>(type));
+
+    return error;
+}
+
+// ----------
+
+// SEE THE NOTE IN json.hpp REGARDING ITS USE IN THIS PROJECT. IN SHORT, DO NOT
+// USE json.hpp ANYWHERE ELSE. IT WILL BE GOING AWAY.
+using json = nlohmann::basic_json<>;
+
+template<typename Type>
+struct JSONCoder {
+    static json encode(Type val)
+    {
+        return json(val);
+    }
+
+    static Type decode(const json& jVal)
+    {
+        return jVal.get<Type>();
+    }
+};
+
+template<>
+struct JSONCoder<const char*> {
+    static json encode(const char* val)
+    {
+        return json(val);
+    }
+};
+
+template<>
+struct JSONCoder<String> {
+    static json encode(const String& val)
+    {
+        return json(static_cast<const char*>(val.utf8().data()));
+    }
+
+    static String decode(const json& jVal)
+    {
+        return String(jVal.get_ref<const std::string&>().c_str());
+    }
+};
+
+template<>
+struct JSONCoder<CaptureTimeType> {
+    static json encode(const CaptureTimeType& time)
+    {
+        return JSONCoder<double>::encode(time.secondsSinceEpoch().seconds());
+    }
+
+    static CaptureTimeType decode(const json& jTime)
+    {
+        return CaptureTimeType::fromRawSeconds(JSONCoder<double>::decode(jTime));
+    }
+};
+
+template<>
+struct JSONCoder<KeyValuePair> {
+    static json encode(const KeyValuePair& pair)
+    {
+        return json {
+            JSONCoder<String>::encode(pair.first),
+            JSONCoder<String>::encode(pair.second)
+        };
+    }
+
+    static KeyValuePair decode(const json& jPair)
+    {
+        return KeyValuePair {
+            JSONCoder<String>::decode(jPair[0]),
+            JSONCoder<String>::decode(jPair[1])
+        };
+    }
+};
+
+template<typename T>
+struct JSONCoder<Vector<T>> {
+    static json encode(const Vector<T>& vector)
+    {
+        json jVector;
+
+        for (const auto& element : vector)
+            jVector.push_back(JSONCoder<T>::encode(element));
+
+        return jVector;
+    }
+
+    static Vector<T> decode(const json& jVector)
+    {
+        Vector<T> vector;
+
+        for (const auto& element : jVector)
+            vector.append(JSONCoder<T>::decode(element));
+
+        return vector;
+    }
+};
+
+template<>
+struct JSONCoder<Request> {
+    static json encode(const Request& request)
+    {
+        return json {
+            { "url", JSONCoder<String>::encode(request.url) },
+            { "referrer", JSONCoder<String>::encode(request.referrer) },
+            { "policy", JSONCoder<int>::encode(request.policy) },
+            { "method", JSONCoder<String>::encode(request.method) },
+            { "headers", JSONCoder<Headers>::encode(request.headers) }
+        };
+    }
+
+    static Request decode(const json& jRequest)
+    {
+        return Request {
+            JSONCoder<String>::decode(jRequest["url"]),
+            JSONCoder<String>::decode(jRequest["referrer"]),
+            JSONCoder<int>::decode(jRequest["policy"]),
+            JSONCoder<String>::decode(jRequest["method"]),
+            JSONCoder<Headers>::decode(jRequest["headers"])
+        };
+    }
+};
+
+template<>
+struct JSONCoder<Response> {
+    static json encode(const Response& response)
+    {
+        return json {
+            { "url", JSONCoder<String>::encode(response.url) },
+            { "mimeType", JSONCoder<String>::encode(response.mimeType) },
+            { "expectedLength", JSONCoder<long long>::encode(response.expectedLength) },
+            { "textEncodingName", JSONCoder<String>::encode(response.textEncodingName) },
+            { "version", JSONCoder<String>::encode(response.version) },
+            { "status", JSONCoder<int>::encode(response.status) },
+            { "reason", JSONCoder<String>::encode(response.reason) },
+            { "headers", JSONCoder<Headers>::encode(response.headers) }
+        };
+    }
+
+    static Response decode(const json& jResponse)
+    {
+        return Response {
+            JSONCoder<String>::decode(jResponse["url"]),
+            JSONCoder<String>::decode(jResponse["mimeType"]),
+            JSONCoder<long long>::decode(jResponse["expectedLength"]),
+            JSONCoder<String>::decode(jResponse["textEncodingName"]),
+            JSONCoder<String>::decode(jResponse["version"]),
+            JSONCoder<int>::decode(jResponse["status"]),
+            JSONCoder<String>::decode(jResponse["reason"]),
+            JSONCoder<Headers>::decode(jResponse["headers"])
+        };
+    }
+};
+
+template<>
+struct JSONCoder<Error> {
+    static json encode(const Error& error)
+    {
+        return json {
+            { "domain", JSONCoder<String>::encode(error.domain) },
+            { "failingURL", JSONCoder<String>::encode(error.failingURL) },
+            { "localizedDescription", JSONCoder<String>::encode(error.localizedDescription) },
+            { "errorCode", JSONCoder<int>::encode(error.errorCode) },
+            { "type", JSONCoder<int>::encode(error.type) }
+        };
+    }
+
+    static Error decode(const json& jError)
+    {
+        return Error {
+            JSONCoder<String>::decode(jError["domain"]),
+            JSONCoder<String>::decode(jError["failingURL"]),
+            JSONCoder<String>::decode(jError["localizedDescription"]),
+            JSONCoder<int>::decode(jError["errorCode"]),
+            JSONCoder<int>::decode(jError["type"])
+        };
+    }
+};
+
+template<>
+struct JSONCoder<WebCore::SharedBuffer> {
+    static json encode(const WebCore::SharedBuffer& data)
+    {
+        Vector<char> buffer;
+        base64Encode(data.data(), data.size(), buffer);
+        return json(&buffer[0], buffer.size());
+    }
+
+    static Ref<WebCore::SharedBuffer> decode(const json& jData)
+    {
+        Vector<char> data;
+        const auto& str = jData.get_ref<const std::string&>();
+        auto result = base64Decode(str.c_str(), str.size(), data);
+        ASSERT_UNUSED(result, result);
+        return WebCore::SharedBuffer::adoptVector(data);
+    }
+};
+
+template<>
+struct JSONCoder<RequestSentEvent> {
+    static json encode(const RequestSentEvent& event)
+    {
+        return json {
+            { "type", JSONCoder<const char*>::encode(event.typeName) },
+            { "time", JSONCoder<CaptureTimeType>::encode(event.time) },
+            { "request", JSONCoder<Request>::encode(event.request) }
+        };
+    }
+
+    static RequestSentEvent decode(const json& jEvent)
+    {
+        return RequestSentEvent {
+            JSONCoder<CaptureTimeType>::decode(jEvent["time"]),
+            JSONCoder<Request>::decode(jEvent["request"])
+        };
+    }
+};
+
+template<>
+struct JSONCoder<ResponseReceivedEvent> {
+    static json encode(const ResponseReceivedEvent& event)
+    {
+        return json {
+            { "type", JSONCoder<const char*>::encode(event.typeName) },
+            { "time", JSONCoder<CaptureTimeType>::encode(event.time) },
+            { "response", JSONCoder<Response>::encode(event.response) }
+        };
+    }
+
+    static ResponseReceivedEvent decode(const json& jEvent)
+    {
+        return ResponseReceivedEvent {
+            JSONCoder<CaptureTimeType>::decode(jEvent["time"]),
+            JSONCoder<Response>::decode(jEvent["response"])
+        };
+    }
+};
+
+template<>
+struct JSONCoder<RedirectReceivedEvent> {
+    static json encode(const RedirectReceivedEvent& event)
+    {
+        return json {
+            { "type", JSONCoder<const char*>::encode(event.typeName) },
+            { "time", JSONCoder<CaptureTimeType>::encode(event.time) },
+            { "request", JSONCoder<Request>::encode(event.request) },
+            { "response", JSONCoder<Response>::encode(event.response) }
+        };
+    }
+
+    static RedirectReceivedEvent decode(const json& jEvent)
+    {
+        return RedirectReceivedEvent {
+            JSONCoder<CaptureTimeType>::decode(jEvent["time"]),
+            JSONCoder<Request>::decode(jEvent["request"]),
+            JSONCoder<Response>::decode(jEvent["response"])
+        };
+    }
+};
+
+template<>
+struct JSONCoder<RedirectSentEvent> {
+    static json encode(const RedirectSentEvent& event)
+    {
+        return json {
+            { "type", JSONCoder<const char*>::encode(event.typeName) },
+            { "time", JSONCoder<CaptureTimeType>::encode(event.time) },
+            { "request", JSONCoder<Request>::encode(event.request) },
+        };
+    }
+
+    static RedirectSentEvent decode(const json& jEvent)
+    {
+        return RedirectSentEvent {
+            JSONCoder<CaptureTimeType>::decode(jEvent["time"]),
+            JSONCoder<Request>::decode(jEvent["request"])
+        };
+    }
+};
+
+template<>
+struct JSONCoder<DataReceivedEvent> {
+    static json encode(const DataReceivedEvent& event)
+    {
+        return json {
+            { "type", JSONCoder<const char*>::encode(event.typeName) },
+            { "time", JSONCoder<CaptureTimeType>::encode(event.time) },
+            { "data", JSONCoder<WebCore::SharedBuffer>::encode(event.data.get()) }
+        };
+    }
+
+    static DataReceivedEvent decode(const json& jEvent)
+    {
+        return DataReceivedEvent {
+            JSONCoder<CaptureTimeType>::decode(jEvent["time"]),
+            JSONCoder<WebCore::SharedBuffer>::decode(jEvent["data"])
+        };
+    }
+};
+
+template<>
+struct JSONCoder<FinishedEvent> {
+    static json encode(const FinishedEvent& event)
+    {
+        return json {
+            { "type", JSONCoder<const char*>::encode(event.typeName) },
+            { "time", JSONCoder<CaptureTimeType>::encode(event.time) },
+            { "error", JSONCoder<Error>::encode(event.error) }
+        };
+    }
+
+    static FinishedEvent decode(const json& jEvent)
+    {
+        return FinishedEvent {
+            JSONCoder<CaptureTimeType>::decode(jEvent["time"]),
+            JSONCoder<Error>::decode(jEvent["error"])
+        };
+    }
+};
+
+std::string eventToString(const CaptureEvent& event)
+{
+    json result;
+
+    WTF::visit([&result](const auto& event) {
+        using EventType = std::decay_t<decltype(event)>;
+        result = JSONCoder<EventType>::encode(event);
+    }, event);
+
+    return result.dump(4);
+}
+
+OptionalCaptureEvent stringToEvent(const char* jsonStr)
+{
+    auto jValue = json::parse(jsonStr);
+    const auto& type = jValue["type"].get_ref<const std::string&>();
+
+    OptionalCaptureEvent result { std::nullopt };
+    brigand::for_each<CaptureEvent>([&](auto T) {
+        using Type = typename decltype(T)::type;
+        if (!result && type == Type::typeName)
+            result = OptionalCaptureEvent(JSONCoder<Type>::decode(jValue));
+    });
+    return result;
+}
+
+} // namespace NetworkCapture
+} // namespace WebKit
+
+#endif // ENABLE(NETWORK_CAPTURE)
diff --git a/Source/WebKit2/NetworkProcess/capture/NetworkCaptureEvent.h b/Source/WebKit2/NetworkProcess/capture/NetworkCaptureEvent.h
new file mode 100644 (file)
index 0000000..0a797ec
--- /dev/null
@@ -0,0 +1,231 @@
+/*
+ * Copyright (C) 2016 Apple Inc. All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ * 1. Redistributions of source code must retain the above copyright
+ *    notice, this list of conditions and the following disclaimer.
+ * 2. Redistributions in binary form must reproduce the above copyright
+ *    notice, this list of conditions and the following disclaimer in the
+ *    documentation and/or other materials provided with the distribution.
+ *
+ * THIS SOFTWARE IS PROVIDED BY APPLE INC. AND ITS CONTRIBUTORS ``AS IS''
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+ * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+ * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL APPLE INC. OR ITS CONTRIBUTORS
+ * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
+ * THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+#pragma once
+
+#if ENABLE(NETWORK_CAPTURE)
+
+#include "NetworkCaptureTypes.h"
+#include <WebCore/SharedBuffer.h>
+#include <wtf/MonotonicTime.h>
+#include <wtf/Optional.h>
+#include <wtf/Variant.h>
+#include <wtf/Vector.h>
+
+namespace WebCore {
+class ResourceError;
+class ResourceRequest;
+class ResourceResponse;
+}
+
+namespace WebKit {
+namespace NetworkCapture {
+
+struct RequestSentEvent;
+struct ResponseReceivedEvent;
+struct RedirectReceivedEvent;
+struct RedirectSentEvent;
+struct DataReceivedEvent;
+struct FinishedEvent;
+
+using CaptureEvent = WTF::Variant<RequestSentEvent, ResponseReceivedEvent, RedirectReceivedEvent, RedirectSentEvent, DataReceivedEvent, FinishedEvent>;
+using OptionalCaptureEvent = std::optional<CaptureEvent>;
+using CaptureEvents = Vector<CaptureEvent>;
+using CaptureClockType = WTF::MonotonicTime;
+using CaptureTimeType = WTF::MonotonicTime;
+using KeyValuePair = std::pair<String, String>;
+using Headers = Vector<KeyValuePair>;
+
+std::string eventToString(const CaptureEvent&);
+OptionalCaptureEvent stringToEvent(const char*);
+
+struct Request {
+    // See comment for RequestSentEvent for why we need this default constructor.
+    Request()
+        : url()
+        , referrer()
+        , policy(0)
+        , method()
+        , headers() { }
+    Request(String&& url, String&& referrer, int policy, String&& method, Headers&&);
+    Request(const WebCore::ResourceRequest&);
+    operator WebCore::ResourceRequest() const;
+
+    String url;
+    String referrer;
+    int policy;
+    String method;
+    Headers headers;
+};
+static_assert(std::is_default_constructible<Request>::value, "Request is not default constructible");
+static_assert(std::is_move_constructible<Request>::value, "Request is not move constructible");
+static_assert(std::is_move_assignable<Request>::value, "Request is not move assignable");
+
+struct Response {
+    Response(String&& url, String&& mimeType, long long expectedLength, String&& textEncodingName, String&& version, int status, String&& reason, Headers&&);
+    Response(const WebCore::ResourceResponse&);
+    operator WebCore::ResourceResponse() const;
+
+    String url;
+    String mimeType;
+    long long expectedLength;
+    String textEncodingName;
+    String version;
+    int status;
+    String reason;
+    Headers headers;
+};
+static_assert(std::is_move_constructible<Response>::value, "Response is not move constructible");
+static_assert(std::is_move_assignable<Response>::value, "Response is not move assignable");
+
+struct Error {
+    Error(String&& domain, String&& failingURL, String&& localizedDescription, int errorCode, int type);
+    Error(const WebCore::ResourceError&);
+    operator WebCore::ResourceError() const;
+
+    String domain;
+    String failingURL;
+    String localizedDescription;
+    int errorCode;
+    int type;
+};
+static_assert(std::is_move_constructible<Error>::value, "Error is not move constructible");
+static_assert(std::is_move_assignable<Error>::value, "Error is not move assignable");
+
+struct TimedEvent {
+    TimedEvent()
+        : time(CaptureClockType::now()) { }
+    TimedEvent(CaptureTimeType&& time)
+        : time(WTFMove(time)) { }
+
+    CaptureTimeType time;
+};
+static_assert(std::is_move_constructible<TimedEvent>::value, "TimedEvent is not move constructible");
+static_assert(std::is_move_assignable<TimedEvent>::value, "TimedEvent is not move assignable");
+
+struct RequestSentEvent final : public TimedEvent {
+    // This default constructor is needed only because this struct is the first
+    // type passed to CaptureEvent, which is a WTF::Variant. This means that if
+    // CaptureEvent is default-constructed, it needs to default-construct an
+    // instance of RequestSentEvent, the first type on its list. If we don't
+    // have a default constructor for this type, the CaptureEvent will be
+    // created in an invalid state and will crash when destructed.
+    RequestSentEvent()
+        : TimedEvent()
+        , request() { }
+    RequestSentEvent(const WebCore::ResourceRequest& request)
+        : TimedEvent()
+        , request(request) { }
+    RequestSentEvent(CaptureTimeType&& time, Request&& request)
+        : TimedEvent(WTFMove(time))
+        , request(WTFMove(request)) { }
+
+    Request request;
+    static const char typeName[];
+};
+static_assert(std::is_default_constructible<RequestSentEvent>::value, "RequestSentEvent is not default constructible");
+static_assert(std::is_move_constructible<RequestSentEvent>::value, "RequestSentEvent is not move constructible");
+static_assert(std::is_move_assignable<RequestSentEvent>::value, "RequestSentEvent is not move assignable");
+
+struct ResponseReceivedEvent final : public TimedEvent {
+    ResponseReceivedEvent(const WebCore::ResourceResponse& response)
+        : TimedEvent()
+        , response(response) { }
+    ResponseReceivedEvent(CaptureTimeType&& time, Response&& response)
+        : TimedEvent(WTFMove(time))
+        , response(WTFMove(response)) { }
+
+    Response response;
+    static const char typeName[];
+};
+static_assert(std::is_move_constructible<ResponseReceivedEvent>::value, "ResponseReceivedEvent is not move constructible");
+static_assert(std::is_move_assignable<ResponseReceivedEvent>::value, "ResponseReceivedEvent is not move assignable");
+
+struct RedirectReceivedEvent final : public TimedEvent {
+    RedirectReceivedEvent(const WebCore::ResourceRequest& request, const WebCore::ResourceResponse& response)
+        : TimedEvent()
+        , request(request)
+        , response(response) { }
+    RedirectReceivedEvent(CaptureTimeType&& time, Request&& request, Response&& response)
+        : TimedEvent(WTFMove(time))
+        , request(WTFMove(request))
+        , response(WTFMove(response)) { }
+
+    Request request;
+    Response response;
+    static const char typeName[];
+};
+static_assert(std::is_move_constructible<RedirectReceivedEvent>::value, "RedirectReceivedEvent is not move constructible");
+static_assert(std::is_move_assignable<RedirectReceivedEvent>::value, "RedirectReceivedEvent is not move assignable");
+
+struct RedirectSentEvent final : public TimedEvent {
+    RedirectSentEvent(const WebCore::ResourceRequest& request)
+        : TimedEvent()
+        , request(request) { }
+    RedirectSentEvent(CaptureTimeType&& time, Request&& request)
+        : TimedEvent(WTFMove(time))
+        , request(WTFMove(request)) { }
+
+    Request request;
+    static const char typeName[];
+};
+static_assert(std::is_move_constructible<RedirectSentEvent>::value, "RedirectSentEvent is not move constructible");
+static_assert(std::is_move_assignable<RedirectSentEvent>::value, "RedirectSentEvent is not move assignable");
+
+struct DataReceivedEvent final : public TimedEvent {
+    DataReceivedEvent()
+        : TimedEvent()
+        , data(WebCore::SharedBuffer::create()) { }
+    DataReceivedEvent(WebCore::SharedBuffer& data)
+        : TimedEvent()
+        , data(Ref<WebCore::SharedBuffer>(data)) { }
+    DataReceivedEvent(CaptureTimeType&& time, WebCore::SharedBuffer& data)
+        : TimedEvent(WTFMove(time))
+        , data(Ref<WebCore::SharedBuffer>(data)) { }
+
+    Ref<WebCore::SharedBuffer> data;
+    static const char typeName[];
+};
+static_assert(std::is_move_constructible<DataReceivedEvent>::value, "DataReceivedEvent is not move constructible");
+static_assert(std::is_move_assignable<DataReceivedEvent>::value, "DataReceivedEvent is not move assignable");
+
+struct FinishedEvent final : public TimedEvent {
+    FinishedEvent(const WebCore::ResourceError& error)
+        : TimedEvent()
+        , error(error) { }
+    FinishedEvent(CaptureTimeType&& time, Error&& error)
+        : TimedEvent(WTFMove(time))
+        , error(WTFMove(error)) { }
+
+    Error error;
+    static const char typeName[];
+};
+static_assert(std::is_move_constructible<FinishedEvent>::value, "FinishedEvent is not move constructible");
+static_assert(std::is_move_assignable<FinishedEvent>::value, "FinishedEvent is not move assignable");
+
+} // namespace NetworkCapture
+} // namespace WebKit
+
+#endif // ENABLE(NETWORK_CAPTURE)
diff --git a/Source/WebKit2/NetworkProcess/capture/NetworkCaptureLogging.h b/Source/WebKit2/NetworkProcess/capture/NetworkCaptureLogging.h
new file mode 100644 (file)
index 0000000..3dafd6b
--- /dev/null
@@ -0,0 +1,53 @@
+/*
+ * Copyright (C) 2016 Apple Inc. All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ * 1. Redistributions of source code must retain the above copyright
+ *    notice, this list of conditions and the following disclaimer.
+ * 2. Redistributions in binary form must reproduce the above copyright
+ *    notice, this list of conditions and the following disclaimer in the
+ *    documentation and/or other materials provided with the distribution.
+ *
+ * THIS SOFTWARE IS PROVIDED BY APPLE INC. AND ITS CONTRIBUTORS ``AS IS''
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+ * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+ * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL APPLE INC. OR ITS CONTRIBUTORS
+ * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
+ * THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+#pragma once
+
+#if ENABLE(NETWORK_CAPTURE)
+
+#include "Logging.h"
+
+#define ENABLE_WTF_CAPTURE_INTERNAL_DEBUGGING 0
+#define ENABLE_WTF_VERBOSE_CAPTURE_INTERNAL_DEBUGGING 0
+
+#define DEBUG_STR(s)                    (s).ascii().data()
+
+#if ENABLE(WTF_CAPTURE_INTERNAL_DEBUGGING)
+#define DEBUG_LOG_QUOTE(str)            #str
+#define DEBUG_LOG_EXPAND_AND_QUOTE(str) DEBUG_LOG_QUOTE(str)
+#define DEBUG_LOG(format, ...)          RELEASE_LOG(Network, "#PLT: %p - %{public}s::%{public}s: " format, this, DEBUG_LOG_EXPAND_AND_QUOTE(DEBUG_CLASS), __FUNCTION__, ##__VA_ARGS__)
+#define DEBUG_LOG_ERROR(format, ...)    RELEASE_LOG_ERROR(Network, "#PLT: %p - %{public}s::%{public}s: " format, this, DEBUG_LOG_EXPAND_AND_QUOTE(DEBUG_CLASS), __FUNCTION__, ##__VA_ARGS__)
+#if ENABLE(WTF_VERBOSE_CAPTURE_INTERNAL_DEBUGGING)
+#define DEBUG_LOG_VERBOSE(format, ...)  DEBUG_LOG(format, ##__VA_ARGS__)
+#else
+#define DEBUG_LOG_VERBOSE(...)          ((void)0)
+#endif
+#else
+#define DEBUG_LOG(...)                  ((void)0)
+#define DEBUG_LOG_ERROR(...)            RELEASE_LOG_ERROR(Network, __VA_ARGS__)
+#define DEBUG_LOG_VERBOSE(...)          ((void)0)
+#endif
+
+#endif // ENABLE(NETWORK_CAPTURE)
diff --git a/Source/WebKit2/NetworkProcess/capture/NetworkCaptureManager.cpp b/Source/WebKit2/NetworkProcess/capture/NetworkCaptureManager.cpp
new file mode 100644 (file)
index 0000000..fc4874e
--- /dev/null
@@ -0,0 +1,599 @@
+/*
+ * Copyright (C) 2016 Apple Inc. All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ * 1. Redistributions of source code must retain the above copyright
+ *    notice, this list of conditions and the following disclaimer.
+ * 2. Redistributions in binary form must reproduce the above copyright
+ *    notice, this list of conditions and the following disclaimer in the
+ *    documentation and/or other materials provided with the distribution.
+ *
+ * THIS SOFTWARE IS PROVIDED BY APPLE INC. AND ITS CONTRIBUTORS ``AS IS''
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+ * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+ * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL APPLE INC. OR ITS CONTRIBUTORS
+ * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
+ * THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+#include "config.h"
+#include "NetworkCaptureManager.h"
+
+#if ENABLE(NETWORK_CAPTURE)
+
+#include "NetworkCaptureLogging.h"
+#include "NetworkCaptureResource.h"
+#include "WebCore/ResourceRequest.h"
+#include "WebCore/URL.h"
+#include <wtf/MD5.h>
+#include <wtf/text/Base64.h>
+#include <wtf/text/StringBuilder.h>
+
+#include <algorithm>
+#include <iterator>
+#include <limits>
+#include <stdarg.h>
+
+#define DEBUG_CLASS Manager
+
+namespace WebKit {
+namespace NetworkCapture {
+
+static const char* kDirNameRecordReplay = "WebKitPerf/record_replay";
+static const char* kDirNameResources = "resources";
+static const char* kFileNameReportLoad = "report_load.txt";
+static const char* kFileNameReportRecord = "report_record.txt";
+static const char* kFileNameReportReplay = "report_replay.txt";
+
+static int kMaxMatch = std::numeric_limits<int>::max();
+static int kMinMatch = std::numeric_limits<int>::min();
+
+Manager& Manager::singleton()
+{
+    static NeverDestroyed<Manager> instance;
+    return instance;
+}
+
+void Manager::initialize(const String& recordReplayMode, const String& recordReplayCacheLocation)
+{
+    DEBUG_LOG("Initializing");
+
+    if (equalIgnoringASCIICase(recordReplayMode, "record"))
+        m_recordReplayMode = Record;
+    else if (equalIgnoringASCIICase(recordReplayMode, "replay"))
+        m_recordReplayMode = Replay;
+    else
+        m_recordReplayMode = Disabled;
+
+    m_recordReplayCacheLocation = WebCore::pathByAppendingComponent(recordReplayCacheLocation, kDirNameRecordReplay);
+
+    DEBUG_LOG("Cache location = %{public}s", DEBUG_STR(m_recordReplayCacheLocation));
+
+    if (isReplaying())
+        loadResources();
+}
+
+void Manager::terminate()
+{
+    m_loadFileHandle.closeFile();
+    m_replayFileHandle.closeFile();
+    m_recordFileHandle.closeFile();
+}
+
+Resource* Manager::findMatch(const WebCore::ResourceRequest& request)
+{
+    DEBUG_LOG_VERBOSE("URL = %{public}s", DEBUG_STR(request.url().string()));
+
+    auto bestMatch = findExactMatch(request);
+    if (!bestMatch)
+        bestMatch = findBestFuzzyMatch(request);
+
+#if ENABLE(WTF_CAPTURE_INTERNAL_DEBUGGING)
+    if (!bestMatch)
+        DEBUG_LOG("Could not find match for: %{public}s", DEBUG_STR(request.url().string()));
+    else if (request.url() == bestMatch->url())
+        DEBUG_LOG("Found exact match for: %{public}s", DEBUG_STR(request.url().string()));
+    else {
+        DEBUG_LOG("Found fuzzy match for: %{public}s", DEBUG_STR(request.url().string()));
+        DEBUG_LOG("       replaced with : %{public}s", DEBUG_STR(bestMatch->url().string()));
+    }
+#endif
+
+    return bestMatch;
+}
+
+Resource* Manager::findExactMatch(const WebCore::ResourceRequest& request)
+{
+    const auto& url = request.url();
+    auto lower = std::lower_bound(std::begin(m_cachedResources), std::end(m_cachedResources), url, [](auto& resource, const auto& url) {
+        return WTF::codePointCompareLessThan(resource.url().string(), url.string());
+    });
+
+    if (lower != std::end(m_cachedResources) && lower->url() == url) {
+        DEBUG_LOG_VERBOSE("Found exact match: %{public}s", DEBUG_STR(lower->url().string()));
+        return &*lower;
+    }
+
+    return nullptr;
+}
+
+Resource* Manager::findBestFuzzyMatch(const WebCore::ResourceRequest& request)
+{
+    const auto& url = request.url();
+    Resource* bestMatch = nullptr;
+    int bestScore = kMinMatch;
+    const auto& baseURL = url.string().left(url.pathStart());
+
+    const auto& lower = std::lower_bound(std::begin(m_cachedResources), std::end(m_cachedResources), baseURL, [](auto& resource, const auto& url) {
+        return WTF::codePointCompareLessThan(resource.baseURL().string(), url);
+    });
+    const auto& upper = std::upper_bound(lower, std::end(m_cachedResources), baseURL, [](const auto& url, auto& resource) {
+        return WTF::codePointCompareLessThan(resource.baseURL().string(), url);
+    });
+
+    const auto& requestParameters = WebCore::URLParser::parseURLEncodedForm(url.query());
+    for (auto iResource = lower; iResource != upper; ++iResource) {
+        int thisScore = fuzzyMatchURLs(url, requestParameters, iResource->url(), iResource->queryParameters());
+        // TODO: Consider ignoring any matches < 0 as being too different.
+        if (bestScore < thisScore) {
+            DEBUG_LOG("New best match (%d): %{public}s", thisScore, DEBUG_STR(iResource->url().string()));
+            bestScore = thisScore;
+            bestMatch = &*iResource;
+            if (bestScore == kMaxMatch)
+                break;
+        }
+    }
+
+    return bestMatch;
+}
+
+// TODO: Convert to an interface based on ResourceRequest so that we can do
+// deeper matching.
+
+int Manager::fuzzyMatchURLs(const WebCore::URL& requestURL, const WebCore::URLParser::URLEncodedForm& requestParameters, const WebCore::URL& resourceURL, const WebCore::URLParser::URLEncodedForm& resourceParameters)
+{
+    // TODO: consider requiring that any trailing suffixes (e.g., ".js",
+    // ".png", ".css", ".html", etc.) should be an exact match.
+
+    // We do fuzzy matching on the path and query parameters. So let's first
+    // make sure that all the other parts are equal.
+
+    // If scheme, host, and port don't all match, return this as the "worst"
+    // match.
+
+    if (!protocolHostAndPortAreEqual(requestURL, resourceURL)) {
+        DEBUG_LOG("Scheme/host/port mismatch: %{public}s != %{public}s", DEBUG_STR(requestURL.string()), DEBUG_STR(resourceURL.string()));
+        return kMinMatch;
+    }
+
+    // If fragments don't match, return this as the "worst" match.
+
+    if (requestURL.fragmentIdentifier() != resourceURL.fragmentIdentifier()) {
+        DEBUG_LOG("Fragments mismatch: %{public}s != %{public}s", DEBUG_STR(requestURL.string()), DEBUG_STR(resourceURL.string()));
+        return kMinMatch;
+    }
+
+    DEBUG_LOG("Fuzzy matching:");
+    DEBUG_LOG("   : %{public}s", DEBUG_STR(requestURL.string()));
+    DEBUG_LOG("   : %{public}s", DEBUG_STR(resourceURL.string()));
+
+    // Compare the path components and the query parameters. Score each partial
+    // match as +4, each mismatch as -1, and each missing component as -1.
+    //
+    // Note that at the current time these values are rather arbitrary and
+    // could fine-tuned.
+
+    const int kPathMatchScore = 4;
+    const int kPathMismatchScore = -1;
+    const int kPathMissingScore = -1;
+    const int kParameterMatchScore = 4;
+    const int kParameterMismatchScore = -1;
+    const int kParameterMissingScore = -1;
+
+    int score = 0;
+
+    // Quantize the differences in URL paths.
+    //
+    // The approach here is to increase our score for each matching path
+    // component, and to subtract for each differing component as well as for
+    // components that exist in one path but not the other.
+
+    const auto& requestPath = requestURL.path();
+    const auto& resourcePath = resourceURL.path();
+
+    Vector<String> requestPathComponents, resourcePathComponents;
+    requestPath.split('/', requestPathComponents);
+    resourcePath.split('/', resourcePathComponents);
+
+    auto updatedIterators = std::mismatch(
+        std::begin(requestPathComponents), std::end(requestPathComponents),
+        std::begin(resourcePathComponents), std::end(resourcePathComponents));
+
+    auto matchingDistance = std::distance(std::begin(requestPathComponents), updatedIterators.first);
+    auto requestPathMismatchDistance = std::distance(updatedIterators.first, std::end(requestPathComponents));
+    auto resourcePathMismatchDistance = std::distance(updatedIterators.second, std::end(resourcePathComponents));
+    decltype(matchingDistance) mismatchingDistance;
+    decltype(matchingDistance) missingDistance;
+    if (requestPathMismatchDistance < resourcePathMismatchDistance) {
+        mismatchingDistance = requestPathMismatchDistance;
+        missingDistance = resourcePathMismatchDistance - requestPathMismatchDistance;
+    } else {
+        mismatchingDistance = resourcePathMismatchDistance;
+        missingDistance = requestPathMismatchDistance - resourcePathMismatchDistance;
+    }
+
+    DEBUG_LOG("Path matching results: matching = %d, mismatching = %d, missing = %d",
+        static_cast<int>(matchingDistance),
+        static_cast<int>(mismatchingDistance),
+        static_cast<int>(missingDistance));
+
+    score += matchingDistance * kPathMatchScore
+        + mismatchingDistance * kPathMismatchScore
+        + missingDistance * kPathMissingScore;
+    DEBUG_LOG("Score = %d", score);
+
+    // Quantize the differences in query parameters.
+    //
+    // The approach here is to walk lock-step over the two sets of query
+    // parameters. For each pair of parameters for each URL, we compare their
+    // names and values. If the names and values match, we add a high score. If
+    // just the names match, we add a lower score.
+    //
+    // If the names don't match, we then assume that some intervening query
+    // parameters have been added to one or the other URL. We therefore try to
+    // sync up the iterators used to traverse the query parameter collections
+    // so that they're again pointing to parameters with the same names. We
+    // first start scanning forward down the query parameters for one URL,
+    // looking for one with the same name as the one we're on in the other URL.
+    // If that doesn't turn up a match, we reverse the roles of the query
+    // parameters perform the same process of scanning forward. If neither of
+    // these scans produces a match, we figure that each query parameter we're
+    // looking at from each of the query parameter collections is unique. We
+    // deduct points from the overall score and move on to the next query
+    // parameters in each set.
+    //
+    // If, on the other hand, the forward-scanning does turn up a match, we
+    // adjust out iterators so that they're now again pointing to query
+    // parameters with the same name. This synchronization involves skipping
+    // over any intervening query parameters in one collection or the other.
+    // The assumption here is that these intervening query parameters are
+    // insertions that exist in one URL but not the other. We treat them as
+    // such, subtracting from the overall score for each one. However, this
+    // assumption might easily be incorrect. It might be that the query
+    // parameters that we're skipping over in one URL might exist in the other
+    // URL. If so, then we are foregoing the possibility of using those matches
+    // to increase the overall match score between the two URLs.
+    //
+    // To address this problem, we might want to consider sorting the query
+    // parameters by their names. However, doing this may cause problems if the
+    // order of the parameters is significant. So if we decide to take the
+    // approach of sorting the parameters, keep in mind this possible drawback.
+
+    auto requestParameter = std::begin(requestParameters);
+    auto resourceParameter = std::begin(resourceParameters);
+
+    for (; requestParameter != std::end(requestParameters) && resourceParameter != std::end(resourceParameters); ++requestParameter, ++resourceParameter) {
+        if (requestParameter->first == resourceParameter->first) {
+#if ENABLE(WTF_CAPTURE_INTERNAL_DEBUGGING)
+            if (requestParameter->second == resourceParameter->second)
+                DEBUG_LOG("Matching parameter names and values: \"%{public}s\" = \"%{public}s\"", DEBUG_STR(requestParameter->first), DEBUG_STR(requestParameter->second));
+            else
+                DEBUG_LOG("Mismatching parameter values: \"%{public}s\" = \"%{public}s\" vs. \"%{public}s\"", DEBUG_STR(requestParameter->first), DEBUG_STR(requestParameter->second), DEBUG_STR(resourceParameter->second));
+#endif
+            score += (requestParameter->second == resourceParameter->second) ? kParameterMatchScore : kParameterMismatchScore;
+            DEBUG_LOG("Score = %d", score);
+        } else {
+            DEBUG_LOG("Mismatching parameter names: %{public}s, %{public}s", DEBUG_STR(requestParameter->first), DEBUG_STR(resourceParameter->first));
+
+            const auto scanForwardForMatch = [this, &score, kParameterMatchScore, kParameterMismatchScore, kParameterMissingScore](const auto& fixedIter, auto& scanningIter, const auto& scannerEnd) {
+                auto scanner = scanningIter;
+                while (scanner != scannerEnd && scanner->first != fixedIter->first)
+                    ++scanner;
+                if (scanner == scannerEnd)
+                    return false;
+                DEBUG_LOG("Skipping past %d non-matching parameter names", static_cast<int>(std::distance(scanningIter, scanner)));
+                score += kParameterMissingScore * std::distance(scanningIter, scanner);
+                DEBUG_LOG("Score = %d", score);
+#if ENABLE(WTF_CAPTURE_INTERNAL_DEBUGGING)
+                if (fixedIter->second == scanner->second)
+                    DEBUG_LOG("Matching parameter names and values: \"%{public}s\" = \"%{public}s\"", DEBUG_STR(fixedIter->first), DEBUG_STR(fixedIter->second));
+                else
+                    DEBUG_LOG("Mismatching parameter values: \"%{public}s\" = \"%{public}s\" vs. \"%{public}s\"", DEBUG_STR(fixedIter->first), DEBUG_STR(fixedIter->second), DEBUG_STR(scanner->second));
+#endif
+                score += (fixedIter->second == scanner->second) ? kParameterMatchScore : kParameterMismatchScore;
+                DEBUG_LOG("Score = %d", score);
+                scanningIter = scanner;
+                return true;
+            };
+
+            if (!scanForwardForMatch(requestParameter, resourceParameter, std::end(resourceParameters))) {
+                if (!scanForwardForMatch(resourceParameter, requestParameter, std::end(requestParameters))) {
+                    DEBUG_LOG("Unmatched parameter: %{public}s=%{public}s", DEBUG_STR(requestParameter->first), DEBUG_STR(requestParameter->second));
+                    DEBUG_LOG("Unmatched parameter: %{public}s=%{public}s", DEBUG_STR(resourceParameter->first), DEBUG_STR(resourceParameter->second));
+                    score += kParameterMissingScore + kParameterMissingScore;
+                    DEBUG_LOG("Score = %d", score);
+                }
+            }
+        }
+    }
+
+    DEBUG_LOG("Adjusting for trailing parameters");
+    score += kParameterMissingScore
+        * (std::distance(requestParameter, std::end(requestParameters))
+            + std::distance(resourceParameter, std::end(resourceParameters)));
+    DEBUG_LOG("Score = %d", score);
+
+    return score;
+}
+
+void Manager::loadResources()
+{
+    auto lines = readFile(reportRecordPath());
+    if (!lines)
+        return;
+
+    for (const auto& line : *lines) {
+        if (line.size() != 2) {
+            DEBUG_LOG_ERROR("line.size == %d", (int) line.size());
+            continue;
+        }
+
+        Resource newResource(hashToPath(line[0]));
+        m_cachedResources.append(WTFMove(newResource));
+    }
+
+    std::sort(std::begin(m_cachedResources), std::end(m_cachedResources), [](auto& left, auto& right) {
+        return WTF::codePointCompareLessThan(left.url().string(), right.url().string());
+    });
+
+    for (auto& resource : m_cachedResources)
+        logLoadedResource(resource);
+}
+
+String Manager::reportLoadPath()
+{
+    return WebCore::pathByAppendingComponent(m_recordReplayCacheLocation, kFileNameReportLoad);
+}
+
+String Manager::reportRecordPath()
+{
+    return WebCore::pathByAppendingComponent(m_recordReplayCacheLocation, kFileNameReportRecord);
+}
+
+String Manager::reportReplayPath()
+{
+    return WebCore::pathByAppendingComponent(m_recordReplayCacheLocation, kFileNameReportReplay);
+}
+
+String Manager::requestToPath(const WebCore::ResourceRequest& request)
+{
+    // TODO: come up with a more comprehensive hash that includes HTTP method
+    // and possibly other values (such as headers).
+
+    const auto& hash = stringToHash(request.url().string());
+    const auto& path = hashToPath(hash);
+    return path;
+}
+
+String Manager::stringToHash(const String& s)
+{
+    WTF::MD5 md5;
+    if (s.characters8())
+        md5.addBytes(static_cast<const uint8_t*>(s.characters8()), s.length());
+    else
+        md5.addBytes(reinterpret_cast<const uint8_t*>(s.characters16()), 2 * s.length());
+
+    WTF::MD5::Digest digest;
+    md5.checksum(digest);
+
+    return WTF::base64URLEncode(&digest[0], WTF::MD5::hashSize);
+}
+
+String Manager::hashToPath(const String& hash)
+{
+    auto hashHead = hash.substring(0, 2);
+    auto hashTail = hash.substring(2);
+
+    StringBuilder fileName;
+    fileName.append(hashTail);
+    fileName.append(".data");
+
+    auto path = WebCore::pathByAppendingComponent(m_recordReplayCacheLocation, kDirNameResources);
+    path = WebCore::pathByAppendingComponent(path, hashHead);
+    path = WebCore::pathByAppendingComponent(path, fileName.toString());
+
+    return path;
+}
+
+void Manager::logRecordedResource(const WebCore::ResourceRequest& request)
+{
+    // Log network resources as they are cached to disk.
+
+    if (ensureFileHandle(reportRecordPath(), m_recordFileHandle)) {
+        const auto& url = request.url();
+        printToFile(m_recordFileHandle, "%s %s\n", DEBUG_STR(stringToHash(url.string())), DEBUG_STR(url.string()));
+    }
+}
+
+void Manager::logLoadedResource(Resource& resource)
+{
+    // Log cached resources as they are loaded from disk.
+
+    if (ensureFileHandle(reportLoadPath(), m_loadFileHandle))
+        printToFile(m_loadFileHandle, "%s\n", DEBUG_STR(resource.url().string()));
+}
+
+void Manager::logPlayedBackResource(const WebCore::ResourceRequest& request, bool wasCacheMiss)
+{
+    // Log network resources that are requested during replay.
+
+    const auto& url = request.url();
+
+    if (wasCacheMiss)
+        DEBUG_LOG("Cache miss: URL = %{public}s", DEBUG_STR(url.string()));
+    else
+        DEBUG_LOG("Cache hit:  URL = %{public}s", DEBUG_STR(url.string()));
+
+    if (ensureFileHandle(reportReplayPath(), m_replayFileHandle))
+        printToFile(m_replayFileHandle, "%s %s\n", wasCacheMiss ? "miss" : "hit ", DEBUG_STR(url.string()));
+}
+
+bool Manager::ensureFileHandle(const String& filePath, FileHandle& fileHandle)
+{
+    if (!fileHandle)
+        fileHandle = openCacheFile(filePath, WebCore::OpenForWrite);
+    return fileHandle;
+}
+
+FileHandle Manager::openCacheFile(const String& filePath, WebCore::FileOpenMode mode)
+{
+    // If we can trivially open the file, then do that and return the new file
+    // handle.
+
+    auto fileHandle = FileHandle::openFile(filePath, mode);
+    if (fileHandle)
+        return fileHandle;
+
+    // If we're opening the file for writing (including appending), then try
+    // again after making sure all intermediate directories have been created.
+
+    if (mode != WebCore::OpenForRead) {
+        const auto& parentDir = WebCore::directoryName(filePath);
+        if (!WebCore::makeAllDirectories(parentDir)) {
+            DEBUG_LOG_ERROR("Error %d trying to create intermediate directories: %{public}s", errno, DEBUG_STR(parentDir));
+            return fileHandle;
+        }
+
+        fileHandle = FileHandle::openFile(filePath, mode);
+        if (fileHandle)
+            return fileHandle;
+    }
+
+    // Could not open the file. Log the error and leave, returning the invalid
+    // file handle.
+
+    if (mode == WebCore::OpenForRead)
+        DEBUG_LOG_ERROR("Error %d trying to open %{public}s for reading", errno, DEBUG_STR(filePath));
+    else
+        DEBUG_LOG_ERROR("Error %d trying to open %{public}s for writing", errno, DEBUG_STR(filePath));
+
+    return fileHandle;
+}
+
+std::optional<Vector<Vector<String>>> Manager::readFile(const String& filePath)
+{
+    bool success = false;
+    WebCore::MappedFileData file(filePath, success);
+    if (!success)
+        return std::nullopt;
+
+    Vector<Vector<String>> lines;
+    auto begin = static_cast<const uint8_t*>(file.data());
+    auto end = begin + file.size();
+
+    Vector<String> line;
+    while (getLine(begin, end, line))
+        lines.append(WTFMove(line));
+
+    return WTFMove(lines);
+}
+
+bool Manager::getLine(uint8_t const *& p, uint8_t const * const end, Vector<String>& line)
+{
+    // NB: Returns true if there may be more data to get, false if we've hit
+    // the end of the buffer.
+
+    DEBUG_LOG_VERBOSE("Getting a line");
+
+    line.clear();
+
+    if (p == end) {
+        DEBUG_LOG_VERBOSE("Iterator at end; returning false");
+        return false;
+    }
+
+    String word;
+    while (getWord(p, end, word)) {
+        if (!word.isEmpty()) {
+            DEBUG_LOG_VERBOSE("Adding word: %{public}s", DEBUG_STR(word));
+            line.append(word);
+        }
+    }
+
+    return true;
+}
+
+bool Manager::getWord(uint8_t const *& p, uint8_t const * const end, String& word)
+{
+    // NB: Returns true if a (possibly empty) word was found and there may be
+    // more, false if we've hit the end of line or buffer.
+
+    DEBUG_LOG_VERBOSE("Getting a word");
+
+    if (p == end) {
+        DEBUG_LOG_VERBOSE("Iterator at end; returning false");
+        return false;
+    }
+
+    if (*p == '\n') {
+        DEBUG_LOG_VERBOSE("Iterator hit EOL; returning false");
+        ++p;
+        return false;
+    }
+
+    bool escaping = false;
+    bool ignoring = false;
+
+    word = String();
+
+    DEBUG_LOG_VERBOSE("Iterating");
+
+    for ( ; p != end; ++p) {
+        if (ignoring) {
+            if (*p == '\n')
+                break;
+        } else if (escaping) {
+            word.append(*p);
+            escaping = false;
+        } else if (*p == '#') {
+            ignoring = true;
+        } else if (*p == '\\') {
+            escaping = true;
+        } else if (*p == ' ') {
+            if (!word.isEmpty())
+                break;
+        } else if (*p == '\n')
+            break;
+        else
+            word.append(*p);
+    }
+
+    return true;
+}
+
+bool Manager::printToFile(const FileHandle& fileHandle, const char* format, ...)
+{
+    va_list args;
+    va_start(args, format);
+
+    char* buffer = nullptr;
+    vasprintf(&buffer, format, args);
+    auto writeResult = fileHandle.writeToFile(buffer, strlen(buffer));
+    free(buffer);
+
+    va_end(args);
+
+    return writeResult >= 0;
+}
+
+} // namespace NetworkCapture
+} // namespace WebKit
+
+#endif // ENABLE(NETWORK_CAPTURE)
diff --git a/Source/WebKit2/NetworkProcess/capture/NetworkCaptureManager.h b/Source/WebKit2/NetworkProcess/capture/NetworkCaptureManager.h
new file mode 100644 (file)
index 0000000..269ae24
--- /dev/null
@@ -0,0 +1,124 @@
+/*
+ * Copyright (C) 2016 Apple Inc. All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ * 1. Redistributions of source code must retain the above copyright
+ *    notice, this list of conditions and the following disclaimer.
+ * 2. Redistributions in binary form must reproduce the above copyright
+ *    notice, this list of conditions and the following disclaimer in the
+ *    documentation and/or other materials provided with the distribution.
+ *
+ * THIS SOFTWARE IS PROVIDED BY APPLE INC. AND ITS CONTRIBUTORS ``AS IS''
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+ * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+ * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL APPLE INC. OR ITS CONTRIBUTORS
+ * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
+ * THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+#pragma once
+
+#if ENABLE(NETWORK_CAPTURE)
+
+#include "NetworkCaptureTypes.h"
+#include <WebCore/FileSystem.h>
+#include <WebCore/URLParser.h>
+#include <wtf/Function.h>
+#include <wtf/NeverDestroyed.h>
+#include <wtf/Vector.h>
+#include <wtf/text/WTFString.h>
+
+namespace WebCore {
+class ResourceRequest;
+}
+
+namespace WebKit {
+namespace NetworkCapture {
+
+class Resource;
+
+/*
+ * NetworkCapture::Manager serves three purposes:
+ *
+ *  * It keeps the state of whether we are recording, replaying, or neither.
+ *  * It keeps the list of cached resources (if replaying), performs fuzzy
+ *    matching on them.
+ *  * It has utilities for logging and file management.
+ *
+ * TODO: Perhaps we should break this up into three classes?
+ */
+class Manager {
+    WTF_MAKE_NONCOPYABLE(Manager);
+    friend class WTF::NeverDestroyed<Manager>;
+
+public:
+    enum RecordReplayMode {
+        Disabled,
+        Record,
+        Replay
+    };
+
+    static Manager& singleton();
+
+    void initialize(const String& recordReplayMode, const String& recordReplayCacheLocation);
+    void terminate();
+
+    bool isRecording() const { return mode() == RecordReplayMode::Record; }
+    bool isReplaying() const { return mode() == RecordReplayMode::Replay; }
+    RecordReplayMode mode() const { return m_recordReplayMode; }
+
+    Resource* findMatch(const WebCore::ResourceRequest&);
+
+    void logRecordedResource(const WebCore::ResourceRequest&);
+    void logLoadedResource(Resource&);
+    void logPlayedBackResource(const WebCore::ResourceRequest&, bool wasCacheMiss);
+
+    FileHandle openCacheFile(const String&, WebCore::FileOpenMode);
+
+    String requestToPath(const WebCore::ResourceRequest&);
+
+private:
+    Manager() = default;
+    ~Manager() = delete;
+
+    Resource* findExactMatch(const WebCore::ResourceRequest&);
+    Resource* findBestFuzzyMatch(const WebCore::ResourceRequest&);
+    int fuzzyMatchURLs(const WebCore::URL& requestURL, const WebCore::URLParser::URLEncodedForm& requestParameters, const WebCore::URL& resourceURL, const WebCore::URLParser::URLEncodedForm& resourceParameters);
+
+    void loadResources();
+
+    String reportLoadPath();
+    String reportRecordPath();
+    String reportReplayPath();
+
+    String stringToHash(const String&);
+    String hashToPath(const String& hash);
+
+    bool ensureFileHandle(const String& filePath, FileHandle&);
+
+    std::optional<Vector<Vector<String>>> readFile(const String& filePath);
+    bool getLine(uint8_t const *& p, uint8_t const * const end, Vector<String>& line);
+    bool getWord(uint8_t const *& p, uint8_t const * const end, String& word);
+    bool printToFile(const FileHandle&, const char* format, ...);
+
+    RecordReplayMode m_recordReplayMode { Disabled };
+    String m_recordReplayCacheLocation;
+
+    FileHandle m_loadFileHandle;
+    FileHandle m_replayFileHandle;
+    FileHandle m_recordFileHandle;
+
+    Vector<Resource> m_cachedResources;
+};
+
+} // namespace NetworkCapture
+} // namespace WebKit
+
+#endif // ENABLE(NETWORK_CAPTURE)
diff --git a/Source/WebKit2/NetworkProcess/capture/NetworkCaptureRecorder.cpp b/Source/WebKit2/NetworkProcess/capture/NetworkCaptureRecorder.cpp
new file mode 100644 (file)
index 0000000..b6c1c52
--- /dev/null
@@ -0,0 +1,156 @@
+/*
+ * Copyright (C) 2016 Apple Inc. All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ * 1. Redistributions of source code must retain the above copyright
+ *    notice, this list of conditions and the following disclaimer.
+ * 2. Redistributions in binary form must reproduce the above copyright
+ *    notice, this list of conditions and the following disclaimer in the
+ *    documentation and/or other materials provided with the distribution.
+ *
+ * THIS SOFTWARE IS PROVIDED BY APPLE INC. AND ITS CONTRIBUTORS ``AS IS''
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+ * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+ * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL APPLE INC. OR ITS CONTRIBUTORS
+ * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
+ * THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+#include "config.h"
+#include "NetworkCaptureRecorder.h"
+
+#if ENABLE(NETWORK_CAPTURE)
+
+#include "NetworkCaptureLogging.h"
+#include "NetworkCaptureManager.h"
+#include <WebCore/ResourceResponse.h>
+#include <WebCore/SharedBuffer.h>
+
+#define DEBUG_CLASS Manager
+
+namespace WebKit {
+namespace NetworkCapture {
+
+void Recorder::recordRequestSent(const WebCore::ResourceRequest& request)
+{
+    // This class records NetworkLoad's process of loading a network resource.
+    // NetworkLoad does this by creating a NetworkDataTask and calling resume
+    // on it. This call to resume can be called immediately after the task has
+    // been created, or -- if the loading is marked as deferred -- it can be
+    // called later in NetworkLoad::setDeferred(true). In fact, the latter can
+    // be called multiple times if the loading is suspended and resumed
+    // multiple times.
+    //
+    // This method is called in both places where resume is called. Our task is
+    // to catch the call to NetworkDataTask::resume that starts the network
+    // loading process. We want to ignore the other calls to resume. Our
+    // approach to knowing which one is the first is to check our collection of
+    // recorded events. If it is empty, then this is the first call into the
+    // recorder, and we want to record the event. Otherwise, ignore it.
+
+    if (m_events.size())
+        return;
+
+    DEBUG_LOG("Sent request for URL = %{public}s", DEBUG_STR(request.url().string()));
+
+    m_initialRequest = request;
+    recordEvent(RequestSentEvent(request));
+}
+
+void Recorder::recordResponseReceived(const WebCore::ResourceResponse& response)
+{
+    // Called when receiving a response other than a redirect or error.
+
+    DEBUG_LOG("Received response from URL = %{public}s", DEBUG_STR(response.url().string()));
+    ASSERT(m_events.size());
+
+    // TODO: Is there a better response to receiving a multi-part resource?
+    // Learn more about multi-part resources. Why don't we record these? (Note,
+    // this decision is based on some NetworkCache code.)
+
+    if (!response.isMultipart())
+        recordEvent(ResponseReceivedEvent(response));
+    else
+        m_events.clear();
+}
+
+void Recorder::recordRedirectReceived(const WebCore::ResourceRequest& request, const WebCore::ResourceResponse& response)
+{
+    DEBUG_LOG("Received redirect to URL = %{public}s", DEBUG_STR(request.url().string()));
+    ASSERT(m_events.size());
+
+    recordEvent(RedirectReceivedEvent(request, response));
+}
+
+void Recorder::recordRedirectSent(const WebCore::ResourceRequest& request)
+{
+    DEBUG_LOG("Sent redirect for URL = %{public}s", DEBUG_STR(request.url().string()));
+    ASSERT(m_events.size());
+
+    recordEvent(RedirectSentEvent(request));
+}
+
+void Recorder::recordDataReceived(WebCore::SharedBuffer& buffer)
+{
+    DEBUG_LOG("Received %u bytes of data", buffer.size());
+
+    if (!m_events.size())
+        return;
+
+    // Prevent memory growth in case of streaming data. TODO: Is there a better
+    // response to this? If we encounter this condition, all of our recording
+    // silently goes out the window. Replay will not work, and the user doesn't
+    // know that.
+
+    constexpr size_t kMaximumCacheBufferSize = 10 * 1024 * 1024;
+    m_dataLength += buffer.size();
+    if (m_dataLength <= kMaximumCacheBufferSize)
+        recordEvent(DataReceivedEvent(buffer));
+    else
+        m_events.clear();
+}
+
+void Recorder::recordFinish(const WebCore::ResourceError& error)
+{
+    DEBUG_LOG("Finished");
+
+    if (!m_events.size())
+        return;
+
+    recordEvent(FinishedEvent(error));
+    writeEvents();
+}
+
+void Recorder::writeEvents()
+{
+    auto path = Manager::singleton().requestToPath(m_initialRequest);
+    auto handle = Manager::singleton().openCacheFile(path, WebCore::OpenForWrite);
+    if (!handle)
+        return;
+
+    for (auto const& event : m_events) {
+        auto asString = eventToString(event);
+        // Write out the JSON string with the terminating NUL. This allows us
+        // to better find the separate JSON objects that we write to a single
+        // file. It also works better with JSON parsers that expect to find a
+        // NUL at the end of their input.
+        if (handle.writeToFile(asString.c_str(), asString.size() + 1) == -1) {
+            DEBUG_LOG_ERROR("Error trying to write to file for URL = %{public}s", DEBUG_STR(m_initialRequest.url().string()));
+            return;
+        }
+    }
+
+    Manager::singleton().logRecordedResource(m_initialRequest);
+}
+
+} // namespace NetworkCapture
+} // namespace WebKit
+
+#endif // ENABLE(NETWORK_CAPTURE)
diff --git a/Source/WebKit2/NetworkProcess/capture/NetworkCaptureRecorder.h b/Source/WebKit2/NetworkProcess/capture/NetworkCaptureRecorder.h
new file mode 100644 (file)
index 0000000..8fd5313
--- /dev/null
@@ -0,0 +1,68 @@
+/*
+ * Copyright (C) 2016 Apple Inc. All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ * 1. Redistributions of source code must retain the above copyright
+ *    notice, this list of conditions and the following disclaimer.
+ * 2. Redistributions in binary form must reproduce the above copyright
+ *    notice, this list of conditions and the following disclaimer in the
+ *    documentation and/or other materials provided with the distribution.
+ *
+ * THIS SOFTWARE IS PROVIDED BY APPLE INC. AND ITS CONTRIBUTORS ``AS IS''
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+ * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+ * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL APPLE INC. OR ITS CONTRIBUTORS
+ * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
+ * THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+#pragma once
+
+#if ENABLE(NETWORK_CAPTURE)
+
+#include "NetworkCaptureEvent.h"
+#include <WebCore/ResourceRequest.h>
+
+namespace WebCore {
+class ResourceError;
+class ResourceResponse;
+class SharedBuffer;
+}
+
+namespace WebKit {
+namespace NetworkCapture {
+
+class Recorder {
+public:
+    void recordRequestSent(const WebCore::ResourceRequest&);
+    void recordResponseReceived(const WebCore::ResourceResponse&);
+    void recordRedirectReceived(const WebCore::ResourceRequest&, const WebCore::ResourceResponse&);
+    void recordRedirectSent(const WebCore::ResourceRequest&);
+    void recordDataReceived(WebCore::SharedBuffer&);
+    void recordFinish(const WebCore::ResourceError&);
+
+private:
+    void writeEvents();
+
+    template <typename T>
+    void recordEvent(T&& event)
+    {
+        m_events.append(CaptureEvent(WTFMove(event)));
+    }
+
+    CaptureEvents m_events;
+    WebCore::ResourceRequest m_initialRequest;
+    size_t m_dataLength { 0 };
+};
+
+} // namespace NetworkCapture
+} // namespace WebKit
+
+#endif // ENABLE(NETWORK_CAPTURE)
diff --git a/Source/WebKit2/NetworkProcess/capture/NetworkCaptureReplayer.cpp b/Source/WebKit2/NetworkProcess/capture/NetworkCaptureReplayer.cpp
new file mode 100644 (file)
index 0000000..a04af69
--- /dev/null
@@ -0,0 +1,51 @@
+/*
+ * Copyright (C) 2016 Apple Inc. All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ * 1. Redistributions of source code must retain the above copyright
+ *    notice, this list of conditions and the following disclaimer.
+ * 2. Redistributions in binary form must reproduce the above copyright
+ *    notice, this list of conditions and the following disclaimer in the
+ *    documentation and/or other materials provided with the distribution.
+ *
+ * THIS SOFTWARE IS PROVIDED BY APPLE INC. AND ITS CONTRIBUTORS ``AS IS''
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+ * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+ * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL APPLE INC. OR ITS CONTRIBUTORS
+ * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
+ * THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+#include "config.h"
+#include "NetworkCaptureReplayer.h"
+
+#if ENABLE(NETWORK_CAPTURE)
+
+#include "NetworkCaptureLogging.h"
+#include "NetworkCaptureManager.h"
+#include "NetworkDataTaskReplay.h"
+#include "NetworkLoadParameters.h"
+
+#define DEBUG_CLASS Replayer
+
+namespace WebKit {
+namespace NetworkCapture {
+
+Ref<NetworkDataTask> Replayer::replayResource(NetworkSession& session, NetworkDataTaskClient& client, const NetworkLoadParameters& parameters)
+{
+    auto foundResource = Manager::singleton().findMatch(parameters.request);
+    Manager::singleton().logPlayedBackResource(parameters.request, !foundResource);
+    return NetworkDataTaskReplay::create(session, client, parameters, foundResource);
+}
+
+} // namespace NetworkCapture
+} // namespace WebKit
+
+#endif // ENABLE(NETWORK_CAPTURE)
diff --git a/Source/WebKit2/NetworkProcess/capture/NetworkCaptureReplayer.h b/Source/WebKit2/NetworkProcess/capture/NetworkCaptureReplayer.h
new file mode 100644 (file)
index 0000000..087ec50
--- /dev/null
@@ -0,0 +1,50 @@
+/*
+ * Copyright (C) 2016 Apple Inc. All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ * 1. Redistributions of source code must retain the above copyright
+ *    notice, this list of conditions and the following disclaimer.
+ * 2. Redistributions in binary form must reproduce the above copyright
+ *    notice, this list of conditions and the following disclaimer in the
+ *    documentation and/or other materials provided with the distribution.
+ *
+ * THIS SOFTWARE IS PROVIDED BY APPLE INC. AND ITS CONTRIBUTORS ``AS IS''
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+ * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+ * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL APPLE INC. OR ITS CONTRIBUTORS
+ * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
+ * THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+#pragma once
+
+#if ENABLE(NETWORK_CAPTURE)
+
+#include <wtf/Ref.h>
+
+namespace WebKit {
+class NetworkDataTask;
+class NetworkDataTaskClient;
+class NetworkLoadParameters;
+class NetworkSession;
+}
+
+namespace WebKit {
+namespace NetworkCapture {
+
+class Replayer {
+public:
+    Ref<NetworkDataTask> replayResource(NetworkSession&, NetworkDataTaskClient&, const NetworkLoadParameters&);
+};
+
+} // namespace NetworkCapture
+} // namespace WebKit
+
+#endif // ENABLE(NETWORK_CAPTURE)
diff --git a/Source/WebKit2/NetworkProcess/capture/NetworkCaptureResource.cpp b/Source/WebKit2/NetworkProcess/capture/NetworkCaptureResource.cpp
new file mode 100644 (file)
index 0000000..e6207d9
--- /dev/null
@@ -0,0 +1,119 @@
+/*
+ * Copyright (C) 2016 Apple Inc. All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ * 1. Redistributions of source code must retain the above copyright
+ *    notice, this list of conditions and the following disclaimer.
+ * 2. Redistributions in binary form must reproduce the above copyright
+ *    notice, this list of conditions and the following disclaimer in the
+ *    documentation and/or other materials provided with the distribution.
+ *
+ * THIS SOFTWARE IS PROVIDED BY APPLE INC. AND ITS CONTRIBUTORS ``AS IS''
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+ * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+ * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL APPLE INC. OR ITS CONTRIBUTORS
+ * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
+ * THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+#include "config.h"
+#include "NetworkCaptureResource.h"
+
+#if ENABLE(NETWORK_CAPTURE)
+
+#include "NetworkCaptureEvent.h"
+#include "NetworkCaptureLogging.h"
+#include "NetworkCaptureRecorder.h"
+
+namespace WebKit {
+namespace NetworkCapture {
+
+Resource::Resource(const String& eventFilePath)
+    : m_eventFilePath(eventFilePath)
+{
+}
+
+const WebCore::URL& Resource::url()
+{
+    if (!m_url) {
+        auto events = eventStream();
+        auto event = events.nextEvent();
+        if (!event)
+            DEBUG_LOG_ERROR("Event stream does not contain events: file = %{public}s", DEBUG_STR(m_eventFilePath));
+        else if (!WTF::holds_alternative<RequestSentEvent>(*event))
+            DEBUG_LOG_ERROR("Event stream does not have a requestSent event: file = %{public}s", DEBUG_STR(m_eventFilePath));
+        else {
+            auto requestSentEvent = WTF::get<RequestSentEvent>(*event);
+            WebCore::URLParser parser(requestSentEvent.request.url);
+            m_url = parser.result();
+        }
+    }
+
+    return *m_url;
+}
+
+const WebCore::URL& Resource::baseURL()
+{
+    if (!m_baseURL) {
+        auto pathStart = url().pathStart();
+        auto baseURLStr = url().string().left(pathStart);
+        WebCore::URLParser parser(baseURLStr);
+        m_baseURL = parser.result();
+    }
+
+    return *m_baseURL;
+}
+
+WebCore::URLParser::URLEncodedForm Resource::queryParameters()
+{
+    if (!m_queryParameters)
+        m_queryParameters = WebCore::URLParser::parseURLEncodedForm(url().query());
+
+    return *m_queryParameters;
+}
+
+Resource::EventStream Resource::eventStream()
+{
+    return EventStream(m_eventFilePath);
+}
+
+Resource::EventStream::EventStream(const String& eventFilePath)
+    : m_eventFilePath(eventFilePath)
+    , m_mappedEventFile(m_eventFilePath, m_haveMappedEventFile)
+{
+}
+
+OptionalCaptureEvent Resource::EventStream::nextEvent()
+{
+    if (m_offset == m_mappedEventFile.size()) {
+        DEBUG_LOG_ERROR("Unable to return event - at end of file: %{public}s", DEBUG_STR(m_eventFilePath));
+        return std::nullopt;
+    }
+
+    const char* charBuffer = static_cast<const char*>(m_mappedEventFile.data());
+    const char* current = charBuffer + m_offset;
+
+    while (m_offset < m_mappedEventFile.size() && charBuffer[m_offset])
+        ++m_offset;
+
+    if (m_offset == m_mappedEventFile.size()) {
+        DEBUG_LOG_ERROR("Unable to return event - no terminating NUL: %{public}s", DEBUG_STR(m_eventFilePath));
+        return std::nullopt;
+    }
+
+    ++m_offset;
+
+    return stringToEvent(current);
+}
+
+} // namespace NetworkCapture
+} // namespace WebKit
+
+#endif // ENABLE(NETWORK_CAPTURE)
diff --git a/Source/WebKit2/NetworkProcess/capture/NetworkCaptureResource.h b/Source/WebKit2/NetworkProcess/capture/NetworkCaptureResource.h
new file mode 100644 (file)
index 0000000..99cd620
--- /dev/null
@@ -0,0 +1,73 @@
+/*
+ * Copyright (C) 2016 Apple Inc. All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ * 1. Redistributions of source code must retain the above copyright
+ *    notice, this list of conditions and the following disclaimer.
+ * 2. Redistributions in binary form must reproduce the above copyright
+ *    notice, this list of conditions and the following disclaimer in the
+ *    documentation and/or other materials provided with the distribution.
+ *
+ * THIS SOFTWARE IS PROVIDED BY APPLE INC. AND ITS CONTRIBUTORS ``AS IS''
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+ * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+ * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL APPLE INC. OR ITS CONTRIBUTORS
+ * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
+ * THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+#pragma once
+
+#if ENABLE(NETWORK_CAPTURE)
+
+#include "NetworkCaptureEvent.h"
+#include <WebCore/FileSystem.h>
+#include <WebCore/URL.h>
+#include <WebCore/URLParser.h>
+#include <wtf/Optional.h>
+
+namespace WebKit {
+namespace NetworkCapture {
+
+class Resource {
+public:
+    class EventStream {
+    public:
+        EventStream() = default;
+        EventStream(const String& eventFilePath);
+
+        OptionalCaptureEvent nextEvent();
+
+    private:
+        String m_eventFilePath;
+        bool m_haveMappedEventFile { false };
+        WebCore::MappedFileData m_mappedEventFile;
+        size_t m_offset { 0 };
+    };
+
+public:
+    Resource(const String& eventFilePath);
+
+    const WebCore::URL& url();
+    const WebCore::URL& baseURL();
+    WebCore::URLParser::URLEncodedForm queryParameters();
+    EventStream eventStream();
+
+private:
+    String m_eventFilePath;
+    std::optional<WebCore::URL> m_url;
+    std::optional<WebCore::URL> m_baseURL;
+    std::optional<WebCore::URLParser::URLEncodedForm> m_queryParameters;
+};
+
+} // namespace NetworkCapture
+} // namespace WebKit
+
+#endif // ENABLE(NETWORK_CAPTURE)
diff --git a/Source/WebKit2/NetworkProcess/capture/NetworkCaptureTypes.h b/Source/WebKit2/NetworkProcess/capture/NetworkCaptureTypes.h
new file mode 100644 (file)
index 0000000..396c164
--- /dev/null
@@ -0,0 +1,97 @@
+/*
+ * Copyright (C) 2016 Apple Inc. All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ * 1. Redistributions of source code must retain the above copyright
+ *    notice, this list of conditions and the following disclaimer.
+ * 2. Redistributions in binary form must reproduce the above copyright
+ *    notice, this list of conditions and the following disclaimer in the
+ *    documentation and/or other materials provided with the distribution.
+ *
+ * THIS SOFTWARE IS PROVIDED BY APPLE INC. AND ITS CONTRIBUTORS ``AS IS''
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+ * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+ * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL APPLE INC. OR ITS CONTRIBUTORS
+ * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
+ * THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+#pragma once
+
+#if ENABLE(NETWORK_CAPTURE)
+
+#include <WebCore/FileSystem.h>
+
+namespace WebKit {
+namespace NetworkCapture {
+
+class FileHandle final {
+public:
+    FileHandle() = default;
+
+    FileHandle(WebCore::PlatformFileHandle fileHandle)
+        : m_fileHandle(fileHandle) { }
+
+    FileHandle(FileHandle&& other)
+        : m_fileHandle(std::exchange(other.m_fileHandle, WebCore::invalidPlatformFileHandle)) { }
+
+    ~FileHandle()
+    {
+        closeFile();
+    }
+
+    FileHandle& operator=(WebCore::PlatformFileHandle fileHandle)
+    {
+        closeFile();
+        m_fileHandle = fileHandle;
+        return *this;
+    }
+
+    FileHandle& operator=(FileHandle&& other)
+    {
+        closeFile();
+        m_fileHandle = std::exchange(other.m_fileHandle, WebCore::invalidPlatformFileHandle);
+        return *this;
+    }
+
+    FileHandle(const FileHandle&) = delete;
+    FileHandle& operator=(const FileHandle&) = delete;
+
+    operator WebCore::PlatformFileHandle() const { return m_fileHandle; }
+    explicit operator bool() const { return WebCore::isHandleValid(m_fileHandle); }
+
+    static FileHandle openFile(const String& path, WebCore::FileOpenMode mode)
+    {
+        return FileHandle(WebCore::openFile(path, mode));
+    }
+
+    int readFromFile(void* data, int length) const
+    {
+        return WebCore::readFromFile(m_fileHandle, static_cast<char*>(data), length);
+    }
+
+    int writeToFile(const void* data, int length) const
+    {
+        return WebCore::writeToFile(m_fileHandle, static_cast<const char*>(data), length);
+    }
+
+    void closeFile()
+    {
+        WebCore::closeFile(m_fileHandle);
+    }
+
+private:
+    WebCore::PlatformFileHandle m_fileHandle { WebCore::invalidPlatformFileHandle };
+};
+
+} // namespace NetworkCapture
+} // namespace WebKit
+
+#endif // ENABLE(NETWORK_CAPTURE)
diff --git a/Source/WebKit2/NetworkProcess/capture/NetworkDataTaskReplay.cpp b/Source/WebKit2/NetworkProcess/capture/NetworkDataTaskReplay.cpp
new file mode 100644 (file)
index 0000000..8b35c81
--- /dev/null
@@ -0,0 +1,288 @@
+/*
+ * Copyright (C) 2016 Apple Inc. All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ * 1. Redistributions of source code must retain the above copyright
+ *    notice, this list of conditions and the following disclaimer.
+ * 2. Redistributions in binary form must reproduce the above copyright
+ *    notice, this list of conditions and the following disclaimer in the
+ *    documentation and/or other materials provided with the distribution.
+ *
+ * THIS SOFTWARE IS PROVIDED BY APPLE INC. AND ITS CONTRIBUTORS ``AS IS''
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+ * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+ * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL APPLE INC. OR ITS CONTRIBUTORS
+ * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
+ * THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+#include "config.h"
+#include "NetworkDataTaskReplay.h"
+
+#if ENABLE(NETWORK_CAPTURE)
+
+#include "NetworkCaptureEvent.h"
+#include "NetworkCaptureLogging.h"
+#include "NetworkCaptureResource.h"
+#include "NetworkLoadParameters.h"
+#include "NetworkSession.h"
+#include <WebCore/ResourceError.h>
+#include <WebCore/ResourceRequest.h>
+#include <WebCore/ResourceResponse.h>
+#include <wtf/RunLoop.h>
+
+#define DEBUG_CLASS NetworkDataTaskReplay
+
+namespace WebKit {
+namespace NetworkCapture {
+
+static const char* const webKitRelayDomain = "WebKitReplay";
+
+NetworkDataTaskReplay::NetworkDataTaskReplay(NetworkSession& session, NetworkDataTaskClient& client, const NetworkLoadParameters& parameters, Resource* resource)
+    : NetworkDataTask(session, client, parameters.request, parameters.allowStoredCredentials, parameters.shouldClearReferrerOnHTTPSToHTTPRedirect)
+    , m_currentRequest(m_firstRequest)
+    , m_resource(resource)
+{
+    DEBUG_LOG("request URL = %{public}s", DEBUG_STR(m_firstRequest.url().string()));
+    DEBUG_LOG("cached URL = %{public}s", resource ? DEBUG_STR(resource->url().string()) : "<not found>");
+
+    m_session->registerNetworkDataTask(*this);
+
+    if (resource)
+        m_eventStream = resource->eventStream();
+}
+
+NetworkDataTaskReplay::~NetworkDataTaskReplay()
+{
+    DEBUG_LOG("URL = %{public}s", DEBUG_STR(m_firstRequest.url().string()));
+
+    m_session->unregisterNetworkDataTask(*this);
+}
+
+void NetworkDataTaskReplay::resume()
+{
+    DEBUG_LOG("URL = %{public}s", DEBUG_STR(m_firstRequest.url().string()));
+
+    if (m_state == State::Canceling || m_state == State::Completed)
+        return;
+
+    m_state = State::Running;
+
+    if (m_scheduledFailureType != NoFailure) {
+        ASSERT(m_failureTimer.isActive());
+        return;
+    }
+
+    enqueueEventHandler();
+}
+
+void NetworkDataTaskReplay::suspend()
+{
+    DEBUG_LOG("URL = %{public}s", DEBUG_STR(m_firstRequest.url().string()));
+
+    if (m_state == State::Canceling || m_state == State::Completed)
+        return;
+
+    m_state = State::Suspended;
+}
+
+void NetworkDataTaskReplay::cancel()
+{
+    DEBUG_LOG("");
+
+    if (m_state == State::Canceling || m_state == State::Completed)
+        return;
+
+    m_state = State::Canceling;
+}
+
+void NetworkDataTaskReplay::complete()
+{
+    DEBUG_LOG("URL = %{public}s", DEBUG_STR(m_firstRequest.url().string()));
+
+    if (m_state == State::Completed)
+        return;
+
+    m_state = State::Completed;
+    m_resource = nullptr;
+}
+
+void NetworkDataTaskReplay::invalidateAndCancel()
+{
+    DEBUG_LOG("URL = %{public}s", DEBUG_STR(m_firstRequest.url().string()));
+
+    cancel();
+    complete();
+}
+
+void NetworkDataTaskReplay::enqueueEventHandler()
+{
+    DEBUG_LOG("URL = %{public}s", DEBUG_STR(m_firstRequest.url().string()));
+
+    RunLoop::main().dispatch([this, protectedThis = makeRef(*this)] {
+        DEBUG_LOG("enqueueEventHandler callback");
+
+        if (m_state == State::Suspended)
+            return;
+
+        if (m_state == State::Canceling || m_state == State::Completed || !m_client) {
+            complete();
+            return;
+        }
+
+        if (!m_resource) {
+            DEBUG_LOG_ERROR("Error loading resource: could not find cached resource, URL = %{public}s", DEBUG_STR(m_currentRequest.url().string()));
+            didFinish(Error::NotFoundError); // TODO: Turn this into a 404?
+            return;
+        }
+
+        if (!equalLettersIgnoringASCIICase(m_currentRequest.httpMethod(), "get")) {
+            DEBUG_LOG_ERROR("Error loading resource: unsupported method (%{public}s), URL = %{public}s", DEBUG_STR(m_currentRequest.httpMethod()), DEBUG_STR(m_currentRequest.url().string()));
+            didFinish(Error::MethodNotAllowed);
+            return;
+        }
+
+        auto event = m_eventStream.nextEvent();
+        if (!event) {
+            DEBUG_LOG_ERROR("Error loading resource: nextEvent return null, URL = %{public}s", DEBUG_STR(m_currentRequest.url().string()));
+            didFinish(Error::NotFoundError); // TODO: Turn this into a 404?
+            return;
+        }
+
+        const auto visitor = WTF::makeVisitor(
+            [this](const RequestSentEvent& event) {
+                replayRequestSent(event);
+            },
+            [this](const ResponseReceivedEvent& event) {
+                replayResponseReceived(event);
+            },
+            [this](const RedirectReceivedEvent& event) {
+                replayRedirectReceived(event);
+            },
+            [this](const RedirectSentEvent& event) {
+                replayRedirectSent(event);
+            },
+            [this](const DataReceivedEvent& event) {
+                replayDataReceived(event);
+            },
+            [this](const FinishedEvent& event) {
+                replayFinished(event);
+            });
+
+        WTF::visit(visitor, *event);
+    });
+}
+
+void NetworkDataTaskReplay::replayRequestSent(const RequestSentEvent& event)
+{
+    DEBUG_LOG("URL = %{public}s", DEBUG_STR(m_firstRequest.url().string()));
+
+    enqueueEventHandler();
+}
+
+void NetworkDataTaskReplay::replayResponseReceived(const ResponseReceivedEvent& event)
+{
+    DEBUG_LOG("URL = %{public}s", DEBUG_STR(m_firstRequest.url().string()));
+
+    WebCore::ResourceResponse response(event.response);
+    didReceiveResponse(WTFMove(response));
+}
+
+void NetworkDataTaskReplay::replayRedirectReceived(const RedirectReceivedEvent& event)
+{
+    DEBUG_LOG("URL = %{public}s", DEBUG_STR(m_firstRequest.url().string()));
+
+    WebCore::ResourceResponse receivedResponse = event.response;
+    WebCore::ResourceRequest receivedRequest = event.request;
+
+    ASSERT(m_client);
+    m_client->willPerformHTTPRedirection(WTFMove(receivedResponse), WTFMove(receivedRequest), [this, protectedThis = makeRef(*this)] (const WebCore::ResourceRequest& updatedRequest) {
+        DEBUG_LOG("replayRedirectReceived callback: URL = %{public}s", DEBUG_STR(m_firstRequest.url().string()));
+
+        m_currentRequest = updatedRequest;
+        enqueueEventHandler();
+    });
+}
+
+void NetworkDataTaskReplay::replayRedirectSent(const RedirectSentEvent& event)
+{
+    DEBUG_LOG("URL = %{public}s", DEBUG_STR(m_firstRequest.url().string()));
+
+    enqueueEventHandler();
+}
+
+void NetworkDataTaskReplay::replayDataReceived(const DataReceivedEvent& event)
+{
+    DEBUG_LOG("URL = %{public}s", DEBUG_STR(m_firstRequest.url().string()));
+
+    ASSERT(m_client);
+    m_client->didReceiveData(event.data.copyRef());
+
+    enqueueEventHandler();
+}
+
+void NetworkDataTaskReplay::replayFinished(const FinishedEvent& event)
+{
+    DEBUG_LOG("URL = %{public}s", DEBUG_STR(m_firstRequest.url().string()));
+
+    didFinish(event.error);
+}
+
+void NetworkDataTaskReplay::didReceiveResponse(WebCore::ResourceResponse&& response)
+{
+    DEBUG_LOG("URL = %{public}s", DEBUG_STR(m_firstRequest.url().string()));
+
+    ASSERT(m_client);
+    m_client->didReceiveResponseNetworkSession(WTFMove(response), [this, protectedThis = makeRef(*this)](WebCore::PolicyAction policyAction) {
+        DEBUG_LOG("didReceiveResponse callback (%u)", static_cast<unsigned>(policyAction));
+
+        if (m_state == State::Canceling || m_state == State::Completed) {
+            complete();
+            return;
+        }
+
+        switch (policyAction) {
+        case WebCore::PolicyAction::PolicyUse:
+            enqueueEventHandler();
+            break;
+        case WebCore::PolicyAction::PolicyIgnore:
+            complete();
+            break;
+        case WebCore::PolicyAction::PolicyDownload:
+            DEBUG_LOG_ERROR("WebCore::PolicyAction::PolicyDownload");
+            break;
+        }
+    });
+}
+
+void NetworkDataTaskReplay::didFinish()
+{
+    didFinish({ });
+}
+
+void NetworkDataTaskReplay::didFinish(Error errorCode)
+{
+    didFinish(WebCore::ResourceError(webKitRelayDomain, static_cast<int>(errorCode), m_firstRequest.url(), String()));
+}
+
+void NetworkDataTaskReplay::didFinish(const WebCore::ResourceError& error)
+{
+    DEBUG_LOG("(%d)", error.errorCode());
+
+    complete();
+
+    ASSERT(m_client);
+    m_client->didCompleteWithError(error);
+}
+
+} // namespace NetworkCapture
+} // namespace WebKit
+
+#endif // ENABLE(NETWORK_CAPTURE)
diff --git a/Source/WebKit2/NetworkProcess/capture/NetworkDataTaskReplay.h b/Source/WebKit2/NetworkProcess/capture/NetworkDataTaskReplay.h
new file mode 100644 (file)
index 0000000..bd28a7d
--- /dev/null
@@ -0,0 +1,103 @@
+/*
+ * Copyright (C) 2016 Apple Inc. All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ * 1. Redistributions of source code must retain the above copyright
+ *    notice, this list of conditions and the following disclaimer.
+ * 2. Redistributions in binary form must reproduce the above copyright
+ *    notice, this list of conditions and the following disclaimer in the
+ *    documentation and/or other materials provided with the distribution.
+ *
+ * THIS SOFTWARE IS PROVIDED BY APPLE INC. AND ITS CONTRIBUTORS ``AS IS''
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+ * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+ * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL APPLE INC. OR ITS CONTRIBUTORS
+ * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
+ * THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+#pragma once
+
+#if ENABLE(NETWORK_CAPTURE)
+
+#include "NetworkCaptureResource.h"
+#include "NetworkDataTask.h"
+#include <WebCore/ResourceRequest.h>
+
+namespace WebCore {
+class ResourceError;
+class ResourceResponse;
+}
+
+namespace WebKit {
+class NetworkDataTaskClient;
+class NetworkLoadParameters;
+class NetworkSession;
+}
+
+namespace WebKit {
+namespace NetworkCapture {
+
+struct RequestSentEvent;
+struct ResponseReceivedEvent;
+struct RedirectReceivedEvent;
+struct RedirectSentEvent;
+struct DataReceivedEvent;
+struct FinishedEvent;
+
+class NetworkDataTaskReplay : public NetworkDataTask {
+public:
+    static Ref<NetworkDataTaskReplay> create(NetworkSession& session, NetworkDataTaskClient& client, const NetworkLoadParameters& parameters, Resource* resource)
+    {
+        return adoptRef(*new NetworkDataTaskReplay(session, client, parameters, resource));
+    }
+
+    void replayRequestSent(const RequestSentEvent&);
+    void replayResponseReceived(const ResponseReceivedEvent&);
+    void replayRedirectReceived(const RedirectReceivedEvent&);
+    void replayRedirectSent(const RedirectSentEvent&);
+    void replayDataReceived(const DataReceivedEvent&);
+    void replayFinished(const FinishedEvent&);
+
+private:
+    NetworkDataTaskReplay(NetworkSession&, NetworkDataTaskClient&, const NetworkLoadParameters&, Resource*);
+    ~NetworkDataTaskReplay() override;
+
+    void resume() override;
+    void suspend() override;
+    void cancel() override;
+    void complete();
+    void invalidateAndCancel() override;
+
+    State state() const override { return m_state; }
+
+    void enqueueEventHandler();
+
+    enum class Error {
+        NoError = 0,
+        NotFoundError = 1,
+        MethodNotAllowed = 5
+    };
+
+    void didReceiveResponse(WebCore::ResourceResponse&&);
+    void didFinish();
+    void didFinish(Error);
+    void didFinish(const WebCore::ResourceError&);
+
+    State m_state { State::Suspended };
+    WebCore::ResourceRequest m_currentRequest;
+    Resource* m_resource;
+    Resource::EventStream m_eventStream;
+};
+
+} // namespace NetworkCapture
+} // namespace WebKit
+
+#endif // ENABLE(NETWORK_CAPTURE)
diff --git a/Source/WebKit2/NetworkProcess/capture/json.hpp b/Source/WebKit2/NetworkProcess/capture/json.hpp
new file mode 100644 (file)
index 0000000..10ac8e2
--- /dev/null
@@ -0,0 +1,10821 @@
+/*
+ * **************************************************************************
+ *
+ * DO NOT USE THIS JSON LIBRARY!
+ *
+ * This JSON library exists as a temporary facility for reading and writing
+ * JSON files. Ultimately, we should be using the JSON facilities that are in
+ * JavaScriptCore. However, those are too heavy-weight for what we want in the
+ * NetworkProcess. The NetworkProcess currently doesn't use JavaScriptCore and
+ * doesn't allocate the data structures and memory-handling facilities that JSC
+ * requires. All we want is something that will do the simple streaming and
+ * parsing of JSON. To ultimately achieve this, we will be modifying the
+ * JSONParse in JSC to be lighter-weight, performing just the streaming or
+ * parsing and leaving the memory management and object creation to the caller.
+ * This will be similar to howe YarrParser works. The new JSONParse will be
+ * used here and in other places like in ContextExtensionParser. Until then, we
+ * use this library.
+ *
+ * In that context, this library should not be used by anyone else. It will be
+ * going away. Also, it has not been vetted for security issues that might
+ * arise if it were used in a context where customer data is being manipulated.
+ *
+ * DO NOT USE THIS JSON LIBRARY!
+ *
+ * **************************************************************************
+ *
+ * This file was taken from <https://github.com/nlohmann/json> at revision
+ * e717492019687bf0edf2b884b51bf37db4831a6f and modified as follows for
+ * inclusion in WebKit:
+ *
+ *  * Exceptions are disabled in WebKit, so all 'throw' statements were
+ *    converted into a call to a Throw function. This function can be enabled
+ *    to invoke 'throw' as before, but by default asserts and crashes.
+ *  * try/catch statements are also disallowed, so these were converted into
+ *    simple if/then checks where possible. Where not possible, the try/catch
+ *    statements were simply removed with the expectation that no code paths
+ *    would trigger the anticipated exceptions.
+ *  * For efficiency, a basic_json constructor that takes a
+ *    string_t::value_type* and a count was added.
+ *
+ * **************************************************************************
+ */
+
+/*
+    __ _____ _____ _____
+ __|  |   __|     |   | |  JSON for Modern C++
+|  |  |__   |  |  | | | |  version 2.0.7
+|_____|_____|_____|_|___|  https://github.com/nlohmann/json
+
+Licensed under the MIT License <http://opensource.org/licenses/MIT>.
+Copyright (c) 2013-2016 Niels Lohmann <http://nlohmann.me>.
+
+Permission is hereby  granted, free of charge, to any  person obtaining a copy
+of this software and associated  documentation files (the "Software"), to deal
+in the Software  without restriction, including without  limitation the rights
+to  use, copy,  modify, merge,  publish, distribute,  sublicense, and/or  sell
+copies  of  the Software,  and  to  permit persons  to  whom  the Software  is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE  IS PROVIDED "AS  IS", WITHOUT WARRANTY  OF ANY KIND,  EXPRESS OR
+IMPLIED,  INCLUDING BUT  NOT  LIMITED TO  THE  WARRANTIES OF  MERCHANTABILITY,
+FITNESS FOR  A PARTICULAR PURPOSE AND  NONINFRINGEMENT. IN NO EVENT  SHALL THE
+AUTHORS  OR COPYRIGHT  HOLDERS  BE  LIABLE FOR  ANY  CLAIM,  DAMAGES OR  OTHER
+LIABILITY, WHETHER IN AN ACTION OF  CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE  OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+*/
+
+#ifndef NLOHMANN_JSON_HPP
+#define NLOHMANN_JSON_HPP
+
+#include <algorithm> // all_of, for_each, transform
+#include <array> // array
+#include <cassert> // assert
+#include <cctype> // isdigit
+#include <ciso646> // and, not, or
+#include <cmath> // isfinite, signbit
+#include <cstddef> // nullptr_t, ptrdiff_t, size_t
+#include <cstdint> // int64_t, uint64_t
+#include <cstdlib> // strtod, strtof, strtold, strtoul
+#include <cstring> // strlen
+#include <functional> // function, hash, less
+#include <initializer_list> // initializer_list
+#include <iomanip> // setw
+#include <iostream> // istream, ostream
+#include <iterator> // advance, begin, bidirectional_iterator_tag, distance, end, inserter, iterator, iterator_traits, next, random_access_iterator_tag, reverse_iterator
+#include <limits> // numeric_limits
+#include <locale> // locale
+#include <map> // map
+#include <memory> // addressof, allocator, allocator_traits, unique_ptr
+#include <numeric> // accumulate
+#include <sstream> // stringstream
+#include <stdexcept> // domain_error, invalid_argument, out_of_range
+#include <string> // getline, stoi, string, to_string
+#include <type_traits> // add_pointer, enable_if, is_arithmetic, is_base_of, is_const, is_constructible, is_convertible, is_floating_point, is_integral, is_nothrow_move_assignable, std::is_nothrow_move_constructible, std::is_pointer, std::is_reference, std::is_same, remove_const, remove_pointer, remove_reference
+#include <utility> // declval, forward, make_pair, move, pair, swap
+#include <vector> // vector
+
+#include <wtf/Assertions.h> // ASSERT
+#include <wtf/Compiler.h> // NO_RETURN
+
+// exclude unsupported compilers
+#if defined(__clang__)
+    #define CLANG_VERSION (__clang_major__ * 10000 + __clang_minor__ * 100 + __clang_patchlevel__)
+    #if CLANG_VERSION < 30400
+        #error "unsupported Clang version - see https://github.com/nlohmann/json#supported-compilers"
+    #endif
+#elif defined(__GNUC__)
+    #define GCC_VERSION (__GNUC__ * 10000 + __GNUC_MINOR__ * 100 + __GNUC_PATCHLEVEL__)
+    #if GCC_VERSION < 40900
+        #error "unsupported GCC version - see https://github.com/nlohmann/json#supported-compilers"
+    #endif
+#endif
+
+// disable float-equal warnings on GCC/clang
+#if defined(__clang__) || defined(__GNUC__) || defined(__GNUG__)
+    #pragma GCC diagnostic push
+    #pragma GCC diagnostic ignored "-Wfloat-equal"
+#endif
+
+// allow for portable deprecation warnings
+#if defined(__clang__) || defined(__GNUC__) || defined(__GNUG__)
+    #define JSON_DEPRECATED __attribute__((deprecated))
+#elif defined(_MSC_VER)
+    #define JSON_DEPRECATED __declspec(deprecated)
+#else
+    #define JSON_DEPRECATED
+#endif
+
+/*!
+@brief namespace for Niels Lohmann
+@see https://github.com/nlohmann
+@since version 1.0.0
+*/
+namespace nlohmann
+{
+
+
+/*!
+@brief unnamed namespace with internal helper functions
+@since version 1.0.0
+*/
+namespace
+{
+/*!
+@brief Helper to determine whether there's a key_type for T.
+
+Thus helper is used to tell associative containers apart from other containers
+such as sequence containers. For instance, `std::map` passes the test as it
+contains a `mapped_type`, whereas `std::vector` fails the test.
+
+@sa http://stackoverflow.com/a/7728728/266378
+@since version 1.0.0, overworked in version 2.0.6
+*/
+template<typename T>
+struct has_mapped_type
+{
+  private:
+    template <typename U, typename = typename U::mapped_type>
+    static int detect(U&&);
+
+    static void detect(...);
+  public:
+    static constexpr bool value =
+        std::is_integral<decltype(detect(std::declval<T>()))>::value;
+};
+
+template <typename T, typename ... Types>
+NO_RETURN void Throw(Types ... args)
+{
+#if 0
+    throw T(std::forward<Types>(args)...);
+#else
+    ASSERT(false);
+    WTFCrash();
+#endif
+}
+}
+
+/*!
+@brief a class to store JSON values
+
+@tparam ObjectType type for JSON objects (`std::map` by default; will be used
+in @ref object_t)
+@tparam ArrayType type for JSON arrays (`std::vector` by default; will be used
+in @ref array_t)
+@tparam StringType type for JSON strings and object keys (`std::string` by
+default; will be used in @ref string_t)
+@tparam BooleanType type for JSON booleans (`bool` by default; will be used
+in @ref boolean_t)
+@tparam NumberIntegerType type for JSON integer numbers (`int64_t` by
+default; will be used in @ref number_integer_t)
+@tparam NumberUnsignedType type for JSON unsigned integer numbers (@c
+`uint64_t` by default; will be used in @ref number_unsigned_t)
+@tparam NumberFloatType type for JSON floating-point numbers (`double` by
+default; will be used in @ref number_float_t)
+@tparam AllocatorType type of the allocator to use (`std::allocator` by
+default)
+
+@requirement The class satisfies the following concept requirements:
+- Basic
+ - [DefaultConstructible](http://en.cppreference.com/w/cpp/concept/DefaultConstructible):
+   JSON values can be default constructed. The result will be a JSON null value.
+ - [MoveConstructible](http://en.cppreference.com/w/cpp/concept/MoveConstructible):
+   A JSON value can be constructed from an rvalue argument.
+ - [CopyConstructible](http://en.cppreference.com/w/cpp/concept/CopyConstructible):
+   A JSON value can be copy-constructed from an lvalue expression.
+ - [MoveAssignable](http://en.cppreference.com/w/cpp/concept/MoveAssignable):
+   A JSON value van be assigned from an rvalue argument.
+ - [CopyAssignable](http://en.cppreference.com/w/cpp/concept/CopyAssignable):
+   A JSON value can be copy-assigned from an lvalue expression.
+ - [Destructible](http://en.cppreference.com/w/cpp/concept/Destructible):
+   JSON values can be destructed.
+- Layout
+ - [StandardLayoutType](http://en.cppreference.com/w/cpp/concept/StandardLayoutType):
+   JSON values have
+   [standard layout](http://en.cppreference.com/w/cpp/language/data_members#Standard_layout):
+   All non-static data members are private and standard layout types, the class
+   has no virtual functions or (virtual) base classes.
+- Library-wide
+ - [EqualityComparable](http://en.cppreference.com/w/cpp/concept/EqualityComparable):
+   JSON values can be compared with `==`, see @ref
+   operator==(const_reference,const_reference).
+ - [LessThanComparable](http://en.cppreference.com/w/cpp/concept/LessThanComparable):
+   JSON values can be compared with `<`, see @ref
+   operator<(const_reference,const_reference).
+ - [Swappable](http://en.cppreference.com/w/cpp/concept/Swappable):
+   Any JSON lvalue or rvalue of can be swapped with any lvalue or rvalue of
+   other compatible types, using unqualified function call @ref swap().
+ - [NullablePointer](http://en.cppreference.com/w/cpp/concept/NullablePointer):
+   JSON values can be compared against `std::nullptr_t` objects which are used
+   to model the `null` value.
+- Container
+ - [Container](http://en.cppreference.com/w/cpp/concept/Container):
+   JSON values can be used like STL containers and provide iterator access.
+ - [ReversibleContainer](http://en.cppreference.com/w/cpp/concept/ReversibleContainer);
+   JSON values can be used like STL containers and provide reverse iterator
+   access.
+
+@invariant The member variables @a m_value and @a m_type have the following
+relationship:
+- If `m_type == value_t::object`, then `m_value.object != nullptr`.
+- If `m_type == value_t::array`, then `m_value.array != nullptr`.
+- If `m_type == value_t::string`, then `m_value.string != nullptr`.
+The invariants are checked by member function assert_invariant().
+
+@internal
+@note ObjectType trick from http://stackoverflow.com/a/9860911
+@endinternal
+
+@see [RFC 7159: The JavaScript Object Notation (JSON) Data Interchange
+Format](http://rfc7159.net/rfc7159)
+
+@since version 1.0.0
+
+@nosubgrouping
+*/
+template <
+    template<typename U, typename V, typename... Args> class ObjectType = std::map,
+    template<typename U, typename... Args> class ArrayType = std::vector,
+    class StringType = std::string,
+    class BooleanType = bool,
+    class NumberIntegerType = std::int64_t,
+    class NumberUnsignedType = std::uint64_t,
+    class NumberFloatType = double,
+    template<typename U> class AllocatorType = std::allocator
+    >
+class basic_json
+{
+  private:
+    /// workaround type for MSVC
+    using basic_json_t = basic_json<ObjectType, ArrayType, StringType,
+          BooleanType, NumberIntegerType, NumberUnsignedType, NumberFloatType,
+          AllocatorType>;
+
+  public:
+    // forward declarations
+    template<typename Base> class json_reverse_iterator;
+    class json_pointer;
+
+    /////////////////////
+    // container types //
+    /////////////////////
+
+    /// @name container types
+    /// The canonic container types to use @ref basic_json like any other STL
+    /// container.
+    /// @{
+
+    /// the type of elements in a basic_json container
+    using value_type = basic_json;
+
+    /// the type of an element reference
+    using reference = value_type&;
+    /// the type of an element const reference
+    using const_reference = const value_type&;
+
+    /// a type to represent differences between iterators
+    using difference_type = std::ptrdiff_t;
+    /// a type to represent container sizes
+    using size_type = std::size_t;
+
+    /// the allocator type
+    using allocator_type = AllocatorType<basic_json>;
+
+    /// the type of an element pointer
+    using pointer = typename std::allocator_traits<allocator_type>::pointer;
+    /// the type of an element const pointer
+    using const_pointer = typename std::allocator_traits<allocator_type>::const_pointer;
+
+    /// an iterator for a basic_json container
+    class iterator;
+    /// a const iterator for a basic_json container
+    class const_iterator;
+    /// a reverse iterator for a basic_json container
+    using reverse_iterator = json_reverse_iterator<typename basic_json::iterator>;
+    /// a const reverse iterator for a basic_json container
+    using const_reverse_iterator = json_reverse_iterator<typename basic_json::const_iterator>;
+
+    /// @}
+
+
+    /*!
+    @brief returns the allocator associated with the container
+    */
+    static allocator_type get_allocator()
+    {
+        return allocator_type();
+    }
+
+
+    ///////////////////////////
+    // JSON value data types //
+    ///////////////////////////
+
+    /// @name JSON value data types
+    /// The data types to store a JSON value. These types are derived from
+    /// the template arguments passed to class @ref basic_json.
+    /// @{
+
+    /*!
+    @brief a type for an object
+
+    [RFC 7159](http://rfc7159.net/rfc7159) describes JSON objects as follows:
+    > An object is an unordered collection of zero or more name/value pairs,
+    > where a name is a string and a value is a string, number, boolean, null,
+    > object, or array.
+
+    To store objects in C++, a type is defined by the template parameters
+    described below.
+
+    @tparam ObjectType  the container to store objects (e.g., `std::map` or
+    `std::unordered_map`)
+    @tparam StringType the type of the keys or names (e.g., `std::string`).
+    The comparison function `std::less<StringType>` is used to order elements
+    inside the container.
+    @tparam AllocatorType the allocator to use for objects (e.g.,
+    `std::allocator`)
+
+    #### Default type
+
+    With the default values for @a ObjectType (`std::map`), @a StringType
+    (`std::string`), and @a AllocatorType (`std::allocator`), the default
+    value for @a object_t is:
+
+    @code {.cpp}
+    std::map<
+      std::string, // key_type
+      basic_json, // value_type
+      std::less<std::string>, // key_compare
+      std::allocator<std::pair<const std::string, basic_json>> // allocator_type
+    >
+    @endcode
+
+    #### Behavior
+
+    The choice of @a object_t influences the behavior of the JSON class. With
+    the default type, objects have the following behavior:
+
+    - When all names are unique, objects will be interoperable in the sense
+      that all software implementations receiving that object will agree on
+      the name-value mappings.
+    - When the names within an object are not unique, later stored name/value
+      pairs overwrite previously stored name/value pairs, leaving the used
+      names unique. For instance, `{"key": 1}` and `{"key": 2, "key": 1}` will
+      be treated as equal and both stored as `{"key": 1}`.
+    - Internally, name/value pairs are stored in lexicographical order of the
+      names. Objects will also be serialized (see @ref dump) in this order.
+      For instance, `{"b": 1, "a": 2}` and `{"a": 2, "b": 1}` will be stored
+      and serialized as `{"a": 2, "b": 1}`.
+    - When comparing objects, the order of the name/value pairs is irrelevant.
+      This makes objects interoperable in the sense that they will not be
+      affected by these differences. For instance, `{"b": 1, "a": 2}` and
+      `{"a": 2, "b": 1}` will be treated as equal.
+
+    #### Limits
+
+    [RFC 7159](http://rfc7159.net/rfc7159) specifies:
+    > An implementation may set limits on the maximum depth of nesting.
+
+    In this class, the object's limit of nesting is not constraint explicitly.
+    However, a maximum depth of nesting may be introduced by the compiler or
+    runtime environment. A theoretical limit can be queried by calling the
+    @ref max_size function of a JSON object.
+
+    #### Storage
+
+    Objects are stored as pointers in a @ref basic_json type. That is, for any
+    access to object values, a pointer of type `object_t*` must be
+    dereferenced.
+
+    @sa @ref array_t -- type for an array value
+
+    @since version 1.0.0
+
+    @note The order name/value pairs are added to the object is *not*
+    preserved by the library. Therefore, iterating an object may return
+    name/value pairs in a different order than they were originally stored. In
+    fact, keys will be traversed in alphabetical order as `std::map` with
+    `std::less` is used by default. Please note this behavior conforms to [RFC
+    7159](http://rfc7159.net/rfc7159), because any order implements the
+    specified "unordered" nature of JSON objects.
+    */
+    using object_t = ObjectType<StringType,
+          basic_json,
+          std::less<StringType>,
+          AllocatorType<std::pair<const StringType,
+          basic_json>>>;
+
+    /*!
+    @brief a type for an array
+
+    [RFC 7159](http://rfc7159.net/rfc7159) describes JSON arrays as follows:
+    > An array is an ordered sequence of zero or more values.
+
+    To store objects in C++, a type is defined by the template parameters
+    explained below.
+
+    @tparam ArrayType  container type to store arrays (e.g., `std::vector` or
+    `std::list`)
+    @tparam AllocatorType allocator to use for arrays (e.g., `std::allocator`)
+
+    #### Default type
+
+    With the default values for @a ArrayType (`std::vector`) and @a
+    AllocatorType (`std::allocator`), the default value for @a array_t is:
+
+    @code {.cpp}
+    std::vector<
+      basic_json, // value_type
+      std::allocator<basic_json> // allocator_type
+    >
+    @endcode
+
+    #### Limits
+
+    [RFC 7159](http://rfc7159.net/rfc7159) specifies:
+    > An implementation may set limits on the maximum depth of nesting.
+
+    In this class, the array's limit of nesting is not constraint explicitly.
+    However, a maximum depth of nesting may be introduced by the compiler or
+    runtime environment. A theoretical limit can be queried by calling the
+    @ref max_size function of a JSON array.
+
+    #### Storage
+
+    Arrays are stored as pointers in a @ref basic_json type. That is, for any
+    access to array values, a pointer of type `array_t*` must be dereferenced.
+
+    @sa @ref object_t -- type for an object value
+
+    @since version 1.0.0
+    */
+    using array_t = ArrayType<basic_json, AllocatorType<basic_json>>;
+
+    /*!
+    @brief a type for a string
+
+    [RFC 7159](http://rfc7159.net/rfc7159) describes JSON strings as follows:
+    > A string is a sequence of zero or more Unicode characters.
+
+    To store objects in C++, a type is defined by the template parameter
+    described below. Unicode values are split by the JSON class into
+    byte-sized characters during deserialization.
+
+    @tparam StringType  the container to store strings (e.g., `std::string`).
+    Note this container is used for keys/names in objects, see @ref object_t.
+
+    #### Default type
+
+    With the default values for @a StringType (`std::string`), the default
+    value for @a string_t is:
+
+    @code {.cpp}
+    std::string
+    @endcode
+
+    #### String comparison
+
+    [RFC 7159](http://rfc7159.net/rfc7159) states:
+    > Software implementations are typically required to test names of object
+    > members for equality. Implementations that transform the textual
+    > representation into sequences of Unicode code units and then perform the
+    > comparison numerically, code unit by code unit, are interoperable in the
+    > sense that implementations will agree in all cases on equality or
+    > inequality of two strings. For example, implementations that compare
+    > strings with escaped characters unconverted may incorrectly find that
+    > `"a\\b"` and `"a\u005Cb"` are not equal.
+
+    This implementation is interoperable as it does compare strings code unit
+    by code unit.
+
+    #### Storage
+
+    String values are stored as pointers in a @ref basic_json type. That is,
+    for any access to string values, a pointer of type `string_t*` must be
+    dereferenced.
+
+    @since version 1.0.0
+    */
+    using string_t = StringType;
+
+    /*!
+    @brief a type for a boolean
+
+    [RFC 7159](http://rfc7159.net/rfc7159) implicitly describes a boolean as a
+    type which differentiates the two literals `true` and `false`.
+
+    To store objects in C++, a type is defined by the template parameter @a
+    BooleanType which chooses the type to use.
+
+    #### Default type
+
+    With the default values for @a BooleanType (`bool`), the default value for
+    @a boolean_t is:
+
+    @code {.cpp}
+    bool
+    @endcode
+
+    #### Storage
+
+    Boolean values are stored directly inside a @ref basic_json type.
+
+    @since version 1.0.0
+    */
+    using boolean_t = BooleanType;
+
+    /*!
+    @brief a type for a number (integer)
+
+    [RFC 7159](http://rfc7159.net/rfc7159) describes numbers as follows:
+    > The representation of numbers is similar to that used in most
+    > programming languages. A number is represented in base 10 using decimal
+    > digits. It contains an integer component that may be prefixed with an
+    > optional minus sign, which may be followed by a fraction part and/or an
+    > exponent part. Leading zeros are not allowed. (...) Numeric values that
+    > cannot be represented in the grammar below (such as Infinity and NaN)
+    > are not permitted.
+
+    This description includes both integer and floating-point numbers.
+    However, C++ allows more precise storage if it is known whether the number
+    is a signed integer, an unsigned integer or a floating-point number.
+    Therefore, three different types, @ref number_integer_t, @ref
+    number_unsigned_t and @ref number_float_t are used.
+
+    To store integer numbers in C++, a type is defined by the template
+    parameter @a NumberIntegerType which chooses the type to use.
+
+    #### Default type
+
+    With the default values for @a NumberIntegerType (`int64_t`), the default
+    value for @a number_integer_t is:
+
+    @code {.cpp}
+    int64_t
+    @endcode
+
+    #### Default behavior
+
+    - The restrictions about leading zeros is not enforced in C++. Instead,
+      leading zeros in integer literals lead to an interpretation as octal
+      number. Internally, the value will be stored as decimal number. For
+      instance, the C++ integer literal `010` will be serialized to `8`.
+      During deserialization, leading zeros yield an error.
+    - Not-a-number (NaN) values will be serialized to `null`.
+
+    #### Limits
+
+    [RFC 7159](http://rfc7159.net/rfc7159) specifies:
+    > An implementation may set limits on the range and precision of numbers.
+
+    When the default type is used, the maximal integer number that can be
+    stored is `9223372036854775807` (INT64_MAX) and the minimal integer number
+    that can be stored is `-9223372036854775808` (INT64_MIN). Integer numbers
+    that are out of range will yield over/underflow when used in a
+    constructor. During deserialization, too large or small integer numbers
+    will be automatically be stored as @ref number_unsigned_t or @ref
+    number_float_t.
+
+    [RFC 7159](http://rfc7159.net/rfc7159) further states:
+    > Note that when such software is used, numbers that are integers and are
+    > in the range \f$[-2^{53}+1, 2^{53}-1]\f$ are interoperable in the sense
+    > that implementations will agree exactly on their numeric values.
+
+    As this range is a subrange of the exactly supported range [INT64_MIN,
+    INT64_MAX], this class's integer type is interoperable.
+
+    #### Storage
+
+    Integer number values are stored directly inside a @ref basic_json type.
+
+    @sa @ref number_float_t -- type for number values (floating-point)
+
+    @sa @ref number_unsigned_t -- type for number values (unsigned integer)
+
+    @since version 1.0.0
+    */
+    using number_integer_t = NumberIntegerType;
+
+    /*!
+    @brief a type for a number (unsigned)
+
+    [RFC 7159](http://rfc7159.net/rfc7159) describes numbers as follows:
+    > The representation of numbers is similar to that used in most
+    > programming languages. A number is represented in base 10 using decimal
+    > digits. It contains an integer component that may be prefixed with an
+    > optional minus sign, which may be followed by a fraction part and/or an
+    > exponent part. Leading zeros are not allowed. (...) Numeric values that
+    > cannot be represented in the grammar below (such as Infinity and NaN)
+    > are not permitted.
+
+    This description includes both integer and floating-point numbers.
+    However, C++ allows more precise storage if it is known whether the number
+    is a signed integer, an unsigned integer or a floating-point number.
+    Therefore, three different types, @ref number_integer_t, @ref
+    number_unsigned_t and @ref number_float_t are used.
+
+    To store unsigned integer numbers in C++, a type is defined by the
+    template parameter @a NumberUnsignedType which chooses the type to use.
+
+    #### Default type
+
+    With the default values for @a NumberUnsignedType (`uint64_t`), the
+    default value for @a number_unsigned_t is:
+
+    @code {.cpp}
+    uint64_t
+    @endcode
+
+    #### Default behavior
+
+    - The restrictions about leading zeros is not enforced in C++. Instead,
+      leading zeros in integer literals lead to an interpretation as octal
+      number. Internally, the value will be stored as decimal number. For
+      instance, the C++ integer literal `010` will be serialized to `8`.
+      During deserialization, leading zeros yield an error.
+    - Not-a-number (NaN) values will be serialized to `null`.
+
+    #### Limits
+
+    [RFC 7159](http://rfc7159.net/rfc7159) specifies:
+    > An implementation may set limits on the range and precision of numbers.
+
+    When the default type is used, the maximal integer number that can be
+    stored is `18446744073709551615` (UINT64_MAX) and the minimal integer
+    number that can be stored is `0`. Integer numbers that are out of range
+    will yield over/underflow when used in a constructor. During
+    deserialization, too large or small integer numbers will be automatically
+    be stored as @ref number_integer_t or @ref number_float_t.
+
+    [RFC 7159](http://rfc7159.net/rfc7159) further states:
+    > Note that when such software is used, numbers that are integers and are
+    > in the range \f$[-2^{53}+1, 2^{53}-1]\f$ are interoperable in the sense
+    > that implementations will agree exactly on their numeric values.
+
+    As this range is a subrange (when considered in conjunction with the
+    number_integer_t type) of the exactly supported range [0, UINT64_MAX],
+    this class's integer type is interoperable.
+
+    #### Storage
+
+    Integer number values are stored directly inside a @ref basic_json type.
+
+    @sa @ref number_float_t -- type for number values (floating-point)
+    @sa @ref number_integer_t -- type for number values (integer)
+
+    @since version 2.0.0
+    */
+    using number_unsigned_t = NumberUnsignedType;
+
+    /*!
+    @brief a type for a number (floating-point)
+
+    [RFC 7159](http://rfc7159.net/rfc7159) describes numbers as follows:
+    > The representation of numbers is similar to that used in most
+    > programming languages. A number is represented in base 10 using decimal
+    > digits. It contains an integer component that may be prefixed with an
+    > optional minus sign, which may be followed by a fraction part and/or an
+    > exponent part. Leading zeros are not allowed. (...) Numeric values that
+    > cannot be represented in the grammar below (such as Infinity and NaN)
+    > are not permitted.
+
+    This description includes both integer and floating-point numbers.
+    However, C++ allows more precise storage if it is known whether the number
+    is a signed integer, an unsigned integer or a floating-point number.
+    Therefore, three different types, @ref number_integer_t, @ref
+    number_unsigned_t and @ref number_float_t are used.
+
+    To store floating-point numbers in C++, a type is defined by the template
+    parameter @a NumberFloatType which chooses the type to use.
+
+    #### Default type
+
+    With the default values for @a NumberFloatType (`double`), the default
+    value for @a number_float_t is:
+
+    @code {.cpp}
+    double
+    @endcode
+
+    #### Default behavior
+
+    - The restrictions about leading zeros is not enforced in C++. Instead,
+      leading zeros in floating-point literals will be ignored. Internally,
+      the value will be stored as decimal number. For instance, the C++
+      floating-point literal `01.2` will be serialized to `1.2`. During
+      deserialization, leading zeros yield an error.
+    - Not-a-number (NaN) values will be serialized to `null`.
+
+    #### Limits
+
+    [RFC 7159](http://rfc7159.net/rfc7159) states:
+    > This specification allows implementations to set limits on the range and
+    > precision of numbers accepted. Since software that implements IEEE
+    > 754-2008 binary64 (double precision) numbers is generally available and
+    > widely used, good interoperability can be achieved by implementations
+    > that expect no more precision or range than these provide, in the sense
+    > that implementations will approximate JSON numbers within the expected
+    > precision.
+
+    This implementation does exactly follow this approach, as it uses double
+    precision floating-point numbers. Note values smaller than
+    `-1.79769313486232e+308` and values greater than `1.79769313486232e+308`
+    will be stored as NaN internally and be serialized to `null`.
+
+    #### Storage
+
+    Floating-point number values are stored directly inside a @ref basic_json
+    type.
+
+    @sa @ref number_integer_t -- type for number values (integer)
+
+    @sa @ref number_unsigned_t -- type for number values (unsigned integer)
+
+    @since version 1.0.0
+    */
+    using number_float_t = NumberFloatType;
+
+    /// @}
+
+
+    ///////////////////////////
+    // JSON type enumeration //
+    ///////////////////////////
+
+    /*!
+    @brief the JSON type enumeration
+
+    This enumeration collects the different JSON types. It is internally used
+    to distinguish the stored values, and the functions @ref is_null(), @ref
+    is_object(), @ref is_array(), @ref is_string(), @ref is_boolean(), @ref
+    is_number() (with @ref is_number_integer(), @ref is_number_unsigned(), and
+    @ref is_number_float()), @ref is_discarded(), @ref is_primitive(), and
+    @ref is_structured() rely on it.
+
+    @note There are three enumeration entries (number_integer,
+    number_unsigned, and number_float), because the library distinguishes
+    these three types for numbers: @ref number_unsigned_t is used for unsigned
+    integers, @ref number_integer_t is used for signed integers, and @ref
+    number_float_t is used for floating-point numbers or to approximate
+    integers which do not fit in the limits of their respective type.
+
+    @sa @ref basic_json(const value_t value_type) -- create a JSON value with
+    the default value for a given type
+
+    @since version 1.0.0
+    */
+    enum class value_t : uint8_t
+    {
+        null,            ///< null value
+        object,          ///< object (unordered set of name/value pairs)
+        array,           ///< array (ordered collection of values)
+        string,          ///< string value
+        boolean,         ///< boolean value
+        number_integer,  ///< number value (signed integer)
+        number_unsigned, ///< number value (unsigned integer)
+        number_float,    ///< number value (floating-point)
+        discarded        ///< discarded by the the parser callback function
+    };
+
+
+  private:
+
+    /// helper for exception-safe object creation
+    template<typename T, typename... Args>
+    static T* create(Args&& ... args)
+    {
+        AllocatorType<T> alloc;
+        auto deleter = [&](T * object)
+        {
+            alloc.deallocate(object, 1);
+        };
+        std::unique_ptr<T, decltype(deleter)> object(alloc.allocate(1), deleter);
+        alloc.construct(object.get(), std::forward<Args>(args)...);
+        assert(object.get() != nullptr);
+        return object.release();
+    }
+
+    ////////////////////////
+    // JSON value storage //
+    ////////////////////////
+
+    /*!
+    @brief a JSON value
+
+    The actual storage for a JSON value of the @ref basic_json class. This
+    union combines the different storage types for the JSON value types
+    defined in @ref value_t.
+
+    JSON type | value_t type    | used type
+    --------- | --------------- | ------------------------
+    object    | object          | pointer to @ref object_t
+    array     | array           | pointer to @ref array_t
+    string    | string          | pointer to @ref string_t
+    boolean   | boolean         | @ref boolean_t
+    number    | number_integer  | @ref number_integer_t
+    number    | number_unsigned | @ref number_unsigned_t
+    number    | number_float    | @ref number_float_t
+    null      | null            | *no value is stored*
+
+    @note Variable-length types (objects, arrays, and strings) are stored as
+    pointers. The size of the union should not exceed 64 bits if the default
+    value types are used.
+
+    @since version 1.0.0
+    */
+    union json_value
+    {
+        /// object (stored with pointer to save storage)
+        object_t* object;
+        /// array (stored with pointer to save storage)
+        array_t* array;
+        /// string (stored with pointer to save storage)
+        string_t* string;
+        /// boolean
+        boolean_t boolean;
+        /// number (integer)
+        number_integer_t number_integer;
+        /// number (unsigned integer)
+        number_unsigned_t number_unsigned;
+        /// number (floating-point)
+        number_float_t number_float;
+
+        /// default constructor (for null values)
+        json_value() = default;
+        /// constructor for booleans
+        json_value(boolean_t v) noexcept : boolean(v) {}
+        /// constructor for numbers (integer)
+        json_value(number_integer_t v) noexcept : number_integer(v) {}
+        /// constructor for numbers (unsigned)
+        json_value(number_unsigned_t v) noexcept : number_unsigned(v) {}
+        /// constructor for numbers (floating-point)
+        json_value(number_float_t v) noexcept : number_float(v) {}
+        /// constructor for empty values of a given type
+        json_value(value_t t)
+        {
+            switch (t)
+            {
+                case value_t::object:
+                {
+                    object = create<object_t>();
+                    break;
+                }
+
+                case value_t::array:
+                {
+                    array = create<array_t>();
+                    break;
+                }
+
+                case value_t::string:
+                {
+                    string = create<string_t>("");
+                    break;
+                }
+
+                case value_t::boolean:
+                {
+                    boolean = boolean_t(false);
+                    break;
+                }
+
+                case value_t::number_integer:
+                {
+                    number_integer = number_integer_t(0);
+                    break;
+                }
+
+                case value_t::number_unsigned:
+                {
+                    number_unsigned = number_unsigned_t(0);
+                    break;
+                }
+
+                case value_t::number_float:
+                {
+                    number_float = number_float_t(0.0);
+                    break;
+                }
+
+                default:
+                {
+                    break;
+                }
+            }
+        }
+
+        /// constructor for strings
+        json_value(const string_t& value)
+        {
+            string = create<string_t>(value);
+        }
+
+        /// constructor for objects
+        json_value(const object_t& value)
+        {
+            object = create<object_t>(value);
+        }
+
+        /// constructor for arrays
+        json_value(const array_t& value)
+        {
+            array = create<array_t>(value);
+        }
+    };
+
+    /*!
+    @brief checks the class invariants
+
+    This function asserts the class invariants. It needs to be called at the
+    end of every constructor to make sure that created objects respect the
+    invariant. Furthermore, it has to be called each time the type of a JSON
+    value is changed, because the invariant expresses a relationship between
+    @a m_type and @a m_value.
+    */
+    void assert_invariant() const
+    {
+        assert(m_type != value_t::object or m_value.object != nullptr);
+        assert(m_type != value_t::array or m_value.array != nullptr);
+        assert(m_type != value_t::string or m_value.string != nullptr);
+    }
+
+  public:
+    //////////////////////////
+    // JSON parser callback //
+    //////////////////////////
+
+    /*!
+    @brief JSON callback events
+
+    This enumeration lists the parser events that can trigger calling a
+    callback function of type @ref parser_callback_t during parsing.
+
+    @image html callback_events.png "Example when certain parse events are triggered"
+
+    @since version 1.0.0
+    */
+    enum class parse_event_t : uint8_t
+    {
+        /// the parser read `{` and started to process a JSON object
+        object_start,
+        /// the parser read `}` and finished processing a JSON object
+        object_end,
+        /// the parser read `[` and started to process a JSON array
+        array_start,
+        /// the parser read `]` and finished processing a JSON array
+        array_end,
+        /// the parser read a key of a value in an object
+        key,
+        /// the parser finished reading a JSON value
+        value
+    };
+
+    /*!
+    @brief per-element parser callback type
+
+    With a parser callback function, the result of parsing a JSON text can be
+    influenced. When passed to @ref parse(std::istream&, const
+    parser_callback_t) or @ref parse(const char*, const parser_callback_t),
+    it is called on certain events (passed as @ref parse_event_t via parameter
+    @a event) with a set recursion depth @a depth and context JSON value
+    @a parsed. The return value of the callback function is a boolean
+    indicating whether the element that emitted the callback shall be kept or
+    not.
+
+    We distinguish six scenarios (determined by the event type) in which the
+    callback function can be called. The following table describes the values
+    of the parameters @a depth, @a event, and @a parsed.
+
+    parameter @a event | description | parameter @a depth | parameter @a parsed
+    ------------------ | ----------- | ------------------ | -------------------
+    parse_event_t::object_start | the parser read `{` and started to process a JSON object | depth of the parent of the JSON object | a JSON value with type discarded
+    parse_event_t::key | the parser read a key of a value in an object | depth of the currently parsed JSON object | a JSON string containing the key
+    parse_event_t::object_end | the parser read `}` and finished processing a JSON object | depth of the parent of the JSON object | the parsed JSON object
+    parse_event_t::array_start | the parser read `[` and started to process a JSON array | depth of the parent of the JSON array | a JSON value with type discarded
+    parse_event_t::array_end | the parser read `]` and finished processing a JSON array | depth of the parent of the JSON array | the parsed JSON array
+    parse_event_t::value | the parser finished reading a JSON value | depth of the value | the parsed JSON value
+
+    @image html callback_events.png "Example when certain parse events are triggered"
+
+    Discarding a value (i.e., returning `false`) has different effects
+    depending on the context in which function was called:
+
+    - Discarded values in structured types are skipped. That is, the parser
+      will behave as if the discarded value was never read.
+    - In case a value outside a structured type is skipped, it is replaced
+      with `null`. This case happens if the top-level element is skipped.
+
+    @param[in] depth  the depth of the recursion during parsing
+
+    @param[in] event  an event of type parse_event_t indicating the context in
+    the callback function has been called
+
+    @param[in,out] parsed  the current intermediate parse result; note that
+    writing to this value has no effect for parse_event_t::key events
+
+    @return Whether the JSON value which called the function during parsing
+    should be kept (`true`) or not (`false`). In the latter case, it is either
+    skipped completely or replaced by an empty discarded object.
+
+    @sa @ref parse(std::istream&, parser_callback_t) or
+    @ref parse(const char*, parser_callback_t) for examples
+
+    @since version 1.0.0
+    */
+    using parser_callback_t = std::function<bool(int depth,
+                              parse_event_t event,
+                              basic_json& parsed)>;
+
+
+    //////////////////
+    // constructors //
+    //////////////////
+
+    /// @name constructors and destructors
+    /// Constructors of class @ref basic_json, copy/move constructor, copy
+    /// assignment, static functions creating objects, and the destructor.
+    /// @{
+
+    /*!
+    @brief create an empty value with a given type
+
+    Create an empty JSON value with a given type. The value will be default
+    initialized with an empty value which depends on the type:
+
+    Value type  | initial value
+    ----------- | -------------
+    null        | `null`
+    boolean     | `false`
+    string      | `""`
+    number      | `0`
+    object      | `{}`
+    array       | `[]`
+
+    @param[in] value_type  the type of the value to create
+
+    @complexity Constant.
+
+    @throw std::bad_alloc if allocation for object, array, or string value
+    fails
+
+    @liveexample{The following code shows the constructor for different @ref
+    value_t values,basic_json__value_t}
+
+    @sa @ref basic_json(std::nullptr_t) -- create a `null` value
+    @sa @ref basic_json(boolean_t value) -- create a boolean value
+    @sa @ref basic_json(const string_t&) -- create a string value
+    @sa @ref basic_json(const object_t&) -- create a object value
+    @sa @ref basic_json(const array_t&) -- create a array value
+    @sa @ref basic_json(const number_float_t) -- create a number
+    (floating-point) value
+    @sa @ref basic_json(const number_integer_t) -- create a number (integer)
+    value
+    @sa @ref basic_json(const number_unsigned_t) -- create a number (unsigned)
+    value
+
+    @since version 1.0.0
+    */
+    basic_json(const value_t value_type)
+        : m_type(value_type), m_value(value_type)
+    {
+        assert_invariant();
+    }
+
+    /*!
+    @brief create a null object
+
+    Create a `null` JSON value. It either takes a null pointer as parameter
+    (explicitly creating `null`) or no parameter (implicitly creating `null`).
+    The passed null pointer itself is not read -- it is only used to choose
+    the right constructor.
+
+    @complexity Constant.
+
+    @exceptionsafety No-throw guarantee: this constructor never throws
+    exceptions.
+
+    @liveexample{The following code shows the constructor with and without a
+    null pointer parameter.,basic_json__nullptr_t}
+
+    @since version 1.0.0
+    */
+    basic_json(std::nullptr_t = nullptr) noexcept
+        : basic_json(value_t::null)
+    {
+        assert_invariant();
+    }
+
+    /*!
+    @brief create an object (explicit)
+
+    Create an object JSON value with a given content.
+
+    @param[in] val  a value for the object
+
+    @complexity Linear in the size of the passed @a val.
+
+    @throw std::bad_alloc if allocation for object value fails
+
+    @liveexample{The following code shows the constructor with an @ref
+    object_t parameter.,basic_json__object_t}
+
+    @sa @ref basic_json(const CompatibleObjectType&) -- create an object value
+    from a compatible STL container
+
+    @since version 1.0.0
+    */
+    basic_json(const object_t& val)
+        : m_type(value_t::object), m_value(val)
+    {
+        assert_invariant();
+    }
+
+    /*!
+    @brief create an object (implicit)
+
+    Create an object JSON value with a given content. This constructor allows
+    any type @a CompatibleObjectType that can be used to construct values of
+    type @ref object_t.
+
+    @tparam CompatibleObjectType An object type whose `key_type` and
+    `value_type` is compatible to @ref object_t. Examples include `std::map`,
+    `std::unordered_map`, `std::multimap`, and `std::unordered_multimap` with
+    a `key_type` of `std::string`, and a `value_type` from which a @ref
+    basic_json value can be constructed.
+
+    @param[in] val  a value for the object
+
+    @complexity Linear in the size of the passed @a val.
+
+    @throw std::bad_alloc if allocation for object value fails
+
+    @liveexample{The following code shows the constructor with several
+    compatible object type parameters.,basic_json__CompatibleObjectType}
+
+    @sa @ref basic_json(const object_t&) -- create an object value
+
+    @since version 1.0.0
+    */
+    template<class CompatibleObjectType, typename std::enable_if<
+                 std::is_constructible<typename object_t::key_type, typename CompatibleObjectType::key_type>::value and
+                 std::is_constructible<basic_json, typename CompatibleObjectType::mapped_type>::value, int>::type = 0>
+    basic_json(const CompatibleObjectType& val)
+        : m_type(value_t::object)
+    {
+        using std::begin;
+        using std::end;
+        m_value.object = create<object_t>(begin(val), end(val));
+        assert_invariant();
+    }
+
+    /*!
+    @brief create an array (explicit)
+
+    Create an array JSON value with a given content.
+
+    @param[in] val  a value for the array
+
+    @complexity Linear in the size of the passed @a val.
+
+    @throw std::bad_alloc if allocation for array value fails
+
+    @liveexample{The following code shows the constructor with an @ref array_t
+    parameter.,basic_json__array_t}
+
+    @sa @ref basic_json(const CompatibleArrayType&) -- create an array value
+    from a compatible STL containers
+
+    @since version 1.0.0
+    */
+    basic_json(const array_t& val)
+        : m_type(value_t::array), m_value(val)
+    {
+        assert_invariant();
+    }
+
+    /*!
+    @brief create an array (implicit)
+
+    Create an array JSON value with a given content. This constructor allows
+    any type @a CompatibleArrayType that can be used to construct values of
+    type @ref array_t.
+
+    @tparam CompatibleArrayType An object type whose `value_type` is
+    compatible to @ref array_t. Examples include `std::vector`, `std::deque`,
+    `std::list`, `std::forward_list`, `std::array`, `std::set`,
+    `std::unordered_set`, `std::multiset`, and `unordered_multiset` with a
+    `value_type` from which a @ref basic_json value can be constructed.
+
+    @param[in] val  a value for the array
+
+    @complexity Linear in the size of the passed @a val.
+
+    @throw std::bad_alloc if allocation for array value fails
+
+    @liveexample{The following code shows the constructor with several
+    compatible array type parameters.,basic_json__CompatibleArrayType}
+
+    @sa @ref basic_json(const array_t&) -- create an array value
+
+    @since version 1.0.0
+    */
+    template<class CompatibleArrayType, typename std::enable_if<
+                 not std::is_same<CompatibleArrayType, typename basic_json_t::iterator>::value and
+                 not std::is_same<CompatibleArrayType, typename basic_json_t::const_iterator>::value and
+                 not std::is_same<CompatibleArrayType, typename basic_json_t::reverse_iterator>::value and
+                 not std::is_same<CompatibleArrayType, typename basic_json_t::const_reverse_iterator>::value and
+                 not std::is_same<CompatibleArrayType, typename array_t::iterator>::value and
+                 not std::is_same<CompatibleArrayType, typename array_t::const_iterator>::value and
+                 std::is_constructible<basic_json, typename CompatibleArrayType::value_type>::value, int>::type = 0>
+    basic_json(const CompatibleArrayType& val)
+        : m_type(value_t::array)
+    {
+        using std::begin;
+        using std::end;
+        m_value.array = create<array_t>(begin(val), end(val));
+        assert_invariant();
+    }
+
+    /*!
+    @brief create a string (explicit)
+
+    Create an string JSON value with a given content.
+
+    @param[in] val  a value for the string
+
+    @complexity Linear in the size of the passed @a val.
+
+    @throw std::bad_alloc if allocation for string value fails
+
+    @liveexample{The following code shows the constructor with an @ref
+    string_t parameter.,basic_json__string_t}
+
+    @sa @ref basic_json(const typename string_t::value_type*) -- create a
+    string value from a character pointer
+    @sa @ref basic_json(const CompatibleStringType&) -- create a string value
+    from a compatible string container
+
+    @since version 1.0.0
+    */
+    basic_json(const string_t& val)
+        : m_type(value_t::string), m_value(val)
+    {
+        assert_invariant();
+    }
+
+    /*!
+    @brief create a string (explicit)
+
+    Create a string JSON value with a given content.
+
+    @param[in] val  a literal value for the string
+
+    @complexity Linear in the size of the passed @a val.
+
+    @throw std::bad_alloc if allocation for string value fails
+
+    @liveexample{The following code shows the constructor with string literal
+    parameter.,basic_json__string_t_value_type}
+
+    @sa @ref basic_json(const string_t&) -- create a string value
+    @sa @ref basic_json(const CompatibleStringType&) -- create a string value
+    from a compatible string container
+
+    @since version 1.0.0
+    */
+    basic_json(const typename string_t::value_type* val)
+        : basic_json(string_t(val))
+    {
+        assert_invariant();
+    }
+
+    basic_json(const typename string_t::value_type* val, typename string_t::size_type count)
+        : basic_json(string_t(val, count))
+    {
+        assert_invariant();
+    }
+
+    /*!
+    @brief create a string (implicit)
+
+    Create a string JSON value with a given content.
+
+    @param[in] val  a value for the string
+
+    @tparam CompatibleStringType an string type which is compatible to @ref
+    string_t, for instance `std::string`.
+
+    @complexity Linear in the size of the passed @a val.
+
+    @throw std::bad_alloc if allocation for string value fails
+
+    @liveexample{The following code shows the construction of a string value
+    from a compatible type.,basic_json__CompatibleStringType}
+
+    @sa @ref basic_json(const string_t&) -- create a string value
+    @sa @ref basic_json(const typename string_t::value_type*) -- create a
+    string value from a character pointer
+
+    @since version 1.0.0
+    */
+    template<class CompatibleStringType, typename std::enable_if<
+                 std::is_constructible<string_t, CompatibleStringType>::value, int>::type = 0>
+    basic_json(const CompatibleStringType& val)
+        : basic_json(string_t(val))
+    {
+        assert_invariant();
+    }
+
+    /*!
+    @brief create a boolean (explicit)
+
+    Creates a JSON boolean type from a given value.
+
+    @param[in] val  a boolean value to store
+
+    @complexity Constant.
+
+    @liveexample{The example below demonstrates boolean
+    values.,basic_json__boolean_t}
+
+    @since version 1.0.0
+    */
+    basic_json(boolean_t val) noexcept
+        : m_type(value_t::boolean), m_value(val)
+    {
+        assert_invariant();
+    }
+
+    /*!
+    @brief create an integer number (explicit)
+
+    Create an integer number JSON value with a given content.
+
+    @tparam T A helper type to remove this function via SFINAE in case @ref
+    number_integer_t is the same as `int`. In this case, this constructor
+    would have the same signature as @ref basic_json(const int value). Note
+    the helper type @a T is not visible in this constructor's interface.
+
+    @param[in] val  an integer to create a JSON number from
+
+    @complexity Constant.
+
+    @liveexample{The example below shows the construction of an integer
+    number value.,basic_json__number_integer_t}
+
+    @sa @ref basic_json(const int) -- create a number value (integer)
+    @sa @ref basic_json(const CompatibleNumberIntegerType) -- create a number
+    value (integer) from a compatible number type
+
+    @since version 1.0.0
+    */
+    template<typename T, typename std::enable_if<
+                 not (std::is_same<T, int>::value) and
+                 std::is_same<T, number_integer_t>::value, int>::type = 0>
+    basic_json(const number_integer_t val) noexcept
+        : m_type(value_t::number_integer), m_value(val)
+    {
+        assert_invariant();
+    }
+
+    /*!
+    @brief create an integer number from an enum type (explicit)
+
+    Create an integer number JSON value with a given content.
+
+    @param[in] val  an integer to create a JSON number from
+
+    @note This constructor allows to pass enums directly to a constructor. As
+    C++ has no way of specifying the type of an anonymous enum explicitly, we
+    can only rely on the fact that such values implicitly convert to int. As
+    int may already be the same type of number_integer_t, we may need to
+    switch off the constructor @ref basic_json(const number_integer_t).
+
+    @complexity Constant.
+
+    @liveexample{The example below shows the construction of an integer
+    number value from an anonymous enum.,basic_json__const_int}
+
+    @sa @ref basic_json(const number_integer_t) -- create a number value
+    (integer)
+    @sa @ref basic_json(const CompatibleNumberIntegerType) -- create a number
+    value (integer) from a compatible number type
+
+    @since version 1.0.0
+    */
+    basic_json(const int val) noexcept
+        : m_type(value_t::number_integer),
+          m_value(static_cast<number_integer_t>(val))
+    {
+        assert_invariant();
+    }
+
+    /*!
+    @brief create an integer number (implicit)
+
+    Create an integer number JSON value with a given content. This constructor
+    allows any type @a CompatibleNumberIntegerType that can be used to
+    construct values of type @ref number_integer_t.
+
+    @tparam CompatibleNumberIntegerType An integer type which is compatible to
+    @ref number_integer_t. Examples include the types `int`, `int32_t`,
+    `long`, and `short`.
+
+    @param[in] val  an integer to create a JSON number from
+
+    @complexity Constant.
+
+    @liveexample{The example below shows the construction of several integer
+    number values from compatible
+    types.,basic_json__CompatibleIntegerNumberType}
+
+    @sa @ref basic_json(const number_integer_t) -- create a number value
+    (integer)
+    @sa @ref basic_json(const int) -- create a number value (integer)
+
+    @since version 1.0.0
+    */
+    template<typename CompatibleNumberIntegerType, typename std::enable_if<
+                 std::is_constructible<number_integer_t, CompatibleNumberIntegerType>::value and
+                 std::numeric_limits<CompatibleNumberIntegerType>::is_integer and
+                 std::numeric_limits<CompatibleNumberIntegerType>::is_signed,
+                 CompatibleNumberIntegerType>::type = 0>
+    basic_json(const CompatibleNumberIntegerType val) noexcept
+        : m_type(value_t::number_integer),
+          m_value(static_cast<number_integer_t>(val))
+    {
+        assert_invariant();
+    }
+
+    /*!
+    @brief create an unsigned integer number (explicit)
+
+    Create an unsigned integer number JSON value with a given content.
+
+    @tparam T  helper type to compare number_unsigned_t and unsigned int (not
+    visible in) the interface.
+
+    @param[in] val  an integer to create a JSON number from
+
+    @complexity Constant.
+
+    @sa @ref basic_json(const CompatibleNumberUnsignedType) -- create a number
+    value (unsigned integer) from a compatible number type
+
+    @since version 2.0.0
+    */
+    template<typename T, typename std::enable_if<
+                 not (std::is_same<T, int>::value) and
+                 std::is_same<T, number_unsigned_t>::value, int>::type = 0>
+    basic_json(const number_unsigned_t val) noexcept
+        : m_type(value_t::number_unsigned), m_value(val)
+    {
+        assert_invariant();
+    }
+
+    /*!
+    @brief create an unsigned number (implicit)
+
+    Create an unsigned number JSON value with a given content. This
+    constructor allows any type @a CompatibleNumberUnsignedType that can be
+    used to construct values of type @ref number_unsigned_t.
+
+    @tparam CompatibleNumberUnsignedType An integer type which is compatible
+    to @ref number_unsigned_t. Examples may include the types `unsigned int`,
+    `uint32_t`, or `unsigned short`.
+
+    @param[in] val  an unsigned integer to create a JSON number from
+
+    @complexity Constant.
+
+    @sa @ref basic_json(const number_unsigned_t) -- create a number value
+    (unsigned)
+
+    @since version 2.0.0
+    */
+    template<typename CompatibleNumberUnsignedType, typename std::enable_if <
+                 std::is_constructible<number_unsigned_t, CompatibleNumberUnsignedType>::value and
+                 std::numeric_limits<CompatibleNumberUnsignedType>::is_integer and
+                 not std::numeric_limits<CompatibleNumberUnsignedType>::is_signed,
+                 CompatibleNumberUnsignedType>::type = 0>
+    basic_json(const CompatibleNumberUnsignedType val) noexcept
+        : m_type(value_t::number_unsigned),
+          m_value(static_cast<number_unsigned_t>(val))
+    {
+        assert_invariant();
+    }
+
+    /*!
+    @brief create a floating-point number (explicit)
+
+    Create a floating-point number JSON value with a given content.
+
+    @param[in] val  a floating-point value to create a JSON number from
+
+    @note [RFC 7159](http://www.rfc-editor.org/rfc/rfc7159.txt), section 6
+    disallows NaN values:
+    > Numeric values that cannot be represented in the grammar below (such as
+    > Infinity and NaN) are not permitted.
+    In case the parameter @a val is not a number, a JSON null value is created
+    instead.
+
+    @complexity Constant.
+
+    @liveexample{The following example creates several floating-point
+    values.,basic_json__number_float_t}
+
+    @sa @ref basic_json(const CompatibleNumberFloatType) -- create a number
+    value (floating-point) from a compatible number type
+
+    @since version 1.0.0
+    */
+    basic_json(const number_float_t val) noexcept
+        : m_type(value_t::number_float), m_value(val)
+    {
+        // replace infinity and NAN by null
+        if (not std::isfinite(val))
+        {
+            m_type = value_t::null;
+            m_value = json_value();
+        }
+
+        assert_invariant();
+    }
+
+    /*!
+    @brief create an floating-point number (implicit)
+
+    Create an floating-point number JSON value with a given content. This
+    constructor allows any type @a CompatibleNumberFloatType that can be used
+    to construct values of type @ref number_float_t.
+
+    @tparam CompatibleNumberFloatType A floating-point type which is
+    compatible to @ref number_float_t. Examples may include the types `float`
+    or `double`.
+
+    @param[in] val  a floating-point to create a JSON number from
+
+    @note [RFC 7159](http://www.rfc-editor.org/rfc/rfc7159.txt), section 6
+    disallows NaN values:
+    > Numeric values that cannot be represented in the grammar below (such as
+    > Infinity and NaN) are not permitted.
+    In case the parameter @a val is not a number, a JSON null value is
+    created instead.
+
+    @complexity Constant.
+
+    @liveexample{The example below shows the construction of several
+    floating-point number values from compatible
+    types.,basic_json__CompatibleNumberFloatType}
+
+    @sa @ref basic_json(const number_float_t) -- create a number value
+    (floating-point)
+
+    @since version 1.0.0
+    */
+    template<typename CompatibleNumberFloatType, typename = typename std::enable_if<
+                 std::is_constructible<number_float_t, CompatibleNumberFloatType>::value and
+                 std::is_floating_point<CompatibleNumberFloatType>::value>::type>
+    basic_json(const CompatibleNumberFloatType val) noexcept
+        : basic_json(number_float_t(val))
+    {
+        assert_invariant();
+    }
+
+    /*!
+    @brief create a container (array or object) from an initializer list
+
+    Creates a JSON value of type array or object from the passed initializer
+    list @a init. In case @a type_deduction is `true` (default), the type of
+    the JSON value to be created is deducted from the initializer list @a init
+    according to the following rules:
+
+    1. If the list is empty, an empty JSON object value `{}` is created.
+    2. If the list consists of pairs whose first element is a string, a JSON
+       object value is created where the first elements of the pairs are
+       treated as keys and the second elements are as values.
+    3. In all other cases, an array is created.
+
+    The rules aim to create the best fit between a C++ initializer list and
+    JSON values. The rationale is as follows:
+
+    1. The empty initializer list is written as `{}` which is exactly an empty
+       JSON object.
+    2. C++ has now way of describing mapped types other than to list a list of
+       pairs. As JSON requires that keys must be of type string, rule 2 is the
+       weakest constraint one can pose on initializer lists to interpret them
+       as an object.
+    3. In all other cases, the initializer list could not be interpreted as
+       JSON object type, so interpreting it as JSON array type is safe.
+
+    With the rules described above, the following JSON values cannot be
+    expressed by an initializer list:
+
+    - the empty array (`[]`): use @ref array(std::initializer_list<basic_json>)
+      with an empty initializer list in this case
+    - arrays whose elements satisfy rule 2: use @ref
+      array(std::initializer_list<basic_json>) with the same initializer list
+      in this case
+
+    @note When used without parentheses around an empty initializer list, @ref
+    basic_json() is called instead of this function, yielding the JSON null
+    value.
+
+    @param[in] init  initializer list with JSON values
+
+    @param[in] type_deduction internal parameter; when set to `true`, the type
+    of the JSON value is deducted from the initializer list @a init; when set
+    to `false`, the type provided via @a manual_type is forced. This mode is
+    used by the functions @ref array(std::initializer_list<basic_json>) and
+    @ref object(std::initializer_list<basic_json>).
+
+    @param[in] manual_type internal parameter; when @a type_deduction is set
+    to `false`, the created JSON value will use the provided type (only @ref
+    value_t::array and @ref value_t::object are valid); when @a type_deduction
+    is set to `true`, this parameter has no effect
+
+    @throw std::domain_error if @a type_deduction is `false`, @a manual_type
+    is `value_t::object`, but @a init contains an element which is not a pair
+    whose first element is a string; example: `"cannot create object from
+    initializer list"`
+
+    @complexity Linear in the size of the initializer list @a init.
+
+    @liveexample{The example below shows how JSON values are created from
+    initializer lists.,basic_json__list_init_t}
+
+    @sa @ref array(std::initializer_list<basic_json>) -- create a JSON array
+    value from an initializer list
+    @sa @ref object(std::initializer_list<basic_json>) -- create a JSON object
+    value from an initializer list
+
+    @since version 1.0.0
+    */
+    basic_json(std::initializer_list<basic_json> init,
+               bool type_deduction = true,
+               value_t manual_type = value_t::array)
+    {
+        // check if each element is an array with two elements whose first
+        // element is a string
+        bool is_an_object = std::all_of(init.begin(), init.end(),
+                                        [](const basic_json & element)
+        {
+            return element.is_array() and element.size() == 2 and element[0].is_string();
+        });
+
+        // adjust type if type deduction is not wanted
+        if (not type_deduction)
+        {
+            // if array is wanted, do not create an object though possible
+            if (manual_type == value_t::array)
+            {
+                is_an_object = false;
+            }
+
+            // if object is wanted but impossible, throw an exception
+            if (manual_type == value_t::object and not is_an_object)
+            {
+                Throw<std::domain_error>("cannot create object from initializer list");
+            }
+        }
+
+        if (is_an_object)
+        {
+            // the initializer list is a list of pairs -> create object
+            m_type = value_t::object;
+            m_value = value_t::object;
+
+            std::for_each(init.begin(), init.end(), [this](const basic_json & element)
+            {
+                m_value.object->emplace(*(element[0].m_value.string), element[1]);
+            });
+        }
+        else
+        {
+            // the initializer list describes an array -> create array
+            m_type = value_t::array;
+            m_value.array = create<array_t>(init);
+        }
+
+        assert_invariant();
+    }
+
+    /*!
+    @brief explicitly create an array from an initializer list
+
+    Creates a JSON array value from a given initializer list. That is, given a
+    list of values `a, b, c`, creates the JSON value `[a, b, c]`. If the
+    initializer list is empty, the empty array `[]` is created.
+
+    @note This function is only needed to express two edge cases that cannot
+    be realized with the initializer list constructor (@ref
+    basic_json(std::initializer_list<basic_json>, bool, value_t)). These cases
+    are:
+    1. creating an array whose elements are all pairs whose first element is a
+    string -- in this case, the initializer list constructor would create an
+    object, taking the first elements as keys
+    2. creating an empty array -- passing the empty initializer list to the
+    initializer list constructor yields an empty object
+
+    @param[in] init  initializer list with JSON values to create an array from
+    (optional)
+
+    @return JSON array value
+
+    @complexity Linear in the size of @a init.
+
+    @liveexample{The following code shows an example for the `array`
+    function.,array}
+
+    @sa @ref basic_json(std::initializer_list<basic_json>, bool, value_t) --
+    create a JSON value from an initializer list
+    @sa @ref object(std::initializer_list<basic_json>) -- create a JSON object
+    value from an initializer list
+
+    @since version 1.0.0
+    */
+    static basic_json array(std::initializer_list<basic_json> init =
+                                std::initializer_list<basic_json>())
+    {
+        return basic_json(init, false, value_t::array);
+    }
+
+    /*!
+    @brief explicitly create an object from an initializer list
+
+    Creates a JSON object value from a given initializer list. The initializer
+    lists elements must be pairs, and their first elements must be strings. If
+    the initializer list is empty, the empty object `{}` is created.
+
+    @note This function is only added for symmetry reasons. In contrast to the
+    related function @ref array(std::initializer_list<basic_json>), there are
+    no cases which can only be expressed by this function. That is, any
+    initializer list @a init can also be passed to the initializer list
+    constructor @ref basic_json(std::initializer_list<basic_json>, bool,
+    value_t).
+
+    @param[in] init  initializer list to create an object from (optional)
+
+    @return JSON object value
+
+    @throw std::domain_error if @a init is not a pair whose first elements are
+    strings; thrown by
+    @ref basic_json(std::initializer_list<basic_json>, bool, value_t)
+
+    @complexity Linear in the size of @a init.
+
+    @liveexample{The following code shows an example for the `object`
+    function.,object}
+
+    @sa @ref basic_json(std::initializer_list<basic_json>, bool, value_t) --
+    create a JSON value from an initializer list
+    @sa @ref array(std::initializer_list<basic_json>) -- create a JSON array
+    value from an initializer list
+
+    @since version 1.0.0
+    */
+    static basic_json object(std::initializer_list<basic_json> init =
+                                 std::initializer_list<basic_json>())
+    {
+        return basic_json(init, false, value_t::object);
+    }
+
+    /*!
+    @brief construct an array with count copies of given value
+
+    Constructs a JSON array value by creating @a cnt copies of a passed value.
+    In case @a cnt is `0`, an empty array is created. As postcondition,
+    `std::distance(begin(),end()) == cnt` holds.
+
+    @param[in] cnt  the number of JSON copies of @a val to create
+    @param[in] val  the JSON value to copy
+
+    @complexity Linear in @a cnt.
+
+    @liveexample{The following code shows examples for the @ref
+    basic_json(size_type\, const basic_json&)
+    constructor.,basic_json__size_type_basic_json}
+
+    @since version 1.0.0
+    */
+    basic_json(size_type cnt, const basic_json& val)
+        : m_type(value_t::array)
+    {
+        m_value.array = create<array_t>(cnt, val);
+        assert_invariant();
+    }
+
+    /*!
+    @brief construct a JSON container given an iterator range
+
+    Constructs the JSON value with the contents of the range `[first, last)`.
+    The semantics depends on the different types a JSON value can have:
+    - In case of primitive types (number, boolean, or string), @a first must
+      be `begin()` and @a last must be `end()`. In this case, the value is
+      copied. Otherwise, std::out_of_range is thrown.
+    - In case of structured types (array, object), the constructor behaves as
+      similar versions for `std::vector`.
+    - In case of a null type, std::domain_error is thrown.
+
+    @tparam InputIT an input iterator type (@ref iterator or @ref
+    const_iterator)
+
+    @param[in] first begin of the range to copy from (included)
+    @param[in] last end of the range to copy from (excluded)
+
+    @pre Iterators @a first and @a last must be initialized. **This
+         precondition is enforced with an assertion.**
+
+    @throw std::domain_error if iterators are not compatible; that is, do not
+    belong to the same JSON value; example: `"iterators are not compatible"`
+    @throw std::out_of_range if iterators are for a primitive type (number,
+    boolean, or string) where an out of range error can be detected easily;
+    example: `"iterators out of range"`
+    @throw std::bad_alloc if allocation for object, array, or string fails
+    @throw std::domain_error if called with a null value; example: `"cannot
+    use construct with iterators from null"`
+
+    @complexity Linear in distance between @a first and @a last.
+
+    @liveexample{The example below shows several ways to create JSON values by
+    specifying a subrange with iterators.,basic_json__InputIt_InputIt}
+
+    @since version 1.0.0
+    */
+    template<class InputIT, typename std::enable_if<
+                 std::is_same<InputIT, typename basic_json_t::iterator>::value or
+                 std::is_same<InputIT, typename basic_json_t::const_iterator>::value, int>::type = 0>
+    basic_json(InputIT first, InputIT last)
+    {
+        assert(first.m_object != nullptr);
+        assert(last.m_object != nullptr);
+
+        // make sure iterator fits the current value
+        if (first.m_object != last.m_object)
+        {
+            Throw<std::domain_error>("iterators are not compatible");
+        }
+
+        // copy type from first iterator
+        m_type = first.m_object->m_type;
+
+        // check if iterator range is complete for primitive values
+        switch (m_type)
+        {
+            case value_t::boolean:
+            case value_t::number_float:
+            case value_t::number_integer:
+            case value_t::number_unsigned:
+            case value_t::string:
+            {
+                if (not first.m_it.primitive_iterator.is_begin() or not last.m_it.primitive_iterator.is_end())
+                {
+                    Throw<std::out_of_range>("iterators out of range");
+                }
+                break;
+            }
+
+            default:
+            {
+                break;
+            }
+        }
+
+        switch (m_type)
+        {
+            case value_t::number_integer:
+            {
+                m_value.number_integer = first.m_object->m_value.number_integer;
+                break;
+            }
+
+            case value_t::number_unsigned:
+            {
+                m_value.number_unsigned = first.m_object->m_value.number_unsigned;
+                break;
+            }
+
+            case value_t::number_float:
+            {
+                m_value.number_float = first.m_object->m_value.number_float;
+                break;
+            }
+
+            case value_t::boolean:
+            {
+                m_value.boolean = first.m_object->m_value.boolean;
+                break;
+            }
+
+            case value_t::string:
+            {
+                m_value = *first.m_object->m_value.string;
+                break;
+            }
+
+            case value_t::object:
+            {
+                m_value.object = create<object_t>(first.m_it.object_iterator, last.m_it.object_iterator);
+                break;
+            }
+
+            case value_t::array:
+            {
+                m_value.array = create<array_t>(first.m_it.array_iterator, last.m_it.array_iterator);
+                break;
+            }
+
+            default:
+            {
+                Throw<std::domain_error>("cannot use construct with iterators from " + first.m_object->type_name());
+            }
+        }
+
+        assert_invariant();
+    }
+
+    /*!
+    @brief construct a JSON value given an input stream
+
+    @param[in,out] i  stream to read a serialized JSON value from
+    @param[in] cb a parser callback function of type @ref parser_callback_t
+    which is used to control the deserialization by filtering unwanted values
+    (optional)
+
+    @complexity Linear in the length of the input. The parser is a predictive
+    LL(1) parser. The complexity can be higher if the parser callback function
+    @a cb has a super-linear complexity.
+
+    @note A UTF-8 byte order mark is silently ignored.
+
+    @deprecated This constructor is deprecated and will be removed in version
+      3.0.0 to unify the interface of the library. Deserialization will be
+      done by stream operators or by calling one of the `parse` functions,
+      e.g. @ref parse(std::istream&, const parser_callback_t). That is, calls
+      like `json j(i);` for an input stream @a i need to be replaced by
+      `json j = json::parse(i);`. See the example below.
+
+    @liveexample{The example below demonstrates constructing a JSON value from
+    a `std::stringstream` with and without callback
+    function.,basic_json__istream}
+
+    @since version 2.0.0, deprecated in version 2.0.3, to be removed in
+           version 3.0.0
+    */
+    JSON_DEPRECATED
+    explicit basic_json(std::istream& i, const parser_callback_t cb = nullptr)
+    {
+        *this = parser(i, cb).parse();
+        assert_invariant();
+    }
+
+    ///////////////////////////////////////
+    // other constructors and destructor //
+    ///////////////////////////////////////
+
+    /*!
+    @brief copy constructor
+
+    Creates a copy of a given JSON value.
+
+    @param[in] other  the JSON value to copy
+
+    @complexity Linear in the size of @a other.
+
+    @requirement This function helps `basic_json` satisfying the
+    [Container](http://en.cppreference.com/w/cpp/concept/Container)
+    requirements:
+    - The complexity is linear.
+    - As postcondition, it holds: `other == basic_json(other)`.
+
+    @throw std::bad_alloc if allocation for object, array, or string fails.
+
+    @liveexample{The following code shows an example for the copy
+    constructor.,basic_json__basic_json}
+
+    @since version 1.0.0
+    */
+    basic_json(const basic_json& other)
+        : m_type(other.m_type)
+    {
+        // check of passed value is valid
+        other.assert_invariant();
+
+        switch (m_type)
+        {
+            case value_t::object:
+            {
+                m_value = *other.m_value.object;
+                break;
+            }
+
+            case value_t::array:
+            {
+                m_value = *other.m_value.array;
+                break;
+            }
+
+            case value_t::string:
+            {
+                m_value = *other.m_value.string;
+                break;
+            }
+
+            case value_t::boolean:
+            {
+                m_value = other.m_value.boolean;
+                break;
+            }
+
+            case value_t::number_integer:
+            {
+                m_value = other.m_value.number_integer;
+                break;
+            }
+
+            case value_t::number_unsigned:
+            {
+                m_value = other.m_value.number_unsigned;
+                break;
+            }
+
+            case value_t::number_float:
+            {
+                m_value = other.m_value.number_float;
+                break;
+            }
+
+            default:
+            {
+                break;
+            }
+        }
+
+        assert_invariant();
+    }
+
+    /*!
+    @brief move constructor
+
+    Move constructor. Constructs a JSON value with the contents of the given
+    value @a other using move semantics. It "steals" the resources from @a
+    other and leaves it as JSON null value.
+
+    @param[in,out] other  value to move to this object
+
+    @post @a other is a JSON null value
+
+    @complexity Constant.
+
+    @liveexample{The code below shows the move constructor explicitly called
+    via std::move.,basic_json__moveconstructor}
+
+    @since version 1.0.0
+    */
+    basic_json(basic_json&& other) noexcept
+        : m_type(std::move(other.m_type)),
+          m_value(std::move(other.m_value))
+    {
+        // check that passed value is valid
+        other.assert_invariant();
+
+        // invalidate payload
+        other.m_type = value_t::null;
+        other.m_value = {};
+
+        assert_invariant();
+    }
+
+    /*!
+    @brief copy assignment
+
+    Copy assignment operator. Copies a JSON value via the "copy and swap"
+    strategy: It is expressed in terms of the copy constructor, destructor,
+    and the swap() member function.
+
+    @param[in] other  value to copy from
+
+    @complexity Linear.
+
+    @requirement This function helps `basic_json` satisfying the
+    [Container](http://en.cppreference.com/w/cpp/concept/Container)
+    requirements:
+    - The complexity is linear.
+
+    @liveexample{The code below shows and example for the copy assignment. It
+    creates a copy of value `a` which is then swapped with `b`. Finally\, the
+    copy of `a` (which is the null value after the swap) is
+    destroyed.,basic_json__copyassignment}
+
+    @since version 1.0.0
+    */
+    reference& operator=(basic_json other) noexcept (
+        std::is_nothrow_move_constructible<value_t>::value and
+        std::is_nothrow_move_assignable<value_t>::value and
+        std::is_nothrow_move_constructible<json_value>::value and
+        std::is_nothrow_move_assignable<json_value>::value
+    )
+    {
+        // check that passed value is valid
+        other.assert_invariant();
+
+        using std::swap;
+        swap(m_type, other.m_type);
+        swap(m_value, other.m_value);
+
+        assert_invariant();
+        return *this;
+    }
+
+    /*!
+    @brief destructor
+
+    Destroys the JSON value and frees all allocated memory.
+
+    @complexity Linear.
+
+    @requirement This function helps `basic_json` satisfying the
+    [Container](http://en.cppreference.com/w/cpp/concept/Container)
+    requirements:
+    - The complexity is linear.
+    - All stored elements are destroyed and all memory is freed.
+
+    @since version 1.0.0
+    */
+    ~basic_json()
+    {
+        assert_invariant();
+
+        switch (m_type)
+        {
+            case value_t::object:
+            {
+                AllocatorType<object_t> alloc;
+                alloc.destroy(m_value.object);
+                alloc.deallocate(m_value.object, 1);
+                break;
+            }
+
+            case value_t::array:
+            {
+                AllocatorType<array_t> alloc;
+                alloc.destroy(m_value.array);
+                alloc.deallocate(m_value.array, 1);
+                break;
+            }
+
+            case value_t::string:
+            {
+                AllocatorType<string_t> alloc;
+                alloc.destroy(m_value.string);
+                alloc.deallocate(m_value.string, 1);
+                break;
+            }
+
+            default:
+            {
+                // all other types need no specific destructor
+                break;
+            }
+        }
+    }
+
+    /// @}
+
+  public:
+    ///////////////////////
+    // object inspection //
+    ///////////////////////
+
+    /// @name object inspection
+    /// Functions to inspect the type of a JSON value.
+    /// @{
+
+    /*!
+    @brief serialization
+
+    Serialization function for JSON values. The function tries to mimic
+    Python's `json.dumps()` function, and currently supports its @a indent
+    parameter.
+
+    @param[in] indent If indent is nonnegative, then array elements and object
+    members will be pretty-printed with that indent level. An indent level of
+    `0` will only insert newlines. `-1` (the default) selects the most compact
+    representation.
+
+    @return string containing the serialization of the JSON value
+
+    @complexity Linear.
+
+    @liveexample{The following example shows the effect of different @a indent
+    parameters to the result of the serialization.,dump}
+
+    @see https://docs.python.org/2/library/json.html#json.dump
+
+    @since version 1.0.0
+    */
+    string_t dump(const int indent = -1) const
+    {
+        std::stringstream ss;
+        // fix locale problems
+        ss.imbue(std::locale::classic());
+
+        // 6, 15 or 16 digits of precision allows round-trip IEEE 754
+        // string->float->string, string->double->string or string->long
+        // double->string; to be safe, we read this value from
+        // std::numeric_limits<number_float_t>::digits10
+        ss.precision(std::numeric_limits<double>::digits10);
+
+        if (indent >= 0)
+        {
+            dump(ss, true, static_cast<unsigned int>(indent));
+        }
+        else
+        {
+            dump(ss, false, 0);
+        }
+
+        return ss.str();
+    }
+
+    /*!
+    @brief return the type of the JSON value (explicit)
+
+    Return the type of the JSON value as a value from the @ref value_t
+    enumeration.
+
+    @return the type of the JSON value
+
+    @complexity Constant.
+
+    @exceptionsafety No-throw guarantee: this member function never throws
+    exceptions.
+
+    @liveexample{The following code exemplifies `type()` for all JSON
+    types.,type}
+
+    @since version 1.0.0
+    */
+    constexpr value_t type() const noexcept
+    {
+        return m_type;
+    }
+
+    /*!
+    @brief return whether type is primitive
+
+    This function returns true iff the JSON type is primitive (string, number,
+    boolean, or null).
+
+    @return `true` if type is primitive (string, number, boolean, or null),
+    `false` otherwise.
+
+    @complexity Constant.
+
+    @exceptionsafety No-throw guarantee: this member function never throws
+    exceptions.
+
+    @liveexample{The following code exemplifies `is_primitive()` for all JSON
+    types.,is_primitive}
+
+    @sa @ref is_structured() -- returns whether JSON value is structured
+    @sa @ref is_null() -- returns whether JSON value is `null`
+    @sa @ref is_string() -- returns whether JSON value is a string
+    @sa @ref is_boolean() -- returns whether JSON value is a boolean
+    @sa @ref is_number() -- returns whether JSON value is a number
+
+    @since version 1.0.0
+    */
+    constexpr bool is_primitive() const noexcept
+    {
+        return is_null() or is_string() or is_boolean() or is_number();
+    }
+
+    /*!
+    @brief return whether type is structured
+
+    This function returns true iff the JSON type is structured (array or
+    object).
+
+    @return `true` if type is structured (array or object), `false` otherwise.
+
+    @complexity Constant.
+
+    @exceptionsafety No-throw guarantee: this member function never throws
+    exceptions.
+
+    @liveexample{The following code exemplifies `is_structured()` for all JSON
+    types.,is_structured}
+
+    @sa @ref is_primitive() -- returns whether value is primitive
+    @sa @ref is_array() -- returns whether value is an array
+    @sa @ref is_object() -- returns whether value is an object
+
+    @since version 1.0.0
+    */
+    constexpr bool is_structured() const noexcept
+    {
+        return is_array() or is_object();
+    }
+
+    /*!
+    @brief return whether value is null
+
+    This function returns true iff the JSON value is null.
+
+    @return `true` if type is null, `false` otherwise.
+
+    @complexity Constant.
+
+    @exceptionsafety No-throw guarantee: this member function never throws
+    exceptions.
+
+    @liveexample{The following code exemplifies `is_null()` for all JSON
+    types.,is_null}
+
+    @since version 1.0.0
+    */
+    constexpr bool is_null() const noexcept
+    {
+        return m_type == value_t::null;
+    }
+
+    /*!
+    @brief return whether value is a boolean
+
+    This function returns true iff the JSON value is a boolean.
+
+    @return `true` if type is boolean, `false` otherwise.
+
+    @complexity Constant.
+
+    @exceptionsafety No-throw guarantee: this member function never throws
+    exceptions.
+
+    @liveexample{The following code exemplifies `is_boolean()` for all JSON
+    types.,is_boolean}
+
+    @since version 1.0.0
+    */
+    constexpr bool is_boolean() const noexcept
+    {
+        return m_type == value_t::boolean;
+    }
+
+    /*!
+    @brief return whether value is a number
+
+    This function returns true iff the JSON value is a number. This includes
+    both integer and floating-point values.
+
+    @return `true` if type is number (regardless whether integer, unsigned
+    integer or floating-type), `false` otherwise.
+
+    @complexity Constant.
+
+    @exceptionsafety No-throw guarantee: this member function never throws
+    exceptions.
+
+    @liveexample{The following code exemplifies `is_number()` for all JSON
+    types.,is_number}
+
+    @sa @ref is_number_integer() -- check if value is an integer or unsigned
+    integer number
+    @sa @ref is_number_unsigned() -- check if value is an unsigned integer
+    number
+    @sa @ref is_number_float() -- check if value is a floating-point number
+
+    @since version 1.0.0
+    */
+    constexpr bool is_number() const noexcept
+    {
+        return is_number_integer() or is_number_float();
+    }
+
+    /*!
+    @brief return whether value is an integer number
+
+    This function returns true iff the JSON value is an integer or unsigned
+    integer number. This excludes floating-point values.
+
+    @return `true` if type is an integer or unsigned integer number, `false`
+    otherwise.
+
+    @complexity Constant.
+
+    @exceptionsafety No-throw guarantee: this member function never throws
+    exceptions.
+
+    @liveexample{The following code exemplifies `is_number_integer()` for all
+    JSON types.,is_number_integer}
+
+    @sa @ref is_number() -- check if value is a number
+    @sa @ref is_number_unsigned() -- check if value is an unsigned integer
+    number
+    @sa @ref is_number_float() -- check if value is a floating-point number
+
+    @since version 1.0.0
+    */
+    constexpr bool is_number_integer() const noexcept
+    {
+        return m_type == value_t::number_integer or m_type == value_t::number_unsigned;
+    }
+
+    /*!
+    @brief return whether value is an unsigned integer number
+
+    This function returns true iff the JSON value is an unsigned integer
+    number. This excludes floating-point and (signed) integer values.
+
+    @return `true` if type is an unsigned integer number, `false` otherwise.
+
+    @complexity Constant.
+
+    @exceptionsafety No-throw guarantee: this member function never throws
+    exceptions.
+
+    @liveexample{The following code exemplifies `is_number_unsigned()` for all
+    JSON types.,is_number_unsigned}
+
+    @sa @ref is_number() -- check if value is a number
+    @sa @ref is_number_integer() -- check if value is an integer or unsigned
+    integer number
+    @sa @ref is_number_float() -- check if value is a floating-point number
+
+    @since version 2.0.0
+    */
+    constexpr bool is_number_unsigned() const noexcept
+    {
+        return m_type == value_t::number_unsigned;
+    }
+
+    /*!
+    @brief return whether value is a floating-point number
+
+    This function returns true iff the JSON value is a floating-point number.
+    This excludes integer and unsigned integer values.
+
+    @return `true` if type is a floating-point number, `false` otherwise.
+
+    @complexity Constant.
+
+    @exceptionsafety No-throw guarantee: this member function never throws
+    exceptions.
+
+    @liveexample{The following code exemplifies `is_number_float()` for all
+    JSON types.,is_number_float}
+
+    @sa @ref is_number() -- check if value is number
+    @sa @ref is_number_integer() -- check if value is an integer number
+    @sa @ref is_number_unsigned() -- check if value is an unsigned integer
+    number
+
+    @since version 1.0.0
+    */
+    constexpr bool is_number_float() const noexcept
+    {
+        return m_type == value_t::number_float;
+    }
+
+    /*!
+    @brief return whether value is an object
+
+    This function returns true iff the JSON value is an object.
+
+    @return `true` if type is object, `false` otherwise.
+
+    @complexity Constant.
+
+    @exceptionsafety No-throw guarantee: this member function never throws
+    exceptions.
+
+    @liveexample{The following code exemplifies `is_object()` for all JSON
+    types.,is_object}
+
+    @since version 1.0.0
+    */
+    constexpr bool is_object() const noexcept
+    {
+        return m_type == value_t::object;
+    }
+
+    /*!
+    @brief return whether value is an array
+
+    This function returns true iff the JSON value is an array.
+
+    @return `true` if type is array, `false` otherwise.
+
+    @complexity Constant.
+
+    @exceptionsafety No-throw guarantee: this member function never throws
+    exceptions.
+
+    @liveexample{The following code exemplifies `is_array()` for all JSON
+    types.,is_array}
+
+    @since version 1.0.0
+    */
+    constexpr bool is_array() const noexcept
+    {
+        return m_type == value_t::array;
+    }
+
+    /*!
+    @brief return whether value is a string
+
+    This function returns true iff the JSON value is a string.
+
+    @return `true` if type is string, `false` otherwise.
+
+    @complexity Constant.
+
+    @exceptionsafety No-throw guarantee: this member function never throws
+    exceptions.
+
+    @liveexample{The following code exemplifies `is_string()` for all JSON
+    types.,is_string}
+
+    @since version 1.0.0
+    */
+    constexpr bool is_string() const noexcept
+    {
+        return m_type == value_t::string;
+    }
+
+    /*!
+    @brief return whether value is discarded
+
+    This function returns true iff the JSON value was discarded during parsing
+    with a callback function (see @ref parser_callback_t).
+
+    @note This function will always be `false` for JSON values after parsing.
+    That is, discarded values can only occur during parsing, but will be
+    removed when inside a structured value or replaced by null in other cases.
+
+    @return `true` if type is discarded, `false` otherwise.
+
+    @complexity Constant.
+
+    @exceptionsafety No-throw guarantee: this member function never throws
+    exceptions.
+
+    @liveexample{The following code exemplifies `is_discarded()` for all JSON
+    types.,is_discarded}
+
+    @since version 1.0.0
+    */
+    constexpr bool is_discarded() const noexcept
+    {
+        return m_type == value_t::discarded;
+    }
+
+    /*!
+    @brief return the type of the JSON value (implicit)
+
+    Implicitly return the type of the JSON value as a value from the @ref
+    value_t enumeration.
+
+    @return the type of the JSON value
+
+    @complexity Constant.
+
+    @exceptionsafety No-throw guarantee: this member function never throws
+    exceptions.
+
+    @liveexample{The following code exemplifies the @ref value_t operator for
+    all JSON types.,operator__value_t}
+
+    @since version 1.0.0
+    */
+    constexpr operator value_t() const noexcept
+    {
+        return m_type;
+    }
+
+    /// @}
+
+  private:
+    //////////////////
+    // value access //
+    //////////////////
+
+    /// get an object (explicit)
+    template<class T, typename std::enable_if<
+                 std::is_convertible<typename object_t::key_type, typename T::key_type>::value and
+                 std::is_convertible<basic_json_t, typename T::mapped_type>::value, int>::type = 0>
+    T get_impl(T*) const
+    {
+        if (is_object())
+        {
+            return T(m_value.object->begin(), m_value.object->end());
+        }
+        else
+        {
+            Throw<std::domain_error>("type must be object, but is " + type_name());
+        }
+    }
+
+    /// get an object (explicit)
+    object_t get_impl(object_t*) const
+    {
+        if (is_object())
+        {
+            return *(m_value.object);
+        }
+        else
+        {
+            Throw<std::domain_error>("type must be object, but is " + type_name());
+        }
+    }
+
+    /// get an array (explicit)
+    template<class T, typename std::enable_if<
+                 std::is_convertible<basic_json_t, typename T::value_type>::value and
+                 not std::is_same<basic_json_t, typename T::value_type>::value and
+                 not std::is_arithmetic<T>::value and
+                 not std::is_convertible<std::string, T>::value and
+                 not has_mapped_type<T>::value, int>::type = 0>
+    T get_impl(T*) const
+    {
+        if (is_array())
+        {
+            T to_vector;
+            std::transform(m_value.array->begin(), m_value.array->end(),
+                           std::inserter(to_vector, to_vector.end()), [](basic_json i)
+            {
+                return i.get<typename T::value_type>();
+            });
+            return to_vector;
+        }
+        else
+        {
+            Throw<std::domain_error>("type must be array, but is " + type_name());
+        }
+    }
+
+    /// get an array (explicit)
+    template<class T, typename std::enable_if<
+                 std::is_convertible<basic_json_t, T>::value and
+                 not std::is_same<basic_json_t, T>::value, int>::type = 0>
+    std::vector<T> get_impl(std::vector<T>*) const
+    {
+        if (is_array())
+        {
+            std::vector<T> to_vector;
+            to_vector.reserve(m_value.array->size());
+            std::transform(m_value.array->begin(), m_value.array->end(),
+                           std::inserter(to_vector, to_vector.end()), [](basic_json i)
+            {
+                return i.get<T>();
+            });
+            return to_vector;
+        }
+        else
+        {
+            Throw<std::domain_error>("type must be array, but is " + type_name());
+        }
+    }
+
+    /// get an array (explicit)
+    template<class T, typename std::enable_if<
+                 std::is_same<basic_json, typename T::value_type>::value and
+                 not has_mapped_type<T>::value, int>::type = 0>
+    T get_impl(T*) const
+    {
+        if (is_array())
+        {
+            return T(m_value.array->begin(), m_value.array->end());
+        }
+        else
+        {
+            Throw<std::domain_error>("type must be array, but is " + type_name());
+        }
+    }
+
+    /// get an array (explicit)
+    array_t get_impl(array_t*) const
+    {
+        if (is_array())
+        {
+            return *(m_value.array);
+        }
+        else
+        {
+            Throw<std::domain_error>("type must be array, but is " + type_name());
+        }
+    }
+
+    /// get a string (explicit)
+    template<typename T, typename std::enable_if<
+                 std::is_convertible<string_t, T>::value, int>::type = 0>
+    T get_impl(T*) const
+    {
+        if (is_string())
+        {
+            return *m_value.string;
+        }
+        else
+        {
+            Throw<std::domain_error>("type must be string, but is " + type_name());
+        }
+    }
+
+    /// get a number (explicit)
+    template<typename T, typename std::enable_if<
+                 std::is_arithmetic<T>::value, int>::type = 0>
+    T get_impl(T*) const
+    {
+        switch (m_type)
+        {
+            case value_t::number_integer:
+            {
+                return static_cast<T>(m_value.number_integer);
+            }
+
+            case value_t::number_unsigned:
+            {
+                return static_cast<T>(m_value.number_unsigned);
+            }
+
+            case value_t::number_float:
+            {
+                return static_cast<T>(m_value.number_float);
+            }
+
+            default:
+            {
+                Throw<std::domain_error>("type must be number, but is " + type_name());
+            }
+        }
+    }
+
+    /// get a boolean (explicit)
+    constexpr boolean_t get_impl(boolean_t*) const
+    {
+        return is_boolean()
+               ? m_value.boolean
+               : Throw<std::domain_error>("type must be boolean, but is " + type_name()), false;
+    }
+
+    /// get a pointer to the value (object)
+    object_t* get_impl_ptr(object_t*) noexcept
+    {
+        return is_object() ? m_value.object : nullptr;
+    }
+
+    /// get a pointer to the value (object)
+    constexpr const object_t* get_impl_ptr(const object_t*) const noexcept
+    {
+        return is_object() ? m_value.object : nullptr;
+    }
+
+    /// get a pointer to the value (array)
+    array_t* get_impl_ptr(array_t*) noexcept
+    {
+        return is_array() ? m_value.array : nullptr;
+    }
+
+    /// get a pointer to the value (array)
+    constexpr const array_t* get_impl_ptr(const array_t*) const noexcept
+    {
+        return is_array() ? m_value.array : nullptr;
+    }
+
+    /// get a pointer to the value (string)
+    string_t* get_impl_ptr(string_t*) noexcept
+    {
+        return is_string() ? m_value.string : nullptr;
+    }
+
+    /// get a pointer to the value (string)
+    constexpr const string_t* get_impl_ptr(const string_t*) const noexcept
+    {
+        return is_string() ? m_value.string : nullptr;
+    }
+
+    /// get a pointer to the value (boolean)
+    boolean_t* get_impl_ptr(boolean_t*) noexcept
+    {
+        return is_boolean() ? &m_value.boolean : nullptr;
+    }
+
+    /// get a pointer to the value (boolean)
+    constexpr const boolean_t* get_impl_ptr(const boolean_t*) const noexcept
+    {
+        return is_boolean() ? &m_value.boolean : nullptr;
+    }
+
+    /// get a pointer to the value (integer number)
+    number_integer_t* get_impl_ptr(number_integer_t*) noexcept
+    {
+        return is_number_integer() ? &m_value.number_integer : nullptr;
+    }
+
+    /// get a pointer to the value (integer number)
+    constexpr const number_integer_t* get_impl_ptr(const number_integer_t*) const noexcept
+    {
+        return is_number_integer() ? &m_value.number_integer : nullptr;
+    }
+
+    /// get a pointer to the value (unsigned number)
+    number_unsigned_t* get_impl_ptr(number_unsigned_t*) noexcept
+    {
+        return is_number_unsigned() ? &m_value.number_unsigned : nullptr;
+    }
+
+    /// get a pointer to the value (unsigned number)
+    constexpr const number_unsigned_t* get_impl_ptr(const number_unsigned_t*) const noexcept
+    {
+        return is_number_unsigned() ? &m_value.number_unsigned : nullptr;
+    }
+
+    /// get a pointer to the value (floating-point number)
+    number_float_t* get_impl_ptr(number_float_t*) noexcept
+    {
+        return is_number_float() ? &m_value.number_float : nullptr;
+    }
+
+    /// get a pointer to the value (floating-point number)
+    constexpr const number_float_t* get_impl_ptr(const number_float_t*) const noexcept
+    {
+        return is_number_float() ? &m_value.number_float : nullptr;
+    }
+
+    /*!
+    @brief helper function to implement get_ref()
+
+    This funcion helps to implement get_ref() without code duplication for
+    const and non-const overloads
+
+    @tparam ThisType will be deduced as `basic_json` or `const basic_json`
+
+    @throw std::domain_error if ReferenceType does not match underlying value
+    type of the current JSON
+    */
+    template<typename ReferenceType, typename ThisType>
+    static ReferenceType get_ref_impl(ThisType& obj)
+    {
+        // helper type
+        using PointerType = typename std::add_pointer<ReferenceType>::type;
+
+        // delegate the call to get_ptr<>()
+        auto ptr = obj.template get_ptr<PointerType>();
+
+        if (ptr != nullptr)
+        {
+            return *ptr;
+        }
+        else
+        {
+            Throw<std::domain_error>("incompatible ReferenceType for get_ref, actual type is " +
+                                    obj.type_name());
+        }
+    }
+
+  public:
+
+    /// @name value access
+    /// Direct access to the stored value of a JSON value.
+    /// @{
+
+    /*!
+    @brief get a value (explicit)
+
+    Explicit type conversion between the JSON value and a compatible value.
+
+    @tparam ValueType non-pointer type compatible to the JSON value, for
+    instance `int` for JSON integer numbers, `bool` for JSON booleans, or
+    `std::vector` types for JSON arrays
+
+    @return copy of the JSON value, converted to type @a ValueType
+
+    @throw std::domain_error in case passed type @a ValueType is incompatible
+    to JSON; example: `"type must be object, but is null"`
+
+    @complexity Linear in the size of the JSON value.
+
+    @liveexample{The example below shows several conversions from JSON values
+    to other types. There a few things to note: (1) Floating-point numbers can
+    be converted to integers\, (2) A JSON array can be converted to a standard
+    `std::vector<short>`\, (3) A JSON object can be converted to C++
+    associative containers such as `std::unordered_map<std::string\,
+    json>`.,get__ValueType_const}
+
+    @internal
+    The idea of using a casted null pointer to choose the correct
+    implementation is from <http://stackoverflow.com/a/8315197/266378>.
+    @endinternal
+
+    @sa @ref operator ValueType() const for implicit conversion
+    @sa @ref get() for pointer-member access
+
+    @since version 1.0.0
+    */
+    template<typename ValueType, typename std::enable_if<
+                 not std::is_pointer<ValueType>::value, int>::type = 0>
+    ValueType get() const
+    {
+        return get_impl(static_cast<ValueType*>(nullptr));
+    }
+
+    /*!
+    @brief get a pointer value (explicit)
+
+    Explicit pointer access to the internally stored JSON value. No copies are
+    made.
+
+    @warning The pointer becomes invalid if the underlying JSON object
+    changes.
+
+    @tparam PointerType pointer type; must be a pointer to @ref array_t, @ref
+    object_t, @ref string_t, @ref boolean_t, @ref number_integer_t,
+    @ref number_unsigned_t, or @ref number_float_t.
+
+    @return pointer to the internally stored JSON value if the requested
+    pointer type @a PointerType fits to the JSON value; `nullptr` otherwise
+
+    @complexity Constant.
+
+    @liveexample{The example below shows how pointers to internal values of a
+    JSON value can be requested. Note that no type conversions are made and a
+    `nullptr` is returned if the value and the requested pointer type does not
+    match.,get__PointerType}
+
+    @sa @ref get_ptr() for explicit pointer-member access
+
+    @since version 1.0.0
+    */
+    template<typename PointerType, typename std::enable_if<
+                 std::is_pointer<PointerType>::value, int>::type = 0>
+    PointerType get() noexcept
+    {
+        // delegate the call to get_ptr
+        return get_ptr<PointerType>();
+    }
+
+    /*!
+    @brief get a pointer value (explicit)
+    @copydoc get()
+    */
+    template<typename PointerType, typename std::enable_if<
+                 std::is_pointer<PointerType>::value, int>::type = 0>
+    constexpr const PointerType get() const noexcept
+    {
+        // delegate the call to get_ptr
+        return get_ptr<PointerType>();
+    }
+
+    /*!
+    @brief get a pointer value (implicit)
+
+    Implicit pointer access to the internally stored JSON value. No copies are
+    made.
+
+    @warning Writing data to the pointee of the result yields an undefined
+    state.
+
+    @tparam PointerType pointer type; must be a pointer to @ref array_t, @ref
+    object_t, @ref string_t, @ref boolean_t, @ref number_integer_t,
+    @ref number_unsigned_t, or @ref number_float_t. Enforced by a static
+    assertion.
+
+    @return pointer to the internally stored JSON value if the requested
+    pointer type @a PointerType fits to the JSON value; `nullptr` otherwise
+
+    @complexity Constant.
+
+    @liveexample{The example below shows how pointers to internal values of a
+    JSON value can be requested. Note that no type conversions are made and a
+    `nullptr` is returned if the value and the requested pointer type does not
+    match.,get_ptr}
+
+    @since version 1.0.0
+    */
+    template<typename PointerType, typename std::enable_if<
+                 std::is_pointer<PointerType>::value, int>::type = 0>
+    PointerType get_ptr() noexcept
+    {
+        // get the type of the PointerType (remove pointer and const)
+        using pointee_t = typename std::remove_const<typename
+                          std::remove_pointer<typename
+                          std::remove_const<PointerType>::type>::type>::type;
+        // make sure the type matches the allowed types
+        static_assert(
+            std::is_same<object_t, pointee_t>::value
+            or std::is_same<array_t, pointee_t>::value
+            or std::is_same<string_t, pointee_t>::value
+            or std::is_same<boolean_t, pointee_t>::value
+            or std::is_same<number_integer_t, pointee_t>::value
+            or std::is_same<number_unsigned_t, pointee_t>::value
+            or std::is_same<number_float_t, pointee_t>::value
+            , "incompatible pointer type");
+
+        // delegate the call to get_impl_ptr<>()
+        return get_impl_ptr(static_cast<PointerType>(nullptr));
+    }
+
+    /*!
+    @brief get a pointer value (implicit)
+    @copydoc get_ptr()
+    */
+    template<typename PointerType, typename std::enable_if<
+                 std::is_pointer<PointerType>::value and
+                 std::is_const<typename std::remove_pointer<PointerType>::type>::value, int>::type = 0>
+    constexpr const PointerType get_ptr() const noexcept
+    {
+        // get the type of the PointerType (remove pointer and const)
+        using pointee_t = typename std::remove_const<typename
+                          std::remove_pointer<typename
+                          std::remove_const<PointerType>::type>::type>::type;
+        // make sure the type matches the allowed types
+        static_assert(
+            std::is_same<object_t, pointee_t>::value
+            or std::is_same<array_t, pointee_t>::value
+            or std::is_same<string_t, pointee_t>::value
+            or std::is_same<boolean_t, pointee_t>::value
+            or std::is_same<number_integer_t, pointee_t>::value
+            or std::is_same<number_unsigned_t, pointee_t>::value
+            or std::is_same<number_float_t, pointee_t>::value
+            , "incompatible pointer type");
+
+        // delegate the call to get_impl_ptr<>() const
+        return get_impl_ptr(static_cast<const PointerType>(nullptr));
+    }
+
+    /*!
+    @brief get a reference value (implicit)
+
+    Implict reference access to the internally stored JSON value. No copies
+    are made.
+
+    @warning Writing data to the referee of the result yields an undefined
+    state.
+
+    @tparam ReferenceType reference type; must be a reference to @ref array_t,
+    @ref object_t, @ref string_t, @ref boolean_t, @ref number_integer_t, or
+    @ref number_float_t. Enforced by static assertion.
+
+    @return reference to the internally stored JSON value if the requested
+    reference type @a ReferenceType fits to the JSON value; throws
+    std::domain_error otherwise
+
+    @throw std::domain_error in case passed type @a ReferenceType is
+    incompatible with the stored JSON value
+
+    @complexity Constant.
+
+    @liveexample{The example shows several calls to `get_ref()`.,get_ref}
+
+    @since version 1.1.0
+    */
+    template<typename ReferenceType, typename std::enable_if<
+                 std::is_reference<ReferenceType>::value, int>::type = 0>
+    ReferenceType get_ref()
+    {
+        // delegate call to get_ref_impl
+        return get_ref_impl<ReferenceType>(*this);
+    }
+
+    /*!
+    @brief get a reference value (implicit)
+    @copydoc get_ref()
+    */
+    template<typename ReferenceType, typename std::enable_if<
+                 std::is_reference<ReferenceType>::value and
+                 std::is_const<typename std::remove_reference<ReferenceType>::type>::value, int>::type = 0>
+    ReferenceType get_ref() const
+    {
+        // delegate call to get_ref_impl
+        return get_ref_impl<ReferenceType>(*this);
+    }
+
+    /*!
+    @brief get a value (implicit)
+
+    Implicit type conversion between the JSON value and a compatible value.
+    The call is realized by calling @ref get() const.
+
+    @tparam ValueType non-pointer type compatible to the JSON value, for
+    instance `int` for JSON integer numbers, `bool` for JSON booleans, or
+    `std::vector` types for JSON arrays. The character type of @ref string_t
+    as well as an initializer list of this type is excluded to avoid
+    ambiguities as these types implicitly convert to `std::string`.
+
+    @return copy of the JSON value, converted to type @a ValueType
+
+    @throw std::domain_error in case passed type @a ValueType is incompatible
+    to JSON, thrown by @ref get() const
+
+    @complexity Linear in the size of the JSON value.
+
+    @liveexample{The example below shows several conversions from JSON values
+    to other types. There a few things to note: (1) Floating-point numbers can
+    be converted to integers\, (2) A JSON array can be converted to a standard
+    `std::vector<short>`\, (3) A JSON object can be converted to C++
+    associative containers such as `std::unordered_map<std::string\,
+    json>`.,operator__ValueType}
+
+    @since version 1.0.0
+    */
+    template < typename ValueType, typename std::enable_if <
+                   not std::is_pointer<ValueType>::value and
+                   not std::is_same<ValueType, typename string_t::value_type>::value
+#ifndef _MSC_VER  // Fix for issue #167 operator<< abiguity under VS2015
+                   and not std::is_same<ValueType, std::initializer_list<typename string_t::value_type>>::value
+#endif
+                   , int >::type = 0 >
+    operator ValueType() const
+    {
+        // delegate the call to get<>() const
+        return get<ValueType>();
+    }
+
+    /// @}
+
+
+    ////////////////////
+    // element access //
+    ////////////////////
+
+    /// @name element access
+    /// Access to the JSON value.
+    /// @{
+
+    /*!
+    @brief access specified array element with bounds checking
+
+    Returns a reference to the element at specified location @a idx, with
+    bounds checking.
+
+    @param[in] idx  index of the element to access
+
+    @return reference to the element at index @a idx
+
+    @throw std::domain_error if the JSON value is not an array; example:
+    `"cannot use at() with string"`
+    @throw std::out_of_range if the index @a idx is out of range of the array;
+    that is, `idx >= size()`; example: `"array index 7 is out of range"`
+
+    @complexity Constant.
+
+    @liveexample{The example below shows how array elements can be read and
+    written using `at()`.,at__size_type}
+
+    @since version 1.0.0
+    */
+    reference at(size_type idx)
+    {
+        // at only works for arrays
+        if (is_array())
+        {
+            if (idx < m_value.array->size())
+                return m_value.array->at(idx);
+            Throw<std::out_of_range>("array index " + std::to_string(idx) + " is out of range");
+        }
+        else
+        {
+            Throw<std::domain_error>("cannot use at() with " + type_name());
+        }
+    }
+
+    /*!
+    @brief access specified array element with bounds checking
+
+    Returns a const reference to the element at specified location @a idx,
+    with bounds checking.
+
+    @param[in] idx  index of the element to access
+
+    @return const reference to the element at index @a idx
+
+    @throw std::domain_error if the JSON value is not an array; example:
+    `"cannot use at() with string"`
+    @throw std::out_of_range if the index @a idx is out of range of the array;
+    that is, `idx >= size()`; example: `"array index 7 is out of range"`
+
+    @complexity Constant.
+
+    @liveexample{The example below shows how array elements can be read using
+    `at()`.,at__size_type_const}
+
+    @since version 1.0.0
+    */
+    const_reference at(size_type idx) const
+    {
+        // at only works for arrays
+        if (is_array())
+        {
+            if (idx < m_value.array->size())
+                return m_value.array->at(idx);
+            Throw<std::out_of_range>("array index " + std::to_string(idx) + " is out of range");
+        }
+        else
+        {
+            Throw<std::domain_error>("cannot use at() with " + type_name());
+        }
+    }
+
+    /*!
+    @brief access specified object element with bounds checking
+
+    Returns a reference to the element at with specified key @a key, with
+    bounds checking.
+
+    @param[in] key  key of the element to access
+
+    @return reference to the element at key @a key
+
+    @throw std::domain_error if the JSON value is not an object; example:
+    `"cannot use at() with boolean"`
+    @throw std::out_of_range if the key @a key is is not stored in the object;
+    that is, `find(key) == end()`; example: `"key "the fast" not found"`
+
+    @complexity Logarithmic in the size of the container.
+
+    @liveexample{The example below shows how object elements can be read and
+    written using `at()`.,at__object_t_key_type}
+
+    @sa @ref operator[](const typename object_t::key_type&) for unchecked
+    access by reference
+    @sa @ref value() for access by value with a default value
+
+    @since version 1.0.0
+    */
+    reference at(const typename object_t::key_type& key)
+    {
+        // at only works for objects
+        if (is_object())
+        {
+            if (m_value.object->count(key) > 0)
+                return m_value.object->at(key);
+            Throw<std::out_of_range>("key '" + key + "' not found");
+        }
+        else
+        {
+            Throw<std::domain_error>("cannot use at() with " + type_name());
+        }
+    }
+
+    /*!
+    @brief access specified object element with bounds checking
+
+    Returns a const reference to the element at with specified key @a key,
+    with bounds checking.
+
+    @param[in] key  key of the element to access
+
+    @return const reference to the element at key @a key
+
+    @throw std::domain_error if the JSON value is not an object; example:
+    `"cannot use at() with boolean"`
+    @throw std::out_of_range if the key @a key is is not stored in the object;
+    that is, `find(key) == end()`; example: `"key "the fast" not found"`
+
+    @complexity Logarithmic in the size of the container.
+
+    @liveexample{The example below shows how object elements can be read using
+    `at()`.,at__object_t_key_type_const}
+
+    @sa @ref operator[](const typename object_t::key_type&) for unchecked
+    access by reference
+    @sa @ref value() for access by value with a default value
+
+    @since version 1.0.0
+    */
+    const_reference at(const typename object_t::key_type& key) const
+    {
+        // at only works for objects
+        if (is_object())
+        {
+            if (m_value.object->count(key) > 0)
+                return m_value.object->at(key);
+            Throw<std::out_of_range>("key '" + key + "' not found");
+        }
+        else
+        {
+            Throw<std::domain_error>("cannot use at() with " + type_name());
+        }
+    }
+
+    /*!
+    @brief access specified array element
+
+    Returns a reference to the element at specified location @a idx.
+
+    @note If @a idx is beyond the range of the array (i.e., `idx >= size()`),
+    then the array is silently filled up with `null` values to make `idx` a
+    valid reference to the last stored element.
+
+    @param[in] idx  index of the element to access
+
+    @return reference to the element at index @a idx
+
+    @throw std::domain_error if JSON is not an array or null; example:
+    `"cannot use operator[] with string"`
+
+    @complexity Constant if @a idx is in the range of the array. Otherwise
+    linear in `idx - size()`.
+
+    @liveexample{The example below shows how array elements can be read and
+    written using `[]` operator. Note the addition of `null`
+    values.,operatorarray__size_type}
+
+    @since version 1.0.0
+    */
+    reference operator[](size_type idx)
+    {
+        // implicitly convert null value to an empty array
+        if (is_null())
+        {
+            m_type = value_t::array;
+            m_value.array = create<array_t>();
+            assert_invariant();
+        }
+
+        // operator[] only works for arrays
+        if (is_array())
+        {
+            // fill up array with null values if given idx is outside range
+            if (idx >= m_value.array->size())
+            {
+                m_value.array->insert(m_value.array->end(),
+                                      idx - m_value.array->size() + 1,
+                                      basic_json());
+            }
+
+            return m_value.array->operator[](idx);
+        }
+        else
+        {
+            Throw<std::domain_error>("cannot use operator[] with " + type_name());
+        }
+    }
+
+    /*!
+    @brief access specified array element
+
+    Returns a const reference to the element at specified location @a idx.
+
+    @param[in] idx  index of the element to access
+
+    @return const reference to the element at index @a idx
+
+    @throw std::domain_error if JSON is not an array; example: `"cannot use
+    operator[] with null"`
+
+    @complexity Constant.
+
+    @liveexample{The example below shows how array elements can be read using
+    the `[]` operator.,operatorarray__size_type_const}
+
+    @since version 1.0.0
+    */
+    const_reference operator[](size_type idx) const
+    {
+        // const operator[] only works for arrays
+        if (is_array())
+        {
+            return m_value.array->operator[](idx);
+        }
+        else
+        {
+            Throw<std::domain_error>("cannot use operator[] with " + type_name());
+        }
+    }
+
+    /*!
+    @brief access specified object element
+
+    Returns a reference to the element at with specified key @a key.
+
+    @note If @a key is not found in the object, then it is silently added to
+    the object and filled with a `null` value to make `key` a valid reference.
+    In case the value was `null` before, it is converted to an object.
+
+    @param[in] key  key of the element to access
+
+    @return reference to the element at key @a key
+
+    @throw std::domain_error if JSON is not an object or null; example:
+    `"cannot use operator[] with string"`
+
+    @complexity Logarithmic in the size of the container.
+
+    @liveexample{The example below shows how object elements can be read and
+    written using the `[]` operator.,operatorarray__key_type}
+
+    @sa @ref at(const typename object_t::key_type&) for access by reference
+    with range checking
+    @sa @ref value() for access by value with a default value
+
+    @since version 1.0.0
+    */
+    reference operator[](const typename object_t::key_type& key)
+    {
+        // implicitly convert null value to an empty object
+        if (is_null())
+        {
+            m_type = value_t::object;
+            m_value.object = create<object_t>();
+            assert_invariant();
+        }
+
+        // operator[] only works for objects
+        if (is_object())
+        {
+            return m_value.object->operator[](key);
+        }
+        else
+        {
+            Throw<std::domain_error>("cannot use operator[] with " + type_name());
+        }
+    }
+
+    /*!
+    @brief read-only access specified object element
+
+    Returns a const reference to the element at with specified key @a key. No
+    bounds checking is performed.
+
+    @warning If the element with key @a key does not exist, the behavior is
+    undefined.
+
+    @param[in] key  key of the element to access
+
+    @return const reference to the element at key @a key
+
+    @pre The element with key @a key must exist. **This precondition is
+         enforced with an assertion.**
+
+    @throw std::domain_error if JSON is not an object; example: `"cannot use
+    operator[] with null"`
+
+    @complexity Logarithmic in the size of the container.
+
+    @liveexample{The example below shows how object elements can be read using
+    the `[]` operator.,operatorarray__key_type_const}
+
+    @sa @ref at(const typename object_t::key_type&) for access by reference
+    with range checking
+    @sa @ref value() for access by value with a default value
+
+    @since version 1.0.0
+    */
+    const_reference operator[](const typename object_t::key_type& key) const
+    {
+        // const operator[] only works for objects
+        if (is_object())
+        {
+            assert(m_value.object->find(key) != m_value.object->end());
+            return m_value.object->find(key)->second;
+        }
+        else
+        {
+            Throw<std::domain_error>("cannot use operator[] with " + type_name());
+        }
+    }
+
+    /*!
+    @brief access specified object element
+
+    Returns a reference to the element at with specified key @a key.
+
+    @note If @a key is not found in the object, then it is silently added to
+    the object and filled with a `null` value to make `key` a valid reference.
+    In case the value was `null` before, it is converted to an object.
+
+    @param[in] key  key of the element to access
+
+    @return reference to the element at key @a key
+
+    @throw std::domain_error if JSON is not an object or null; example:
+    `"cannot use operator[] with string"`
+
+    @complexity Logarithmic in the size of the container.
+
+    @liveexample{The example below shows how object elements can be read and
+    written using the `[]` operator.,operatorarray__key_type}
+
+    @sa @ref at(const typename object_t::key_type&) for access by reference
+    with range checking
+    @sa @ref value() for access by value with a default value
+
+    @since version 1.0.0
+    */
+    template<typename T, std::size_t n>
+    reference operator[](T * (&key)[n])
+    {
+        return operator[](static_cast<const T>(key));
+    }
+
+    /*!
+    @brief read-only access specified object element
+
+    Returns a const reference to the element at with specified key @a key. No
+    bounds checking is performed.
+
+    @warning If the element with key @a key does not exist, the behavior is
+    undefined.
+
+    @note This function is required for compatibility reasons with Clang.
+
+    @param[in] key  key of the element to access
+
+    @return const reference to the element at key @a key
+
+    @throw std::domain_error if JSON is not an object; example: `"cannot use
+    operator[] with null"`
+
+    @complexity Logarithmic in the size of the container.
+
+    @liveexample{The example below shows how object elements can be read using
+    the `[]` operator.,operatorarray__key_type_const}
+
+    @sa @ref at(const typename object_t::key_type&) for access by reference
+    with range checking
+    @sa @ref value() for access by value with a default value
+
+    @since version 1.0.0
+    */
+    template<typename T, std::size_t n>
+    const_reference operator[](T * (&key)[n]) const
+    {
+        return operator[](static_cast<const T>(key));
+    }
+
+    /*!
+    @brief access specified object element
+
+    Returns a reference to the element at with specified key @a key.
+
+    @note If @a key is not found in the object, then it is silently added to
+    the object and filled with a `null` value to make `key` a valid reference.
+    In case the value was `null` before, it is converted to an object.
+
+    @param[in] key  key of the element to access
+
+    @return reference to the element at key @a key
+
+    @throw std::domain_error if JSON is not an object or null; example:
+    `"cannot use operator[] with string"`
+
+    @complexity Logarithmic in the size of the container.
+
+    @liveexample{The example below shows how object elements can be read and
+    written using the `[]` operator.,operatorarray__key_type}
+
+    @sa @ref at(const typename object_t::key_type&) for access by reference
+    with range checking
+    @sa @ref value() for access by value with a default value
+
+    @since version 1.1.0
+    */
+    template<typename T>
+    reference operator[](T* key)
+    {
+        // implicitly convert null to object
+        if (is_null())
+        {
+            m_type = value_t::object;
+            m_value = value_t::object;
+            assert_invariant();
+        }
+
+        // at only works for objects
+        if (is_object())
+        {
+            return m_value.object->operator[](key);
+        }
+        else
+        {
+            Throw<std::domain_error>("cannot use operator[] with " + type_name());
+        }
+    }
+
+    /*!
+    @brief read-only access specified object element
+
+    Returns a const reference to the element at with specified key @a key. No
+    bounds checking is performed.
+
+    @warning If the element with key @a key does not exist, the behavior is
+    undefined.
+
+    @param[in] key  key of the element to access
+
+    @return const reference to the element at key @a key
+
+    @pre The element with key @a key must exist. **This precondition is
+         enforced with an assertion.**
+
+    @throw std::domain_error if JSON is not an object; example: `"cannot use
+    operator[] with null"`
+
+    @complexity Logarithmic in the size of the container.
+
+    @liveexample{The example below shows how object elements can be read using
+    the `[]` operator.,operatorarray__key_type_const}
+
+    @sa @ref at(const typename object_t::key_type&) for access by reference
+    with range checking
+    @sa @ref value() for access by value with a default value
+
+    @since version 1.1.0
+    */
+    template<typename T>
+    const_reference operator[](T* key) const
+    {
+        // at only works for objects
+        if (is_object())
+        {
+            assert(m_value.object->find(key) != m_value.object->end());
+            return m_value.object->find(key)->second;
+        }
+        else
+        {
+            Throw<std::domain_error>("cannot use operator[] with " + type_name());
+        }
+    }
+
+    /*!
+    @brief access specified object element with default value
+
+    Returns either a copy of an object's element at the specified key @a key
+    or a given default value if no element with key @a key exists.
+
+    The function is basically equivalent to executing
+    @code {.cpp}
+    try {
+        return at(key);
+    } catch(std::out_of_range) {
+        return default_value;
+    }
+    @endcode
+
+    @note Unlike @ref at(const typename object_t::key_type&), this function
+    does not throw if the given key @a key was not found.
+
+    @note Unlike @ref operator[](const typename object_t::key_type& key), this
+    function does not implicitly add an element to the position defined by @a
+    key. This function is furthermore also applicable to const objects.
+
+    @param[in] key  key of the element to access
+    @param[in] default_value  the value to return if @a key is not found
+
+    @tparam ValueType type compatible to JSON values, for instance `int` for
+    JSON integer numbers, `bool` for JSON booleans, or `std::vector` types for
+    JSON arrays. Note the type of the expected value at @a key and the default
+    value @a default_value must be compatible.
+
+    @return copy of the element at key @a key or @a default_value if @a key
+    is not found
+
+    @throw std::domain_error if JSON is not an object; example: `"cannot use
+    value() with null"`
+
+    @complexity Logarithmic in the size of the container.
+
+    @liveexample{The example below shows how object elements can be queried
+    with a default value.,basic_json__value}
+
+    @sa @ref at(const typename object_t::key_type&) for access by reference
+    with range checking
+    @sa @ref operator[](const typename object_t::key_type&) for unchecked
+    access by reference
+
+    @since version 1.0.0
+    */
+    template<class ValueType, typename std::enable_if<
+                 std::is_convertible<basic_json_t, ValueType>::value, int>::type = 0>
+    ValueType value(const typename object_t::key_type& key, ValueType default_value) const
+    {
+        // at only works for objects
+        if (is_object())
+        {
+            // if key is found, return value and given default value otherwise
+            const auto it = find(key);
+            if (it != end())
+            {
+                return *it;
+            }
+            else
+            {
+                return default_value;
+            }
+        }
+        else
+        {
+            Throw<std::domain_error>("cannot use value() with " + type_name());
+        }
+    }
+
+    /*!
+    @brief overload for a default value of type const char*
+    @copydoc basic_json::value(const typename object_t::key_type&, ValueType) const
+    */
+    string_t value(const typename object_t::key_type& key, const char* default_value) const
+    {
+        return value(key, string_t(default_value));
+    }
+
+    /*!
+    @brief access specified object element via JSON Pointer with default value
+
+    Returns either a copy of an object's element at the specified key @a key
+    or a given default value if no element with key @a key exists.
+
+    The function is basically equivalent to executing
+    @code {.cpp}
+    try {
+        return at(ptr);
+    } catch(std::out_of_range) {
+        return default_value;
+    }
+    @endcode
+
+    @note Unlike @ref at(const json_pointer&), this function does not throw
+    if the given key @a key was not found.
+
+    @param[in] ptr  a JSON pointer to the element to access
+    @param[in] default_value  the value to return if @a ptr found no value
+
+    @tparam ValueType type compatible to JSON values, for instance `int` for
+    JSON integer numbers, `bool` for JSON booleans, or `std::vector` types for
+    JSON arrays. Note the type of the expected value at @a key and the default
+    value @a default_value must be compatible.
+
+    @return copy of the element at key @a key or @a default_value if @a key
+    is not found
+
+    @throw std::domain_error if JSON is not an object; example: `"cannot use
+    value() with null"`
+
+    @complexity Logarithmic in the size of the container.
+
+    @liveexample{The example below shows how object elements can be queried
+    with a default value.,basic_json__value_ptr}
+
+    @sa @ref operator[](const json_pointer&) for unchecked access by reference
+
+    @since version 2.0.2
+    */
+    template<class ValueType, typename std::enable_if<
+                 std::is_convertible<basic_json_t, ValueType>::value, int>::type = 0>
+    ValueType value(const json_pointer& ptr, ValueType default_value) const
+    {
+        // at only works for objects
+        if (is_object())
+        {
+            return ptr.get_checked(this);
+        }
+        else
+        {
+            Throw<std::domain_error>("cannot use value() with " + type_name());
+        }
+    }
+
+    /*!
+    @brief overload for a default value of type const char*
+    @copydoc basic_json::value(const json_pointer&, ValueType) const
+    */
+    string_t value(const json_pointer& ptr, const char* default_value) const
+    {
+        return value(ptr, string_t(default_value));
+    }
+
+    /*!
+    @brief access the first element
+
+    Returns a reference to the first element in the container. For a JSON
+    container `c`, the expression `c.front()` is equivalent to `*c.begin()`.
+
+    @return In case of a structured type (array or object), a reference to the
+    first element is returned. In cast of number, string, or boolean values, a
+    reference to the value is returned.
+
+    @complexity Constant.
+
+    @pre The JSON value must not be `null` (would throw `std::out_of_range`)
+    or an empty array or object (undefined behavior, **guarded by
+    assertions**).
+    @post The JSON value remains unchanged.
+
+    @throw std::out_of_range when called on `null` value
+
+    @liveexample{The following code shows an example for `front()`.,front}
+
+    @sa @ref back() -- access the last element
+
+    @since version 1.0.0
+    */
+    reference front()
+    {
+        return *begin();
+    }
+
+    /*!
+    @copydoc basic_json::front()
+    */
+    const_reference front() const
+    {
+        return *cbegin();
+    }
+
+    /*!
+    @brief access the last element
+
+    Returns a reference to the last element in the container. For a JSON
+    container `c`, the expression `c.back()` is equivalent to
+    @code {.cpp}
+    auto tmp = c.end();
+    --tmp;
+    return *tmp;
+    @endcode
+
+    @return In case of a structured type (array or object), a reference to the
+    last element is returned. In cast of number, string, or boolean values, a
+    reference to the value is returned.
+
+    @complexity Constant.
+
+    @pre The JSON value must not be `null` (would throw `std::out_of_range`)
+    or an empty array or object (undefined behavior, **guarded by
+    assertions**).
+    @post The JSON value remains unchanged.
+
+    @throw std::out_of_range when called on `null` value.
+
+    @liveexample{The following code shows an example for `back()`.,back}
+
+    @sa @ref front() -- access the first element
+
+    @since version 1.0.0
+    */
+    reference back()
+    {
+        auto tmp = end();
+        --tmp;
+        return *tmp;
+    }
+
+    /*!
+    @copydoc basic_json::back()
+    */
+    const_reference back() const
+    {
+        auto tmp = cend();
+        --tmp;
+        return *tmp;
+    }
+
+    /*!
+    @brief remove element given an iterator
+
+    Removes the element specified by iterator @a pos. The iterator @a pos must
+    be valid and dereferenceable. Thus the `end()` iterator (which is valid,
+    but is not dereferenceable) cannot be used as a value for @a pos.
+
+    If called on a primitive type other than `null`, the resulting JSON value
+    will be `null`.
+
+    @param[in] pos iterator to the element to remove
+    @return Iterator following the last removed element. If the iterator @a
+    pos refers to the last element, the `end()` iterator is returned.
+
+    @tparam IteratorType an @ref iterator or @ref const_iterator
+
+    @post Invalidates iterators and references at or after the point of the
+    erase, including the `end()` iterator.
+
+    @throw std::domain_error if called on a `null` value; example: `"cannot
+    use erase() with null"`
+    @throw std::domain_error if called on an iterator which does not belong to
+    the current JSON value; example: `"iterator does not fit current value"`
+    @throw std::out_of_range if called on a primitive type with invalid
+    iterator (i.e., any iterator which is not `begin()`); example: `"iterator
+    out of range"`
+
+    @complexity The complexity depends on the type:
+    - objects: amortized constant
+    - arrays: linear in distance between pos and the end of the container
+    - strings: linear in the length of the string
+    - other types: constant
+
+    @liveexample{The example shows the result of `erase()` for different JSON
+    types.,erase__IteratorType}
+
+    @sa @ref erase(IteratorType, IteratorType) -- removes the elements in
+    the given range
+    @sa @ref erase(const typename object_t::key_type&) -- removes the element
+    from an object at the given key
+    @sa @ref erase(const size_type) -- removes the element from an array at
+    the given index
+
+    @since version 1.0.0
+    */
+    template<class IteratorType, typename std::enable_if<
+                 std::is_same<IteratorType, typename basic_json_t::iterator>::value or
+                 std::is_same<IteratorType, typename basic_json_t::const_iterator>::value, int>::type
+             = 0>
+    IteratorType erase(IteratorType pos)
+    {
+        // make sure iterator fits the current value
+        if (this != pos.m_object)
+        {
+            Throw<std::domain_error>("iterator does not fit current value");
+        }
+
+        IteratorType result = end();
+
+        switch (m_type)
+        {
+            case value_t::boolean:
+            case value_t::number_float:
+            case value_t::number_integer:
+            case value_t::number_unsigned:
+            case value_t::string:
+            {
+                if (not pos.m_it.primitive_iterator.is_begin())
+                {
+                    Throw<std::out_of_range>("iterator out of range");
+                }
+
+                if (is_string())
+                {
+                    AllocatorType<string_t> alloc;
+                    alloc.destroy(m_value.string);
+                    alloc.deallocate(m_value.string, 1);
+                    m_value.string = nullptr;
+                }
+
+                m_type = value_t::null;
+                assert_invariant();
+                break;
+            }
+
+            case value_t::object:
+            {
+                result.m_it.object_iterator = m_value.object->erase(pos.m_it.object_iterator);
+                break;
+            }
+
+            case value_t::array:
+            {
+                result.m_it.array_iterator = m_value.array->erase(pos.m_it.array_iterator);
+                break;
+            }
+
+            default:
+            {
+                Throw<std::domain_error>("cannot use erase() with " + type_name());
+            }
+        }
+
+        return result;
+    }
+
+    /*!
+    @brief remove elements given an iterator range
+
+    Removes the element specified by the range `[first; last)`. The iterator
+    @a first does not need to be dereferenceable if `first == last`: erasing
+    an empty range is a no-op.
+
+    If called on a primitive type other than `null`, the resulting JSON value
+    will be `null`.
+
+    @param[in] first iterator to the beginning of the range to remove
+    @param[in] last iterator past the end of the range to remove
+    @return Iterator following the last removed element. If the iterator @a
+    second refers to the last element, the `end()` iterator is returned.
+
+    @tparam IteratorType an @ref iterator or @ref const_iterator
+
+    @post Invalidates iterators and references at or after the point of the
+    erase, including the `end()` iterator.
+
+    @throw std::domain_error if called on a `null` value; example: `"cannot
+    use erase() with null"`
+    @throw std::domain_error if called on iterators which does not belong to
+    the current JSON value; example: `"iterators do not fit current value"`
+    @throw std::out_of_range if called on a primitive type with invalid
+    iterators (i.e., if `first != begin()` and `last != end()`); example:
+    `"iterators out of range"`
+
+    @complexity The complexity depends on the type:
+    - objects: `log(size()) + std::distance(first, last)`
+    - arrays: linear in the distance between @a first and @a last, plus linear
+      in the distance between @a last and end of the container
+    - strings: linear in the length of the string
+    - other types: constant
+
+    @liveexample{The example shows the result of `erase()` for different JSON
+    types.,erase__IteratorType_IteratorType}
+
+    @sa @ref erase(IteratorType) -- removes the element at a given position
+    @sa @ref erase(const typename object_t::key_type&) -- removes the element
+    from an object at the given key
+    @sa @ref erase(const size_type) -- removes the element from an array at
+    the given index
+
+    @since version 1.0.0
+    */
+    template<class IteratorType, typename std::enable_if<
+                 std::is_same<IteratorType, typename basic_json_t::iterator>::value or
+                 std::is_same<IteratorType, typename basic_json_t::const_iterator>::value, int>::type
+             = 0>
+    IteratorType erase(IteratorType first, IteratorType last)
+    {
+        // make sure iterator fits the current value
+        if (this != first.m_object or this != last.m_object)
+        {
+            Throw<std::domain_error>("iterators do not fit current value");
+        }
+
+        IteratorType result = end();
+
+        switch (m_type)
+        {
+            case value_t::boolean:
+            case value_t::number_float:
+            case value_t::number_integer:
+            case value_t::number_unsigned:
+            case value_t::string:
+            {
+                if (not first.m_it.primitive_iterator.is_begin() or not last.m_it.primitive_iterator.is_end())
+                {
+                    Throw<std::out_of_range>("iterators out of range");
+                }
+
+                if (is_string())
+                {
+                    AllocatorType<string_t> alloc;
+                    alloc.destroy(m_value.string);
+                    alloc.deallocate(m_value.string, 1);
+                    m_value.string = nullptr;
+                }
+
+                m_type = value_t::null;
+                assert_invariant();
+                break;
+            }
+
+            case value_t::object:
+            {
+                result.m_it.object_iterator = m_value.object->erase(first.m_it.object_iterator,
+                                              last.m_it.object_iterator);
+                break;
+            }
+
+            case value_t::array:
+            {
+                result.m_it.array_iterator = m_value.array->erase(first.m_it.array_iterator,
+                                             last.m_it.array_iterator);
+                break;
+            }
+
+            default:
+            {
+                Throw<std::domain_error>("cannot use erase() with " + type_name());
+            }
+        }
+
+        return result;
+    }
+
+    /*!
+    @brief remove element from a JSON object given a key
+
+    Removes elements from a JSON object with the key value @a key.
+
+    @param[in] key value of the elements to remove
+
+    @return Number of elements removed. If @a ObjectType is the default
+    `std::map` type, the return value will always be `0` (@a key was not
+    found) or `1` (@a key was found).
+
+    @post References and iterators to the erased elements are invalidated.
+    Other references and iterators are not affected.
+
+    @throw std::domain_error when called on a type other than JSON object;
+    example: `"cannot use erase() with null"`
+
+    @complexity `log(size()) + count(key)`
+
+    @liveexample{The example shows the effect of `erase()`.,erase__key_type}
+
+    @sa @ref erase(IteratorType) -- removes the element at a given position
+    @sa @ref erase(IteratorType, IteratorType) -- removes the elements in
+    the given range
+    @sa @ref erase(const size_type) -- removes the element from an array at
+    the given index
+
+    @since version 1.0.0
+    */
+    size_type erase(const typename object_t::key_type& key)
+    {
+        // this erase only works for objects
+        if (is_object())
+        {
+            return m_value.object->erase(key);
+        }
+        else
+        {
+            Throw<std::domain_error>("cannot use erase() with " + type_name());
+        }
+    }
+
+    /*!
+    @brief remove element from a JSON array given an index
+
+    Removes element from a JSON array at the index @a idx.
+
+    @param[in] idx index of the element to remove
+
+    @throw std::domain_error when called on a type other than JSON array;
+    example: `"cannot use erase() with null"`
+    @throw std::out_of_range when `idx >= size()`; example: `"array index 17
+    is out of range"`
+
+    @complexity Linear in distance between @a idx and the end of the container.
+
+    @liveexample{The example shows the effect of `erase()`.,erase__size_type}
+
+    @sa @ref erase(IteratorType) -- removes the element at a given position
+    @sa @ref erase(IteratorType, IteratorType) -- removes the elements in
+    the given range
+    @sa @ref erase(const typename object_t::key_type&) -- removes the element
+    from an object at the given key
+
+    @since version 1.0.0
+    */
+    void erase(const size_type idx)
+    {
+        // this erase only works for arrays
+        if (is_array())
+        {
+            if (idx >= size())
+            {
+                Throw<std::out_of_range>("array index " + std::to_string(idx) + " is out of range");
+            }
+
+            m_value.array->erase(m_value.array->begin() + static_cast<difference_type>(idx));
+        }
+        else
+        {
+            Throw<std::domain_error>("cannot use erase() with " + type_name());
+        }
+    }
+
+    /// @}
+
+
+    ////////////
+    // lookup //
+    ////////////
+
+    /// @name lookup
+    /// @{
+
+    /*!
+    @brief find an element in a JSON object
+
+    Finds an element in a JSON object with key equivalent to @a key. If the
+    element is not found or the JSON value is not an object, end() is
+    returned.
+
+    @param[in] key key value of the element to search for
+
+    @return Iterator to an element with key equivalent to @a key. If no such
+    element is found, past-the-end (see end()) iterator is returned.
+
+    @complexity Logarithmic in the size of the JSON object.
+
+    @liveexample{The example shows how `find()` is used.,find__key_type}
+
+    @since version 1.0.0
+    */
+    iterator find(typename object_t::key_type key)
+    {
+        auto result = end();
+
+        if (is_object())
+        {
+            result.m_it.object_iterator = m_value.object->find(key);
+        }
+
+        return result;
+    }
+
+    /*!
+    @brief find an element in a JSON object
+    @copydoc find(typename object_t::key_type)
+    */
+    const_iterator find(typename object_t::key_type key) const
+    {
+        auto result = cend();
+
+        if (is_object())
+        {
+            result.m_it.object_iterator = m_value.object->find(key);
+        }
+
+        return result;
+    }
+
+    /*!
+    @brief returns the number of occurrences of a key in a JSON object
+
+    Returns the number of elements with key @a key. If ObjectType is the
+    default `std::map` type, the return value will always be `0` (@a key was
+    not found) or `1` (@a key was found).
+
+    @param[in] key key value of the element to count
+
+    @return Number of elements with key @a key. If the JSON value is not an
+    object, the return value will be `0`.
+
+    @complexity Logarithmic in the size of the JSON object.
+
+    @liveexample{The example shows how `count()` is used.,count}
+
+    @since version 1.0.0
+    */
+    size_type count(typename object_t::key_type key) const
+    {
+        // return 0 for all nonobject types
+        return is_object() ? m_value.object->count(key) : 0;
+    }
+
+    /// @}
+
+
+    ///////////////
+    // iterators //
+    ///////////////
+
+    /// @name iterators
+    /// @{
+
+    /*!
+    @brief returns an iterator to the first element
+
+    Returns an iterator to the first element.
+
+    @image html range-begin-end.svg "Illustration from cppreference.com"
+
+    @return iterator to the first element
+
+    @complexity Constant.
+
+    @requirement This function helps `basic_json` satisfying the
+    [Container](http://en.cppreference.com/w/cpp/concept/Container)
+    requirements:
+    - The complexity is constant.
+
+    @liveexample{The following code shows an example for `begin()`.,begin}
+
+    @sa @ref cbegin() -- returns a const iterator to the beginning
+    @sa @ref end() -- returns an iterator to the end
+    @sa @ref cend() -- returns a const iterator to the end
+
+    @since version 1.0.0
+    */
+    iterator begin() noexcept
+    {
+        iterator result(this);
+        result.set_begin();
+        return result;
+    }
+
+    /*!
+    @copydoc basic_json::cbegin()
+    */
+    const_iterator begin() const noexcept
+    {
+        return cbegin();
+    }
+
+    /*!
+    @brief returns a const iterator to the first element
+
+    Returns a const iterator to the first element.
+
+    @image html range-begin-end.svg "Illustration from cppreference.com"
+
+    @return const iterator to the first element
+
+    @complexity Constant.
+
+    @requirement This function helps `basic_json` satisfying the
+    [Container](http://en.cppreference.com/w/cpp/concept/Container)
+    requirements:
+    - The complexity is constant.
+    - Has the semantics of `const_cast<const basic_json&>(*this).begin()`.
+
+    @liveexample{The following code shows an example for `cbegin()`.,cbegin}
+
+    @sa @ref begin() -- returns an iterator to the beginning
+    @sa @ref end() -- returns an iterator to the end
+    @sa @ref cend() -- returns a const iterator to the end
+
+    @since version 1.0.0
+    */
+    const_iterator cbegin() const noexcept
+    {
+        const_iterator result(this);
+        result.set_begin();
+        return result;
+    }
+
+    /*!
+    @brief returns an iterator to one past the last element
+
+    Returns an iterator to one past the last element.
+
+    @image html range-begin-end.svg "Illustration from cppreference.com"
+
+    @return iterator one past the last element
+
+    @complexity Constant.
+
+    @requirement This function helps `basic_json` satisfying the
+    [Container](http://en.cppreference.com/w/cpp/concept/Container)
+    requirements:
+    - The complexity is constant.
+
+    @liveexample{The following code shows an example for `end()`.,end}
+
+    @sa @ref cend() -- returns a const iterator to the end
+    @sa @ref begin() -- returns an iterator to the beginning
+    @sa @ref cbegin() -- returns a const iterator to the beginning
+
+    @since version 1.0.0
+    */
+    iterator end() noexcept
+    {
+        iterator result(this);
+        result.set_end();
+        return result;
+    }
+
+    /*!
+    @copydoc basic_json::cend()
+    */
+    const_iterator end() const noexcept
+    {
+        return cend();
+    }
+
+    /*!
+    @brief returns a const iterator to one past the last element
+
+    Returns a const iterator to one past the last element.
+
+    @image html range-begin-end.svg "Illustration from cppreference.com"
+
+    @return const iterator one past the last element
+
+    @complexity Constant.
+
+    @requirement This function helps `basic_json` satisfying the
+    [Container](http://en.cppreference.com/w/cpp/concept/Container)
+    requirements:
+    - The complexity is constant.
+    - Has the semantics of `const_cast<const basic_json&>(*this).end()`.
+
+    @liveexample{The following code shows an example for `cend()`.,cend}
+
+    @sa @ref end() -- returns an iterator to the end
+    @sa @ref begin() -- returns an iterator to the beginning
+    @sa @ref cbegin() -- returns a const iterator to the beginning
+
+    @since version 1.0.0
+    */
+    const_iterator cend() const noexcept
+    {
+        const_iterator result(this);
+        result.set_end();
+        return result;
+    }
+
+    /*!
+    @brief returns an iterator to the reverse-beginning
+
+    Returns an iterator to the reverse-beginning; that is, the last element.
+
+    @image html range-rbegin-rend.svg "Illustration from cppreference.com"
+
+    @complexity Constant.
+
+    @requirement This function helps `basic_json` satisfying the
+    [ReversibleContainer](http://en.cppreference.com/w/cpp/concept/ReversibleContainer)
+    requirements:
+    - The complexity is constant.
+    - Has the semantics of `reverse_iterator(end())`.
+
+    @liveexample{The following code shows an example for `rbegin()`.,rbegin}
+
+    @sa @ref crbegin() -- returns a const reverse iterator to the beginning
+    @sa @ref rend() -- returns a reverse iterator to the end
+    @sa @ref crend() -- returns a const reverse iterator to the end
+
+    @since version 1.0.0
+    */
+    reverse_iterator rbegin() noexcept
+    {
+        return reverse_iterator(end());
+    }
+
+    /*!
+    @copydoc basic_json::crbegin()
+    */
+    const_reverse_iterator rbegin() const noexcept
+    {
+        return crbegin();
+    }
+
+    /*!
+    @brief returns an iterator to the reverse-end
+
+    Returns an iterator to the reverse-end; that is, one before the first
+    element.
+
+    @image html range-rbegin-rend.svg "Illustration from cppreference.com"
+
+    @complexity Constant.
+
+    @requirement This function helps `basic_json` satisfying the
+    [ReversibleContainer](http://en.cppreference.com/w/cpp/concept/ReversibleContainer)
+    requirements:
+    - The complexity is constant.
+    - Has the semantics of `reverse_iterator(begin())`.
+
+    @liveexample{The following code shows an example for `rend()`.,rend}
+
+    @sa @ref crend() -- returns a const reverse iterator to the end
+    @sa @ref rbegin() -- returns a reverse iterator to the beginning
+    @sa @ref crbegin() -- returns a const reverse iterator to the beginning
+
+    @since version 1.0.0
+    */
+    reverse_iterator rend() noexcept
+    {
+        return reverse_iterator(begin());
+    }
+
+    /*!
+    @copydoc basic_json::crend()
+    */
+    const_reverse_iterator rend() const noexcept
+    {
+        return crend();
+    }
+
+    /*!
+    @brief returns a const reverse iterator to the last element
+
+    Returns a const iterator to the reverse-beginning; that is, the last
+    element.
+
+    @image html range-rbegin-rend.svg "Illustration from cppreference.com"
+
+    @complexity Constant.
+
+    @requirement This function helps `basic_json` satisfying the
+    [ReversibleContainer](http://en.cppreference.com/w/cpp/concept/ReversibleContainer)
+    requirements:
+    - The complexity is constant.
+    - Has the semantics of `const_cast<const basic_json&>(*this).rbegin()`.
+
+    @liveexample{The following code shows an example for `crbegin()`.,crbegin}
+
+    @sa @ref rbegin() -- returns a reverse iterator to the beginning
+    @sa @ref rend() -- returns a reverse iterator to the end
+    @sa @ref crend() -- returns a const reverse iterator to the end
+
+    @since version 1.0.0
+    */
+    const_reverse_iterator crbegin() const noexcept
+    {
+        return const_reverse_iterator(cend());
+    }
+
+    /*!
+    @brief returns a const reverse iterator to one before the first
+
+    Returns a const reverse iterator to the reverse-end; that is, one before
+    the first element.
+
+    @image html range-rbegin-rend.svg "Illustration from cppreference.com"
+
+    @complexity Constant.
+
+    @requirement This function helps `basic_json` satisfying the
+    [ReversibleContainer](http://en.cppreference.com/w/cpp/concept/ReversibleContainer)
+    requirements:
+    - The complexity is constant.
+    - Has the semantics of `const_cast<const basic_json&>(*this).rend()`.
+
+    @liveexample{The following code shows an example for `crend()`.,crend}
+
+    @sa @ref rend() -- returns a reverse iterator to the end
+    @sa @ref rbegin() -- returns a reverse iterator to the beginning
+    @sa @ref crbegin() -- returns a const reverse iterator to the beginning
+
+    @since version 1.0.0
+    */
+    const_reverse_iterator crend() const noexcept
+    {
+        return const_reverse_iterator(cbegin());
+    }
+
+  private:
+    // forward declaration
+    template<typename IteratorType> class iteration_proxy;
+
+  public:
+    /*!
+    @brief wrapper to access iterator member functions in range-based for
+
+    This function allows to access @ref iterator::key() and @ref
+    iterator::value() during range-based for loops. In these loops, a
+    reference to the JSON values is returned, so there is no access to the
+    underlying iterator.
+
+    @note The name of this function is not yet final and may change in the
+    future.
+    */
+    static iteration_proxy<iterator> iterator_wrapper(reference cont)
+    {
+        return iteration_proxy<iterator>(cont);
+    }
+
+    /*!
+    @copydoc iterator_wrapper(reference)
+    */
+    static iteration_proxy<const_iterator> iterator_wrapper(const_reference cont)
+    {
+        return iteration_proxy<const_iterator>(cont);
+    }
+
+    /// @}
+
+
+    //////////////
+    // capacity //
+    //////////////
+
+    /// @name capacity
+    /// @{
+
+    /*!
+    @brief checks whether the container is empty
+
+    Checks if a JSON value has no elements.
+
+    @return The return value depends on the different types and is
+            defined as follows:
+            Value type  | return value
+            ----------- | -------------
+            null        | `true`
+            boolean     | `false`
+            string      | `false`
+            number      | `false`
+            object      | result of function `object_t::empty()`
+            array       | result of function `array_t::empty()`
+
+    @note This function does not return whether a string stored as JSON value
+    is empty - it returns whether the JSON container itself is empty which is
+    false in the case of a string.
+
+    @complexity Constant, as long as @ref array_t and @ref object_t satisfy
+    the Container concept; that is, their `empty()` functions have constant
+    complexity.
+
+    @requirement This function helps `basic_json` satisfying the
+    [Container](http://en.cppreference.com/w/cpp/concept/Container)
+    requirements:
+    - The complexity is constant.
+    - Has the semantics of `begin() == end()`.
+
+    @liveexample{The following code uses `empty()` to check if a JSON
+    object contains any elements.,empty}
+
+    @sa @ref size() -- returns the number of elements
+
+    @since version 1.0.0
+    */
+    bool empty() const noexcept
+    {
+        switch (m_type)
+        {
+            case value_t::null:
+            {
+                // null values are empty
+                return true;
+            }
+
+            case value_t::array:
+            {
+                // delegate call to array_t::empty()
+                return m_value.array->empty();
+            }
+
+            case value_t::object:
+            {
+                // delegate call to object_t::empty()
+                return m_value.object->empty();
+            }
+
+            default:
+            {
+                // all other types are nonempty
+                return false;
+            }
+        }
+    }
+
+    /*!
+    @brief returns the number of elements
+
+    Returns the number of elements in a JSON value.
+
+    @return The return value depends on the different types and is
+            defined as follows:
+            Value type  | return value
+            ----------- | -------------
+            null        | `0`
+            boolean     | `1`
+            string      | `1`
+            number      | `1`
+            object      | result of function object_t::size()
+            array       | result of function array_t::size()
+
+    @note This function does not return the length of a string stored as JSON
+    value - it returns the number of elements in the JSON value which is 1 in
+    the case of a string.
+
+    @complexity Constant, as long as @ref array_t and @ref object_t satisfy
+    the Container concept; that is, their size() functions have constant
+    complexity.
+
+    @requirement This function helps `basic_json` satisfying the
+    [Container](http://en.cppreference.com/w/cpp/concept/Container)
+    requirements:
+    - The complexity is constant.
+    - Has the semantics of `std::distance(begin(), end())`.
+
+    @liveexample{The following code calls `size()` on the different value
+    types.,size}
+
+    @sa @ref empty() -- checks whether the container is empty
+    @sa @ref max_size() -- returns the maximal number of elements
+
+    @since version 1.0.0
+    */
+    size_type size() const noexcept
+    {
+        switch (m_type)
+        {
+            case value_t::null:
+            {
+                // null values are empty
+                return 0;
+            }
+
+            case value_t::array:
+            {
+                // delegate call to array_t::size()
+                return m_value.array->size();
+            }
+
+            case value_t::object:
+            {
+                // delegate call to object_t::size()
+                return m_value.object->size();
+            }
+
+            default:
+            {
+                // all other types have size 1
+                return 1;
+            }
+        }
+    }
+
+    /*!
+    @brief returns the maximum possible number of elements
+
+    Returns the maximum number of elements a JSON value is able to hold due to
+    system or library implementation limitations, i.e. `std::distance(begin(),
+    end())` for the JSON value.
+
+    @return The return value depends on the different types and is
+            defined as follows:
+            Value type  | return value
+            ----------- | -------------
+            null        | `0` (same as `size()`)
+            boolean     | `1` (same as `size()`)
+            string      | `1` (same as `size()`)
+            number      | `1` (same as `size()`)
+            object      | result of function `object_t::max_size()`
+            array       | result of function `array_t::max_size()`
+
+    @complexity Constant, as long as @ref array_t and @ref object_t satisfy
+    the Container concept; that is, their `max_size()` functions have constant
+    complexity.
+
+    @requirement This function helps `basic_json` satisfying the
+    [Container](http://en.cppreference.com/w/cpp/concept/Container)
+    requirements:
+    - The complexity is constant.
+    - Has the semantics of returning `b.size()` where `b` is the largest
+      possible JSON value.
+
+    @liveexample{The following code calls `max_size()` on the different value
+    types. Note the output is implementation specific.,max_size}
+
+    @sa @ref size() -- returns the number of elements
+
+    @since version 1.0.0
+    */
+    size_type max_size() const noexcept
+    {
+        switch (m_type)
+        {
+            case value_t::array:
+            {
+                // delegate call to array_t::max_size()
+                return m_value.array->max_size();
+            }
+
+            case value_t::object:
+            {
+                // delegate call to object_t::max_size()
+                return m_value.object->max_size();
+            }
+
+            default:
+            {
+                // all other types have max_size() == size()
+                return size();
+            }
+        }
+    }
+
+    /// @}
+
+
+    ///////////////
+    // modifiers //
+    ///////////////
+
+    /// @name modifiers
+    /// @{
+
+    /*!
+    @brief clears the contents
+
+    Clears the content of a JSON value and resets it to the default value as
+    if @ref basic_json(value_t) would have been called:
+
+    Value type  | initial value
+    ----------- | -------------
+    null        | `null`
+    boolean     | `false`
+    string      | `""`
+    number      | `0`
+    object      | `{}`
+    array       | `[]`
+
+    @note Floating-point numbers are set to `0.0` which will be serialized to
+    `0`. The vale type remains @ref number_float_t.
+
+    @complexity Linear in the size of the JSON value.
+
+    @liveexample{The example below shows the effect of `clear()` to different
+    JSON types.,clear}
+
+    @since version 1.0.0
+    */
+    void clear() noexcept
+    {
+        switch (m_type)
+        {
+            case value_t::number_integer:
+            {
+                m_value.number_integer = 0;
+                break;
+            }
+
+            case value_t::number_unsigned:
+            {
+                m_value.number_unsigned = 0;
+                break;
+            }
+
+            case value_t::number_float:
+            {
+                m_value.number_float = 0.0;
+                break;
+            }
+
+            case value_t::boolean:
+            {
+                m_value.boolean = false;
+                break;
+            }
+
+            case value_t::string:
+            {
+                m_value.string->clear();
+                break;
+            }
+
+            case value_t::array:
+            {
+                m_value.array->clear();
+                break;
+            }
+
+            case value_t::object:
+            {
+                m_value.object->clear();
+                break;
+            }
+
+            default:
+            {
+                break;
+            }
+        }
+    }
+
+    /*!
+    @brief add an object to an array
+
+    Appends the given element @a val to the end of the JSON value. If the
+    function is called on a JSON null value, an empty array is created before
+    appending @a val.
+
+    @param[in] val the value to add to the JSON array
+
+    @throw std::domain_error when called on a type other than JSON array or
+    null; example: `"cannot use push_back() with number"`
+
+    @complexity Amortized constant.
+
+    @liveexample{The example shows how `push_back()` and `+=` can be used to
+    add elements to a JSON array. Note how the `null` value was silently
+    converted to a JSON array.,push_back}
+
+    @since version 1.0.0
+    */
+    void push_back(basic_json&& val)
+    {
+        // push_back only works for null objects or arrays
+        if (not(is_null() or is_array()))
+        {
+            Throw<std::domain_error>("cannot use push_back() with " + type_name());
+        }
+
+        // transform null object into an array
+        if (is_null())
+        {
+            m_type = value_t::array;
+            m_value = value_t::array;
+            assert_invariant();
+        }
+
+        // add element to array (move semantics)
+        m_value.array->push_back(std::move(val));
+        // invalidate object
+        val.m_type = value_t::null;
+    }
+
+    /*!
+    @brief add an object to an array
+    @copydoc push_back(basic_json&&)
+    */
+    reference operator+=(basic_json&& val)
+    {
+        push_back(std::move(val));
+        return *this;
+    }
+
+    /*!
+    @brief add an object to an array
+    @copydoc push_back(basic_json&&)
+    */
+    void push_back(const basic_json& val)
+    {
+        // push_back only works for null objects or arrays
+        if (not(is_null() or is_array()))
+        {
+            Throw<std::domain_error>("cannot use push_back() with " + type_name());
+        }
+
+        // transform null object into an array
+        if (is_null())
+        {
+            m_type = value_t::array;
+            m_value = value_t::array;
+            assert_invariant();
+        }
+
+        // add element to array
+        m_value.array->push_back(val);
+    }
+
+    /*!
+    @brief add an object to an array
+    @copydoc push_back(basic_json&&)
+    */
+    reference operator+=(const basic_json& val)
+    {
+        push_back(val);
+        return *this;
+    }
+
+    /*!
+    @brief add an object to an object
+
+    Inserts the given element @a val to the JSON object. If the function is
+    called on a JSON null value, an empty object is created before inserting
+    @a val.
+
+    @param[in] val the value to add to the JSON object
+
+    @throw std::domain_error when called on a type other than JSON object or
+    null; example: `"cannot use push_back() with number"`
+
+    @complexity Logarithmic in the size of the container, O(log(`size()`)).
+
+    @liveexample{The example shows how `push_back()` and `+=` can be used to
+    add elements to a JSON object. Note how the `null` value was silently
+    converted to a JSON object.,push_back__object_t__value}
+
+    @since version 1.0.0
+    */
+    void push_back(const typename object_t::value_type& val)
+    {
+        // push_back only works for null objects or objects
+        if (not(is_null() or is_object()))
+        {
+            Throw<std::domain_error>("cannot use push_back() with " + type_name());
+        }
+
+        // transform null object into an object
+        if (is_null())
+        {
+            m_type = value_t::object;
+            m_value = value_t::object;
+            assert_invariant();
+        }
+
+        // add element to array
+        m_value.object->insert(val);
+    }
+
+    /*!
+    @brief add an object to an object
+    @copydoc push_back(const typename object_t::value_type&)
+    */
+    reference operator+=(const typename object_t::value_type& val)
+    {
+        push_back(val);
+        return *this;
+    }
+
+    /*!
+    @brief add an object to an object
+
+    This function allows to use `push_back` with an initializer list. In case
+
+    1. the current value is an object,
+    2. the initializer list @a init contains only two elements, and
+    3. the first element of @a init is a string,
+
+    @a init is converted into an object element and added using
+    @ref push_back(const typename object_t::value_type&). Otherwise, @a init
+    is converted to a JSON value and added using @ref push_back(basic_json&&).
+
+    @param init  an initializer list
+
+    @complexity Linear in the size of the initializer list @a init.
+
+    @note This function is required to resolve an ambiguous overload error,
+          because pairs like `{"key", "value"}` can be both interpreted as
+          `object_t::value_type` or `std::initializer_list<basic_json>`, see
+          https://github.com/nlohmann/json/issues/235 for more information.
+
+    @liveexample{The example shows how initializer lists are treated as
+    objects when possible.,push_back__initializer_list}
+    */
+    void push_back(std::initializer_list<basic_json> init)
+    {
+        if (is_object() and init.size() == 2 and init.begin()->is_string())
+        {
+            const string_t key = *init.begin();
+            push_back(typename object_t::value_type(key, *(init.begin() + 1)));
+        }
+        else
+        {
+            push_back(basic_json(init));
+        }
+    }
+
+    /*!
+    @brief add an object to an object
+    @copydoc push_back(std::initializer_list<basic_json>)
+    */
+    reference operator+=(std::initializer_list<basic_json> init)
+    {
+        push_back(init);
+        return *this;
+    }
+
+    /*!
+    @brief inserts element
+
+    Inserts element @a val before iterator @a pos.
+
+    @param[in] pos iterator before which the content will be inserted; may be
+    the end() iterator
+    @param[in] val element to insert
+    @return iterator pointing to the inserted @a val.
+
+    @throw std::domain_error if called on JSON values other than arrays;
+    example: `"cannot use insert() with string"`
+    @throw std::domain_error if @a pos is not an iterator of *this; example:
+    `"iterator does not fit current value"`
+
+    @complexity Constant plus linear in the distance between pos and end of the
+    container.
+
+    @liveexample{The example shows how `insert()` is used.,insert}
+
+    @since version 1.0.0
+    */
+    iterator insert(const_iterator pos, const basic_json& val)
+    {
+        // insert only works for arrays
+        if (is_array())
+        {
+            // check if iterator pos fits to this JSON value
+            if (pos.m_object != this)
+            {
+                Throw<std::domain_error>("iterator does not fit current value");
+            }
+
+            // insert to array and return iterator
+            iterator result(this);
+            result.m_it.array_iterator = m_value.array->insert(pos.m_it.array_iterator, val);
+            return result;
+        }
+        else
+        {
+            Throw<std::domain_error>("cannot use insert() with " + type_name());
+        }
+    }
+
+    /*!
+    @brief inserts element
+    @copydoc insert(const_iterator, const basic_json&)
+    */
+    iterator insert(const_iterator pos, basic_json&& val)
+    {
+        return insert(pos, val);
+    }
+
+    /*!
+    @brief inserts elements
+
+    Inserts @a cnt copies of @a val before iterator @a pos.
+
+    @param[in] pos iterator before which the content will be inserted; may be
+    the end() iterator
+    @param[in] cnt number of copies of @a val to insert
+    @param[in] val element to insert
+    @return iterator pointing to the first element inserted, or @a pos if
+    `cnt==0`
+
+    @throw std::domain_error if called on JSON values other than arrays;
+    example: `"cannot use insert() with string"`
+    @throw std::domain_error if @a pos is not an iterator of *this; example:
+    `"iterator does not fit current value"`
+
+    @complexity Linear in @a cnt plus linear in the distance between @a pos
+    and end of the container.
+
+    @liveexample{The example shows how `insert()` is used.,insert__count}
+
+    @since version 1.0.0
+    */
+    iterator insert(const_iterator pos, size_type cnt, const basic_json& val)
+    {
+        // insert only works for arrays
+        if (is_array())
+        {
+            // check if iterator pos fits to this JSON value
+            if (pos.m_object != this)
+            {
+                Throw<std::domain_error>("iterator does not fit current value");
+            }
+
+            // insert to array and return iterator
+            iterator result(this);
+            result.m_it.array_iterator = m_value.array->insert(pos.m_it.array_iterator, cnt, val);
+            return result;
+        }
+        else
+        {
+            Throw<std::domain_error>("cannot use insert() with " + type_name());
+        }
+    }
+
+    /*!
+    @brief inserts elements
+
+    Inserts elements from range `[first, last)` before iterator @a pos.
+
+    @param[in] pos iterator before which the content will be inserted; may be
+    the end() iterator
+    @param[in] first begin of the range of elements to insert
+    @param[in] last end of the range of elements to insert
+
+    @throw std::domain_error if called on JSON values other than arrays;
+    example: `"cannot use insert() with string"`
+    @throw std::domain_error if @a pos is not an iterator of *this; example:
+    `"iterator does not fit current value"`
+    @throw std::domain_error if @a first and @a last do not belong to the same
+    JSON value; example: `"iterators do not fit"`
+    @throw std::domain_error if @a first or @a last are iterators into
+    container for which insert is called; example: `"passed iterators may not
+    belong to container"`
+
+    @return iterator pointing to the first element inserted, or @a pos if
+    `first==last`
+
+    @complexity Linear in `std::distance(first, last)` plus linear in the
+    distance between @a pos and end of the container.
+
+    @liveexample{The example shows how `insert()` is used.,insert__range}
+
+    @since version 1.0.0
+    */
+    iterator insert(const_iterator pos, const_iterator first, const_iterator last)
+    {
+        // insert only works for arrays
+        if (not is_array())
+        {
+            Throw<std::domain_error>("cannot use insert() with " + type_name());
+        }
+
+        // check if iterator pos fits to this JSON value
+        if (pos.m_object != this)
+        {
+            Throw<std::domain_error>("iterator does not fit current value");
+        }
+
+        // check if range iterators belong to the same JSON object
+        if (first.m_object != last.m_object)
+        {
+            Throw<std::domain_error>("iterators do not fit");
+        }
+
+        if (first.m_object == this or last.m_object == this)
+        {
+            Throw<std::domain_error>("passed iterators may not belong to container");
+        }
+
+        // insert to array and return iterator
+        iterator result(this);
+        result.m_it.array_iterator = m_value.array->insert(
+                                         pos.m_it.array_iterator,
+                                         first.m_it.array_iterator,
+                                         last.m_it.array_iterator);
+        return result;
+    }
+
+    /*!
+    @brief inserts elements
+
+    Inserts elements from initializer list @a ilist before iterator @a pos.
+
+    @param[in] pos iterator before which the content will be inserted; may be
+    the end() iterator
+    @param[in] ilist initializer list to insert the values from
+
+    @throw std::domain_error if called on JSON values other than arrays;
+    example: `"cannot use insert() with string"`
+    @throw std::domain_error if @a pos is not an iterator of *this; example:
+    `"iterator does not fit current value"`
+
+    @return iterator pointing to the first element inserted, or @a pos if
+    `ilist` is empty
+
+    @complexity Linear in `ilist.size()` plus linear in the distance between
+    @a pos and end of the container.
+
+    @liveexample{The example shows how `insert()` is used.,insert__ilist}
+
+    @since version 1.0.0
+    */
+    iterator insert(const_iterator pos, std::initializer_list<basic_json> ilist)
+    {
+        // insert only works for arrays
+        if (not is_array())
+        {
+            Throw<std::domain_error>("cannot use insert() with " + type_name());
+        }
+
+        // check if iterator pos fits to this JSON value
+        if (pos.m_object != this)
+        {
+            Throw<std::domain_error>("iterator does not fit current value");
+        }
+
+        // insert to array and return iterator
+        iterator result(this);
+        result.m_it.array_iterator = m_value.array->insert(pos.m_it.array_iterator, ilist);
+        return result;
+    }
+
+    /*!
+    @brief exchanges the values
+
+    Exchanges the contents of the JSON value with those of @a other. Does not
+    invoke any move, copy, or swap operations on individual elements. All
+    iterators and references remain valid. The past-the-end iterator is
+    invalidated.
+
+    @param[in,out] other JSON value to exchange the contents with
+
+    @complexity Constant.
+
+    @liveexample{The example below shows how JSON values can be swapped with
+    `swap()`.,swap__reference}
+
+    @since version 1.0.0
+    */
+    void swap(reference other) noexcept (
+        std::is_nothrow_move_constructible<value_t>::value and
+        std::is_nothrow_move_assignable<value_t>::value and
+        std::is_nothrow_move_constructible<json_value>::value and
+        std::is_nothrow_move_assignable<json_value>::value
+    )
+    {
+        std::swap(m_type, other.m_type);
+        std::swap(m_value, other.m_value);
+        assert_invariant();
+    }
+
+    /*!
+    @brief exchanges the values
+
+    Exchanges the contents of a JSON array with those of @a other. Does not
+    invoke any move, copy, or swap operations on individual elements. All
+    iterators and references remain valid. The past-the-end iterator is
+    invalidated.
+
+    @param[in,out] other array to exchange the contents with
+
+    @throw std::domain_error when JSON value is not an array; example: `"cannot
+    use swap() with string"`
+
+    @complexity Constant.
+
+    @liveexample{The example below shows how arrays can be swapped with
+    `swap()`.,swap__array_t}
+
+    @since version 1.0.0
+    */
+    void swap(array_t& other)
+    {
+        // swap only works for arrays
+        if (is_array())
+        {
+            std::swap(*(m_value.array), other);
+        }
+        else
+        {
+            Throw<std::domain_error>("cannot use swap() with " + type_name());
+        }
+    }
+
+    /*!
+    @brief exchanges the values
+
+    Exchanges the contents of a JSON object with those of @a other. Does not
+    invoke any move, copy, or swap operations on individual elements. All
+    iterators and references remain valid. The past-the-end iterator is
+    invalidated.
+
+    @param[in,out] other object to exchange the contents with
+
+    @throw std::domain_error when JSON value is not an object; example:
+    `"cannot use swap() with string"`
+
+    @complexity Constant.
+
+    @liveexample{The example below shows how objects can be swapped with
+    `swap()`.,swap__object_t}
+
+    @since version 1.0.0
+    */
+    void swap(object_t& other)
+    {
+        // swap only works for objects
+        if (is_object())
+        {
+            std::swap(*(m_value.object), other);
+        }
+        else
+        {
+            Throw<std::domain_error>("cannot use swap() with " + type_name());
+        }
+    }
+
+    /*!
+    @brief exchanges the values
+
+    Exchanges the contents of a JSON string with those of @a other. Does not
+    invoke any move, copy, or swap operations on individual elements. All
+    iterators and references remain valid. The past-the-end iterator is
+    invalidated.
+
+    @param[in,out] other string to exchange the contents with
+
+    @throw std::domain_error when JSON value is not a string; example: `"cannot
+    use swap() with boolean"`
+
+    @complexity Constant.
+
+    @liveexample{The example below shows how strings can be swapped with
+    `swap()`.,swap__string_t}
+
+    @since version 1.0.0
+    */
+    void swap(string_t& other)
+    {
+        // swap only works for strings
+        if (is_string())
+        {
+            std::swap(*(m_value.string), other);
+        }
+        else
+        {
+            Throw<std::domain_error>("cannot use swap() with " + type_name());
+        }
+    }
+
+    /// @}
+
+
+    //////////////////////////////////////////
+    // lexicographical comparison operators //
+    //////////////////////////////////////////
+
+    /// @name lexicographical comparison operators
+    /// @{
+
+  private:
+    /*!
+    @brief comparison operator for JSON types
+
+    Returns an ordering that is similar to Python:
+    - order: null < boolean < number < object < array < string
+    - furthermore, each type is not smaller than itself
+
+    @since version 1.0.0
+    */
+    friend bool operator<(const value_t lhs, const value_t rhs) noexcept
+    {
+        static constexpr std::array<uint8_t, 8> order = {{
+                0, // null
+                3, // object
+                4, // array
+                5, // string
+                1, // boolean
+                2, // integer
+                2, // unsigned
+                2, // float
+            }
+        };
+
+        // discarded values are not comparable
+        if (lhs == value_t::discarded or rhs == value_t::discarded)
+        {
+            return false;
+        }
+
+        return order[static_cast<std::size_t>(lhs)] < order[static_cast<std::size_t>(rhs)];
+    }
+
+  public:
+    /*!
+    @brief comparison: equal
+
+    Compares two JSON values for equality according to the following rules:
+    - Two JSON values are equal if (1) they are from the same type and (2)
+      their stored values are the same.
+    - Integer and floating-point numbers are automatically converted before
+      comparison. Floating-point numbers are compared indirectly: two
+      floating-point numbers `f1` and `f2` are considered equal if neither
+      `f1 > f2` nor `f2 > f1` holds.
+    - Two JSON null values are equal.
+
+    @param[in] lhs  first JSON value to consider
+    @param[in] rhs  second JSON value to consider
+    @return whether the values @a lhs and @a rhs are equal
+
+    @complexity Linear.
+
+    @liveexample{The example demonstrates comparing several JSON
+    types.,operator__equal}
+
+    @since version 1.0.0
+    */
+    friend bool operator==(const_reference lhs, const_reference rhs) noexcept
+    {
+        const auto lhs_type = lhs.type();
+        const auto rhs_type = rhs.type();
+
+        if (lhs_type == rhs_type)
+        {
+            switch (lhs_type)
+            {
+                case value_t::array:
+                {
+                    return *lhs.m_value.array == *rhs.m_value.array;
+                }
+                case value_t::object:
+                {
+                    return *lhs.m_value.object == *rhs.m_value.object;
+                }
+                case value_t::null:
+                {
+                    return true;
+                }
+                case value_t::string:
+                {
+                    return *lhs.m_value.string == *rhs.m_value.string;
+                }
+                case value_t::boolean:
+                {
+                    return lhs.m_value.boolean == rhs.m_value.boolean;
+                }
+                case value_t::number_integer:
+                {
+                    return lhs.m_value.number_integer == rhs.m_value.number_integer;
+                }
+                case value_t::number_unsigned:
+                {
+                    return lhs.m_value.number_unsigned == rhs.m_value.number_unsigned;
+                }
+                case value_t::number_float:
+                {
+                    return lhs.m_value.number_float == rhs.m_value.number_float;
+                }
+                default:
+                {
+                    return false;
+                }
+            }
+        }
+        else if (lhs_type == value_t::number_integer and rhs_type == value_t::number_float)
+        {
+            return static_cast<number_float_t>(lhs.m_value.number_integer) == rhs.m_value.number_float;
+        }
+        else if (lhs_type == value_t::number_float and rhs_type == value_t::number_integer)
+        {
+            return lhs.m_value.number_float == static_cast<number_float_t>(rhs.m_value.number_integer);
+        }
+        else if (lhs_type == value_t::number_unsigned and rhs_type == value_t::number_float)
+        {
+            return static_cast<number_float_t>(lhs.m_value.number_unsigned) == rhs.m_value.number_float;
+        }
+        else if (lhs_type == value_t::number_float and rhs_type == value_t::number_unsigned)
+        {
+            return lhs.m_value.number_float == static_cast<number_float_t>(rhs.m_value.number_unsigned);
+        }
+        else if (lhs_type == value_t::number_unsigned and rhs_type == value_t::number_integer)
+        {
+            return static_cast<number_integer_t>(lhs.m_value.number_unsigned) == rhs.m_value.number_integer;
+        }
+        else if (lhs_type == value_t::number_integer and rhs_type == value_t::number_unsigned)
+        {
+            return lhs.m_value.number_integer == static_cast<number_integer_t>(rhs.m_value.number_unsigned);
+        }
+
+        return false;
+    }
+
+    /*!
+    @brief comparison: equal
+
+    The functions compares the given JSON value against a null pointer. As the
+    null pointer can be used to initialize a JSON value to null, a comparison
+    of JSON value @a v with a null pointer should be equivalent to call
+    `v.is_null()`.
+
+    @param[in] v  JSON value to consider
+    @return whether @a v is null
+
+    @complexity Constant.
+
+    @liveexample{The example compares several JSON types to the null pointer.
+    ,operator__equal__nullptr_t}
+
+    @since version 1.0.0
+    */
+    friend bool operator==(const_reference v, std::nullptr_t) noexcept
+    {
+        return v.is_null();
+    }
+
+    /*!
+    @brief comparison: equal
+    @copydoc operator==(const_reference, std::nullptr_t)
+    */
+    friend bool operator==(std::nullptr_t, const_reference v) noexcept
+    {
+        return v.is_null();
+    }
+
+    /*!
+    @brief comparison: not equal
+
+    Compares two JSON values for inequality by calculating `not (lhs == rhs)`.
+
+    @param[in] lhs  first JSON value to consider
+    @param[in] rhs  second JSON value to consider
+    @return whether the values @a lhs and @a rhs are not equal
+
+    @complexity Linear.
+
+    @liveexample{The example demonstrates comparing several JSON
+    types.,operator__notequal}
+
+    @since version 1.0.0
+    */
+    friend bool operator!=(const_reference lhs, const_reference rhs) noexcept
+    {
+        return not (lhs == rhs);
+    }
+
+    /*!
+    @brief comparison: not equal
+
+    The functions compares the given JSON value against a null pointer. As the
+    null pointer can be used to initialize a JSON value to null, a comparison
+    of JSON value @a v with a null pointer should be equivalent to call
+    `not v.is_null()`.
+
+    @param[in] v  JSON value to consider
+    @return whether @a v is not null
+
+    @complexity Constant.
+
+    @liveexample{The example compares several JSON types to the null pointer.
+    ,operator__notequal__nullptr_t}
+
+    @since version 1.0.0
+    */
+    friend bool operator!=(const_reference v, std::nullptr_t) noexcept
+    {
+        return not v.is_null();
+    }
+
+    /*!
+    @brief comparison: not equal
+    @copydoc operator!=(const_reference, std::nullptr_t)
+    */
+    friend bool operator!=(std::nullptr_t, const_reference v) noexcept
+    {
+        return not v.is_null();
+    }
+
+    /*!
+    @brief comparison: less than
+
+    Compares whether one JSON value @a lhs is less than another JSON value @a
+    rhs according to the following rules:
+    - If @a lhs and @a rhs have the same type, the values are compared using
+      the default `<` operator.
+    - Integer and floating-point numbers are automatically converted before
+      comparison
+    - In case @a lhs and @a rhs have different types, the values are ignored
+      and the order of the types is considered, see
+      @ref operator<(const value_t, const value_t).
+
+    @param[in] lhs  first JSON value to consider
+    @param[in] rhs  second JSON value to consider
+    @return whether @a lhs is less than @a rhs
+
+    @complexity Linear.
+
+    @liveexample{The example demonstrates comparing several JSON
+    types.,operator__less}
+
+    @since version 1.0.0
+    */
+    friend bool operator<(const_reference lhs, const_reference rhs) noexcept
+    {
+        const auto lhs_type = lhs.type();
+        const auto rhs_type = rhs.type();
+
+        if (lhs_type == rhs_type)
+        {
+            switch (lhs_type)
+            {
+                case value_t::array:
+                {
+                    return *lhs.m_value.array < *rhs.m_value.array;
+                }
+                case value_t::object:
+                {
+                    return *lhs.m_value.object < *rhs.m_value.object;
+                }
+                case value_t::null:
+                {
+                    return false;
+                }
+                case value_t::string:
+                {
+                    return *lhs.m_value.string < *rhs.m_value.string;
+                }
+                case value_t::boolean:
+                {
+                    return lhs.m_value.boolean < rhs.m_value.boolean;
+                }
+                case value_t::number_integer:
+                {
+                    return lhs.m_value.number_integer < rhs.m_value.number_integer;
+                }
+                case value_t::number_unsigned:
+                {
+                    return lhs.m_value.number_unsigned < rhs.m_value.number_unsigned;
+                }
+                case value_t::number_float:
+                {
+                    return lhs.m_value.number_float < rhs.m_value.number_float;
+                }
+                default:
+                {
+                    return false;
+                }
+            }
+        }
+        else if (lhs_type == value_t::number_integer and rhs_type == value_t::number_float)
+        {
+            return static_cast<number_float_t>(lhs.m_value.number_integer) < rhs.m_value.number_float;
+        }
+        else if (lhs_type == value_t::number_float and rhs_type == value_t::number_integer)
+        {
+            return lhs.m_value.number_float < static_cast<number_float_t>(rhs.m_value.number_integer);
+        }
+        else if (lhs_type == value_t::number_unsigned and rhs_type == value_t::number_float)
+        {
+            return static_cast<number_float_t>(lhs.m_value.number_unsigned) < rhs.m_value.number_float;
+        }
+        else if (lhs_type == value_t::number_float and rhs_type == value_t::number_unsigned)
+        {
+            return lhs.m_value.number_float < static_cast<number_float_t>(rhs.m_value.number_unsigned);
+        }
+        else if (lhs_type == value_t::number_integer and rhs_type == value_t::number_unsigned)
+        {
+            return lhs.m_value.number_integer < static_cast<number_integer_t>(rhs.m_value.number_unsigned);
+        }
+        else if (lhs_type == value_t::number_unsigned and rhs_type == value_t::number_integer)
+        {
+            return static_cast<number_integer_t>(lhs.m_value.number_unsigned) < rhs.m_value.number_integer;
+        }
+
+        // We only reach this line if we cannot compare values. In that case,
+        // we compare types. Note we have to call the operator explicitly,
+        // because MSVC has problems otherwise.
+        return operator<(lhs_type, rhs_type);
+    }
+
+    /*!
+    @brief comparison: less than or equal
+
+    Compares whether one JSON value @a lhs is less than or equal to another
+    JSON value by calculating `not (rhs < lhs)`.
+
+    @param[in] lhs  first JSON value to consider
+    @param[in] rhs  second JSON value to consider
+    @return whether @a lhs is less than or equal to @a rhs
+
+    @complexity Linear.
+
+    @liveexample{The example demonstrates comparing several JSON
+    types.,operator__greater}
+
+    @since version 1.0.0
+    */
+    friend bool operator<=(const_reference lhs, const_reference rhs) noexcept
+    {
+        return not (rhs < lhs);
+    }
+
+    /*!
+    @brief comparison: greater than
+
+    Compares whether one JSON value @a lhs is greater than another
+    JSON value by calculating `not (lhs <= rhs)`.
+
+    @param[in] lhs  first JSON value to consider
+    @param[in] rhs  second JSON value to consider
+    @return whether @a lhs is greater than to @a rhs
+
+    @complexity Linear.
+
+    @liveexample{The example demonstrates comparing several JSON
+    types.,operator__lessequal}
+
+    @since version 1.0.0
+    */
+    friend bool operator>(const_reference lhs, const_reference rhs) noexcept
+    {
+        return not (lhs <= rhs);
+    }
+
+    /*!
+    @brief comparison: greater than or equal
+
+    Compares whether one JSON value @a lhs is greater than or equal to another
+    JSON value by calculating `not (lhs < rhs)`.
+
+    @param[in] lhs  first JSON value to consider
+    @param[in] rhs  second JSON value to consider
+    @return whether @a lhs is greater than or equal to @a rhs
+
+    @complexity Linear.
+
+    @liveexample{The example demonstrates comparing several JSON
+    types.,operator__greaterequal}
+
+    @since version 1.0.0
+    */
+    friend bool operator>=(const_reference lhs, const_reference rhs) noexcept
+    {
+        return not (lhs < rhs);
+    }
+
+    /// @}
+
+
+    ///////////////////
+    // serialization //
+    ///////////////////
+
+    /// @name serialization
+    /// @{
+
+    /*!
+    @brief serialize to stream
+
+    Serialize the given JSON value @a j to the output stream @a o. The JSON
+    value will be serialized using the @ref dump member function. The
+    indentation of the output can be controlled with the member variable
+    `width` of the output stream @a o. For instance, using the manipulator
+    `std::setw(4)` on @a o sets the indentation level to `4` and the
+    serialization result is the same as calling `dump(4)`.
+
+    @note During serializaion, the locale and the precision of the output
+    stream @a o are changed. The original values are restored when the
+    function returns.
+
+    @param[in,out] o  stream to serialize to
+    @param[in] j  JSON value to serialize
+
+    @return the stream @a o
+
+    @complexity Linear.
+
+    @liveexample{The example below shows the serialization with different
+    parameters to `width` to adjust the indentation level.,operator_serialize}
+
+    @since version 1.0.0
+    */
+    friend std::ostream& operator<<(std::ostream& o, const basic_json& j)
+    {
+        // read width member and use it as indentation parameter if nonzero
+        const bool pretty_print = (o.width() > 0);
+        const auto indentation = (pretty_print ? o.width() : 0);
+
+        // reset width to 0 for subsequent calls to this stream
+        o.width(0);
+
+        // fix locale problems
+        const auto old_locale = o.imbue(std::locale::classic());
+        // set precision
+
+        // 6, 15 or 16 digits of precision allows round-trip IEEE 754
+        // string->float->string, string->double->string or string->long
+        // double->string; to be safe, we read this value from
+        // std::numeric_limits<number_float_t>::digits10
+        const auto old_precision = o.precision(std::numeric_limits<double>::digits10);
+
+        // do the actual serialization
+        j.dump(o, pretty_print, static_cast<unsigned int>(indentation));
+
+        // reset locale and precision
+        o.imbue(old_locale);
+        o.precision(old_precision);
+        return o;
+    }
+
+    /*!
+    @brief serialize to stream
+    @copydoc operator<<(std::ostream&, const basic_json&)
+    */
+    friend std::ostream& operator>>(const basic_json& j, std::ostream& o)
+    {
+        return o << j;
+    }
+
+    /// @}
+
+
+    /////////////////////
+    // deserialization //
+    /////////////////////
+
+    /// @name deserialization
+    /// @{
+
+    /*!
+    @brief deserialize from an array
+
+    This function reads from an array of 1-byte values.
+
+    @pre Each element of the container has a size of 1 byte. Violating this
+    precondition yields undefined behavior. **This precondition is enforced
+    with a static assertion.**
+
+    @param[in] array  array to read from
+    @param[in] cb  a parser callback function of type @ref parser_callback_t
+    which is used to control the deserialization by filtering unwanted values
+    (optional)
+
+    @return result of the deserialization
+
+    @complexity Linear in the length of the input. The parser is a predictive
+    LL(1) parser. The complexity can be higher if the parser callback function
+    @a cb has a super-linear complexity.
+
+    @note A UTF-8 byte order mark is silently ignored.
+
+    @liveexample{The example below demonstrates the `parse()` function reading
+    from an array.,parse__array__parser_callback_t}
+
+    @since version 2.0.3
+    */
+    template<class T, std::size_t N>
+    static basic_json parse(T (&array)[N],
+                            const parser_callback_t cb = nullptr)
+    {
+        // delegate the call to the iterator-range parse overload
+        return parse(std::begin(array), std::end(array), cb);
+    }
+
+    /*!
+    @brief deserialize from string literal
+
+    @tparam CharT character/literal type with size of 1 byte
+    @param[in] s  string literal to read a serialized JSON value from
+    @param[in] cb a parser callback function of type @ref parser_callback_t
+    which is used to control the deserialization by filtering unwanted values
+    (optional)
+
+    @return result of the deserialization
+
+    @complexity Linear in the length of the input. The parser is a predictive
+    LL(1) parser. The complexity can be higher if the parser callback function
+    @a cb has a super-linear complexity.
+
+    @note A UTF-8 byte order mark is silently ignored.
+    @note String containers like `std::string` or @ref string_t can be parsed
+          with @ref parse(const ContiguousContainer&, const parser_callback_t)
+
+    @liveexample{The example below demonstrates the `parse()` function with
+    and without callback function.,parse__string__parser_callback_t}
+
+    @sa @ref parse(std::istream&, const parser_callback_t) for a version that
+    reads from an input stream
+
+    @since version 1.0.0 (originally for @ref string_t)
+    */
+    template<typename CharPT, typename std::enable_if<
+                 std::is_pointer<CharPT>::value and
+                 std::is_integral<typename std::remove_pointer<CharPT>::type>::value and
+                 sizeof(typename std::remove_pointer<CharPT>::type) == 1, int>::type = 0>
+    static basic_json parse(const CharPT s,
+                            const parser_callback_t cb = nullptr)
+    {
+        return parser(reinterpret_cast<const char*>(s), cb).parse();
+    }
+
+    /*!
+    @brief deserialize from stream
+
+    @param[in,out] i  stream to read a serialized JSON value from
+    @param[in] cb a parser callback function of type @ref parser_callback_t
+    which is used to control the deserialization by filtering unwanted values
+    (optional)
+
+    @return result of the deserialization
+
+    @complexity Linear in the length of the input. The parser is a predictive
+    LL(1) parser. The complexity can be higher if the parser callback function
+    @a cb has a super-linear complexity.
+
+    @note A UTF-8 byte order mark is silently ignored.
+
+    @liveexample{The example below demonstrates the `parse()` function with
+    and without callback function.,parse__istream__parser_callback_t}
+
+    @sa @ref parse(const char*, const parser_callback_t) for a version
+    that reads from a string
+
+    @since version 1.0.0
+    */
+    static basic_json parse(std::istream& i,
+                            const parser_callback_t cb = nullptr)
+    {
+        return parser(i, cb).parse();
+    }
+
+    /*!
+    @copydoc parse(std::istream&, const parser_callback_t)
+    */
+    static basic_json parse(std::istream&& i,
+                            const parser_callback_t cb = nullptr)
+    {
+        return parser(i, cb).parse();
+    }
+
+    /*!
+    @brief deserialize from an iterator range with contiguous storage
+
+    This function reads from an iterator range of a container with contiguous
+    storage of 1-byte values. Compatible container types include
+    `std::vector`, `std::string`, `std::array`, `std::valarray`, and
+    `std::initializer_list`. Furthermore, C-style arrays can be used with
+    `std::begin()`/`std::end()`. User-defined containers can be used as long
+    as they implement random-access iterators and a contiguous storage.
+
+    @pre The iterator range is contiguous. Violating this precondition yields
+    undefined behavior. **This precondition is enforced with an assertion.**
+    @pre Each element in the range has a size of 1 byte. Violating this
+    precondition yields undefined behavior. **This precondition is enforced
+    with a static assertion.**
+
+    @warning There is no way to enforce all preconditions at compile-time. If
+             the function is called with noncompliant iterators and with
+             assertions switched off, the behavior is undefined and will most
+             likely yield segmentation violation.
+
+    @tparam IteratorType iterator of container with contiguous storage
+    @param[in] first  begin of the range to parse (included)
+    @param[in] last  end of the range to parse (excluded)
+    @param[in] cb  a parser callback function of type @ref parser_callback_t
+    which is used to control the deserialization by filtering unwanted values
+    (optional)
+
+    @return result of the deserialization
+
+    @complexity Linear in the length of the input. The parser is a predictive
+    LL(1) parser. The complexity can be higher if the parser callback function
+    @a cb has a super-linear complexity.
+
+    @note A UTF-8 byte order mark is silently ignored.
+
+    @liveexample{The example below demonstrates the `parse()` function reading
+    from an iterator range.,parse__iteratortype__parser_callback_t}
+
+    @since version 2.0.3
+    */
+    template<class IteratorType, typename std::enable_if<
+                 std::is_base_of<
+                     std::random_access_iterator_tag,
+                     typename std::iterator_traits<IteratorType>::iterator_category>::value, int>::type = 0>
+    static basic_json parse(IteratorType first, IteratorType last,
+                            const parser_callback_t cb = nullptr)
+    {
+        // assertion to check that the iterator range is indeed contiguous,
+        // see http://stackoverflow.com/a/35008842/266378 for more discussion
+        assert(std::accumulate(first, last, std::make_pair<bool, int>(true, 0),
+                               [&first](std::pair<bool, int> res, decltype(*first) val)
+        {
+            res.first &= (val == *(std::next(std::addressof(*first), res.second++)));
+            return res;
+        }).first);
+
+        // assertion to check that each element is 1 byte long
+        static_assert(sizeof(typename std::iterator_traits<IteratorType>::value_type) == 1,
+                      "each element in the iterator range must have the size of 1 byte");
+
+        // if iterator range is empty, create a parser with an empty string
+        // to generate "unexpected EOF" error message
+        if (std::distance(first, last) <= 0)
+        {
+            return parser("").parse();
+        }
+
+        return parser(first, last, cb).parse();
+    }
+
+    /*!
+    @brief deserialize from a container with contiguous storage
+
+    This function reads from a container with contiguous storage of 1-byte
+    values. Compatible container types include `std::vector`, `std::string`,
+    `std::array`, and `std::initializer_list`. User-defined containers can be
+    used as long as they implement random-access iterators and a contiguous
+    storage.
+
+    @pre The container storage is contiguous. Violating this precondition
+    yields undefined behavior. **This precondition is enforced with an
+    assertion.**
+    @pre Each element of the container has a size of 1 byte. Violating this
+    precondition yields undefined behavior. **This precondition is enforced
+    with a static assertion.**
+
+    @warning There is no way to enforce all preconditions at compile-time. If
+             the function is called with a noncompliant container and with
+             assertions switched off, the behavior is undefined and will most
+             likely yield segmentation violation.
+
+    @tparam ContiguousContainer container type with contiguous storage
+    @param[in] c  container to read from
+    @param[in] cb  a parser callback function of type @ref parser_callback_t
+    which is used to control the deserialization by filtering unwanted values
+    (optional)
+
+    @return result of the deserialization
+
+    @complexity Linear in the length of the input. The parser is a predictive
+    LL(1) parser. The complexity can be higher if the parser callback function
+    @a cb has a super-linear complexity.
+
+    @note A UTF-8 byte order mark is silently ignored.
+
+    @liveexample{The example below demonstrates the `parse()` function reading
+    from a contiguous container.,parse__contiguouscontainer__parser_callback_t}
+
+    @since version 2.0.3
+    */
+    template<class ContiguousContainer, typename std::enable_if<
+                 not std::is_pointer<ContiguousContainer>::value and
+                 std::is_base_of<
+                     std::random_access_iterator_tag,
+                     typename std::iterator_traits<decltype(std::begin(std::declval<ContiguousContainer const>()))>::iterator_category>::value
+                 , int>::type = 0>
+    static basic_json parse(const ContiguousContainer& c,
+                            const parser_callback_t cb = nullptr)
+    {
+        // delegate the call to the iterator-range parse overload
+        return parse(std::begin(c), std::end(c), cb);
+    }
+
+    /*!
+    @brief deserialize from stream
+
+    Deserializes an input stream to a JSON value.
+
+    @param[in,out] i  input stream to read a serialized JSON value from
+    @param[in,out] j  JSON value to write the deserialized input to
+
+    @throw std::invalid_argument in case of parse errors
+
+    @complexity Linear in the length of the input. The parser is a predictive
+    LL(1) parser.
+
+    @note A UTF-8 byte order mark is silently ignored.
+
+    @liveexample{The example below shows how a JSON value is constructed by
+    reading a serialization from a stream.,operator_deserialize}
+
+    @sa parse(std::istream&, const parser_callback_t) for a variant with a
+    parser callback function to filter values while parsing
+
+    @since version 1.0.0
+    */
+    friend std::istream& operator<<(basic_json& j, std::istream& i)
+    {
+        j = parser(i).parse();
+        return i;
+    }
+
+    /*!
+    @brief deserialize from stream
+    @copydoc operator<<(basic_json&, std::istream&)
+    */
+    friend std::istream& operator>>(std::istream& i, basic_json& j)
+    {
+        j = parser(i).parse();
+        return i;
+    }
+
+    /// @}
+
+
+  private:
+    ///////////////////////////
+    // convenience functions //
+    ///////////////////////////
+
+    /*!
+    @brief return the type as string
+
+    Returns the type name as string to be used in error messages - usually to
+    indicate that a function was called on a wrong JSON type.
+
+    @return basically a string representation of a the @a m_type member
+
+    @complexity Constant.
+
+    @since version 1.0.0
+    */
+    std::string type_name() const
+    {
+        switch (m_type)
+        {
+            case value_t::null:
+                return "null";
+            case value_t::object:
+                return "object";
+            case value_t::array:
+                return "array";
+            case value_t::string:
+                return "string";
+            case value_t::boolean:
+                return "boolean";
+            case value_t::discarded:
+                return "discarded";
+            default:
+                return "number";
+        }
+    }
+
+    /*!
+    @brief calculates the extra space to escape a JSON string
+
+    @param[in] s  the string to escape
+    @return the number of characters required to escape string @a s
+
+    @complexity Linear in the length of string @a s.
+    */
+    static std::size_t extra_space(const string_t& s) noexcept
+    {
+        return std::accumulate(s.begin(), s.end(), size_t{},
+                               [](size_t res, typename string_t::value_type c)
+        {
+            switch (c)
+            {
+                case '"':
+                case '\\':
+                case '\b':
+                case '\f':
+                case '\n':
+                case '\r':
+                case '\t':
+                {
+                    // from c (1 byte) to \x (2 bytes)
+                    return res + 1;
+                }
+
+                default:
+                {
+                    if (c >= 0x00 and c <= 0x1f)
+                    {
+                        // from c (1 byte) to \uxxxx (6 bytes)
+                        return res + 5;
+                    }
+                    else
+                    {
+                        return res;
+                    }
+                }
+            }
+        });
+    }
+
+    /*!
+    @brief escape a string
+
+    Escape a string by replacing certain special characters by a sequence of
+    an escape character (backslash) and another character and other control
+    characters by a sequence of "\u" followed by a four-digit hex
+    representation.
+
+    @param[in] s  the string to escape
+    @return  the escaped string
+
+    @complexity Linear in the length of string @a s.
+    */
+    static string_t escape_string(const string_t& s)
+    {
+        const auto space = extra_space(s);
+        if (space == 0)
+        {
+            return s;
+        }
+
+        // create a result string of necessary size
+        string_t result(s.size() + space, '\\');
+        std::size_t pos = 0;
+
+        for (const auto& c : s)
+        {
+            switch (c)
+            {
+                // quotation mark (0x22)
+                case '"':
+                {
+                    result[pos + 1] = '"';
+                    pos += 2;
+                    break;
+                }
+
+                // reverse solidus (0x5c)
+                case '\\':
+                {
+                    // nothing to change
+                    pos += 2;
+                    break;
+                }
+
+                // backspace (0x08)
+                case '\b':
+                {
+                    result[pos + 1] = 'b';
+                    pos += 2;
+                    break;
+                }
+
+                // formfeed (0x0c)
+                case '\f':
+                {
+                    result[pos + 1] = 'f';
+                    pos += 2;
+                    break;
+                }
+
+                // newline (0x0a)
+                case '\n':
+                {
+                    result[pos + 1] = 'n';
+                    pos += 2;
+                    break;
+                }
+
+                // carriage return (0x0d)
+                case '\r':
+                {
+                    result[pos + 1] = 'r';
+                    pos += 2;
+                    break;
+                }
+
+                // horizontal tab (0x09)
+                case '\t':
+                {
+                    result[pos + 1] = 't';
+                    pos += 2;
+                    break;
+                }
+
+                default:
+                {
+                    if (c >= 0x00 and c <= 0x1f)
+                    {
+                        // convert a number 0..15 to its hex representation
+                        // (0..f)
+                        static const char hexify[16] =
+                        {
+                            '0', '1', '2', '3', '4', '5', '6', '7',
+                            '8', '9', 'a', 'b', 'c', 'd', 'e', 'f'
+                        };
+
+                        // print character c as \uxxxx
+                        for (const char m :
+                    { 'u', '0', '0', hexify[c >> 4], hexify[c & 0x0f]
+                        })
+                        {
+                            result[++pos] = m;
+                        }
+
+                        ++pos;
+                    }
+                    else
+                    {
+                        // all other characters are added as-is
+                        result[pos++] = c;
+                    }
+                    break;
+                }
+            }
+        }
+
+        return result;
+    }
+
+    /*!
+    @brief internal implementation of the serialization function
+
+    This function is called by the public member function dump and organizes
+    the serialization internally. The indentation level is propagated as
+    additional parameter. In case of arrays and objects, the function is
+    called recursively. Note that
+
+    - strings and object keys are escaped using `escape_string()`
+    - integer numbers are converted implicitly via `operator<<`
+    - floating-point numbers are converted to a string using `"%g"` format
+
+    @param[out] o              stream to write to
+    @param[in] pretty_print    whether the output shall be pretty-printed
+    @param[in] indent_step     the indent level
+    @param[in] current_indent  the current indent level (only used internally)
+    */
+    void dump(std::ostream& o,
+              const bool pretty_print,
+              const unsigned int indent_step,
+              const unsigned int current_indent = 0) const
+    {
+        // variable to hold indentation for recursive calls
+        unsigned int new_indent = current_indent;
+
+        switch (m_type)
+        {
+            case value_t::object:
+            {
+                if (m_value.object->empty())
+                {
+                    o << "{}";
+                    return;
+                }
+
+                o << "{";
+
+                // increase indentation
+                if (pretty_print)
+                {
+                    new_indent += indent_step;
+                    o << "\n";
+                }
+
+                for (auto i = m_value.object->cbegin(); i != m_value.object->cend(); ++i)
+                {
+                    if (i != m_value.object->cbegin())
+                    {
+                        o << (pretty_print ? ",\n" : ",");
+                    }
+                    o << string_t(new_indent, ' ') << "\""
+                      << escape_string(i->first) << "\":"
+                      << (pretty_print ? " " : "");
+                    i->second.dump(o, pretty_print, indent_step, new_indent);
+                }
+
+                // decrease indentation
+                if (pretty_print)
+                {
+                    new_indent -= indent_step;
+                    o << "\n";
+                }
+
+                o << string_t(new_indent, ' ') + "}";
+                return;
+            }
+
+            case value_t::array:
+            {
+                if (m_value.array->empty())
+                {
+                    o << "[]";
+                    return;
+                }
+
+                o << "[";
+
+                // increase indentation
+                if (pretty_print)
+                {
+                    new_indent += indent_step;
+                    o << "\n";
+                }
+
+                for (auto i = m_value.array->cbegin(); i != m_value.array->cend(); ++i)
+                {
+                    if (i != m_value.array->cbegin())
+                    {
+                        o << (pretty_print ? ",\n" : ",");
+                    }
+                    o << string_t(new_indent, ' ');
+                    i->dump(o, pretty_print, indent_step, new_indent);
+                }
+
+                // decrease indentation
+                if (pretty_print)
+                {
+                    new_indent -= indent_step;
+                    o << "\n";
+                }
+
+                o << string_t(new_indent, ' ') << "]";
+                return;
+            }
+
+            case value_t::string:
+            {
+                o << string_t("\"") << escape_string(*m_value.string) << "\"";
+                return;
+            }
+
+            case value_t::boolean:
+            {
+                o << (m_value.boolean ? "true" : "false");
+                return;
+            }
+
+            case value_t::number_integer:
+            {
+                o << m_value.number_integer;
+                return;
+            }
+
+            case value_t::number_unsigned:
+            {
+                o << m_value.number_unsigned;
+                return;
+            }
+
+            case value_t::number_float:
+            {
+                if (m_value.number_float == 0)
+                {
+                    // special case for zero to get "0.0"/"-0.0"
+                    o << (std::signbit(m_value.number_float) ? "-0.0" : "0.0");
+                }
+                else
+                {
+                    o << m_value.number_float;
+                }
+                return;
+            }
+
+            case value_t::discarded:
+            {
+                o << "<discarded>";
+                return;
+            }
+
+            case value_t::null:
+            {
+                o << "null";
+                return;
+            }
+        }
+    }
+
+  private:
+    //////////////////////
+    // member variables //
+    //////////////////////
+
+    /// the type of the current element
+    value_t m_type = value_t::null;
+
+    /// the value of the current element
+    json_value m_value = {};
+
+
+  private:
+    ///////////////
+    // iterators //
+    ///////////////
+
+    /*!
+    @brief an iterator for primitive JSON types
+
+    This class models an iterator for primitive JSON types (boolean, number,
+    string). It's only purpose is to allow the iterator/const_iterator classes
+    to "iterate" over primitive values. Internally, the iterator is modeled by
+    a `difference_type` variable. Value begin_value (`0`) models the begin,
+    end_value (`1`) models past the end.
+    */
+    class primitive_iterator_t
+    {
+      public:
+        /// set iterator to a defined beginning
+        void set_begin() noexcept
+        {
+            m_it = begin_value;
+        }
+
+        /// set iterator to a defined past the end
+        void set_end() noexcept
+  &