include/boost/burl/urlencoded_form.hpp

100.0% Lines (9/9) 100.0% List of functions (3/3) 100.0% Branches (1/1)

[ ] prev/next file

urlencoded_form.hpp

f(x) Functions (3)

Function Calls Lines Branches Blocks

Line	Branch	Hits	Source Code
1			//
2			// Copyright (c) 2026 Mohammad Nejati
3			//
4			// Distributed under the Boost Software License, Version 1.0. (See accompanying
5			// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
6			//
7			// Official repository: https://github.com/cppalliance/burl
8			//
9
10			#ifndef BOOST_BURL_URLENCODED_FORM_HPP
11			#define BOOST_BURL_URLENCODED_FORM_HPP
12
13			#include <boost/burl/any_request_body.hpp>
14			#include <boost/burl/conversion.hpp>
15			#include <boost/burl/detail/config.hpp>
16
17			#include <concepts>
18			#include <initializer_list>
19			#include <ranges>
20			#include <string>
21			#include <string_view>
22			#include <utility>
23
24			namespace boost
25			{
26			namespace burl
27			{
28
29			/** A URL-encoded form request body.
30
31			This container builds the payload of an
32			`application/x-www-form-urlencoded` request from
33			a sequence of name and value pairs. Names and
34			values are percent-encoded, with spaces encoded
35			as `'+'`.
36
37			@par Example
38			@code
39			auto r = co_await c.post("https://example.com/post")
40			.body(burl::urlencoded_form()
41			.append("user", "John")
42			.append("lang", "En"))
43			.send();
44			@endcode
45
46			@see
47			@ref multipart_form,
48			@ref request_builder::body.
49			*/
50			class urlencoded_form
51			{
52			std::string body_;
53
54			class body;
55
56			public:
57			/** Constructor.
58
59			A default-constructed form contains no
60			fields.
61
62			@par Complexity
63			Constant.
64
65			@par Exception Safety
66			Throws nothing.
67			*/
68		3x	urlencoded_form() = default;
69
70			/** Constructor.
71
72			Constructs a form containing the passed
73			name and value pairs.
74
75			@par Example
76			@code
77			burl::urlencoded_form form({
78			{ "user", "John" },
79			{ "lang", "En" } });
80			@endcode
81
82			@par Exception Safety
83			Calls to allocate may throw.
84
85			@param fields The name and value pairs to
86			append.
87			*/
88			BOOST_BURL_DECL
89			urlencoded_form(
90			std::initializer_list<
91			std::pair<std::string_view, std::string_view>> fields);
92
93			/** Constructor.
94
95			Constructs a form containing the name and
96			value pairs from the passed range.
97
98			@par Example
99			@code
100			std::map<std::string, std::string> fields = {
101			{ "user", "John" },
102			{ "lang", "En" } };
103
104			auto r = co_await c.post("https://example.com/post")
105			.body<burl::urlencoded_form>(fields)
106			.send();
107			@endcode
108
109			@par Exception Safety
110			Calls to allocate may throw.
111
112			@param fields The range of name and value
113			pairs to append.
114			*/
115			template<class Range>
116			requires std::ranges::input_range<Range> &&
117			std::convertible_to<
118			std::ranges::range_reference_t<Range>,
119			std::pair<std::string_view, std::string_view>>
120		2x	urlencoded_form(Range&& fields)
121		2x	{
122	1/1 ✓ Branch 2 taken 2 times.	2x	append(std::forward<Range>(fields));
123		2x	}
124
125			/** Append a field to the form.
126
127			The name and value are percent-encoded,
128			with spaces encoded as `'+'`.
129
130			@par Exception Safety
131			Calls to allocate may throw.
132
133			@param name The name of the field.
134
135			@param value The value of the field.
136
137			@return A reference to this object, for
138			chaining.
139			*/
140			BOOST_BURL_DECL
141			urlencoded_form&
142			append(std::string_view name, std::string_view value);
143
144			/** Append fields to the form.
145
146			Appends the name and value pairs from the
147			passed range.
148
149			@par Exception Safety
150			Calls to allocate may throw.
151
152			@param fields The range of name and value
153			pairs to append.
154
155			@return A reference to this object, for
156			chaining.
157			*/
158			template<class Range>
159			requires std::ranges::input_range<Range> &&
160			std::convertible_to<
161			std::ranges::range_reference_t<Range>,
162			std::pair<std::string_view, std::string_view>>
163			urlencoded_form&
164		4x	append(Range&& fields)
165			{
166		12x	for(std::pair<std::string_view, std::string_view> field : fields)
167		8x	append(field.first, field.second);
168		4x	return *this;
169			}
170
171			private:
172			friend BOOST_BURL_DECL any_request_body
173			tag_invoke(body_from_tag<urlencoded_form>, urlencoded_form form);
174			};
175
176			/** Create a request body from a URL-encoded form.
177
178			@param form The form to send.
179
180			@return The request body.
181			*/
182			BOOST_BURL_DECL
183			any_request_body
184			tag_invoke(body_from_tag<urlencoded_form>, urlencoded_form form);
185
186			} // namespace burl
187			} // namespace boost
188
189			#endif
190