1 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
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_STRING_NUMBER_CONVERSIONS_H_
6 #define BASE_STRINGS_STRING_NUMBER_CONVERSIONS_H_
7
8 #include <stddef.h>
9 #include <stdint.h>
10
11 #include <string>
12 #include <vector>
13
14 #include "base/base_export.h"
15 #include "base/strings/string16.h"
16 #include "base/strings/string_piece.h"
17 #include "build/build_config.h"
18
19 // ----------------------------------------------------------------------------
20 // IMPORTANT MESSAGE FROM YOUR SPONSOR
21 //
22 // This file contains no "wstring" variants. New code should use string16. If
23 // you need to make old code work, use the UTF8 version and convert. Please do
24 // not add wstring variants.
25 //
26 // Please do not add "convenience" functions for converting strings to integers
27 // that return the value and ignore success/failure. That encourages people to
28 // write code that doesn't properly handle the error conditions.
29 //
30 // DO NOT use these functions in any UI unless it's NOT localized on purpose.
31 // Instead, use base::MessageFormatter for a complex message with numbers
32 // (integer, float, double) embedded or base::Format{Number,Double,Percent} to
33 // just format a single number/percent. Note that some languages use native
34 // digits instead of ASCII digits while others use a group separator or decimal
35 // point different from ',' and '.'. Using these functions in the UI would lead
36 // numbers to be formatted in a non-native way.
37 // ----------------------------------------------------------------------------
38
39 namespace base {
40
41 // Number -> string conversions ------------------------------------------------
42
43 // Ignores locale! see warning above.
44 BASE_EXPORT std::string NumberToString(int value);
45 BASE_EXPORT string16 NumberToString16(int value);
46 BASE_EXPORT std::string NumberToString(unsigned int value);
47 BASE_EXPORT string16 NumberToString16(unsigned int value);
48 BASE_EXPORT std::string NumberToString(long value);
49 BASE_EXPORT string16 NumberToString16(long value);
50 BASE_EXPORT std::string NumberToString(unsigned long value);
51 BASE_EXPORT string16 NumberToString16(unsigned long value);
52 BASE_EXPORT std::string NumberToString(long long value);
53 BASE_EXPORT string16 NumberToString16(long long value);
54 BASE_EXPORT std::string NumberToString(unsigned long long value);
55 BASE_EXPORT string16 NumberToString16(unsigned long long value);
56 BASE_EXPORT std::string NumberToString(double value);
57 BASE_EXPORT string16 NumberToString16(double value);
58
59 // Type-specific naming for backwards compatibility.
60 //
61 // TODO(brettw) these should be removed and callers converted to the overloaded
62 // "NumberToString" variant.
IntToString(int value)63 inline std::string IntToString(int value) {
64 return NumberToString(value);
65 }
IntToString16(int value)66 inline string16 IntToString16(int value) {
67 return NumberToString16(value);
68 }
UintToString(unsigned value)69 inline std::string UintToString(unsigned value) {
70 return NumberToString(value);
71 }
UintToString16(unsigned value)72 inline string16 UintToString16(unsigned value) {
73 return NumberToString16(value);
74 }
Int64ToString(int64_t value)75 inline std::string Int64ToString(int64_t value) {
76 return NumberToString(value);
77 }
Int64ToString16(int64_t value)78 inline string16 Int64ToString16(int64_t value) {
79 return NumberToString16(value);
80 }
81
82 // String -> number conversions ------------------------------------------------
83
84 // Perform a best-effort conversion of the input string to a numeric type,
85 // setting |*output| to the result of the conversion. Returns true for
86 // "perfect" conversions; returns false in the following cases:
87 // - Overflow. |*output| will be set to the maximum value supported
88 // by the data type.
89 // - Underflow. |*output| will be set to the minimum value supported
90 // by the data type.
91 // - Trailing characters in the string after parsing the number. |*output|
92 // will be set to the value of the number that was parsed.
93 // - Leading whitespace in the string before parsing the number. |*output| will
94 // be set to the value of the number that was parsed.
95 // - No characters parseable as a number at the beginning of the string.
96 // |*output| will be set to 0.
97 // - Empty string. |*output| will be set to 0.
98 // WARNING: Will write to |output| even when returning false.
99 // Read the comments above carefully.
100 BASE_EXPORT bool StringToInt(StringPiece input, int* output);
101 BASE_EXPORT bool StringToInt(StringPiece16 input, int* output);
102
103 BASE_EXPORT bool StringToUint(StringPiece input, unsigned* output);
104 BASE_EXPORT bool StringToUint(StringPiece16 input, unsigned* output);
105
106 BASE_EXPORT bool StringToInt64(StringPiece input, int64_t* output);
107 BASE_EXPORT bool StringToInt64(StringPiece16 input, int64_t* output);
108
109 BASE_EXPORT bool StringToUint64(StringPiece input, uint64_t* output);
110 BASE_EXPORT bool StringToUint64(StringPiece16 input, uint64_t* output);
111
112 BASE_EXPORT bool StringToSizeT(StringPiece input, size_t* output);
113 BASE_EXPORT bool StringToSizeT(StringPiece16 input, size_t* output);
114
115 // For floating-point conversions, only conversions of input strings in decimal
116 // form are defined to work. Behavior with strings representing floating-point
117 // numbers in hexadecimal, and strings representing non-finite values (such as
118 // NaN and inf) is undefined. Otherwise, these behave the same as the integral
119 // variants. This expects the input string to NOT be specific to the locale.
120 // If your input is locale specific, use ICU to read the number.
121 // WARNING: Will write to |output| even when returning false.
122 // Read the comments here and above StringToInt() carefully.
123 BASE_EXPORT bool StringToDouble(const std::string& input, double* output);
124
125 // Hex encoding ----------------------------------------------------------------
126
127 // Returns a hex string representation of a binary buffer. The returned hex
128 // string will be in upper case. This function does not check if |size| is
129 // within reasonable limits since it's written with trusted data in mind. If
130 // you suspect that the data you want to format might be large, the absolute
131 // max size for |size| should be is
132 // std::numeric_limits<size_t>::max() / 2
133 BASE_EXPORT std::string HexEncode(const void* bytes, size_t size);
134
135 // Best effort conversion, see StringToInt above for restrictions.
136 // Will only successful parse hex values that will fit into |output|, i.e.
137 // -0x80000000 < |input| < 0x7FFFFFFF.
138 BASE_EXPORT bool HexStringToInt(StringPiece input, int* output);
139
140 // Best effort conversion, see StringToInt above for restrictions.
141 // Will only successful parse hex values that will fit into |output|, i.e.
142 // 0x00000000 < |input| < 0xFFFFFFFF.
143 // The string is not required to start with 0x.
144 BASE_EXPORT bool HexStringToUInt(StringPiece input, uint32_t* output);
145
146 // Best effort conversion, see StringToInt above for restrictions.
147 // Will only successful parse hex values that will fit into |output|, i.e.
148 // -0x8000000000000000 < |input| < 0x7FFFFFFFFFFFFFFF.
149 BASE_EXPORT bool HexStringToInt64(StringPiece input, int64_t* output);
150
151 // Best effort conversion, see StringToInt above for restrictions.
152 // Will only successful parse hex values that will fit into |output|, i.e.
153 // 0x0000000000000000 < |input| < 0xFFFFFFFFFFFFFFFF.
154 // The string is not required to start with 0x.
155 BASE_EXPORT bool HexStringToUInt64(StringPiece input, uint64_t* output);
156
157 // Similar to the previous functions, except that output is a vector of bytes.
158 // |*output| will contain as many bytes as were successfully parsed prior to the
159 // error. There is no overflow, but input.size() must be evenly divisible by 2.
160 // Leading 0x or +/- are not allowed.
161 BASE_EXPORT bool HexStringToBytes(StringPiece input,
162 std::vector<uint8_t>* output);
163
164 } // namespace base
165
166 #endif // BASE_STRINGS_STRING_NUMBER_CONVERSIONS_H_
167