X-Git-Url: http://plrg.eecs.uci.edu/git/?p=folly.git;a=blobdiff_plain;f=folly%2FString.h;h=0251b987be1287a8d0137cd3aa1bc8a3fb5c42ca;hp=da93cd265d106a296e60a651aad59cd1cfb16bfd;hb=f885995c00a27e0e440c0e5cb66ec3298fc507d4;hpb=35dc92a727f253dfd2594ffd12a03ce166d8ffef diff --git a/folly/String.h b/folly/String.h index da93cd26..0251b987 100644 --- a/folly/String.h +++ b/folly/String.h @@ -1,5 +1,5 @@ /* - * Copyright 2013 Facebook, Inc. + * Copyright 2017 Facebook, Inc. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -14,23 +14,27 @@ * limitations under the License. */ -#ifndef FOLLY_BASE_STRING_H_ -#define FOLLY_BASE_STRING_H_ +#pragma once +#define FOLLY_STRING_H_ +#include #include #include -#include +#include +#include +#include -#ifdef __GNUC__ -# include -# include -#endif +#include +#include -#include "folly/Conv.h" -#include "folly/FBString.h" -#include "folly/FBVector.h" -#include "folly/Range.h" -#include "folly/ScopeGuard.h" +#include +#include +#include +#include +#include +#include +#include +#include // Compatibility function, to make sure toStdString(s) can be called // to convert a std::string or fbstring variable s into type std::string @@ -168,16 +172,26 @@ String uriUnescape(StringPiece str, UriEscapeMode mode = UriEscapeMode::ALL) { * resulting string, and the second appends the produced characters to * the specified string and returns a reference to it. */ -std::string stringPrintf(const char* format, ...) - __attribute__ ((format (printf, 1, 2))); +std::string stringPrintf(FOLLY_PRINTF_FORMAT const char* format, ...) + FOLLY_PRINTF_FORMAT_ATTR(1, 2); + +/* Similar to stringPrintf, with different signature. */ +void stringPrintf(std::string* out, FOLLY_PRINTF_FORMAT const char* fmt, ...) + FOLLY_PRINTF_FORMAT_ATTR(2, 3); -/** Similar to stringPrintf, with different signiture. - */ -void stringPrintf(std::string* out, const char* fmt, ...) - __attribute__ ((format (printf, 2, 3))); +std::string& stringAppendf(std::string* output, + FOLLY_PRINTF_FORMAT const char* format, ...) + FOLLY_PRINTF_FORMAT_ATTR(2, 3); -std::string& stringAppendf(std::string* output, const char* format, ...) - __attribute__ ((format (printf, 2, 3))); +/** + * Similar to stringPrintf, but accepts a va_list argument. + * + * As with vsnprintf() itself, the value of ap is undefined after the call. + * These functions do not call va_end() on ap. + */ +std::string stringVPrintf(const char* format, va_list ap); +void stringVPrintf(std::string* out, const char* format, va_list ap); +std::string& stringVAppendf(std::string* out, const char* format, va_list ap); /** * Backslashify a string, that is, replace non-printable characters @@ -198,12 +212,15 @@ std::string& stringAppendf(std::string* output, const char* format, ...) * C++, use cEscape instead. This function is for display purposes * only. */ -template -void backslashify(const String1& input, String2& output, bool hex_style=false); - -template -String backslashify(const String& input, bool hex_style=false) { - String output; +template +void backslashify( + folly::StringPiece input, + OutputString& output, + bool hex_style = false); + +template +OutputString backslashify(StringPiece input, bool hex_style = false) { + OutputString output; backslashify(input, output, hex_style); return output; } @@ -236,17 +253,43 @@ String humanify(const String& input) { * If append_output is true, append data to the output rather than * replace it. */ -template +template bool hexlify(const InputString& input, OutputString& output, bool append=false); +template +OutputString hexlify(ByteRange input) { + OutputString output; + if (!hexlify(input, output)) { + // hexlify() currently always returns true, so this can't really happen + throw std::runtime_error("hexlify failed"); + } + return output; +} + +template +OutputString hexlify(StringPiece input) { + return hexlify(ByteRange{input}); +} + /** * Same functionality as Python's binascii.unhexlify. Returns true * on successful conversion. */ -template +template bool unhexlify(const InputString& input, OutputString& output); +template +OutputString unhexlify(StringPiece input) { + OutputString output; + if (!unhexlify(input, output)) { + // unhexlify() fails if the input has non-hexidecimal characters, + // or if it doesn't consist of a whole number of bytes + throw std::domain_error("unhexlify() called with non-hex input"); + } + return output; +} + /* * A pretty-printer for numbers that appends suffixes of units of the * given type. It prints 4 sig-figs of value with the most @@ -263,7 +306,8 @@ bool unhexlify(const InputString& input, OutputString& output); * PRETTY_UNITS_METRIC - k, M, G, etc (goes up by 10^3 = 1000 each time) * PRETTY_UNITS_BINARY - k, M, G, etc (goes up by 2^10 = 1024 each time) * PRETTY_UNITS_BINARY_IEC - Ki, Mi, Gi, etc - * + * PRETTY_SI - full SI metric prefixes from yocto to Yotta + * http://en.wikipedia.org/wiki/Metric_prefix * @author Mark Rabkin */ enum PrettyType { @@ -279,11 +323,38 @@ enum PrettyType { PRETTY_UNITS_BINARY, PRETTY_UNITS_BINARY_IEC, - PRETTY_NUM_TYPES + PRETTY_SI, + PRETTY_NUM_TYPES, }; std::string prettyPrint(double val, PrettyType, bool addSpace = true); +/** + * This utility converts StringPiece in pretty format (look above) to double, + * with progress information. Alters the StringPiece parameter + * to get rid of the already-parsed characters. + * Expects string in form {space}* [] + * If string is not in correct format, utility finds longest valid prefix and + * if there at least one, returns double value based on that prefix and + * modifies string to what is left after parsing. Throws and std::range_error + * exception if there is no correct parse. + * Examples(for PRETTY_UNITS_METRIC): + * '10M' => 10 000 000 + * '10 M' => 10 000 000 + * '10' => 10 + * '10 Mx' => 10 000 000, prettyString == "x" + * 'abc' => throws std::range_error + */ +double prettyToDouble(folly::StringPiece *const prettyString, + const PrettyType type); + +/* + * Same as prettyToDouble(folly::StringPiece*, PrettyType), but + * expects whole string to be correctly parseable. Throws std::range_error + * otherwise + */ +double prettyToDouble(folly::StringPiece prettyString, const PrettyType type); + /** * Write a hex dump of size bytes starting at ptr to out. * @@ -313,62 +384,6 @@ std::string hexDump(const void* ptr, size_t size); */ fbstring errnoStr(int err); -/** - * Return the demangled (prettyfied) version of a C++ type. - * - * This function tries to produce a human-readable type, but the type name will - * be returned unchanged in case of error or if demangling isn't supported on - * your system. - * - * Use for debugging -- do not rely on demangle() returning anything useful. - * - * This function may allocate memory (and therefore throw std::bad_alloc). - */ -fbstring demangle(const char* name); -inline fbstring demangle(const std::type_info& type) { - return demangle(type.name()); -} - -/** - * Return the demangled (prettyfied) version of a C++ type in a user-provided - * buffer. - * - * The semantics are the same as for snprintf or strlcpy: bufSize is the size - * of the buffer, the string is always null-terminated, and the return value is - * the number of characters (not including the null terminator) that would have - * been written if the buffer was big enough. (So a return value >= bufSize - * indicates that the output was truncated) - * - * This function does not allocate memory and is async-signal-safe. - * - * Note that the underlying function for the fbstring-returning demangle is - * somewhat standard (abi::__cxa_demangle, which uses malloc), the underlying - * function for this version is less so (cplus_demangle_v3_callback from - * libiberty), so it is possible for the fbstring version to work, while this - * version returns the original, mangled name. - */ -size_t demangle(const char* name, char* buf, size_t bufSize); -inline size_t demangle(const std::type_info& type, char* buf, size_t bufSize) { - return demangle(type.name(), buf, bufSize); -} - -/** - * Debug string for an exception: include type and what(). - */ -inline fbstring exceptionStr(const std::exception& e) { - return folly::to(demangle(typeid(e)), ": ", e.what()); -} - -inline fbstring exceptionStr(std::exception_ptr ep) { - try { - std::rethrow_exception(ep); - } catch (const std::exception& e) { - return exceptionStr(e); - } catch (...) { - return ""; - } -} - /* * Split a string into a list of tokens by delimiter. * @@ -398,36 +413,49 @@ inline fbstring exceptionStr(std::exception_ptr ep) { * or not (generating empty tokens). */ -template +template void split(const Delim& delimiter, const String& input, std::vector& out, - bool ignoreEmpty = false); + const bool ignoreEmpty = false); -template +template void split(const Delim& delimiter, const String& input, folly::fbvector& out, - bool ignoreEmpty = false); + const bool ignoreEmpty = false); -template +template < + class OutputValueType, + class Delim, + class String, + class OutputIterator> void splitTo(const Delim& delimiter, const String& input, OutputIterator out, - bool ignoreEmpty = false); + const bool ignoreEmpty = false); /* - * Split a string into a fixed number of pieces by delimiter. Returns 'true' if - * the fields were all successfully populated. + * Split a string into a fixed number of string pieces and/or numeric types + * by delimiter. Conversions are supported for any type which folly:to<> can + * target, including all overloads of parseTo(). Returns 'true' if the fields + * were all successfully populated. Returns 'false' if there were too few + * fields in the input, or too many fields if exact=true. Casting exceptions + * will not be caught. * - * Example: + * Examples: * * folly::StringPiece name, key, value; * if (folly::split('\t', line, name, key, value)) * ... * - * The 'exact' template paremeter specifies how the function behaves when too + * folly::StringPiece name; + * double value; + * int id; + * if (folly::split('\t', line, name, value, id)) + * ... + * + * The 'exact' template parameter specifies how the function behaves when too * many fields are present in the input string. When 'exact' is set to its * default value of 'true', a call to split will fail if the number of fields in * the input string does not exactly match the number of output parameters @@ -437,14 +465,28 @@ void splitTo(const Delim& delimiter, * folly::StringPiece x, y. * if (folly::split(':', "a:b:c", x, y)) * assert(x == "a" && y == "b:c"); + * + * Note that this will likely not work if the last field's target is of numeric + * type, in which case folly::to<> will throw an exception. */ -template -bool split(const Delim& delimiter, - StringPiece input, - StringPiece& outHead, - StringPieces&... outTail); +namespace detail { +template +struct IsConvertible : std::false_type {}; + +template +struct IsConvertible< + void_t()))>, + OutputType> : std::true_type {}; +} // namespace detail +template +struct IsConvertible : detail::IsConvertible {}; + +template +typename std::enable_if< + StrictConjunction...>::value && + sizeof...(OutputTypes) >= 1, + bool>::type +split(const Delim& delimiter, StringPiece input, OutputTypes&... outputs); /* * Join list of tokens. @@ -489,37 +531,92 @@ std::string join(const Delim& delimiter, return output; } -} // namespace folly +template < + class Delim, + class Iterator, + typename std::enable_if::iterator_category, + std::random_access_iterator_tag>::value>::type* = nullptr> +std::string join(const Delim& delimiter, Iterator begin, Iterator end) { + std::string output; + join(delimiter, begin, end, output); + return output; +} -// Hash functions for string and fbstring usable with e.g. hash_map -#ifdef __GNUC__ -namespace __gnu_cxx { +/** + * Returns a subpiece with all whitespace removed from the front of @sp. + * Whitespace means any of [' ', '\n', '\r', '\t']. + */ +StringPiece ltrimWhitespace(StringPiece sp); -template -struct hash > : private hash { - size_t operator()(const folly::basic_fbstring & s) const { - return hash::operator()(s.c_str()); - } -}; +/** + * Returns a subpiece with all whitespace removed from the back of @sp. + * Whitespace means any of [' ', '\n', '\r', '\t']. + */ +StringPiece rtrimWhitespace(StringPiece sp); -template -struct hash > : private hash { - size_t operator()(const std::basic_string & s) const { - return hash::operator()(s.c_str()); - } -}; +/** + * Returns a subpiece with all whitespace removed from the back and front of @sp. + * Whitespace means any of [' ', '\n', '\r', '\t']. + */ +inline StringPiece trimWhitespace(StringPiece sp) { + return ltrimWhitespace(rtrimWhitespace(sp)); +} + +/** + * Returns a subpiece with all whitespace removed from the front of @sp. + * Whitespace means any of [' ', '\n', '\r', '\t']. + * DEPRECATED: @see ltrimWhitespace @see rtrimWhitespace + */ +inline StringPiece skipWhitespace(StringPiece sp) { + return ltrimWhitespace(sp); +} + +/** + * Strips the leading and the trailing whitespace-only lines. Then looks for + * the least indented non-whitespace-only line and removes its amount of + * leading whitespace from every line. Assumes leading whitespace is either all + * spaces or all tabs. + * + * Purpose: including a multiline string literal in source code, indented to + * the level expected from context. + */ +std::string stripLeftMargin(std::string s); + +/** + * Fast, in-place lowercasing of ASCII alphabetic characters in strings. + * Leaves all other characters unchanged, including those with the 0x80 + * bit set. + * @param str String to convert + * @param length Length of str, in bytes + */ +void toLowerAscii(char* str, size_t length); -} // namespace __gnu_cxx -#endif +inline void toLowerAscii(MutableStringPiece str) { + toLowerAscii(str.begin(), str.size()); +} + +inline void toLowerAscii(std::string& str) { + // str[0] is legal also if the string is empty. + toLowerAscii(&str[0], str.size()); +} -// Hook into boost's type traits -namespace boost { -template -struct has_nothrow_constructor > : true_type { - enum { value = true }; +template < + class Iterator = const char*, + class Base = folly::Range>> +class UTF8Range : public Base { + public: + /* implicit */ UTF8Range(const folly::Range baseRange) + : Base(boost::u8_to_u32_iterator( + baseRange.begin(), baseRange.begin(), baseRange.end()), + boost::u8_to_u32_iterator( + baseRange.end(), baseRange.begin(), baseRange.end())) {} + /* implicit */ UTF8Range(const std::string& baseString) + : Base(folly::Range(baseString)) {} }; -} // namespace boost -#include "folly/String-inl.h" +using UTF8StringPiece = UTF8Range; + +} // namespace folly -#endif +#include