Gnome::Glib — N-Error
use v6.d;
=begin rakudoc
Gnome::Glib::Error =end rakudoc
#------------------------------------------------------------------------------- #--[Class Description]---------------------------------------------------------- #-------------------------------------------------------------------------------
=begin rakudoc

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
=end rakudoc
#------------------------------------------------------------------------------- #--[Record Structure Documentation]--------------------------------------------- #-------------------------------------------------------------------------------
=begin rakudoc
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
=end rakudoc
#------------------------------------------------------------------------------- #--[Class Initialization]------------------------------------------------------- #-------------------------------------------------------------------------------
=begin rakudoc
Class initialization
new
:native-object
Create an object using a native object from an object of the same type found elsewhere. See also Gnome::N::TopLevelSupportClass.
multi method new ( N-Object() :$native-object! )
=end rakudoc
#------------------------------------------------------------------------------- =begin rakudoc
new-error
Creates a new N-Error with the given $domain and $code,
and a message formatted with $format.
=end rakudoc
#------------------------------------------------------------------------------- =begin rakudoc
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.
=end rakudoc
#------------------------------------------------------------------------------- =begin rakudoc
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!
=end rakudoc
#------------------------------------------------------------------------------- #--[Methods]-------------------------------------------------------------------- #-------------------------------------------------------------------------------
=begin rakudoc
Methods =end rakudoc
#------------------------------------------------------------------------------- =begin rakudoc
copy
Makes a copy of $error.
method copy (--> CArray[N-Error] )
Return value; a new N-Error.
=end rakudoc
#------------------------------------------------------------------------------- =begin rakudoc
free
Frees a N-Error and associated resources.
method free ( )
=end rakudoc
#------------------------------------------------------------------------------- =begin rakudoc
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.
=end rakudoc
#------------------------------------------------------------------------------- #--[Functions]------------------------------------------------------------------ #-------------------------------------------------------------------------------
=begin rakudoc
Functions =end rakudoc
#------------------------------------------------------------------------------- =begin rakudoc
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.
=end rakudoc
#------------------------------------------------------------------------------- =begin rakudoc
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.
=end rakudoc