2fb57988-1891-456a-9f50-ba8202ac9608

Committed 27 Jan 2026 07:00AM UTC coverage: 83.928% (+1.1%) from 82.793%

Build # 2fb57988-1891-456a-9f50-ba8202ac9608

Build Type

Pull #87

circleci

Committed by

doomlaur

Commit Message

Slightly clarified character encodings in README.md

Pull Request Pull Request #87: Improve documentation when exceptions are thrown (fixes #81)

Run Details

15263 of 19954 branches covered (76.49%)

722 of 901 new or added lines in 37 files covered. (80.13%)

15 existing lines in 5 files now uncovered.

12491 of 14883 relevant lines covered (83.93%)

12216.5 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

98.86

./include/xlnt/utils/optional.hpp

// Copyright (c) 2016-2022 Thomas Fussell
// Copyright (c) 2024-2025 xlnt-community
//
// 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
//
// @license: http://www.opensource.org/licenses/mit-license.php
// @author: see AUTHORS file

#pragma once

#include "xlnt/utils/exceptions.hpp"
#include "xlnt/utils/numeric.hpp"
#include <type_traits>
#include <cstring>

namespace xlnt {

/// <summary>
/// Many settings in xlnt are allowed to not have a value set. This class
/// encapsulates a value which may or may not be set. Memory is allocated
/// within the optional class.
/// </summary>
template <typename T>
class optional
{
#if ((defined(_MSC_VER) && _MSC_VER <= 1900) || (defined(__GNUC__) && __GNUC__ < 5))
// Disable enhanced type checking on Visual Studio <= 2015 and GCC <5
#define XLNT_NOEXCEPT_VALUE_COMPAT(...) (false)
#else
#define XLNT_NOEXCEPT_VALUE_COMPAT(...) (__VA_ARGS__)
    using ctor_copy_T_noexcept = typename std::conditional<std::is_nothrow_copy_constructible<T>{}, std::true_type, std::false_type>::type;
    using ctor_move_T_noexcept = typename std::conditional<std::is_nothrow_move_constructible<T>{}, std::true_type, std::false_type>::type;
    using copy_ctor_noexcept = ctor_copy_T_noexcept;
    using move_ctor_noexcept = ctor_move_T_noexcept;
    using set_copy_noexcept_t = typename std::conditional<std::is_nothrow_copy_constructible<T>{} && std::is_nothrow_assignable<T, T>{}, std::true_type, std::false_type>::type;
    using set_move_noexcept_t = typename std::conditional<std::is_nothrow_move_constructible<T>{} && std::is_nothrow_move_assignable<T>{}, std::true_type, std::false_type>::type;
    using clear_noexcept_t = typename std::conditional<std::is_nothrow_destructible<T>{}, std::true_type, std::false_type>::type;
#endif
    /// <summary>
    /// Default equality operation, just uses operator==
    /// </summary>
    template <typename U = T, typename std::enable_if<!std::is_floating_point<U>::value>::type * = nullptr>
    constexpr bool compare_equal(const U &lhs, const U &rhs) const
    {
        return lhs == rhs;
    }

    /// <summary>
    /// equality operation for floating point numbers. Provides "fuzzy" equality
    /// </summary>
    template <typename U = T, typename std::enable_if<std::is_floating_point<U>::value>::type * = nullptr>
    constexpr bool compare_equal(const U &lhs, const U &rhs) const
    {
        return detail::float_equals(lhs, rhs);
    }

public:
    /// <summary>
    /// Default contructor. is_set() will be false initially.
    /// </summary>
    optional() noexcept
        : has_value_(false),
        storage_{}
    {
    }

    /// <summary>
    /// Constructs this optional with a value.
    /// noexcept if T copy ctor is noexcept
    /// </summary>
    optional(const T &value) noexcept(XLNT_NOEXCEPT_VALUE_COMPAT(ctor_copy_T_noexcept{}))
        : has_value_(true)
    {
        new (&storage_) T(value);
    }

    /// <summary>
    /// Constructs this optional with a value.
    /// noexcept if T move ctor is noexcept
    /// </summary>
    optional(T &&value) noexcept(XLNT_NOEXCEPT_VALUE_COMPAT(ctor_move_T_noexcept{}))
        : has_value_(true)
    {
        new (&storage_) T(std::move(value));
    }

    /// <summary>
    /// Copy constructs this optional from other
    /// noexcept if T copy ctor is noexcept
    /// </summary>
    optional(const optional &other) noexcept(XLNT_NOEXCEPT_VALUE_COMPAT(copy_ctor_noexcept{}))
        : has_value_(other.has_value_)
    {
        if (has_value_)
        {
            new (&storage_) T(other.value_ref());
        }
        else
        {
            std::memset(storage_, 0, sizeof(T));
        }
    }

    /// <summary>
    /// Move constructs this optional from other. Clears the value from other if set
    /// noexcept if T move ctor is noexcept
    /// </summary>
    optional(optional &&other) noexcept(XLNT_NOEXCEPT_VALUE_COMPAT(move_ctor_noexcept{}))
        : has_value_(other.has_value_)
    {
        if (has_value_)
        {
            new (&storage_) T(std::move(other.value_ref()));
            other.clear();
        }
        else
        {
            std::memset(storage_, 0, sizeof(T));
        }
    }

    /// <summary>
    /// Copy assignment of this optional from other
    /// noexcept if set and clear are noexcept for T&
    /// </summary>
    optional &operator=(const optional &other) noexcept(XLNT_NOEXCEPT_VALUE_COMPAT(set_copy_noexcept_t{} && clear_noexcept_t{}))
    {
        if (other.has_value_)
        {
            set(other.value_ref());
        }
        else
        {
            clear();
        }
        return *this;
    }

    /// <summary>
    /// Move assignment of this optional from other
    /// noexcept if set and clear are noexcept for T&&
    /// </summary>
    optional &operator=(optional &&other) noexcept(XLNT_NOEXCEPT_VALUE_COMPAT(set_move_noexcept_t{} && clear_noexcept_t{}))
    {
        if (other.has_value_)
        {
            set(std::move(other.value_ref()));
            other.clear();
        }
        else
        {
            clear();
        }
        return *this;
    }

    /// <summary>
    /// Destructor cleans up the T instance if set
    /// </summary>
    ~optional() noexcept // note:: unconditional because msvc freaks out otherwise
    {
        clear();
    }

    /// <summary>
    /// Returns true if this object currently has a value set. This should
    /// be called before accessing the value with optional::get().
    /// </summary>
    bool is_set() const noexcept
    {
        return has_value_;
    }

    /// <summary>
    /// Copies the value into the stored value
    /// </summary>
    void set(const T &value) noexcept(XLNT_NOEXCEPT_VALUE_COMPAT(set_copy_noexcept_t{}))
    {
        if (has_value_)
        {
            value_ref() = value;
        }
        else
        {
            new (&storage_) T(value);
            has_value_ = true;
        }
    }

    /// <summary>
    /// Moves the value into the stored value
    /// </summary>
    void set(T &&value) noexcept(XLNT_NOEXCEPT_VALUE_COMPAT(set_move_noexcept_t{}))
    {
        // note seperate overload for two reasons (as opposed to perfect forwarding)
        // 1. have to deal with implicit conversions internally with perfect forwarding
        // 2. have to deal with the noexcept specfiers for all the different variations
        // overload is just far and away the simpler solution
        if (has_value_)
        {
            value_ref() = std::move(value);
        }
        else
        {
            new (&storage_) T(std::move(value));
            has_value_ = true;
        }
    }

    /// <summary>
    /// Assignment operator overload. Equivalent to setting the value using optional::set.
    /// </summary>
    optional &operator=(const T &rhs) noexcept(XLNT_NOEXCEPT_VALUE_COMPAT(set_copy_noexcept_t{}))
    {
        set(rhs);
        return *this;
    }

    /// <summary>
    /// Assignment operator overload. Equivalent to setting the value using optional::set.
    /// </summary>
    optional &operator=(T &&rhs) noexcept(XLNT_NOEXCEPT_VALUE_COMPAT(set_move_noexcept_t{}))
    {
        set(std::move(rhs));
        return *this;
    }

    /// <summary>
    /// After this is called, is_set() will return false until a new value is provided.
    /// </summary>
    void clear() noexcept(XLNT_NOEXCEPT_VALUE_COMPAT(clear_noexcept_t{}))
    {
        if (has_value_)
        {
            reinterpret_cast<T *>(&storage_)->~T();
        }
        has_value_ = false;
    }

    /// <summary>
    /// Gets the value. Assumes that the value exists (please call is_set() to check).
    /// If no value has been initialized in this object,
    /// an xlnt::invalid_attribute exception will be thrown.
    /// </summary>
    T &get()
    {
        if (!has_value_)
        {
            throw invalid_attribute("access to empty optional");
        }

        return value_ref();
    }

    /// <summary>
    /// Gets the value. Assumes that the value exists (please call is_set() to check).
    /// If no value has been initialized in this object,
    /// an xlnt::invalid_attribute exception will be thrown.
    /// </summary>
    const T &get() const
    {
        if (!has_value_)
        {
            throw invalid_attribute("access to empty optional");
        }

        return value_ref();
    }

    /// <summary>
    /// Returns true if neither this nor other have a value
    /// or both have a value and those values are equal according to
    /// their equality operator.
    /// </summary>
    bool operator==(const optional<T> &other) const noexcept
    {
        if (has_value_ != other.has_value_)
        {
            return false;
        }
        if (!has_value_)
        {
            return true;
        }
        // equality is overloaded to provide fuzzy equality when T is a fp number
        return compare_equal(value_ref(), other.value_ref());
    }

    /// <summary>
    /// Returns false if neither this nor other have a value
    /// or both have a value and those values are equal according to
    /// their equality operator.
    /// </summary>
    bool operator!=(const optional<T> &other) const noexcept
    {
        return !operator==(other);
    }

private:
    // helpers for getting a T out of storage
    T &value_ref() noexcept
    {
        return *reinterpret_cast<T *>(&storage_);
    }

    const T &value_ref() const noexcept
    {
        return *reinterpret_cast<const T *>(&storage_);
    }

    bool has_value_;
    alignas(T) unsigned char storage_[sizeof(T)];
};

#ifdef XLNT_NOEXCEPT_VALUE_COMPAT
#undef XLNT_NOEXCEPT_VALUE_COMPAT
#endif

} // namespace xlnt

1	// Copyright (c) 2016-2022 Thomas Fussell
2	// Copyright (c) 2024-2025 xlnt-community
3	//
4	// Permission is hereby granted, free of charge, to any person obtaining a copy
5	// of this software and associated documentation files (the "Software"), to deal
6	// in the Software without restriction, including without limitation the rights
7	// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
8	// copies of the Software, and to permit persons to whom the Software is
9	// furnished to do so, subject to the following conditions:
10	//
11	// The above copyright notice and this permission notice shall be included in
12	// all copies or substantial portions of the Software.
13	//
14	// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
15	// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
16	// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
17	// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
18	// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
19	// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
20	// THE SOFTWARE
21	//
22	// @license: http://www.opensource.org/licenses/mit-license.php
23	// @author: see AUTHORS file
24
25	#pragma once
26
27	#include "xlnt/utils/exceptions.hpp"
28	#include "xlnt/utils/numeric.hpp"
29	#include <type_traits>
30	#include <cstring>
31
32	namespace xlnt {
33
34	/// <summary>
35	/// Many settings in xlnt are allowed to not have a value set. This class
36	/// encapsulates a value which may or may not be set. Memory is allocated
37	/// within the optional class.
38	/// </summary>
39	template <typename T>
40	class optional
41	{
42	#if ((defined(_MSC_VER) && _MSC_VER <= 1900) \|\| (defined(__GNUC__) && __GNUC__ < 5))
43	// Disable enhanced type checking on Visual Studio <= 2015 and GCC <5
44	#define XLNT_NOEXCEPT_VALUE_COMPAT(...) (false)
45	#else
46	#define XLNT_NOEXCEPT_VALUE_COMPAT(...) (__VA_ARGS__)
47	using ctor_copy_T_noexcept = typename std::conditional<std::is_nothrow_copy_constructible<T>{}, std::true_type, std::false_type>::type;
48	using ctor_move_T_noexcept = typename std::conditional<std::is_nothrow_move_constructible<T>{}, std::true_type, std::false_type>::type;
49	using copy_ctor_noexcept = ctor_copy_T_noexcept;
50	using move_ctor_noexcept = ctor_move_T_noexcept;
51	using set_copy_noexcept_t = typename std::conditional<std::is_nothrow_copy_constructible<T>{} && std::is_nothrow_assignable<T, T>{}, std::true_type, std::false_type>::type;
52	using set_move_noexcept_t = typename std::conditional<std::is_nothrow_move_constructible<T>{} && std::is_nothrow_move_assignable<T>{}, std::true_type, std::false_type>::type;
53	using clear_noexcept_t = typename std::conditional<std::is_nothrow_destructible<T>{}, std::true_type, std::false_type>::type;
54	#endif
55	/// <summary>
56	/// Default equality operation, just uses operator==
57	/// </summary>
58	template <typename U = T, typename std::enable_if<!std::is_floating_point<U>::value>::type * = nullptr>
59	constexpr bool compare_equal(const U &lhs, const U &rhs) const	9,812✔
60	{
61	return lhs == rhs;	9,812✔
62	}
63
64	/// <summary>
65	/// equality operation for floating point numbers. Provides "fuzzy" equality
66	/// </summary>
67	template <typename U = T, typename std::enable_if<std::is_floating_point<U>::value>::type * = nullptr>
68	constexpr bool compare_equal(const U &lhs, const U &rhs) const	5,153✔
69	{
70	return detail::float_equals(lhs, rhs);	5,153✔
71	}
72
73	public:
74	/// <summary>
75	/// Default contructor. is_set() will be false initially.
76	/// </summary>
77	optional() noexcept	506,719✔
78	: has_value_(false),	506,719✔
79	storage_{}	506,719✔
80	{
81	}	506,719✔
82
83	/// <summary>
84	/// Constructs this optional with a value.
85	/// noexcept if T copy ctor is noexcept
86	/// </summary>
87	optional(const T &value) noexcept(XLNT_NOEXCEPT_VALUE_COMPAT(ctor_copy_T_noexcept{}))	27✔
88	: has_value_(true)	27✔
89	{
90	new (&storage_) T(value);	27!
91	}	27✔
92
93	/// <summary>
94	/// Constructs this optional with a value.
95	/// noexcept if T move ctor is noexcept
96	/// </summary>
97	optional(T &&value) noexcept(XLNT_NOEXCEPT_VALUE_COMPAT(ctor_move_T_noexcept{}))	5,383✔
98	: has_value_(true)	5,383✔
99	{
100	new (&storage_) T(std::move(value));	5,383✔
101	}	5,383✔
102
103	/// <summary>
104	/// Copy constructs this optional from other
105	/// noexcept if T copy ctor is noexcept
106	/// </summary>
107	optional(const optional &other) noexcept(XLNT_NOEXCEPT_VALUE_COMPAT(copy_ctor_noexcept{}))	175,123✔
108	: has_value_(other.has_value_)	175,123✔
109	{
110	if (has_value_)	175,123✔
111	{
112	new (&storage_) T(other.value_ref());	42,773!
113	}
114	else
115	{
116	std::memset(storage_, 0, sizeof(T));	132,350✔
117	}
118	}	175,123✔
119
120	/// <summary>
121	/// Move constructs this optional from other. Clears the value from other if set
122	/// noexcept if T move ctor is noexcept
123	/// </summary>
124	optional(optional &&other) noexcept(XLNT_NOEXCEPT_VALUE_COMPAT(move_ctor_noexcept{}))	101,073✔
125	: has_value_(other.has_value_)	101,073✔
126	{
127	if (has_value_)	101,073✔
128	{
129	new (&storage_) T(std::move(other.value_ref()));	19,088!
130	other.clear();	19,088✔
131	}
132	else
133	{
134	std::memset(storage_, 0, sizeof(T));	81,985✔
135	}
136	}	101,073✔
137
138	/// <summary>
139	/// Copy assignment of this optional from other
140	/// noexcept if set and clear are noexcept for T&
141	/// </summary>
142	optional &operator=(const optional &other) noexcept(XLNT_NOEXCEPT_VALUE_COMPAT(set_copy_noexcept_t{} && clear_noexcept_t{}))	234,113✔
143	{
144	if (other.has_value_)	234,113✔
145	{
146	set(other.value_ref());	195,396✔
147	}
148	else
149	{
150	clear();	38,717✔
151	}
152	return *this;	234,113✔
153	}
154
155	/// <summary>
156	/// Move assignment of this optional from other
157	/// noexcept if set and clear are noexcept for T&&
158	/// </summary>
159	optional &operator=(optional &&other) noexcept(XLNT_NOEXCEPT_VALUE_COMPAT(set_move_noexcept_t{} && clear_noexcept_t{}))	7,650✔
160	{
161	if (other.has_value_)	7,650✔
162	{
163	set(std::move(other.value_ref()));	5,720✔
164	other.clear();	5,720✔
165	}
166	else
167	{
168	clear();	1,930✔
169	}
170	return *this;	7,650✔
171	}
172
173	/// <summary>
174	/// Destructor cleans up the T instance if set
175	/// </summary>
176	~optional() noexcept // note:: unconditional because msvc freaks out otherwise	788,325✔
177	{
178	clear();	788,325✔
179	}	788,325✔
180
181	/// <summary>
182	/// Returns true if this object currently has a value set. This should
183	/// be called before accessing the value with optional::get().
184	/// </summary>
185	bool is_set() const noexcept	288,495✔
186	{
187	return has_value_;	288,495✔
188	}
189
190	/// <summary>
191	/// Copies the value into the stored value
192	/// </summary>
193	void set(const T &value) noexcept(XLNT_NOEXCEPT_VALUE_COMPAT(set_copy_noexcept_t{}))	393,527✔
194	{
195	if (has_value_)	393,527✔
196	{
197	value_ref() = value;	5,907✔
198	}
199	else
200	{
201	new (&storage_) T(value);	387,620!
202	has_value_ = true;	387,620✔
203	}
204	}	393,527✔
205
206	/// <summary>
207	/// Moves the value into the stored value
208	/// </summary>
209	void set(T &&value) noexcept(XLNT_NOEXCEPT_VALUE_COMPAT(set_move_noexcept_t{}))	26,312✔
210	{
211	// note seperate overload for two reasons (as opposed to perfect forwarding)
212	// 1. have to deal with implicit conversions internally with perfect forwarding
213	// 2. have to deal with the noexcept specfiers for all the different variations
214	// overload is just far and away the simpler solution
215	if (has_value_)	26,312✔
216	{
217	value_ref() = std::move(value);	1,463✔
218	}
219	else
220	{
221	new (&storage_) T(std::move(value));	24,849!
222	has_value_ = true;	24,849✔
223	}
224	}	26,312✔
225
226	/// <summary>
227	/// Assignment operator overload. Equivalent to setting the value using optional::set.
228	/// </summary>
229	optional &operator=(const T &rhs) noexcept(XLNT_NOEXCEPT_VALUE_COMPAT(set_copy_noexcept_t{}))	197,903✔
230	{
231	set(rhs);	197,903✔
232	return *this;	197,903✔
233	}
234
235	/// <summary>
236	/// Assignment operator overload. Equivalent to setting the value using optional::set.
237	/// </summary>
238	optional &operator=(T &&rhs) noexcept(XLNT_NOEXCEPT_VALUE_COMPAT(set_move_noexcept_t{}))	19,930✔
239	{
240	set(std::move(rhs));	19,930✔
241	return *this;	19,930✔
242	}
243
244	/// <summary>
245	/// After this is called, is_set() will return false until a new value is provided.
246	/// </summary>
247	void clear() noexcept(XLNT_NOEXCEPT_VALUE_COMPAT(clear_noexcept_t{}))	863,350✔
248	{
249	if (has_value_)	863,350✔
250	{
251	reinterpret_cast<T *>(&storage_)->~T();	479,740✔
252	}
253	has_value_ = false;	863,350✔
254	}	863,350✔
255
256	/// <summary>
257	/// Gets the value. Assumes that the value exists (please call is_set() to check).
258	/// If no value has been initialized in this object,
259	/// an xlnt::invalid_attribute exception will be thrown.
260	/// </summary>
261	T &get()	199,408✔
262	{
263	if (!has_value_)	199,408✔
264	{
265	throw invalid_attribute("access to empty optional");	6✔
266	}
267
268	return value_ref();	199,406✔
269	}
270
271	/// <summary>
272	/// Gets the value. Assumes that the value exists (please call is_set() to check).
273	/// If no value has been initialized in this object,
274	/// an xlnt::invalid_attribute exception will be thrown.
275	/// </summary>
276	const T &get() const	18,589✔
277	{
278	if (!has_value_)	18,589!
279	{
NEW 280	throw invalid_attribute("access to empty optional");	×
281	}
282
283	return value_ref();	18,589✔
284	}
285
286	/// <summary>
287	/// Returns true if neither this nor other have a value
288	/// or both have a value and those values are equal according to
289	/// their equality operator.
290	/// </summary>
291	bool operator==(const optional<T> &other) const noexcept	31,943✔
292	{
293	if (has_value_ != other.has_value_)	31,943✔
294	{
295	return false;	189✔
296	}
297	if (!has_value_)	31,754✔
298	{
299	return true;	16,789✔
300	}
301	// equality is overloaded to provide fuzzy equality when T is a fp number
302	return compare_equal(value_ref(), other.value_ref());	14,965✔
303	}
304
305	/// <summary>
306	/// Returns false if neither this nor other have a value
307	/// or both have a value and those values are equal according to
308	/// their equality operator.
309	/// </summary>
310	bool operator!=(const optional<T> &other) const noexcept	79✔
311	{
312	return !operator==(other);	79✔
313	}
314
315	private:
316	// helpers for getting a T out of storage
317	T &value_ref() noexcept	231,584✔
318	{
319	return reinterpret_cast<T >(&storage_);	231,584✔
320	}
321
322	const T &value_ref() const noexcept	286,688✔
323	{
324	return reinterpret_cast<const T >(&storage_);	286,688✔
325	}
326
327	bool has_value_;
328	alignas(T) unsigned char storage_[sizeof(T)];
329	};
330
331	#ifdef XLNT_NOEXCEPT_VALUE_COMPAT
332	#undef XLNT_NOEXCEPT_VALUE_COMPAT
333	#endif
334
335	} // namespace xlnt

xlnt-community / xlnt / 2fb57988-1891-456a-9f50-ba8202ac9608

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous