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
18// ----------------------------------------------------------------------------
19// IMPORTANT MESSAGE FROM YOUR SPONSOR
20//
21// This file contains no "wstring" variants. New code should use string16. If
22// you need to make old code work, use the UTF8 version and convert. Please do
23// not add wstring variants.
24//
25// Please do not add "convenience" functions for converting strings to integers
26// that return the value and ignore success/failure. That encourages people to
27// write code that doesn't properly handle the error conditions.
28// ----------------------------------------------------------------------------
29
30namespace base {
31
32// Number -> string conversions ------------------------------------------------
33
34BASE_EXPORT std::string IntToString(int value);
35BASE_EXPORT string16 IntToString16(int value);
36
37BASE_EXPORT std::string UintToString(unsigned value);
38BASE_EXPORT string16 UintToString16(unsigned value);
39
40BASE_EXPORT std::string Int64ToString(int64_t value);
41BASE_EXPORT string16 Int64ToString16(int64_t value);
42
43BASE_EXPORT std::string Uint64ToString(uint64_t value);
44BASE_EXPORT string16 Uint64ToString16(uint64_t value);
45
46BASE_EXPORT std::string SizeTToString(size_t value);
47BASE_EXPORT string16 SizeTToString16(size_t value);
48
49// Deprecated: prefer std::to_string(double) instead.
50// DoubleToString converts the double to a string format that ignores the
51// locale. If you want to use locale specific formatting, use ICU.
52BASE_EXPORT std::string DoubleToString(double value);
53
54// String -> number conversions ------------------------------------------------
55
56// Perform a best-effort conversion of the input string to a numeric type,
57// setting |*output| to the result of the conversion.  Returns true for
58// "perfect" conversions; returns false in the following cases:
59//  - Overflow. |*output| will be set to the maximum value supported
60//    by the data type.
61//  - Underflow. |*output| will be set to the minimum value supported
62//    by the data type.
63//  - Trailing characters in the string after parsing the number.  |*output|
64//    will be set to the value of the number that was parsed.
65//  - Leading whitespace in the string before parsing the number. |*output| will
66//    be set to the value of the number that was parsed.
67//  - No characters parseable as a number at the beginning of the string.
68//    |*output| will be set to 0.
69//  - Empty string.  |*output| will be set to 0.
70// WARNING: Will write to |output| even when returning false.
71//          Read the comments above carefully.
72BASE_EXPORT bool StringToInt(const StringPiece& input, int* output);
73BASE_EXPORT bool StringToInt(const StringPiece16& input, int* output);
74
75BASE_EXPORT bool StringToUint(const StringPiece& input, unsigned* output);
76BASE_EXPORT bool StringToUint(const StringPiece16& input, unsigned* output);
77
78BASE_EXPORT bool StringToInt64(const StringPiece& input, int64_t* output);
79BASE_EXPORT bool StringToInt64(const StringPiece16& input, int64_t* output);
80
81BASE_EXPORT bool StringToUint64(const StringPiece& input, uint64_t* output);
82BASE_EXPORT bool StringToUint64(const StringPiece16& input, uint64_t* output);
83
84BASE_EXPORT bool StringToSizeT(const StringPiece& input, size_t* output);
85BASE_EXPORT bool StringToSizeT(const StringPiece16& input, size_t* output);
86
87// Deprecated: prefer std::stod() instead.
88// For floating-point conversions, only conversions of input strings in decimal
89// form are defined to work.  Behavior with strings representing floating-point
90// numbers in hexadecimal, and strings representing non-finite values (such as
91// NaN and inf) is undefined.  Otherwise, these behave the same as the integral
92// variants.  This expects the input string to NOT be specific to the locale.
93// If your input is locale specific, use ICU to read the number.
94// WARNING: Will write to |output| even when returning false.
95//          Read the comments here and above StringToInt() carefully.
96BASE_EXPORT bool StringToDouble(const std::string& input, double* output);
97
98// Hex encoding ----------------------------------------------------------------
99
100// Returns a hex string representation of a binary buffer. The returned hex
101// string will be in upper case. This function does not check if |size| is
102// within reasonable limits since it's written with trusted data in mind.  If
103// you suspect that the data you want to format might be large, the absolute
104// max size for |size| should be is
105//   std::numeric_limits<size_t>::max() / 2
106BASE_EXPORT std::string HexEncode(const void* bytes, size_t size);
107
108// Best effort conversion, see StringToInt above for restrictions.
109// Will only successful parse hex values that will fit into |output|, i.e.
110// -0x80000000 < |input| < 0x7FFFFFFF.
111BASE_EXPORT bool HexStringToInt(const StringPiece& input, int* output);
112
113// Best effort conversion, see StringToInt above for restrictions.
114// Will only successful parse hex values that will fit into |output|, i.e.
115// 0x00000000 < |input| < 0xFFFFFFFF.
116// The string is not required to start with 0x.
117BASE_EXPORT bool HexStringToUInt(const StringPiece& input, uint32_t* output);
118
119// Best effort conversion, see StringToInt above for restrictions.
120// Will only successful parse hex values that will fit into |output|, i.e.
121// -0x8000000000000000 < |input| < 0x7FFFFFFFFFFFFFFF.
122BASE_EXPORT bool HexStringToInt64(const StringPiece& input, int64_t* output);
123
124// Best effort conversion, see StringToInt above for restrictions.
125// Will only successful parse hex values that will fit into |output|, i.e.
126// 0x0000000000000000 < |input| < 0xFFFFFFFFFFFFFFFF.
127// The string is not required to start with 0x.
128BASE_EXPORT bool HexStringToUInt64(const StringPiece& input, uint64_t* output);
129
130// Similar to the previous functions, except that output is a vector of bytes.
131// |*output| will contain as many bytes as were successfully parsed prior to the
132// error.  There is no overflow, but input.size() must be evenly divisible by 2.
133// Leading 0x or +/- are not allowed.
134BASE_EXPORT bool HexStringToBytes(const std::string& input,
135                                  std::vector<uint8_t>* output);
136
137}  // namespace base
138
139#endif  // BASE_STRINGS_STRING_NUMBER_CONVERSIONS_H_
140