parse_number.h 3.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112
  1. // Copyright 2016 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. #ifndef NET_BASE_PARSE_NUMBER_H_
  5. #define NET_BASE_PARSE_NUMBER_H_
  6. #include "base/strings/string_piece.h"
  7. #include "net/base/net_export.h"
  8. // This file contains utility functions for parsing numbers, in the context of
  9. // network protocols.
  10. //
  11. // Q: Doesn't //base already provide these in string_number_conversions.h, with
  12. // functions like base::StringToInt()?
  13. //
  14. // A: Yes, and those functions are used under the hood by these implementations.
  15. //
  16. // However using the base::StringTo*() has historically led to subtle bugs
  17. // in the context of parsing network protocols:
  18. //
  19. // * Permitting a leading '+'
  20. // * Incorrectly classifying overflow/underflow from a parsing failure
  21. // * Allowing negative numbers for non-negative fields
  22. //
  23. // This API tries to avoid these problems by picking sensible defaults for
  24. // //net code. For more details see crbug.com/596523.
  25. namespace net {
  26. // Format to use when parsing integers.
  27. enum class ParseIntFormat {
  28. // Accepts non-negative base 10 integers of the form:
  29. //
  30. // 1*DIGIT
  31. //
  32. // This construction is used in a variety of IETF standards, such as RFC 7230
  33. // (HTTP).
  34. //
  35. // When attempting to parse a negative number using this format, the failure
  36. // will be FAILED_PARSE since it violated the expected format (and not
  37. // FAILED_UNDERFLOW).
  38. //
  39. // Also note that inputs need not be in minimal encoding: "0003" is valid and
  40. // equivalent to "3".
  41. NON_NEGATIVE,
  42. // Accept optionally negative base 10 integers of the form:
  43. //
  44. // ["-"] 1*DIGIT
  45. //
  46. // In other words, this accepts the same things as NON_NEGATIVE, and
  47. // additionally recognizes those numbers prefixed with a '-'.
  48. //
  49. // Note that by this defintion "-0" IS a valid input.
  50. OPTIONALLY_NEGATIVE
  51. };
  52. // The specific reason why a ParseInt*() function failed.
  53. enum class ParseIntError {
  54. // The parsed number couldn't fit into the provided output type because it was
  55. // too high.
  56. FAILED_OVERFLOW,
  57. // The parsed number couldn't fit into the provided output type because it was
  58. // too low.
  59. FAILED_UNDERFLOW,
  60. // The number failed to be parsed because it wasn't a valid decimal number (as
  61. // determined by the policy).
  62. FAILED_PARSE,
  63. };
  64. // The ParseInt*() functions parse a string representing a number.
  65. //
  66. // The format of the strings that are accepted is controlled by the |format|
  67. // parameter. This allows rejecting negative numbers.
  68. //
  69. // These functions return true on success, and fill |*output| with the result.
  70. //
  71. // On failure, it is guaranteed that |*output| was not modified. If
  72. // |optional_error| was non-null, then it is filled with the reason for the
  73. // failure.
  74. [[nodiscard]] NET_EXPORT bool ParseInt32(
  75. const base::StringPiece& input,
  76. ParseIntFormat format,
  77. int32_t* output,
  78. ParseIntError* optional_error = nullptr);
  79. [[nodiscard]] NET_EXPORT bool ParseInt64(
  80. const base::StringPiece& input,
  81. ParseIntFormat format,
  82. int64_t* output,
  83. ParseIntError* optional_error = nullptr);
  84. // The ParseUint*() functions parse a string representing a number.
  85. //
  86. // These are equivalent to calling ParseInt*() with a format string of
  87. // ParseIntFormat::NON_NEGATIVE and unsigned output types.
  88. [[nodiscard]] NET_EXPORT bool ParseUint32(
  89. const base::StringPiece& input,
  90. uint32_t* output,
  91. ParseIntError* optional_error = nullptr);
  92. [[nodiscard]] NET_EXPORT bool ParseUint64(
  93. const base::StringPiece& input,
  94. uint64_t* output,
  95. ParseIntError* optional_error = nullptr);
  96. } // namespace net
  97. #endif // NET_BASE_PARSE_NUMBER_H_