1 // Copyright 2019 The Pigweed Authors
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License"); you may not
4 // use this file except in compliance with the License. You may obtain a copy of
5 // the License at
6 //
7 // https://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
11 // WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
12 // License for the specific language governing permissions and limitations under
13 // the License.
14 #pragma once
15
16 // Provides the ToString function, which outputs string representations of
17 // arbitrary types to a buffer.
18 //
19 // ToString returns the number of characters written, excluding the null
20 // terminator, and a status. A null terminator is always written if the output
21 // buffer has room.
22 //
23 // ToString functions may be defined for any type. This is done by providing a
24 // ToString template specialization in the pw namespace. The specialization must
25 // follow ToString's semantics:
26 //
27 // 1. Always null terminate if the output buffer has room.
28 // 2. Return the number of characters written, excluding the null terminator,
29 // as a StatusWithSize.
30 // 3. If the buffer is too small to fit the output, return a StatusWithSize
31 // with the number of characters written and a status of
32 // RESOURCE_EXHAUSTED. Other status codes may be used for different errors.
33 //
34 // For example, providing the following specialization would allow ToString, and
35 // any classes that use it, to print instances of a custom type:
36 //
37 // namespace pw {
38 //
39 // template <>
40 // StatusWithSize ToString<SomeCustomType>(const SomeCustomType& value,
41 // span<char> buffer) {
42 // return /* ... implementation ... */;
43 // }
44 //
45 // } // namespace pw
46 //
47 // Note that none of the functions in this module use std::snprintf. ToString
48 // overloads may use snprintf if needed, but the ToString semantics must be
49 // maintained.
50 //
51 // ToString is a low-level function. To write complex objects to string, a
52 // StringBuilder may be easier to work with. StringBuilder's operator<< may be
53 // overloaded for custom types.
54
55 #include <string_view>
56 #include <type_traits>
57
58 #include "pw_span/span.h"
59 #include "pw_status/status.h"
60 #include "pw_status/status_with_size.h"
61 #include "pw_string/format.h"
62 #include "pw_string/internal/config.h"
63 #include "pw_string/type_to_string.h"
64
65 namespace pw {
66
67 // This function provides string printing numeric types, enums, and anything
68 // that convertible to a std::string_view, such as std::string.
69 template <typename T>
ToString(const T & value,span<char> buffer)70 StatusWithSize ToString(const T& value, span<char> buffer) {
71 if constexpr (std::is_same_v<std::remove_cv_t<T>, bool>) {
72 return string::BoolToString(value, buffer);
73 } else if constexpr (std::is_same_v<std::remove_cv_t<T>, char>) {
74 return string::Copy(std::string_view(&value, 1), buffer);
75 } else if constexpr (std::is_integral_v<T>) {
76 return string::IntToString(value, buffer);
77 } else if constexpr (std::is_enum_v<T>) {
78 return string::IntToString(std::underlying_type_t<T>(value), buffer);
79 } else if constexpr (std::is_floating_point_v<T>) {
80 if constexpr (string::internal::config::kEnableDecimalFloatExpansion) {
81 // TODO(hepler): Look into using the float overload of std::to_chars when
82 // it is available.
83 return string::Format(buffer, "%.3f", value);
84 } else {
85 return string::FloatAsIntToString(value, buffer);
86 }
87 } else if constexpr (std::is_convertible_v<T, std::string_view>) {
88 return string::CopyStringOrNull(value, buffer);
89 } else if constexpr (std::is_pointer_v<std::remove_cv_t<T>> ||
90 std::is_null_pointer_v<T>) {
91 return string::PointerToString(value, buffer);
92 } else {
93 // By default, no definition of UnknownTypeToString is provided.
94 return string::UnknownTypeToString(value, buffer);
95 }
96 }
97
98 // ToString overloads for Pigweed types. To override ToString for a custom type,
99 // specialize the ToString template function.
ToString(Status status,span<char> buffer)100 inline StatusWithSize ToString(Status status, span<char> buffer) {
101 return string::Copy(status.str(), buffer);
102 }
103
ToString(pw_Status status,span<char> buffer)104 inline StatusWithSize ToString(pw_Status status, span<char> buffer) {
105 return ToString(Status(status), buffer);
106 }
107
ToString(std::byte byte,span<char> buffer)108 inline StatusWithSize ToString(std::byte byte, span<char> buffer) {
109 return string::IntToHexString(static_cast<unsigned>(byte), buffer, 2);
110 }
111
112 } // namespace pw
113