luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-02-09 12:25:48 +01:00
Code Issues Packages Projects Releases Wiki Activity

docs: Fix references to omitted requirements in GVariant Specification

Browse Source 
I believe the specification was originally a shorter extract of
Allison’s thesis. This left a few dangling references to requirements
which were listed in a part of the thesis not included in the
specification.

Reword them slightly so they’re not quite so awkward.

Signed-off-by: Philip Withnall <pwithnall@endlessos.org>
This commit is contained in:
Philip Withnall 2022-11-02 11:05:40 +00:00
parent e34fdb0cd5
commit ca45f84789
1 changed files with 7 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
docs/reference/glib/gvariant-specification-1.0.rst
View File

@ -223,13 +223,13 @@ format for GVariant.
To do so, however, would conflict with a number of requirements that were established To do so, however, would conflict with a number of requirements that were established
for GVariant. for GVariant.
Most fundamentally, requirement would be violated. DBus messages are encoded in such Most fundamentally, the requirements would be violated. DBus messages are encoded in such
a way that in order to fetch the 100th item out of an array you first have to iterate over a way that in order to fetch the 100th item out of an array you first have to iterate over
the first 99 items to discover where the 100th item lies. A side effect of this iteration the first 99 items to discover where the 100th item lies. A side effect of this iteration
would be a violation of requirement . would be a violation of the requirements.
Additionally, using the DBus serialisation format with an API like that mandated by Additionally, using the DBus serialisation format with an API like that mandated by
requirement would likely imply a violation of requirement due to the fact that subparts the requirements would likely imply a violation of the requirements due to the fact that subparts
of DBus messages can change meaning when subjected to different starting alignments. of DBus messages can change meaning when subjected to different starting alignments.
This is discussed in more detail in `Simple Containment`_. This is discussed in more detail in `Simple Containment`_.
@ -303,7 +303,7 @@ equivalently, length) of each child element.
This property permits a container to be deconstructed into child values simply by This property permits a container to be deconstructed into child values simply by
referencing a subsequence of the byte sequence of the container as the value of the referencing a subsequence of the byte sequence of the container as the value of the
child which is an effective way of satisfying requirement . child which is an effective way of satisfying the requirements.
This property is not the case for the DBus serialisation format. In many cases (for This property is not the case for the DBus serialisation format. In many cases (for
example, arrays) the encoding of a child value of a DBus message will change depending example, arrays) the encoding of a child value of a DBus message will change depending
@ -316,7 +316,7 @@ direction.
Alignment Alignment
--------- ---------
In order to satisfy requirement , we must provide programmers with a pointer that they In order to satisfy the requirement, we must provide programmers with a pointer that they
can comfortably use. On many machines, programmers cannot directly dereference can comfortably use. On many machines, programmers cannot directly dereference
unaligned values, and even on machines where they can, there is often a performance unaligned values, and even on machines where they can, there is often a performance
hit. hit.
@ -384,7 +384,7 @@ Endianness
---------- ----------
Although the framing offsets of serialised data are always stored in little-endian byte Although the framing offsets of serialised data are always stored in little-endian byte
order, the data visible to the user (via the interface mandated by requirement ) is order, the data visible to the user (via the interface mandated by the requirements) is
allowed to be in either big or little-endian byte order. This is referred to as the “encoding allowed to be in either big or little-endian byte order. This is referred to as the “encoding
byte order”. When transmitting messages, this byte order should be specified if not byte order”. When transmitting messages, this byte order should be specified if not
explicitly agreed upon. explicitly agreed upon.
@ -739,7 +739,7 @@ serialised data is not in normal form. Normally this would result in an error be
An Argument Against Errors An Argument Against Errors
-------------------------- --------------------------
Requirement XXX forbids us from scanning the entirety of the serialised byte sequence The requirements forbids us from scanning the entirety of the serialised byte sequence
at load time; we can not check for normality and issue errors at this time. This leaves at load time; we can not check for normality and issue errors at this time. This leaves
any errors that might occur to be raised as exceptions as the values are accessed. any errors that might occur to be raised as exceptions as the values are accessed.