BigfootDev/flatbuffers
1
0
Fork 1
mirror of https://github.com/google/flatbuffers.git synced 2026-06-02 12:05:50 +00:00
Code Issues Packages Projects Releases Wiki Activity

Revamping the FlatBuffers docs.

Browse Source 
Adding an API reference for the supported languages.

General docs cleanup, including a new `tutorial` section that
supports all of the supported languages.

Added samples for each supported language to mirror the new
tutorial page.

Cleaned up all the links by making them `@ref` style links,
instead of referencing the names of the generated `.html` files.

Removed all generated files that were unnecessarily committed.

Also fixed the C# tests (two were failing due to a missing file).

Bug: b/25801305

Tested: Tested all samples on Ubuntu, Mac, and Android. Docs were
generated using doxygen and viewed on Chrome.

Change-Id: I2acaba6e332a15ae2deff5f26a4a25da7bd2c954
This commit is contained in:
Mark Klara
2015-12-03 20:30:54 -08:00
parent d75d29e2fe
commit 69a31b807a
115 changed files with 5537 additions and 5917 deletions
Download Patch File Download Diff File Expand all files Collapse all files

195
python/flatbuffers/builder.py
View File

@@ -23,6 +23,11 @@ from .compat import range_func
from .compat import memoryview_type
## @file
## @addtogroup flatbuffers_python_api
## @{
## @cond FLATBUFFERS_INTERNAL
class OffsetArithmeticError(RuntimeError):
"""
Error caused by an Offset arithmetic error. Probably caused by bad
@@ -72,12 +77,13 @@ class BuilderNotFinishedError(RuntimeError):
# VtableMetadataFields is the count of metadata fields in each vtable.
VtableMetadataFields = 2
## @endcond
class Builder(object):
"""
A Builder is used to construct one or more FlatBuffers. Typically, Builder
objects will be used from code generated by the `flatc` compiler.
""" A Builder is used to construct one or more FlatBuffers.
Typically, Builder objects will be used from code generated by the `flatc`
compiler.
A Builder constructs byte buffers in a last-first manner for simplicity and
performance during reading.
@@ -85,24 +91,30 @@ class Builder(object):
Internally, a Builder is a state machine for creating FlatBuffer objects.
It holds the following internal state:
Bytes: an array of bytes.
current_vtable: a list of integers.
vtables: a list of vtable entries (i.e. a list of list of integers).
- Bytes: an array of bytes.
- current_vtable: a list of integers.
- vtables: a list of vtable entries (i.e. a list of list of integers).
Attributes:
Bytes: The internal `bytearray` for the Builder.
finished: A boolean determining if the Builder has been finalized.
"""
## @cond FLATBUFFERS_INTENRAL
__slots__ = ("Bytes", "current_vtable", "head", "minalign", "objectEnd",
"vtables", "nested", "finished")
"""
Maximum buffer size constant, in bytes.
"""Maximum buffer size constant, in bytes.
Builder will never allow it's buffer grow over this size.
Currently equals 2Gb.
"""
MAX_BUFFER_SIZE = 2**31
## @endcond
def __init__(self, initialSize):
"""
Initializes a Builder of size `initial_size`.
"""Initializes a Builder of size `initial_size`.
The internal buffer is grown as needed.
"""
@@ -111,19 +123,27 @@ class Builder(object):
raise BuilderSizeError(msg)
self.Bytes = bytearray(initialSize)
## @cond FLATBUFFERS_INTERNAL
self.current_vtable = None
self.head = UOffsetTFlags.py_type(initialSize)
self.minalign = 1
self.objectEnd = None
self.vtables = []
self.nested = False
## @endcond
self.finished = False
def Output(self):
"""
Output returns the portion of the buffer that has been used for
writing data. It raises BuilderNotFinishedError if the buffer has not
been finished with `Finish`.
"""Return the portion of the buffer that has been used for writing data.
This is the typical way to access the FlatBuffer data inside the
builder. If you try to access `Builder.Bytes` directly, you would need
to manually index it with `Head()`, since the buffer is constructed
backwards.
It raises BuilderNotFinishedError if the buffer has not been finished
with `Finish`.
"""
if not self.finished:
@@ -131,6 +151,7 @@ class Builder(object):
return self.Bytes[self.Head():]
## @cond FLATBUFFERS_INTERNAL
def StartObject(self, numfields):
"""StartObject initializes bookkeeping for writing a new object."""
@@ -266,14 +287,19 @@ class Builder(object):
bytes2 = bytearray(newSize)
bytes2[newSize-len(self.Bytes):] = self.Bytes
self.Bytes = bytes2
## @endcond
def Head(self):
"""
Head gives the start of useful data in the underlying byte buffer.
Note: unlike other functions, this value is interpreted as from the left.
"""
return self.head
"""Get the start of useful data in the underlying byte buffer.
Note: unlike other functions, this value is interpreted as from the
left.
"""
## @cond FLATBUFFERS_INTERNAL
return self.head
## @endcond
## @cond FLATBUFFERS_INTERNAL
def Offset(self):
"""Offset relative to the end of the buffer."""
return UOffsetTFlags.py_type(len(self.Bytes) - self.Head())
@@ -322,10 +348,10 @@ class Builder(object):
raise OffsetArithmeticError(msg)
off2 = self.Offset() - off + N.SOffsetTFlags.bytewidth
self.PlaceSOffsetT(off2)
## @endcond
def PrependUOffsetTRelative(self, off):
"""
PrependUOffsetTRelative prepends an UOffsetT, relative to where it
"""Prepends an unsigned offset into vector data, relative to where it
will be written.
"""
@@ -337,13 +363,14 @@ class Builder(object):
off2 = self.Offset() - off + N.UOffsetTFlags.bytewidth
self.PlaceUOffsetT(off2)
## @cond FLATBUFFERS_INTERNAL
def StartVector(self, elemSize, numElems, alignment):
"""
StartVector initializes bookkeeping for writing a new vector.
A vector has the following format:
<UOffsetT: number of elements in this vector>
<T: data>+, where T is the type of elements of this vector.
- <UOffsetT: number of elements in this vector>
- <T: data>+, where T is the type of elements of this vector.
"""
self.assertNotNested()
@@ -351,12 +378,15 @@ class Builder(object):
self.Prep(N.Uint32Flags.bytewidth, elemSize*numElems)
self.Prep(alignment, elemSize*numElems) # In case alignment > int.
return self.Offset()
## @endcond
def EndVector(self, vectorNumElems):
"""EndVector writes data necessary to finish vector construction."""
self.assertNested()
## @cond FLATBUFFERS_INTERNAL
self.nested = False
## @endcond
# we already made space for this, so write without PrependUint32
self.PlaceUOffsetT(vectorNumElems)
return self.Offset()
@@ -365,7 +395,9 @@ class Builder(object):
"""CreateString writes a null-terminated byte string as a vector."""
self.assertNotNested()
## @cond FLATBUFFERS_INTERNAL
self.nested = True
## @endcond
if isinstance(s, compat.string_types):
x = s.encode()
@@ -378,12 +410,14 @@ class Builder(object):
self.Place(0, N.Uint8Flags)
l = UOffsetTFlags.py_type(len(s))
## @cond FLATBUFFERS_INTERNAL
self.head = UOffsetTFlags.py_type(self.Head() - l)
## @endcond
self.Bytes[self.Head():self.Head()+l] = x
return self.EndVector(len(x))
## @cond FLATBUFFERS_INTERNAL
def assertNested(self):
"""
Check that we are in the process of building an object.
@@ -422,6 +456,7 @@ class Builder(object):
"""
self.assertNested()
self.current_vtable[slotnum] = self.Offset()
## @endcond
def Finish(self, rootTable):
"""Finish finalizes a buffer, pointing to the given `rootTable`."""
@@ -431,6 +466,7 @@ class Builder(object):
self.finished = True
return self.Head()
## @cond FLATBUFFERS_INTERNAL
def Prepend(self, flags, off):
self.Prep(flags.bytewidth, 0)
self.Place(off, flags)
@@ -491,30 +527,95 @@ class Builder(object):
self.assertStructIsInline(x)
self.Slot(v)
def PrependBool(self, x): self.Prepend(N.BoolFlags, x)
## @endcond
def PrependByte(self, x): self.Prepend(N.Uint8Flags, x)
def PrependBool(self, x):
"""Prepend a `bool` to the Builder buffer.
def PrependUint8(self, x): self.Prepend(N.Uint8Flags, x)
Note: aligns and checks for space.
"""
self.Prepend(N.BoolFlags, x)
def PrependUint16(self, x): self.Prepend(N.Uint16Flags, x)
def PrependByte(self, x):
"""Prepend a `byte` to the Builder buffer.
def PrependUint32(self, x): self.Prepend(N.Uint32Flags, x)
Note: aligns and checks for space.
"""
self.Prepend(N.Uint8Flags, x)
def PrependUint64(self, x): self.Prepend(N.Uint64Flags, x)
def PrependUint8(self, x):
"""Prepend an `uint8` to the Builder buffer.
def PrependInt8(self, x): self.Prepend(N.Int8Flags, x)
Note: aligns and checks for space.
"""
self.Prepend(N.Uint8Flags, x)
def PrependInt16(self, x): self.Prepend(N.Int16Flags, x)
def PrependUint16(self, x):
"""Prepend an `uint16` to the Builder buffer.
def PrependInt32(self, x): self.Prepend(N.Int32Flags, x)
Note: aligns and checks for space.
"""
self.Prepend(N.Uint16Flags, x)
def PrependInt64(self, x): self.Prepend(N.Int64Flags, x)
def PrependUint32(self, x):
"""Prepend an `uint32` to the Builder buffer.
def PrependFloat32(self, x): self.Prepend(N.Float32Flags, x)
Note: aligns and checks for space.
"""
self.Prepend(N.Uint32Flags, x)
def PrependFloat64(self, x): self.Prepend(N.Float64Flags, x)
def PrependUint64(self, x):
"""Prepend an `uint64` to the Builder buffer.
Note: aligns and checks for space.
"""
self.Prepend(N.Uint64Flags, x)
def PrependInt8(self, x):
"""Prepend an `int8` to the Builder buffer.
Note: aligns and checks for space.
"""
self.Prepend(N.Int8Flags, x)
def PrependInt16(self, x):
"""Prepend an `int16` to the Builder buffer.
Note: aligns and checks for space.
"""
self.Prepend(N.Int16Flags, x)
def PrependInt32(self, x):
"""Prepend an `int32` to the Builder buffer.
Note: aligns and checks for space.
"""
self.Prepend(N.Int32Flags, x)
def PrependInt64(self, x):
"""Prepend an `int64` to the Builder buffer.
Note: aligns and checks for space.
"""
self.Prepend(N.Int64Flags, x)
def PrependFloat32(self, x):
"""Prepend a `float32` to the Builder buffer.
Note: aligns and checks for space.
"""
self.Prepend(N.Float32Flags, x)
def PrependFloat64(self, x):
"""Prepend a `float64` to the Builder buffer.
Note: aligns and checks for space.
"""
self.Prepend(N.Float64Flags, x)
##############################################################
## @cond FLATBUFFERS_INTERNAL
def PrependVOffsetT(self, x): self.Prepend(N.VOffsetTFlags, x)
def Place(self, x, flags):
@@ -528,33 +629,31 @@ class Builder(object):
encode.Write(flags.packer_type, self.Bytes, self.Head(), x)
def PlaceVOffsetT(self, x):
"""
PlaceVOffsetT prepends a VOffsetT to the Builder, without checking for
space.
"""PlaceVOffsetT prepends a VOffsetT to the Builder, without checking
for space.
"""
N.enforce_number(x, N.VOffsetTFlags)
self.head = self.head - N.VOffsetTFlags.bytewidth
encode.Write(packer.voffset, self.Bytes, self.Head(), x)
def PlaceSOffsetT(self, x):
"""
PlaceSOffsetT prepends a SOffsetT to the Builder, without checking for
space.
"""PlaceSOffsetT prepends a SOffsetT to the Builder, without checking
for space.
"""
N.enforce_number(x, N.SOffsetTFlags)
self.head = self.head - N.SOffsetTFlags.bytewidth
encode.Write(packer.soffset, self.Bytes, self.Head(), x)
def PlaceUOffsetT(self, x):
"""
PlaceUOffsetT prepends a UOffsetT to the Builder, without checking for
space.
"""PlaceUOffsetT prepends a UOffsetT to the Builder, without checking
for space.
"""
N.enforce_number(x, N.UOffsetTFlags)
self.head = self.head - N.UOffsetTFlags.bytewidth
encode.Write(packer.uoffset, self.Bytes, self.Head(), x)
## @endcond
## @cond FLATBUFFERS_INTERNAL
def vtableEqual(a, objectStart, b):
"""vtableEqual compares an unwritten vtable to a written vtable."""
@@ -574,3 +673,5 @@ def vtableEqual(a, objectStart, b):
if x != y:
return False
return True
## @endcond
## @}