arrow/util/string.h

0001 // Licensed to the Apache Software Foundation (ASF) under one
0002 // or more contributor license agreements.  See the NOTICE file
0003 // distributed with this work for additional information
0004 // regarding copyright ownership.  The ASF licenses this file
0005 // to you under the Apache License, Version 2.0 (the
0006 // "License"); you may not use this file except in compliance
0007 // with the License.  You may obtain a copy of the License at
0008 //
0009 //   http://www.apache.org/licenses/LICENSE-2.0
0010 //
0011 // Unless required by applicable law or agreed to in writing,
0012 // software distributed under the License is distributed on an
0013 // "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
0014 // KIND, either express or implied.  See the License for the
0015 // specific language governing permissions and limitations
0016 // under the License.
0017
0018 #pragma once
0019
0020 #include <cassert>
0021 #include <optional>
0022 #include <string>
0023 #include <string_view>
0024 #include <type_traits>
0025 #include <utility>
0026 #include <vector>
0027
0028 #if __has_include(<charconv>)
0029 #  include <charconv>
0030 #endif
0031
0032 #include "arrow/result.h"
0033 #include "arrow/util/visibility.h"
0034
0035 namespace arrow {
0036
0037 class Status;
0038
0039 ARROW_EXPORT std::string HexEncode(const uint8_t* data, size_t length);
0040
0041 ARROW_EXPORT std::string Escape(const char* data, size_t length);
0042
0043 ARROW_EXPORT std::string HexEncode(const char* data, size_t length);
0044
0045 ARROW_EXPORT std::string HexEncode(std::string_view str);
0046
0047 ARROW_EXPORT std::string Escape(std::string_view str);
0048
0049 ARROW_EXPORT Status ParseHexValue(const char* hex_pair, uint8_t* out);
0050
0051 ARROW_EXPORT Status ParseHexValues(std::string_view hex_string, uint8_t* out);
0052
0053 namespace internal {
0054
0055 /// Like std::string_view::starts_with in C++20
0056 inline bool StartsWith(std::string_view s, std::string_view prefix) {
0057   return s.length() >= prefix.length() &&
0058          (s.empty() || s.substr(0, prefix.length()) == prefix);
0059 }
0060
0061 /// Like std::string_view::ends_with in C++20
0062 inline bool EndsWith(std::string_view s, std::string_view suffix) {
0063   return s.length() >= suffix.length() &&
0064          (s.empty() || s.substr(s.length() - suffix.length()) == suffix);
0065 }
0066
0067 /// \brief Split a string with a delimiter
0068 ARROW_EXPORT
0069 std::vector<std::string_view> SplitString(std::string_view v, char delim,
0070                                           int64_t limit = 0);
0071
0072 /// \brief Join strings with a delimiter
0073 ARROW_EXPORT
0074 std::string JoinStrings(const std::vector<std::string_view>& strings,
0075                         std::string_view delimiter);
0076
0077 /// \brief Join strings with a delimiter
0078 ARROW_EXPORT
0079 std::string JoinStrings(const std::vector<std::string>& strings,
0080                         std::string_view delimiter);
0081
0082 /// \brief Trim whitespace from left and right sides of string
0083 ARROW_EXPORT
0084 std::string TrimString(std::string value);
0085
0086 ARROW_EXPORT
0087 bool AsciiEqualsCaseInsensitive(std::string_view left, std::string_view right);
0088
0089 ARROW_EXPORT
0090 std::string AsciiToLower(std::string_view value);
0091
0092 ARROW_EXPORT
0093 std::string AsciiToUpper(std::string_view value);
0094
0095 /// \brief Search for the first instance of a token and replace it or return nullopt if
0096 /// the token is not found.
0097 ARROW_EXPORT
0098 std::optional<std::string> Replace(std::string_view s, std::string_view token,
0099                                    std::string_view replacement);
0100
0101 /// \brief Get boolean value from string
0102 ///
0103 /// If "1", "true" (case-insensitive), returns true
0104 /// If "0", "false" (case-insensitive), returns false
0105 /// Otherwise, returns Status::Invalid
0106 ARROW_EXPORT
0107 arrow::Result<bool> ParseBoolean(std::string_view value);
0108
0109 #if __has_include(<charconv>)
0110
0111 namespace detail {
0112 template <typename T, typename = void>
0113 struct can_to_chars : public std::false_type {};
0114
0115 template <typename T>
0116 struct can_to_chars<
0117     T, std::void_t<decltype(std::to_chars(std::declval<char*>(), std::declval<char*>(),
0118                                           std::declval<std::remove_reference_t<T>>()))>>
0119     : public std::true_type {};
0120 }  // namespace detail
0121
0122 /// \brief Whether std::to_chars exists for the current value type.
0123 ///
0124 /// This is useful as some C++ libraries do not implement all specified overloads
0125 /// for std::to_chars.
0126 template <typename T>
0127 inline constexpr bool have_to_chars = detail::can_to_chars<T>::value;
0128
0129 /// \brief An ergonomic wrapper around std::to_chars, returning a std::string
0130 ///
0131 /// For most inputs, the std::string result will not incur any heap allocation
0132 /// thanks to small string optimization.
0133 ///
0134 /// Compared to std::to_string, this function gives locale-agnostic results
0135 /// and might also be faster.
0136 template <typename T, typename... Args>
0137 std::string ToChars(T value, Args&&... args) {
0138   if constexpr (!have_to_chars<T>) {
0139     // Some C++ standard libraries do not yet implement std::to_chars for all types,
0140     // in which case we have to fallback to std::string.
0141     return std::to_string(value);
0142   } else {
0143     // According to various sources, the GNU libstdc++ and Microsoft's C++ STL
0144     // allow up to 15 bytes of small string optimization, while clang's libc++
0145     // goes up to 22 bytes. Choose the pessimistic value.
0146     std::string out(15, 0);
0147     auto res = std::to_chars(&out.front(), &out.back(), value, args...);
0148     while (res.ec != std::errc{}) {
0149       assert(res.ec == std::errc::value_too_large);
0150       out.resize(out.capacity() * 2);
0151       res = std::to_chars(&out.front(), &out.back(), value, args...);
0152     }
0153     const auto length = res.ptr - out.data();
0154     assert(length <= static_cast<int64_t>(out.length()));
0155     out.resize(length);
0156     return out;
0157   }
0158 }
0159
0160 #else  // !__has_include(<charconv>)
0161
0162 template <typename T>
0163 inline constexpr bool have_to_chars = false;
0164
0165 template <typename T, typename... Args>
0166 std::string ToChars(T value, Args&&... args) {
0167   return std::to_string(value);
0168 }
0169
0170 #endif
0171
0172 }  // namespace internal
0173 }  // namespace arrow