[#util-Result]
= xref:util.adoc[util]::Result
:relfileprefix: ../
:mrdocs:

The util&colon;&colon;Result class provides a standard way for functions to return either error messages or result values&period;

== Synopsis

Declared in `&lt;util&sol;result&period;h&gt;`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
template&lt;class M&gt;
class Result;
----

== Description

It is intended for high&hyphen;level functions that need to report error strings to end users&period; Lower&hyphen;level functions that don&apos;t need this error&hyphen;reporting and that only need error&hyphen;handling should avoid util&colon;&colon;Result and instead use util&colon;&colon;Expected, std&colon;&colon;optional, std&colon;&colon;variant, or custom structs and enum types to return function results&period;

Usage examples can be found in

general code returning `util&colon;&colon;Result&lt;T&gt;` values is very similar to code returning `std&colon;&colon;optional&lt;T&gt;` values&period; Existing functions returning `std&colon;&colon;optional&lt;T&gt;` can be updated to return `util&colon;&colon;Result&lt;T&gt;` and return error strings usually just replacing `return std&colon;&colon;nullopt&semi;` with &grave;return util&colon;&colon;Error&lcub;error&lowbar;string&rcub;&semi;&grave;&period;

== Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:util/Result/2constructor-09.adoc[`Result`]         [.small]#[constructor]#
| Constructors
| xref:util/Result/2destructor.adoc[`&#126;Result`] [.small]#[destructor]#
| Destroys the result and its held value or error message&period;
| xref:util/Result/has_value.adoc[`has&lowbar;value`] 
| std&colon;&colon;optional methods, so functions returning optional&lt;T&gt; can change to return Result&lt;T&gt; with minimal changes to existing code, and vice versa&period;
| xref:util/Result/operator_star-0d.adoc[`operator&ast;`] 
| Dereferences the held value&period;
| xref:util/Result/operator_ptr-0b.adoc[`operator&hyphen;&gt;`] 
| Member access to the held value&period;
| xref:util/Result/value-0ad.adoc[`value`] 
| Accesses the held value&semi; asserts that the result holds a value&period;
| xref:util/Result/value_or-0e.adoc[`value&lowbar;or`] 
| `value&lowbar;or` overloads
| xref:util/Result/2conversion.adoc[`operator bool`] 
| Tests whether the result holds a value&period;
|===


== Friends

[cols="1,4"]
|===
| Name| Description
| `xref:util/ErrorString-01.adoc[util::ErrorString]`
| Extracts the error message from a result&period;
|===

== Non-Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:util/ErrorString-07.adoc[`ErrorString`]
| Extracts the error message from a result&period;
| xref:ApplyArgsManOptions.adoc[`&colon;&colon;ApplyArgsManOptions`]
| Overlay the options set in `argsman` on top of corresponding members in `mempool&lowbar;opts&period;` Returns an error if one was encountered&period;
| xref:DecodeBase64PSBT.adoc[`&colon;&colon;DecodeBase64PSBT`]
| Decode a base64&hyphen;encoded PSBT into a PartiallySignedTransaction&period;
| xref:DecodeRawPSBT.adoc[`&colon;&colon;DecodeRawPSBT`]
| Decode a raw binary PSBT into a PartiallySignedTransaction&period;
| xref:LoadAddrman.adoc[`&colon;&colon;LoadAddrman`]
| Loads the address manager (peers&period;dat), creating a fresh one if needed&period;
| xref:SighashFromStr.adoc[`&colon;&colon;SighashFromStr`]
| Parse a signature&hyphen;hash type from its textual name&period;
| xref:init/SetLoggingCategories.adoc[`&colon;&colon;init&colon;&colon;SetLoggingCategories`]
| Enables or disables the debug logging categories selected by the arguments&period;
| xref:init/SetLoggingLevel.adoc[`&colon;&colon;init&colon;&colon;SetLoggingLevel`]
| Sets the global logging severity level selected by the arguments&period;
| xref:kernel/SanityChecks.adoc[`&colon;&colon;kernel&colon;&colon;SanityChecks`]
| Ensure a usable environment with all necessary library support&period;
| xref:node/ApplyArgsManOptions-06.adoc[`&colon;&colon;node&colon;&colon;ApplyArgsManOptions`]
| Apply block&hyphen;storage options taken from the argument manager&period;
| xref:node/ApplyArgsManOptions-0e.adoc[`&colon;&colon;node&colon;&colon;ApplyArgsManOptions`]
| Apply chainstate&hyphen;manager options taken from the argument manager&period;
| xref:node/CheckMiningOptions.adoc[`&colon;&colon;node&colon;&colon;CheckMiningOptions`]
| Check option values for validity&period; Returns an error for invalid values&period;
| xref:node/ReadMiningArgs.adoc[`&colon;&colon;node&colon;&colon;ReadMiningArgs`]
| Read the mining options set in `args&period;` Returns an error if one was encountered&period;
| xref:wallet/AttemptSelection.adoc[`&colon;&colon;wallet&colon;&colon;AttemptSelection`]
| Attempt to find a valid input set that preserves privacy by not mixing OutputTypes&period; `ChooseSelectionResult()` will be called on each OutputType individually and the best the solution (according to the waste metric) will be chosen&period; If a valid input cannot be found from any single OutputType, fallback to running `ChooseSelectionResult()` over all available coins&period;
| xref:wallet/AutomaticCoinSelection.adoc[`&colon;&colon;wallet&colon;&colon;AutomaticCoinSelection`]
| Select a set of coins such that nTargetValue is met&semi; never select unconfirmed coins if they are not ours
| xref:wallet/ChooseSelectionResult.adoc[`&colon;&colon;wallet&colon;&colon;ChooseSelectionResult`]
| Attempt to find a valid input set that meets the provided eligibility filter and target&period; Multiple coin selection algorithms will be run and the input set that produces the least waste (according to the waste metric) will be chosen&period;
| xref:wallet/CoinGrinder.adoc[`&colon;&colon;wallet&colon;&colon;CoinGrinder`]
| Select coins using the CoinGrinder deterministic search algorithm&period;
| xref:wallet/CreateTransaction.adoc[`&colon;&colon;wallet&colon;&colon;CreateTransaction`]
| Create a new transaction paying the recipients with a set of coins selected by SelectCoins()&semi; Also create the change output, when needed
| xref:wallet/ExportWatchOnlyWallet.adoc[`&colon;&colon;wallet&colon;&colon;ExportWatchOnlyWallet`]
| Make a new watchonly wallet file containing the public descriptors from this wallet The exported watchonly wallet file will be named and placed at the path specified in &apos;destination&apos;
| xref:wallet/FetchSelectedInputs.adoc[`&colon;&colon;wallet&colon;&colon;FetchSelectedInputs`]
| Fetch and validate coin control selected inputs&period; Coins could be internal (from the wallet) or external&period;
| xref:wallet/FundTransaction.adoc[`&colon;&colon;wallet&colon;&colon;FundTransaction`]
| Insert additional inputs into the transaction by calling CreateTransaction()&semi;
| xref:wallet/GetWalletPath.adoc[`&colon;&colon;wallet&colon;&colon;GetWalletPath`]
| Determine the path that the wallet is stored in
| xref:wallet/KnapsackSolver.adoc[`&colon;&colon;wallet&colon;&colon;KnapsackSolver`]
| Select coins using the original Knapsack approximation, used as a fallback&period;
| xref:wallet/MigrateLegacyToDescriptor-06.adoc[`&colon;&colon;wallet&colon;&colon;MigrateLegacyToDescriptor`]
| Do all steps to migrate a legacy wallet to a descriptor wallet
| xref:wallet/MigrateLegacyToDescriptor-09.adoc[`&colon;&colon;wallet&colon;&colon;MigrateLegacyToDescriptor`]
| Requirement&colon; The wallet provided to this function must be isolated, with no attachment to the node&apos;s context&period;
| xref:wallet/SelectCoins.adoc[`&colon;&colon;wallet&colon;&colon;SelectCoins`]
| Select all coins from coin&lowbar;control, and if coin&lowbar;control &apos;m&lowbar;allow&lowbar;other&lowbar;inputs&equals;true&apos;, call &apos;AutomaticCoinSelection&apos; to select a set of coins such that nTargetValue &hyphen; pre&lowbar;set&lowbar;inputs&period;total&lowbar;amount is met&period;
| xref:wallet/SelectCoinsBnB.adoc[`&colon;&colon;wallet&colon;&colon;SelectCoinsBnB`]
| Select coins using the Branch and Bound algorithm to find a changeless solution&period;
| xref:wallet/SelectCoinsSRD.adoc[`&colon;&colon;wallet&colon;&colon;SelectCoinsSRD`]
| Select coins by Single Random Draw (SRD)&period; SRD selects eligible OutputGroups from a shuffled ordering until the effective value of the input set suffices to create the recipient outputs and a change output with an amount of at least CHANGE&lowbar;LOWER&period; While the maximum selection weight is exceeded during selection, the OutputGroup with the lowest effective value is dropped from the selection before additional OutputGroups are selected&period; Due to this greedy approach, SRD can fail to discover possible solutions in pathological cases&period;
|===


[.small]#Created with https://www.mrdocs.com[MrDocs]#
