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.BinaryMessage');
55goog.forwardDeclare('jspb.BinaryReader');
56goog.forwardDeclare('jspb.BinaryWriter');
57goog.forwardDeclare('jspb.Message');
58goog.forwardDeclare('jsprotolib.BinaryExtension');
59
60
61
62/**
63 * Base interface class for all const messages.
64 * @interface
65 */
66jspb.ConstBinaryMessage = function() {};
67
68/**
69 * Generate a debug string for this proto that is in proto2 text format.
70 * @return {string} The debug string.
71 */
72jspb.ConstBinaryMessage.prototype.toDebugString;
73
74/**
75 * Helper to generate a debug string for this proto at some indent level. The
76 * first line is not indented.
77 * @param {number} indentLevel The number of spaces by which to indent lines.
78 * @return {string} The debug string.
79 * @protected
80 */
81jspb.ConstBinaryMessage.prototype.toDebugStringInternal;
82
83/**
84 * Base interface class for all messages. Does __not__ define any methods, as
85 * doing so on a widely-used interface defeats dead-code elimination.
86 * @interface
87 * @extends {jspb.ConstBinaryMessage}
88 */
89jspb.BinaryMessage = function() {};
90
91
92/**
93 * The types convertible to Uint8Arrays. Strings are assumed to be
94 * base64-encoded.
95 * @typedef {ArrayBuffer|Uint8Array|Array<number>|string}
96 */
97jspb.ByteSource;
98
99
100/**
101 * A scalar field in jspb can be a boolean, number, or string.
102 * @typedef {boolean|number|string}
103 */
104jspb.ScalarFieldType;
105
106
107/**
108 * A repeated field in jspb is an array of scalars, blobs, or messages.
109 * @typedef {!Array<jspb.ScalarFieldType>|
110             !Array<!Uint8Array>|
111             !Array<!jspb.ConstBinaryMessage>|
112             !Array<!jspb.BinaryMessage>}
113 */
114jspb.RepeatedFieldType;
115
116
117/**
118 * A field in jspb can be a scalar, a block of bytes, another proto, or an
119 * array of any of the above.
120 * @typedef {jspb.ScalarFieldType|
121             jspb.RepeatedFieldType|
122             !Uint8Array|
123             !jspb.ConstBinaryMessage|
124             !jspb.BinaryMessage|
125             !jsprotolib.BinaryExtension}
126 */
127jspb.AnyFieldType;
128
129
130/**
131 * A builder function creates an instance of a message object.
132 * @typedef {function():!jspb.BinaryMessage}
133 */
134jspb.BuilderFunction;
135
136
137/**
138 * A cloner function creates a deep copy of a message object.
139 * @typedef {function(jspb.ConstBinaryMessage):jspb.BinaryMessage}
140 */
141jspb.ClonerFunction;
142
143
144/**
145 * A recycler function destroys an instance of a message object.
146 * @typedef {function(!jspb.BinaryMessage):void}
147 */
148jspb.RecyclerFunction;
149
150
151/**
152 * A reader function initializes a message using data from a BinaryReader.
153 * @typedef {function(!jspb.BinaryMessage, !jspb.BinaryReader):void}
154 */
155jspb.ReaderFunction;
156
157
158/**
159 * A writer function serializes a message to a BinaryWriter.
160 * @typedef {function((!jspb.Message|!jspb.ConstBinaryMessage),
161 *                    !jspb.BinaryWriter):void}
162 */
163jspb.WriterFunction;
164
165
166/**
167 * A pruner function removes default-valued fields and empty submessages from a
168 * message and returns either the pruned message or null if the entire message
169 * was pruned away.
170 * @typedef {function(?jspb.BinaryMessage):?jspb.BinaryMessage}
171 */
172jspb.PrunerFunction;
173
174
175/**
176 * A comparer function returns true if two protos are equal.
177 * @typedef {function(?jspb.ConstBinaryMessage,
178 *                     ?jspb.ConstBinaryMessage):boolean}
179 */
180jspb.ComparerFunction;
181
182
183/**
184 * Field type codes, taken from proto2/public/wire_format_lite.h.
185 * @enum {number}
186 */
187jspb.BinaryConstants.FieldType = {
188  INVALID: -1,
189  DOUBLE: 1,
190  FLOAT: 2,
191  INT64: 3,
192  UINT64: 4,
193  INT32: 5,
194  FIXED64: 6,
195  FIXED32: 7,
196  BOOL: 8,
197  STRING: 9,
198  GROUP: 10,
199  MESSAGE: 11,
200  BYTES: 12,
201  UINT32: 13,
202  ENUM: 14,
203  SFIXED32: 15,
204  SFIXED64: 16,
205  SINT32: 17,
206  SINT64: 18,
207
208  // Extended types for Javascript
209
210  FHASH64: 30, // 64-bit hash string, fixed-length encoding.
211  VHASH64: 31  // 64-bit hash string, varint encoding.
212};
213
214
215/**
216 * Wire-format type codes, taken from proto2/public/wire_format_lite.h.
217 * @enum {number}
218 */
219jspb.BinaryConstants.WireType = {
220  INVALID: -1,
221  VARINT: 0,
222  FIXED64: 1,
223  DELIMITED: 2,
224  START_GROUP: 3,
225  END_GROUP: 4,
226  FIXED32: 5
227};
228
229
230/**
231 * Translates field type to wire type.
232 * @param {jspb.BinaryConstants.FieldType} fieldType
233 * @return {jspb.BinaryConstants.WireType}
234 */
235jspb.BinaryConstants.FieldTypeToWireType = function(fieldType) {
236  var fieldTypes = jspb.BinaryConstants.FieldType;
237  var wireTypes = jspb.BinaryConstants.WireType;
238  switch (fieldType) {
239    case fieldTypes.INT32:
240    case fieldTypes.INT64:
241    case fieldTypes.UINT32:
242    case fieldTypes.UINT64:
243    case fieldTypes.SINT32:
244    case fieldTypes.SINT64:
245    case fieldTypes.BOOL:
246    case fieldTypes.ENUM:
247    case fieldTypes.VHASH64:
248      return wireTypes.VARINT;
249
250    case fieldTypes.DOUBLE:
251    case fieldTypes.FIXED64:
252    case fieldTypes.SFIXED64:
253    case fieldTypes.FHASH64:
254      return wireTypes.FIXED64;
255
256    case fieldTypes.STRING:
257    case fieldTypes.MESSAGE:
258    case fieldTypes.BYTES:
259      return wireTypes.DELIMITED;
260
261    case fieldTypes.FLOAT:
262    case fieldTypes.FIXED32:
263    case fieldTypes.SFIXED32:
264      return wireTypes.FIXED32;
265
266    case fieldTypes.INVALID:
267    case fieldTypes.GROUP:
268    default:
269      return wireTypes.INVALID;
270  }
271};
272
273
274/**
275 * Flag to indicate a missing field.
276 * @const {number}
277 */
278jspb.BinaryConstants.INVALID_FIELD_NUMBER = -1;
279
280
281/**
282 * The smallest denormal float32 value.
283 * @const {number}
284 */
285jspb.BinaryConstants.FLOAT32_EPS = 1.401298464324817e-45;
286
287
288/**
289 * The smallest normal float64 value.
290 * @const {number}
291 */
292jspb.BinaryConstants.FLOAT32_MIN = 1.1754943508222875e-38;
293
294
295/**
296 * The largest finite float32 value.
297 * @const {number}
298 */
299jspb.BinaryConstants.FLOAT32_MAX = 3.4028234663852886e+38;
300
301
302/**
303 * The smallest denormal float64 value.
304 * @const {number}
305 */
306jspb.BinaryConstants.FLOAT64_EPS = 5e-324;
307
308
309/**
310 * The smallest normal float64 value.
311 * @const {number}
312 */
313jspb.BinaryConstants.FLOAT64_MIN = 2.2250738585072014e-308;
314
315
316/**
317 * The largest finite float64 value.
318 * @const {number}
319 */
320jspb.BinaryConstants.FLOAT64_MAX = 1.7976931348623157e+308;
321
322
323/**
324 * Convenience constant equal to 2^20.
325 * @const {number}
326 */
327jspb.BinaryConstants.TWO_TO_20 = 1048576;
328
329
330/**
331 * Convenience constant equal to 2^23.
332 * @const {number}
333 */
334jspb.BinaryConstants.TWO_TO_23 = 8388608;
335
336
337/**
338 * Convenience constant equal to 2^31.
339 * @const {number}
340 */
341jspb.BinaryConstants.TWO_TO_31 = 2147483648;
342
343
344/**
345 * Convenience constant equal to 2^32.
346 * @const {number}
347 */
348jspb.BinaryConstants.TWO_TO_32 = 4294967296;
349
350
351/**
352 * Convenience constant equal to 2^52.
353 * @const {number}
354 */
355jspb.BinaryConstants.TWO_TO_52 = 4503599627370496;
356
357
358/**
359 * Convenience constant equal to 2^63.
360 * @const {number}
361 */
362jspb.BinaryConstants.TWO_TO_63 = 9223372036854775808;
363
364
365/**
366 * Convenience constant equal to 2^64.
367 * @const {number}
368 */
369jspb.BinaryConstants.TWO_TO_64 = 18446744073709551616;
370
371
372/**
373 * Eight-character string of zeros, used as the default 64-bit hash value.
374 * @const {string}
375 */
376jspb.BinaryConstants.ZERO_HASH = '\0\0\0\0\0\0\0\0';
377