@c -*-texinfo-*-
@c This is part of the GNU G-Golf Reference Manual.
@c Copyright (C) 2019 - 2025 Free Software Foundation, Inc.
@c See the file g-golf.texi for copying conditions.


@node Struct
@subsection Struct

G-Golf class, accessors, methods and procedures to deal with C struct
types.


@subheading Classes

@indentedblock
@table @code
@item @ref{<gi-struct>}
@end table
@end indentedblock


@subheading Procedures, Accessors and Methods

@indentedblock
@table @code
@item @ref{!g-type____}
@item @ref{!g-name_}
@item @ref{!name____}
@item @ref{!alignment}
@item @ref{!size}
@item @ref{!is-gtype-struct?}
@item @ref{!is-foreign?}
@item @ref{!field-types}
@item @ref{!field-desc}
@item @ref{!scm-types}
@item @ref{!init-vals}
@item @ref{!is-opaque?}
@item @ref{!is-semi-opaque?}
@item @ref{field-offset}
@end table
@end indentedblock


@subheading Description

G-Golf class, accessors, methods and procedures to deal with C struct
types.


@subheading Classes

@anchor{<gi-struct>}
@deftp Class <gi-struct>

@code{<gi-struct>} is a class. It's an instance of @code{<class>}.

Superclasses are:

@indentedblock
@table @code
@item <object>
@end table
@end indentedblock

Class Precedence List is:

@indentedblock
@table @code
@item <g-struct>
@item <object>
@item <top>
@end table
@end indentedblock

Directs slots are:

@indentedblock
@table @code
@item g-type
@item g-name
@item name
@item alignment
@item size
@item is-gtype-struct?
@item is-foreign?
@item field-types
@item field-desc
@item scm-types
@item init-vals
@item is-opaque?
@item is-semi-opaque?
@end table
@end indentedblock

Instances of the @code{<gi-struct>} are immutable (to be precise, there
are not meant to be mutated, see @ref{GOOPS Notes - Conventions - Recommendations},
'Slots are not Immutable').
@end deftp


@subheading Procedures and Accessors

@anchor{!g-type____}
@anchor{!g-name_}
@anchor{!name____}
@anchor{!alignment}
@anchor{!size}
@anchor{!is-gtype-struct?}
@anchor{!is-foreign?}
@anchor{!field-types}
@anchor{!field-desc}
@anchor{!scm-types}
@anchor{!init-vals}
@deffn Accessor !g-type (inst <gi-struct>)
@deffnx Accessor !g-name (inst <gi-struct>)
@deffnx Accessor !name (inst <gi-struct>)
@deffnx Accessor !alignment (inst <gi-struct>)
@deffnx Accessor !size (inst <gi-struct>)
@deffnx Accessor !is-gtype-struct? (inst <gi-struct>)
@deffnx Accessor !field-types (inst <gi-struct>)
@deffnx Accessor !field-desc (inst <gi-struct>)
@deffnx Accessor !scm-types (inst <gi-struct>)
@deffnx Accessor !init-vals (inst <gi-struct>)

Returns the content of their respective slot for @var{inst}.
@end deffn


@anchor{!is-opaque?}
@deffn Accessor !is-opaque? (inst <gi-struct>)

Returns @code{#t} if @var{inst} is @samp{opaque}, otherwise,
it returns @code{#f}.

A <gi-struct> instance is said to be @samp{opaque} when the call to
@code{g-struct-info-get-size} upon its GIStructInfo pointer returns
@code{zero}. In scheme, these <gi-struct> instances have no fields.

@samp{Opaque} boxed types should never be @samp{decoded}, nor
@samp{encoded}. Instead, procedures, accessors and methods should
@samp{blindingly} receive, pass and/or return their pointer(s).
@end deffn


@anchor{!is-semi-opaque?}
@deffn Accessor !is-semi-opaque? (inst <gi-struct>)

Returns @code{#t} if @var{inst} is @samp{semi-opaque}, otherwise,
it returns @code{#f}.

A <gi-struct> instance is said to be @samp{semi-opaque} when one of its
field types is @code{void}, @code{interface} or if the total size of the
@code{scm-types} differs from the @var{inst} size slot vlue.

@samp{Semi-opaque} boxed types should never be @samp{decoded}, nor
@samp{encoded}. Instead, procedures, accessors and methods should
@samp{blindingly} receive, pass and/or return their pointer(s).
@end deffn


@anchor{field-offset}
@deffn Method field-offset (inst <gi-struct>) field-name

Returns an integer.

Obtain and returns the @var{field-name} offset for @var{inst}, It is an
error to call this method if there is no such @var{field-name} defined
for @var{inst}.
@end deffn
