1 // Copyright 2011 The Chromium Authors
2 // Use of this source code is governed by a BSD-style license that can be
3 // found in the LICENSE file.
4
5 #ifndef BASE_STRINGS_UTF_STRING_CONVERSIONS_H_
6 #define BASE_STRINGS_UTF_STRING_CONVERSIONS_H_
7
8 #include <stddef.h>
9
10 #include <string>
11 #include <string_view>
12
13 #include "base/base_export.h"
14 #include "base/types/always_false.h"
15 #include "build/build_config.h"
16
17 namespace base {
18
19 // These convert between UTF-8, -16, and -32 strings. They are potentially slow,
20 // so avoid unnecessary conversions. The low-level versions return a boolean
21 // indicating whether the conversion was 100% valid. In this case, it will still
22 // do the best it can and put the result in the output buffer. The versions that
23 // return strings ignore this error and just return the best conversion
24 // possible.
25 BASE_EXPORT bool WideToUTF8(const wchar_t* src, size_t src_len,
26 std::string* output);
27 [[nodiscard]] BASE_EXPORT std::string WideToUTF8(std::wstring_view wide);
28 BASE_EXPORT bool UTF8ToWide(const char* src, size_t src_len,
29 std::wstring* output);
30 [[nodiscard]] BASE_EXPORT std::wstring UTF8ToWide(std::string_view utf8);
31
32 BASE_EXPORT bool WideToUTF16(const wchar_t* src,
33 size_t src_len,
34 std::u16string* output);
35 [[nodiscard]] BASE_EXPORT std::u16string WideToUTF16(std::wstring_view wide);
36 BASE_EXPORT bool UTF16ToWide(const char16_t* src,
37 size_t src_len,
38 std::wstring* output);
39 [[nodiscard]] BASE_EXPORT std::wstring UTF16ToWide(std::u16string_view utf16);
40
41 BASE_EXPORT bool UTF8ToUTF16(const char* src,
42 size_t src_len,
43 std::u16string* output);
44 [[nodiscard]] BASE_EXPORT std::u16string UTF8ToUTF16(std::string_view utf8);
45 BASE_EXPORT bool UTF16ToUTF8(const char16_t* src,
46 size_t src_len,
47 std::string* output);
48 [[nodiscard]] BASE_EXPORT std::string UTF16ToUTF8(std::u16string_view utf16);
49
50 // This converts an ASCII string, typically a hardcoded constant, to a UTF16
51 // string.
52 [[nodiscard]] BASE_EXPORT std::u16string ASCIIToUTF16(std::string_view ascii);
53
54 // Converts to 7-bit ASCII by truncating. The result must be known to be ASCII
55 // beforehand.
56 [[nodiscard]] BASE_EXPORT std::string UTF16ToASCII(std::u16string_view utf16);
57
58 #if defined(WCHAR_T_IS_16_BIT)
59 // This converts an ASCII string, typically a hardcoded constant, to a wide
60 // string.
61 [[nodiscard]] BASE_EXPORT std::wstring ASCIIToWide(std::string_view ascii);
62
63 // Converts to 7-bit ASCII by truncating. The result must be known to be ASCII
64 // beforehand.
65 [[nodiscard]] BASE_EXPORT std::string WideToASCII(std::wstring_view wide);
66 #endif // defined(WCHAR_T_IS_16_BIT)
67
68 // The conversion functions in this file should not be used to convert string
69 // literals. Instead, the corresponding prefixes (e.g. u"" for UTF16 or L"" for
70 // Wide) should be used. Catch those cases with overloads that assert at compile
71 // time.
72 template <size_t N>
WideToUTF16(const wchar_t (& str)[N])73 [[noreturn]] std::u16string WideToUTF16(const wchar_t (&str)[N]) {
74 static_assert(AlwaysFalse<decltype(N)>,
75 "Error: Use u\"...\" to create a std::u16string literal.");
76 }
77
78 template <size_t N>
UTF8ToUTF16(const char (& str)[N])79 [[noreturn]] std::u16string UTF8ToUTF16(const char (&str)[N]) {
80 static_assert(AlwaysFalse<decltype(N)>,
81 "Error: Use u\"...\" to create a std::u16string literal.");
82 }
83
84 template <size_t N>
ASCIIToUTF16(const char (& str)[N])85 [[noreturn]] std::u16string ASCIIToUTF16(const char (&str)[N]) {
86 static_assert(AlwaysFalse<decltype(N)>,
87 "Error: Use u\"...\" to create a std::u16string literal.");
88 }
89
90 // Mutable character arrays are usually only populated during runtime. Continue
91 // to allow this conversion.
92 template <size_t N>
ASCIIToUTF16(char (& str)[N])93 std::u16string ASCIIToUTF16(char (&str)[N]) {
94 return ASCIIToUTF16(std::string_view(str));
95 }
96
97 } // namespace base
98
99 #endif // BASE_STRINGS_UTF_STRING_CONVERSIONS_H_
100