N-Error
use v6.d;
Gnome::Glib::Error
#------------------------------------------------------------------------------- #--[Class Description]---------------------------------------------------------- #-------------------------------------------------------------------------------
Description
The `N-Error` structure contains information about an error that has occurred.
Example
my GQuark $domain = 45444;
my Int $code = 1012342;
my Str $message = 'my error';
my Gnome::Glib::N-Error $error .= new-error( $domain, $code, $message);
say $error.matches( $domain, $code), '.matches()'; # True
$error.free;
say $error.matches( $domain, $code); # False
#------------------------------------------------------------------------------- #--[Record Structure Documentation]--------------------------------------------- #-------------------------------------------------------------------------------
Record N-Error
class N-Error:auth<github:MARTIMM>:api<2> is export is repr('CStruct') {
has GQuark $.domain;
has gint $.code;
has Str $.message;
}
domain; error domain, e.g. %G_FILE_ERROR
code; error code, e.g. %G_FILE_ERROR_NOENT
message; human-readable informative error message
#------------------------------------------------------------------------------- #--[Class Initialization]------------------------------------------------------- #-------------------------------------------------------------------------------
Class initialization
new
:native-object
Create an object using a native object from elsewhere. See also Gnome::N::TopLevelSupportClass.
multi method new ( N-Object :$native-object! )
#-------------------------------------------------------------------------------
new-error
Creates a new N-Error with the given $domain and $code,
and a message formatted with $format.
begin comment
method new-error ( UInt $domain, Int() $code, Str $format, ā¦ --> Gnome::Glib::Error )
$domain; error domain.
$code; error code.
$format; printf()-style format for error message.
ā¦; parameters for message format. Note that each argument must be specified as a type followed by its value!
Example # Example for new-error
#-------------------------------------------------------------------------------
new-literal
Creates a new N-Error; unlike g_error_new(), $message is not a printf()-style format string. Use this function if $message contains text you don't have control over,
that could include printf() escape sequences.
method new-literal ( UInt $domain, Int() $code, Str $message --> Gnome::Glib::Error )
$domain; error domain.
$code; error code.
$message; error message.
#-------------------------------------------------------------------------------
new-valist This function is not yet available
Creates a new N-Error with the given $domain and $code,
and a message formatted with $format.
method new-valist ( UInt $domain, Int() $code, Str $format, ā¦ --> Gnome::Glib::Error )
$domain; error domain.
$code; error code.
$format; printf()-style format for error message.
args;
va_listof parameters for the message format. Note that each argument must be specified as a type followed by its value!
#------------------------------------------------------------------------------- #--[Methods]-------------------------------------------------------------------- #-------------------------------------------------------------------------------
Methods
#-------------------------------------------------------------------------------
copy
Makes a copy of $error.
method copy (--> CArray[N-Error] )
Return value; a new N-Error.
#-------------------------------------------------------------------------------
free
Frees a N-Error and associated resources.
method free ( )
#-------------------------------------------------------------------------------
matches
Returns True if $error matches $domain and $code, False
otherwise. In particular, when $error is Nil, False will be returned.
If $domain contains a `FAILED` (or otherwise generic) error code,
you should generally not check for it explicitly, but should instead treat any not-explicitly-recognized error code as being equivalent to the `FAILED` code. This way, if the domain is extended in the future to provide a more specific error code for a certain case, your code will still work.
method matches ( UInt $domain, Int() $code --> Bool )
$domain; an error domain.
$code; an error code.
Return value; whether $error has $domain and $code.
#------------------------------------------------------------------------------- #--[Functions]------------------------------------------------------------------ #-------------------------------------------------------------------------------
Functions
#-------------------------------------------------------------------------------
domain-register
This function registers an extended N-Error domain. $error_type_name will be duplicated. Otherwise does the same as g_error_domain_register_static().
method domain-register (
Str $error-type-name, Int() $error-type-private-size,
&error-type-init, &error-type-copy, &error-type-clear
--> UInt
)
$error-type-name; string to create a GQuark from.
$error-type-private-size; size of the private error data in bytes.
&error-type-init; function initializing fields of the private error data. Tthe function must be specified with following signature;
:( N-Error $error ).&error-type-copy; function copying fields of the private error data. Tthe function must be specified with following signature;
:( N-Error $src-error, N-Error $dest-error ).&error-type-clear; function freeing fields of the private error data. Tthe function must be specified with following signature;
:( N-Error $error ).
Return value; GQuark representing the error domain.
#-------------------------------------------------------------------------------
domain-register-static
This function registers an extended N-Error domain.
$error_type_name should not be freed. $error_type_private_size must be greater than 0.
$error_type_init receives an initialized N-Error and should then initialize the private data.
$error_type_copy is a function that receives both original and a copy N-Error and should copy the fields of the private error data. The standard N-Error fields are already handled.
$error_type_clear receives the pointer to the error, and it should free the fields of the private error data. It should not free the struct itself though.
Normally, it is better to use G_DEFINE_EXTENDED_ERROR(), as it already takes care of passing valid information to this function.
method domain-register-static (
Str $error-type-name, Int() $error-type-private-size,
&error-type-init, &error-type-copy, &error-type-clear
--> UInt
)
$error-type-name; static string to create a GQuark from.
$error-type-private-size; size of the private error data in bytes.
&error-type-init; function initializing fields of the private error data. Tthe function must be specified with following signature;
:( N-Error $error ).&error-type-copy; function copying fields of the private error data. Tthe function must be specified with following signature;
:( N-Error $src-error, N-Error $dest-error ).&error-type-clear; function freeing fields of the private error data. Tthe function must be specified with following signature;
:( N-Error $error ).
Return value; GQuark representing the error domain.