folly/folly/String-inl.h

/*
 * Copyright (c) Meta Platforms, Inc. and affiliates.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

#pragma once

#include <iterator>
#include <stdexcept>

#include <folly/CppAttributes.h>
#include <folly/container/Reserve.h>

#ifndef FOLLY_STRING_H_
#error This file may only be included from String.h
#endif

namespace folly {

namespace detail {
// Map from character code to value of one-character escape sequence
// ('\n' = 10 maps to 'n'), 'O' if the character should be printed as
// an octal escape sequence, or 'P' if the character is printable and
// should be printed as is.
extern const std::array<char, 256> cEscapeTable;
} // namespace detail

template <class String>
void cEscape(StringPiece str, String& out) { … }

namespace detail {
// Map from the character code of the character following a backslash to
// the unescaped character if a valid one-character escape sequence
// ('n' maps to 10 = '\n'), 'O' if this is the first character of an
// octal escape sequence, 'X' if this is the first character of a
// hexadecimal escape sequence, or 'I' if this escape sequence is invalid.
extern const std::array<char, 256> cUnescapeTable;

// Map from the character code to the hex value, or 16 if invalid hex char.
extern const std::array<unsigned char, 256> hexTable;
} // namespace detail

template <class String>
void cUnescape(StringPiece str, String& out, bool strict) { … }

namespace detail {
// Map from character code to escape mode:
// 0 = pass through
// 1 = unused
// 2 = pass through in PATH mode
// 3 = space, replace with '+' in QUERY mode
// 4 = percent-encode
extern const std::array<unsigned char, 256> uriEscapeTable;
} // namespace detail

template <class String>
void uriEscape(StringPiece str, String& out, UriEscapeMode mode) { … }

template <class String>
bool tryUriUnescape(StringPiece str, String& out, UriEscapeMode mode) { … }

template <class String>
void uriUnescape(StringPiece str, String& out, UriEscapeMode mode) { … }

namespace detail {

/*
 * The following functions are type-overloaded helpers for
 * internalSplit().
 */
inline size_t delimSize(char) { … }
inline size_t delimSize(StringPiece s) { … }
inline bool atDelim(const char* s, char c) { … }
inline bool atDelim(const char* s, StringPiece sp) { … }

// These are used to short-circuit internalSplit() in the case of
// 1-character strings.
inline char delimFront(char) { … }
inline char delimFront(StringPiece s) { … }

template <class OutStringT, class DelimT, class OutputIterator>
void internalSplit(
    DelimT delim, StringPiece sp, OutputIterator out, bool ignoreEmpty);

template <class OutStringT, class Container>
std::enable_if_t<
    IsSplitSupportedContainer<Container>::value &&
    HasSimdSplitCompatibleValueType<Container>::value>
internalSplitRecurseChar(
    char delim,
    folly::StringPiece sp,
    std::back_insert_iterator<Container> it,
    bool ignoreEmpty) { … }

template <class OutStringT, class Iterator>
void internalSplitRecurseChar(
    char delim, folly::StringPiece sp, Iterator it, bool ignoreEmpty) { … }

/*
 * Shared implementation for all the split() overloads.
 *
 * This uses some external helpers that are overloaded to let this
 * algorithm be more performant if the deliminator is a single
 * character instead of a whole string.
 *
 * @param ignoreEmpty if true, don't copy empty segments to output
 */
template <class OutStringT, class DelimT, class OutputIterator>
void internalSplit(
    DelimT delim, StringPiece sp, OutputIterator out, bool ignoreEmpty) { … }

template <class String>
StringPiece prepareDelim(const String& s) { … }
inline char prepareDelim(char c) { … }

template <class OutputType>
void toOrIgnore(StringPiece input, OutputType& output) { … }

inline void toOrIgnore(StringPiece, decltype(std::ignore)&) { … }

template <bool exact, class Delim, class OutputType>
bool splitFixed(const Delim& delimiter, StringPiece input, OutputType& output) { … }

template <bool exact, class Delim, class OutputType, class... OutputTypes>
bool splitFixed(
    const Delim& delimiter,
    StringPiece input,
    OutputType& outHead,
    OutputTypes&... outTail) { … }

} // namespace detail

//////////////////////////////////////////////////////////////////////

template <class Delim, class String, class OutputType>
std::enable_if_t<
    (!detail::IsSimdSupportedDelim<Delim>::value ||
     !detail::HasSimdSplitCompatibleValueType<OutputType>::value) &&
    detail::IsSplitSupportedContainer<OutputType>::value>
split(
    const Delim& delimiter,
    const String& input,
    OutputType& out,
    bool ignoreEmpty) { … }

template <
    class OutputValueType,
    class Delim,
    class String,
    class OutputIterator>
void splitTo(
    const Delim& delimiter,
    const String& input,
    OutputIterator out,
    bool ignoreEmpty) { … }

template <bool exact, class Delim, class... OutputTypes>
typename std::enable_if<
    StrictConjunction<IsConvertible<OutputTypes>...>::value &&
        sizeof...(OutputTypes) >= 1,
    bool>::type
split(const Delim& delimiter, StringPiece input, OutputTypes&... outputs) { … }

namespace detail {

/*
 * If a type can have its string size determined cheaply, we can more
 * efficiently append it in a loop (see internalJoinAppend). Note that the
 * struct need not conform to the std::string api completely (ex. does not need
 * to implement append()).
 */
template <class T>
struct IsSizableString { … };

template <class Iterator>
struct IsSizableStringContainerIterator
    : IsSizableString<typename std::iterator_traits<Iterator>::value_type> { … };

template <class Delim, class Iterator, class String>
void internalJoinAppend(
    Delim delimiter, Iterator begin, Iterator end, String& output) { … }

template <class Delim, class Iterator, class String>
typename std::enable_if<IsSizableStringContainerIterator<Iterator>::value>::type
internalJoin(Delim delimiter, Iterator begin, Iterator end, String& output) { … }

template <class Delim, class Iterator, class String>
typename std::enable_if<
    !IsSizableStringContainerIterator<Iterator>::value>::type
internalJoin(Delim delimiter, Iterator begin, Iterator end, String& output) { … }

} // namespace detail

template <class Delim, class Iterator, class String>
void join(
    const Delim& delimiter, Iterator begin, Iterator end, String& output) { … }

template <class OutputString>
void backslashify(
    folly::StringPiece input, OutputString& output, bool hex_style) { … }

template <class String1, class String2>
void humanify(const String1& input, String2& output) { … }

template <class InputString, class OutputString>
bool hexlify(
    const InputString& input, OutputString& output, bool append_output) { … }

template <class InputString, class OutputString>
bool unhexlify(const InputString& input, OutputString& output) { … }

namespace detail {
/**
 * Hex-dump at most 16 bytes starting at offset from a memory area of size
 * bytes.  Return the number of bytes actually dumped.
 */
size_t hexDumpLine(
    const void* ptr, size_t offset, size_t size, std::string& line);
} // namespace detail

template <class OutIt>
void hexDump(const void* ptr, size_t size, OutIt out) { … }

} // namespace folly