Skip to main content

Encoder

An Encoder is an isolated encode/decode context. Each instance carries its own table of custom per-type encoders, so two encoders configured differently can co-exist without interfering with each other or with the module-level Bufferize.encode / Bufferize.decode functions.

Create one with Bufferize.custom:

local myEncoder = Bufferize.custom()
myEncoder:override("Color3", { read = ..., write = ... })

local b = myEncoder:encode(Color3.new(1, 0, 0))
local color = myEncoder:decode(b)

A buffer produced by an Encoder with overrides can only be decoded by an encoder configured with the same overrides — there is no way to recover the override information from the buffer alone.

Properties​

VERSION​

</>
Encoder.VERSION: string

The semantic version string of the running Bufferize module. Mirrors Bufferize.VERSION.

Functions​

new​

</>
Encoder.new() → Encoder

Creates a new encoder with no overrides registered. Prefer calling this via Bufferize.custom for clarity at the call site.

readVersion​

</>
Encoder.readVersion(
b: buffer--

A buffer previously produced by an encoder's encode method.

) → string?--

The semantic version string written into the header, or nil if it could not be parsed.

Reads the Bufferize version stored in the buffer's header without decoding the body. See Bufferize.readVersion.

isCompatible​

</>
Encoder.isCompatible(
b: buffer--

A buffer previously produced by an encoder's encode method.

) → boolean--

Whether the running version of Bufferize is able to decode the buffer.

Checks whether the version written into the buffer's header is compatible with the running version of Bufferize, i.e. whether decode will accept it rather than raising a version error. See Bufferize.isCompatible.

override​

</>
Encoder:override(
typeOf: string,--

The typeof name of the data type to override (e.g. "CFrame", "Color3").

encoder: {
read: (buffer) → T,
write: (T) → buffer
}--

A pair of conversion functions between the data type and a buffer.

) → ()

Registers a custom read/write pair for the given data type on this encoder. The same override must be present on whichever encoder decodes the buffer later — there is no way to recover it from the buffer itself.

Attempting to override a type that is not overridable raises an error.

encode​

</>
Encoder:encode(
...: Supported--

One or more values of supported data types.

) → buffer--

A buffer that round-trips through this encoder's decode to the same values.

Encodes the given values into a buffer, applying any overrides registered via Encoder:override. The buffer is prefixed with the running Bufferize version.

decode​

</>
Encoder:decode(
b: buffer--

A buffer previously produced by this encoder (or one with the same overrides).

) → ...Supported--

The original values, in the same order they were passed to encode.

Decodes a buffer produced by encode. Raises an error if the buffer was encoded with an incompatible major version, or with a newer version of Bufferize than the one currently loaded.

encodeHeaderless​

</>
Encoder:encodeHeaderless(
...: Supported--

One or more values of supported data types.

) → buffer--

A buffer that round-trips through this encoder's decodeHeaderless to the same values.

Same as Encoder:encode, but the version header is omitted. This saves a few bytes per buffer at the cost of the version compatibility checks, so it's best suited to short-lived data (e.g. networking) where both ends are guaranteed to be running the same version of Bufferize.

decodeHeaderless​

</>
Encoder:decodeHeaderless(
b: buffer--

A buffer previously produced by this encoder's encodeHeaderless (or one with the same overrides).

) → ...Supported--

The original values, in the same order they were passed to encodeHeaderless.

Decodes a buffer produced by Encoder:encodeHeaderless. No version checks are performed, so decoding a buffer produced by an incompatible version of Bufferize may error or return incorrect values.

Show raw api
{
    "functions": [
        {
            "name": "new",
            "desc": "Creates a new encoder with no overrides registered. Prefer calling this via\n[Bufferize.custom] for clarity at the call site.",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Encoder"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 266,
                "path": "src/Encoder.luau"
            }
        },
        {
            "name": "readVersion",
            "desc": "Reads the Bufferize version stored in the buffer's header without decoding\nthe body. See [Bufferize.readVersion].",
            "params": [
                {
                    "name": "b",
                    "desc": "A buffer previously produced by an encoder's `encode` method.",
                    "lua_type": "buffer"
                }
            ],
            "returns": [
                {
                    "desc": "The semantic version string written into the header, or `nil` if it could not be parsed.",
                    "lua_type": "string?"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 283,
                "path": "src/Encoder.luau"
            }
        },
        {
            "name": "isCompatible",
            "desc": "Checks whether the version written into the buffer's header is compatible\nwith the running version of Bufferize, i.e. whether `decode` will accept it\nrather than raising a version error. See [Bufferize.isCompatible].",
            "params": [
                {
                    "name": "b",
                    "desc": "A buffer previously produced by an encoder's `encode` method.",
                    "lua_type": "buffer"
                }
            ],
            "returns": [
                {
                    "desc": "Whether the running version of Bufferize is able to decode the buffer.",
                    "lua_type": "boolean"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 298,
                "path": "src/Encoder.luau"
            }
        },
        {
            "name": "override",
            "desc": "Registers a custom read/write pair for the given data type on this encoder.\nThe same override must be present on whichever encoder decodes the buffer\nlater — there is no way to recover it from the buffer itself.\n\nAttempting to override a type that is not overridable raises an error.",
            "params": [
                {
                    "name": "typeOf",
                    "desc": "The `typeof` name of the data type to override (e.g. `\"CFrame\"`, `\"Color3\"`).",
                    "lua_type": "string"
                },
                {
                    "name": "encoder",
                    "desc": "A pair of conversion functions between the data type and a `buffer`.",
                    "lua_type": "{ read: (buffer) -> T, write: (T) -> buffer }"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 315,
                "path": "src/Encoder.luau"
            }
        },
        {
            "name": "encode",
            "desc": "Encodes the given values into a buffer, applying any overrides registered\nvia [Encoder:override]. The buffer is prefixed with the running Bufferize\nversion.",
            "params": [
                {
                    "name": "...",
                    "desc": "One or more values of supported data types.",
                    "lua_type": "Supported"
                }
            ],
            "returns": [
                {
                    "desc": "A buffer that round-trips through this encoder's `decode` to the same values.",
                    "lua_type": "buffer"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 333,
                "path": "src/Encoder.luau"
            }
        },
        {
            "name": "decode",
            "desc": "Decodes a buffer produced by `encode`. Raises an error if the buffer was\nencoded with an incompatible major version, or with a newer version of\nBufferize than the one currently loaded.",
            "params": [
                {
                    "name": "b",
                    "desc": "A buffer previously produced by this encoder (or one with the same overrides).",
                    "lua_type": "buffer"
                }
            ],
            "returns": [
                {
                    "desc": "The original values, in the same order they were passed to `encode`.",
                    "lua_type": "...Supported"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 347,
                "path": "src/Encoder.luau"
            }
        },
        {
            "name": "encodeHeaderless",
            "desc": "Same as [Encoder:encode], but the version header is omitted. This saves a\nfew bytes per buffer at the cost of the version compatibility checks, so\nit's best suited to short-lived data (e.g. networking) where both ends are\nguaranteed to be running the same version of Bufferize.",
            "params": [
                {
                    "name": "...",
                    "desc": "One or more values of supported data types.",
                    "lua_type": "Supported"
                }
            ],
            "returns": [
                {
                    "desc": "A buffer that round-trips through this encoder's `decodeHeaderless` to the same values.",
                    "lua_type": "buffer"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 362,
                "path": "src/Encoder.luau"
            }
        },
        {
            "name": "decodeHeaderless",
            "desc": "Decodes a buffer produced by [Encoder:encodeHeaderless]. No version checks\nare performed, so decoding a buffer produced by an incompatible version of\nBufferize may error or return incorrect values.",
            "params": [
                {
                    "name": "b",
                    "desc": "A buffer previously produced by this encoder's `encodeHeaderless` (or one with the same overrides).",
                    "lua_type": "buffer"
                }
            ],
            "returns": [
                {
                    "desc": "The original values, in the same order they were passed to `encodeHeaderless`.",
                    "lua_type": "...Supported"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 376,
                "path": "src/Encoder.luau"
            }
        }
    ],
    "properties": [
        {
            "name": "VERSION",
            "desc": "The semantic version string of the running Bufferize module. Mirrors\n[Bufferize.VERSION].",
            "lua_type": "string",
            "source": {
                "line": 245,
                "path": "src/Encoder.luau"
            }
        }
    ],
    "types": [],
    "name": "Encoder",
    "desc": "An `Encoder` is an isolated encode/decode context. Each instance carries\nits own table of custom per-type encoders, so two encoders configured\ndifferently can co-exist without interfering with each other or with the\nmodule-level [Bufferize.encode] / [Bufferize.decode] functions.\n\nCreate one with [Bufferize.custom]\\:\n\n```lua\nlocal myEncoder = Bufferize.custom()\nmyEncoder:override(\"Color3\", { read = ..., write = ... })\n\nlocal b = myEncoder:encode(Color3.new(1, 0, 0))\nlocal color = myEncoder:decode(b)\n```\n\nA buffer produced by an `Encoder` with overrides can only be decoded by an\nencoder configured with the same overrides — there is no way to recover the\noverride information from the buffer alone.",
    "source": {
        "line": 236,
        "path": "src/Encoder.luau"
    }
}