{
	"format": 1,
	"id": "saw-buffer",
	"kind": "class",
	"name": "buffer",
	"namespace": "saw",
	"module": "core",
	"header": "modules/core/c++/buffer.hpp",
	"brief_description": "Access class to reduce templated buffer segment bloat.",
	"detailed_description": [
		[
			"A buffer has two independent cursors, one for reading and one for writing, and may be split into segments which are contiguous only up to a point. Everything is phrased around that: composite length is what remains in total, segment length is what remains without a jump."
		],
		[
			"Code which copies in bulk loops on the segment length; code which works byte by byte uses read and write with an offset. Both cursors move only through the advance calls, so a reader can look ahead without consuming."
		]
	],
	"functions": {
		"saw-buffer-read_position": {
			"id": "saw-buffer-read_position",
			"name": "read_position",
			"type": ["size_t"],
			"const": true,
			"virtual": true,
			"brief_description": "Where the read cursor currently is."
		},
		"saw-buffer-read_composite_length": {
			"id": "saw-buffer-read_composite_length",
			"name": "read_composite_length",
			"type": ["size_t"],
			"const": true,
			"virtual": true,
			"brief_description": "How many bytes can be read in total, across segments."
		},
		"saw-buffer-read_segment_length": {
			"id": "saw-buffer-read_segment_length",
			"name": "read_segment_length",
			"type": ["size_t"],
			"const": true,
			"virtual": true,
			"brief_description": "How many bytes can be read contiguously from an offset.",
			"parameters": [
				{"name": "offset", "type": ["size_t"], "default": "0"}
			]
		},
		"saw-buffer-read_advance": {
			"id": "saw-buffer-read_advance",
			"name": "read_advance",
			"type": ["void"],
			"virtual": true,
			"brief_description": "Consumes bytes from the read side.",
			"parameters": [
				{"name": "bytes", "type": ["size_t"]}
			]
		},
		"saw-buffer-read": {
			"id": "saw-buffer-read",
			"name": "read",
			"type": ["uint8_t &"],
			"virtual": true,
			"brief_description": "The byte at an offset from the read cursor, without consuming it.",
			"parameters": [
				{"name": "i", "type": ["size_t"], "default": "0"}
			]
		},
		"saw-buffer-write_position": {
			"id": "saw-buffer-write_position",
			"name": "write_position",
			"type": ["size_t"],
			"const": true,
			"virtual": true,
			"brief_description": "Where the write cursor currently is."
		},
		"saw-buffer-write_composite_length": {
			"id": "saw-buffer-write_composite_length",
			"name": "write_composite_length",
			"type": ["size_t"],
			"const": true,
			"virtual": true,
			"brief_description": "How many bytes can be written in total, across segments."
		},
		"saw-buffer-write_segment_length": {
			"id": "saw-buffer-write_segment_length",
			"name": "write_segment_length",
			"type": ["size_t"],
			"const": true,
			"virtual": true,
			"brief_description": "How many bytes can be written contiguously from an offset.",
			"parameters": [
				{"name": "offset", "type": ["size_t"], "default": "0"}
			]
		},
		"saw-buffer-write_advance": {
			"id": "saw-buffer-write_advance",
			"name": "write_advance",
			"type": ["void"],
			"virtual": true,
			"brief_description": "Marks bytes as written.",
			"parameters": [
				{"name": "bytes", "type": ["size_t"]}
			]
		},
		"saw-buffer-write": {
			"id": "saw-buffer-write",
			"name": "write",
			"type": ["uint8_t &"],
			"virtual": true,
			"brief_description": "The byte at an offset from the write cursor.",
			"parameters": [
				{"name": "i", "type": ["size_t"], "default": "0"}
			]
		},
		"saw-buffer-write_require_length": {
			"id": "saw-buffer-write_require_length",
			"name": "write_require_length",
			"type": [{"name": "error", "id": "saw-error"}],
			"virtual": true,
			"brief_description": "Asks for room before writing in bulk.",
			"detailed_description": [
				[
					"Nothing can be done if the read side has not been filled, but the write side can grow on demand. Call this before pushing a run of bytes, so a failure happens once up front instead of halfway through."
				]
			],
			"parameters": [
				{"name": "bytes", "type": ["size_t"]}
			]
		},
		"saw-buffer-push-1": {
			"id": "saw-buffer-push-1",
			"name": "push",
			"type": [{"name": "error", "id": "saw-error"}],
			"brief_description": "Writes one byte.",
			"detailed_description": [
				["Fails with", {"name": "buffer_exhausted", "id": "saw-err-buffer_exhausted"}, "if there is no room."]
			],
			"parameters": [
				{"name": "value", "type": ["const uint8_t &"]}
			]
		},
		"saw-buffer-push-2": {
			"id": "saw-buffer-push-2",
			"name": "push",
			"type": [{"name": "error", "id": "saw-error"}],
			"brief_description": "Writes a run of bytes, segment by segment.",
			"parameters": [
				{"name": "buffer", "type": ["const uint8_t &"], "brief_description": "First byte of the run."},
				{"name": "size", "type": ["size_t"]}
			]
		},
		"saw-buffer-pop-1": {
			"id": "saw-buffer-pop-1",
			"name": "pop",
			"type": [{"name": "error", "id": "saw-error"}],
			"brief_description": "Reads one byte and consumes it.",
			"parameters": [
				{"name": "value", "type": ["uint8_t &"]}
			]
		},
		"saw-buffer-pop-2": {
			"id": "saw-buffer-pop-2",
			"name": "pop",
			"type": [{"name": "error", "id": "saw-error"}],
			"brief_description": "Reads a run of bytes and consumes them.",
			"parameters": [
				{"name": "buffer", "type": ["uint8_t &"]},
				{"name": "size", "type": ["size_t"]}
			]
		},
		"saw-buffer-write_from": {
			"id": "saw-buffer-write_from",
			"name": "write_from",
			"type": ["error_or< uint64_t >"],
			"brief_description": "Reads from another buffer and writes into this one.",
			"parameters": [
				{"name": "buff", "type": ["const buffer &"]}
			]
		}
	},
	"notes": [
		"The concrete buffers differ in what happens when space runs out, which is the thing to pick on."
	]
}