1// Protocol Buffers - Google's data interchange format
2// Copyright 2008 Google Inc.  All rights reserved.
3// https://developers.google.com/protocol-buffers/
4//
5// Redistribution and use in source and binary forms, with or without
6// modification, are permitted provided that the following conditions are
7// met:
8//
9//     * Redistributions of source code must retain the above copyright
10// notice, this list of conditions and the following disclaimer.
11//     * Redistributions in binary form must reproduce the above
12// copyright notice, this list of conditions and the following disclaimer
13// in the documentation and/or other materials provided with the
14// distribution.
15//     * Neither the name of Google Inc. nor the names of its
16// contributors may be used to endorse or promote products derived from
17// this software without specific prior written permission.
18//
19// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
20// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
21// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
22// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
23// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
24// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
25// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
26// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
27// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
28// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
29// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
30
31/**
32 * @fileoverview This file contains constants and typedefs used by
33 * jspb.BinaryReader and BinaryWriter.
34 *
35 * @author aappleby@google.com (Austin Appleby)
36 */
37
38goog.provide('jspb.AnyFieldType');
39goog.provide('jspb.BinaryConstants');
40goog.provide('jspb.BinaryMessage');
41goog.provide('jspb.BuilderFunction');
42goog.provide('jspb.ByteSource');
43goog.provide('jspb.ClonerFunction');
44goog.provide('jspb.ComparerFunction');
45goog.provide('jspb.ConstBinaryMessage');
46goog.provide('jspb.PrunerFunction');
47goog.provide('jspb.ReaderFunction');
48goog.provide('jspb.RecyclerFunction');
49goog.provide('jspb.RepeatedFieldType');
50goog.provide('jspb.ScalarFieldType');
51goog.provide('jspb.WriterFunction');
52
53
54goog.forwardDeclare('jspb.Message');
55goog.forwardDeclare('jsproto.BinaryExtension');
56
57
58
59/**
60 * Base interface class for all const messages. Does __not__ define any
61 * methods, as doing so on a widely-used interface defeats dead-code
62 * elimination.
63 * @interface
64 */
65jspb.ConstBinaryMessage = function() {};
66
67
68
69/**
70 * Base interface class for all messages. Does __not__ define any methods, as
71 * doing so on a widely-used interface defeats dead-code elimination.
72 * @interface
73 * @extends {jspb.ConstBinaryMessage}
74 */
75jspb.BinaryMessage = function() {};
76
77
78/**
79 * The types convertible to Uint8Arrays. Strings are assumed to be
80 * base64-encoded.
81 * @typedef {ArrayBuffer|Uint8Array|Array<number>|string}
82 */
83jspb.ByteSource;
84
85
86/**
87 * A scalar field in jspb can be a boolean, number, or string.
88 * @typedef {boolean|number|string}
89 */
90jspb.ScalarFieldType;
91
92
93/**
94 * A repeated field in jspb is an array of scalars, blobs, or messages.
95 * @typedef {!Array<jspb.ScalarFieldType>|
96             !Array<!Uint8Array>|
97             !Array<!jspb.BinaryMessage>}
98 */
99jspb.RepeatedFieldType;
100
101
102/**
103 * A field in jspb can be a scalar, a block of bytes, another proto, or an
104 * array of any of the above.
105 * @typedef {jspb.ScalarFieldType|
106             jspb.RepeatedFieldType|
107             !Uint8Array|
108             !jspb.BinaryMessage|
109             !jsproto.BinaryExtension}
110 */
111jspb.AnyFieldType;
112
113
114/**
115 * A builder function creates an instance of a message object.
116 * @typedef {function():!jspb.BinaryMessage}
117 */
118jspb.BuilderFunction;
119
120
121/**
122 * A cloner function creates a deep copy of a message object.
123 * @typedef {function(jspb.ConstBinaryMessage):jspb.BinaryMessage}
124 */
125jspb.ClonerFunction;
126
127
128/**
129 * A recycler function destroys an instance of a message object.
130 * @typedef {function(!jspb.BinaryMessage):void}
131 */
132jspb.RecyclerFunction;
133
134
135/**
136 * A reader function initializes a message using data from a BinaryReader.
137 * @typedef {function(!jspb.BinaryMessage, !jspb.BinaryReader):void}
138 */
139jspb.ReaderFunction;
140
141
142/**
143 * A writer function serializes a message to a BinaryWriter.
144 * @typedef {!function(!jspb.Message, !jspb.BinaryWriter):void |
145 *           !function(!jspb.ConstBinaryMessage, !jspb.BinaryWriter):void}
146 */
147jspb.WriterFunction;
148
149
150/**
151 * A pruner function removes default-valued fields and empty submessages from a
152 * message and returns either the pruned message or null if the entire message
153 * was pruned away.
154 * @typedef {function(?jspb.BinaryMessage):?jspb.BinaryMessage}
155 */
156jspb.PrunerFunction;
157
158
159/**
160 * A comparer function returns true if two protos are equal.
161 * @typedef {!function(?jspb.ConstBinaryMessage,
162 *                     ?jspb.ConstBinaryMessage):boolean}
163 */
164jspb.ComparerFunction;
165
166
167/**
168 * Field type codes, taken from proto2/public/wire_format_lite.h.
169 * @enum {number}
170 */
171jspb.BinaryConstants.FieldType = {
172  INVALID: -1,
173  DOUBLE: 1,
174  FLOAT: 2,
175  INT64: 3,
176  UINT64: 4,
177  INT32: 5,
178  FIXED64: 6,
179  FIXED32: 7,
180  BOOL: 8,
181  STRING: 9,
182  GROUP: 10,
183  MESSAGE: 11,
184  BYTES: 12,
185  UINT32: 13,
186  ENUM: 14,
187  SFIXED32: 15,
188  SFIXED64: 16,
189  SINT32: 17,
190  SINT64: 18,
191
192  // Extended types for Javascript
193
194  FHASH64: 30, // 64-bit hash string, fixed-length encoding.
195  VHASH64: 31  // 64-bit hash string, varint encoding.
196};
197
198
199/**
200 * Wire-format type codes, taken from proto2/public/wire_format_lite.h.
201 * @enum {number}
202 */
203jspb.BinaryConstants.WireType = {
204  INVALID: -1,
205  VARINT: 0,
206  FIXED64: 1,
207  DELIMITED: 2,
208  START_GROUP: 3,
209  END_GROUP: 4,
210  FIXED32: 5
211};
212
213
214/**
215 * Translates field type to wire type.
216 * @param {jspb.BinaryConstants.FieldType} fieldType
217 * @return {jspb.BinaryConstants.WireType}
218 */
219jspb.BinaryConstants.FieldTypeToWireType = function(fieldType) {
220  var fieldTypes = jspb.BinaryConstants.FieldType;
221  var wireTypes = jspb.BinaryConstants.WireType;
222  switch (fieldType) {
223    case fieldTypes.INT32:
224    case fieldTypes.INT64:
225    case fieldTypes.UINT32:
226    case fieldTypes.UINT64:
227    case fieldTypes.SINT32:
228    case fieldTypes.SINT64:
229    case fieldTypes.BOOL:
230    case fieldTypes.ENUM:
231    case fieldTypes.VHASH64:
232      return wireTypes.VARINT;
233
234    case fieldTypes.DOUBLE:
235    case fieldTypes.FIXED64:
236    case fieldTypes.SFIXED64:
237    case fieldTypes.FHASH64:
238      return wireTypes.FIXED64;
239
240    case fieldTypes.STRING:
241    case fieldTypes.MESSAGE:
242    case fieldTypes.BYTES:
243      return wireTypes.DELIMITED;
244
245    case fieldTypes.FLOAT:
246    case fieldTypes.FIXED32:
247    case fieldTypes.SFIXED32:
248      return wireTypes.FIXED32;
249
250    case fieldTypes.INVALID:
251    case fieldTypes.GROUP:
252    default:
253      return wireTypes.INVALID;
254  }
255};
256
257
258/**
259 * Flag to indicate a missing field.
260 * @const {number}
261 */
262jspb.BinaryConstants.INVALID_FIELD_NUMBER = -1;
263
264
265/**
266 * The smallest denormal float32 value.
267 * @const {number}
268 */
269jspb.BinaryConstants.FLOAT32_EPS = 1.401298464324817e-45;
270
271
272/**
273 * The smallest normal float64 value.
274 * @const {number}
275 */
276jspb.BinaryConstants.FLOAT32_MIN = 1.1754943508222875e-38;
277
278
279/**
280 * The largest finite float32 value.
281 * @const {number}
282 */
283jspb.BinaryConstants.FLOAT32_MAX = 3.4028234663852886e+38;
284
285
286/**
287 * The smallest denormal float64 value.
288 * @const {number}
289 */
290jspb.BinaryConstants.FLOAT64_EPS = 5e-324;
291
292
293/**
294 * The smallest normal float64 value.
295 * @const {number}
296 */
297jspb.BinaryConstants.FLOAT64_MIN = 2.2250738585072014e-308;
298
299
300/**
301 * The largest finite float64 value.
302 * @const {number}
303 */
304jspb.BinaryConstants.FLOAT64_MAX = 1.7976931348623157e+308;
305
306
307/**
308 * Convenience constant equal to 2^20.
309 * @const {number}
310 */
311jspb.BinaryConstants.TWO_TO_20 = 1048576;
312
313
314/**
315 * Convenience constant equal to 2^23.
316 * @const {number}
317 */
318jspb.BinaryConstants.TWO_TO_23 = 8388608;
319
320
321/**
322 * Convenience constant equal to 2^31.
323 * @const {number}
324 */
325jspb.BinaryConstants.TWO_TO_31 = 2147483648;
326
327
328/**
329 * Convenience constant equal to 2^32.
330 * @const {number}
331 */
332jspb.BinaryConstants.TWO_TO_32 = 4294967296;
333
334
335/**
336 * Convenience constant equal to 2^52.
337 * @const {number}
338 */
339jspb.BinaryConstants.TWO_TO_52 = 4503599627370496;
340
341
342/**
343 * Convenience constant equal to 2^63.
344 * @const {number}
345 */
346jspb.BinaryConstants.TWO_TO_63 = 9223372036854775808;
347
348
349/**
350 * Convenience constant equal to 2^64.
351 * @const {number}
352 */
353jspb.BinaryConstants.TWO_TO_64 = 18446744073709551616;
354
355
356/**
357 * Eight-character string of zeros, used as the default 64-bit hash value.
358 * @const {string}
359 */
360jspb.BinaryConstants.ZERO_HASH = '\0\0\0\0\0\0\0\0';
361