{
	"format": 1,
	"id": "saw-error",
	"kind": "class",
	"name": "error",
	"namespace": "saw",
	"module": "core",
	"header": "modules/core/c++/error.hpp",
	"brief_description": "Exception replacement. Carries a code, a criticality and a message.",
	"detailed_description": [
		[
			"The library is written without exceptions, so this takes their place. An error is either recoverable or critical, and the code distinguishes the kind. Additional kinds are added by defining a tag struct with a description and an is_critical flag, which registers itself the first time it is used."
		],
		[
			"The code is an index into a process local registry handed out in first use order. Only",
			{"name": "no_error", "id": "saw-err-no_error"},
			{"name": "not_found", "id": "saw-err-not_found"},
			"and",
			{"name": "out_of_memory", "id": "saw-err-out_of_memory"},
			"are preregistered, so the same error has different codes in two processes. A code must therefore never be sent anywhere; the category string is the portable identity."
		],
		[
			"Copying is forbidden on purpose. An error is moved, or copied explicitly through copy_error, so passing one around stays visible at the call site."
		]
	],
	"attributes": {
		"saw-error-error_code_": {
			"id": "saw-error-error_code_",
			"name": "error_code_",
			"type": ["code"],
			"visibility": "private",
			"brief_description": "Distinguishes the different error types."
		},
		"saw-error-is_critical_": {
			"id": "saw-error-is_critical_",
			"name": "is_critical_",
			"type": ["bool"],
			"visibility": "private",
			"brief_description": "Kept next to the code so checking doesn't need the registry."
		},
		"saw-error-error_message_": {
			"id": "saw-error-error_message_",
			"name": "error_message_",
			"type": ["std::variant< std::string_view, std::string >"],
			"visibility": "private",
			"brief_description": "A variant for the edge case of being out of memory, where a string cannot be built."
		}
	},
	"aliases": {
		"saw-error-code": {
			"id": "saw-error-code",
			"name": "code",
			"type": ["uint32_t"],
			"brief_description": "Type representing the error code."
		}
	},
	"functions": {
		"saw-error-ctor-1": {
			"id": "saw-error-ctor-1",
			"name": "error",
			"type": [],
			"parameters": [
				{"name": "id", "type": ["error::code"]},
				{"name": "is_critical", "type": ["bool"]}
			]
		},
		"saw-error-ctor-2": {
			"id": "saw-error-ctor-2",
			"name": "error",
			"type": [],
			"brief_description": "With a message which outlives the error, such as a literal.",
			"parameters": [
				{"name": "id", "type": ["error::code"]},
				{"name": "is_critical", "type": ["bool"]},
				{"name": "msg", "type": ["const std::string_view &"]}
			]
		},
		"saw-error-ctor-3": {
			"id": "saw-error-ctor-3",
			"name": "error",
			"type": [],
			"brief_description": "With an owned message, for text built at the point of failure.",
			"parameters": [
				{"name": "id", "type": ["error::code"]},
				{"name": "is_critical", "type": ["bool"]},
				{"name": "msg", "type": ["std::string &&"]}
			]
		},
		"saw-error-get_message": {
			"id": "saw-error-get_message",
			"name": "get_message",
			"type": ["const std::string_view"],
			"const": true,
			"brief_description": "Returns a string view to the message."
		},
		"saw-error-get_category": {
			"id": "saw-error-get_category",
			"name": "get_category",
			"type": ["const std::string_view"],
			"const": true,
			"brief_description": "Returns a view describing which error this is.",
			"detailed_description": [
				["Looked up in the registry. This, not the code, is the identity which means the same thing in another process."]
			]
		},
		"saw-error-failed": {
			"id": "saw-error-failed",
			"name": "failed",
			"type": ["bool"],
			"const": true,
			"brief_description": "Checks if it is an error at all, since the code zero is reserved for no error."
		},
		"saw-error-is_critical": {
			"id": "saw-error-is_critical",
			"name": "is_critical",
			"type": ["bool"],
			"const": true,
			"brief_description": "Checks if the error is critical."
		},
		"saw-error-is_recoverable": {
			"id": "saw-error-is_recoverable",
			"name": "is_recoverable",
			"type": ["bool"],
			"const": true,
			"brief_description": "Checks if the error is recoverable."
		},
		"saw-error-copy_error": {
			"id": "saw-error-copy_error",
			"name": "copy_error",
			"type": ["error"],
			"const": true,
			"brief_description": "Replaces the copy constructor, so copying an error is always explicit.",
			"detailed_description": [
				["If copying the message runs out of memory, the copy keeps the code and gets a static message instead of failing."]
			]
		},
		"saw-error-get_id": {
			"id": "saw-error-get_id",
			"name": "get_id",
			"type": ["error::code"],
			"const": true,
			"brief_description": "Returns the code."
		},
		"saw-error-is_type": {
			"id": "saw-error-is_type",
			"name": "is_type",
			"type": ["bool"],
			"const": true,
			"brief_description": "Checks whether this error is of a given kind.",
			"detailed_description": [
				["The way to branch on an error. Comparing codes directly only works inside one process."]
			],
			"templates": [
				{"name": "T", "kind": "type", "brief_description": "An error tag struct, e.g. err::not_found."}
			],
			"examples": [
				{
					"title": "Branching on the kind of failure",
					"language": "cpp",
					"code": "auto eov = srv.receive(dat_id);\nif(eov.is_error()){\n\tauto& err = eov.get_error();\n\tif(err.is_type<err::not_found>()){\n\t\t/// Nothing stored under that id yet.\n\t\treturn make_void();\n\t}\n\treturn std::move(err);\n}\n"
				}
			]
		}
	},
	"notes": [
		"Copy is forbidden; use copy_error when a second instance is genuinely needed."
	]
}