1// Copyright 2021 Google LLC 2// 3// Licensed under the Apache License, Version 2.0 (the "License"); 4// you may not use this file except in compliance with the License. 5// You may obtain a copy of the License at 6// 7// http://www.apache.org/licenses/LICENSE-2.0 8// 9// Unless required by applicable law or agreed to in writing, software 10// distributed under the License is distributed on an "AS IS" BASIS, 11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12// See the License for the specific language governing permissions and 13// limitations under the License. 14 15syntax = "proto3"; 16 17package google.type; 18 19option cc_enable_arenas = true; 20option go_package = "google.golang.org/genproto/googleapis/type/decimal;decimal"; 21option java_multiple_files = true; 22option java_outer_classname = "DecimalProto"; 23option java_package = "com.google.type"; 24option objc_class_prefix = "GTP"; 25 26// A representation of a decimal value, such as 2.5. Clients may convert values 27// into language-native decimal formats, such as Java's [BigDecimal][] or 28// Python's [decimal.Decimal][]. 29// 30// [BigDecimal]: 31// https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/math/BigDecimal.html 32// [decimal.Decimal]: https://docs.python.org/3/library/decimal.html 33message Decimal { 34 // The decimal value, as a string. 35 // 36 // The string representation consists of an optional sign, `+` (`U+002B`) 37 // or `-` (`U+002D`), followed by a sequence of zero or more decimal digits 38 // ("the integer"), optionally followed by a fraction, optionally followed 39 // by an exponent. 40 // 41 // The fraction consists of a decimal point followed by zero or more decimal 42 // digits. The string must contain at least one digit in either the integer 43 // or the fraction. The number formed by the sign, the integer and the 44 // fraction is referred to as the significand. 45 // 46 // The exponent consists of the character `e` (`U+0065`) or `E` (`U+0045`) 47 // followed by one or more decimal digits. 48 // 49 // Services **should** normalize decimal values before storing them by: 50 // 51 // - Removing an explicitly-provided `+` sign (`+2.5` -> `2.5`). 52 // - Replacing a zero-length integer value with `0` (`.5` -> `0.5`). 53 // - Coercing the exponent character to lower-case (`2.5E8` -> `2.5e8`). 54 // - Removing an explicitly-provided zero exponent (`2.5e0` -> `2.5`). 55 // 56 // Services **may** perform additional normalization based on its own needs 57 // and the internal decimal implementation selected, such as shifting the 58 // decimal point and exponent value together (example: `2.5e-1` <-> `0.25`). 59 // Additionally, services **may** preserve trailing zeroes in the fraction 60 // to indicate increased precision, but are not required to do so. 61 // 62 // Note that only the `.` character is supported to divide the integer 63 // and the fraction; `,` **should not** be supported regardless of locale. 64 // Additionally, thousand separators **should not** be supported. If a 65 // service does support them, values **must** be normalized. 66 // 67 // The ENBF grammar is: 68 // 69 // DecimalString = 70 // [Sign] Significand [Exponent]; 71 // 72 // Sign = '+' | '-'; 73 // 74 // Significand = 75 // Digits ['.'] [Digits] | [Digits] '.' Digits; 76 // 77 // Exponent = ('e' | 'E') [Sign] Digits; 78 // 79 // Digits = { '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' }; 80 // 81 // Services **should** clearly document the range of supported values, the 82 // maximum supported precision (total number of digits), and, if applicable, 83 // the scale (number of digits after the decimal point), as well as how it 84 // behaves when receiving out-of-bounds values. 85 // 86 // Services **may** choose to accept values passed as input even when the 87 // value has a higher precision or scale than the service supports, and 88 // **should** round the value to fit the supported scale. Alternatively, the 89 // service **may** error with `400 Bad Request` (`INVALID_ARGUMENT` in gRPC) 90 // if precision would be lost. 91 // 92 // Services **should** error with `400 Bad Request` (`INVALID_ARGUMENT` in 93 // gRPC) if the service receives a value outside of the supported range. 94 string value = 1; 95} 96