.TH "FBB::Field" "3bobcat" "2005\-2023" "libbobcat\-dev_6\&.04\&.00" "Number fields"

.PP 
.SH "NAME"
FBB::Field \- sets and retrieves offset based number fields
.PP 
.SH "SYNOPSIS"
\fB#include <bobcat/field>\fP
.br 

.PP 
.SH "DESCRIPTION"

.PP 
Numbers may contain offset\-based sub\-fields\&. E\&.g\&., a value like 12345 might
consist of fields 12 and 345\&. Such fields can be considered offset\-based,
using end\- and begin offsets in the number representations\&. In this example
345 begins at digit position 0 (indicating the least significant digit of
12345) and at digit position 3 the next field starts\&. Likewise, the field 12
begins at digit position 3 and has ended at digit position 5\&.
.PP 
The \fIField\fP class template provides facilities for retrieving and assigning
position based values of existing numeric values of (currently) at most 64
bits\&.
.PP 
To represent such fields the following format is used:
.nf 

    Field<base, end, begin>::function(argument(s))
        
.fi 
where \fIbase\fP specifies the number system\(cq\&s base value, \fIend\fP specifies
the (0\-based) index position where the number field ends, and \fIbegin\fP
specifies the index position where the number field begins\&. Here are two
examples, using the decimal number system:
.nf 

    Field<10, 3, 0>::get(12345)    // returns 345
    Field<10, 5, 3>::get(12345)    // returns  12
        
.fi 

.PP 
The decision to specify the \fIend\fP offset before (i\&.e\&., left of) the
\fIbegin\fP offset is based on the consideration that this corresponds to the
standard way of looking at digit positions in numbers, where the end offset is
found to the left of the begin offset\&.
.PP 
Values of fields can be retrieved, but they can also
be set: to set a field\(cq\&s value the following format is used:
.nf 

    Field<10, 3, 1>::set(12345, 99)   // returns 12995
    Field<10, 1, 0>::set(12345, 0)    // returns 12450
        
.fi 
When values are assigned to fields the maximum width of the destination
field is taken into account\&. When specifying 9999 instead of 99 in
the above example the returned value will still be 12995, as the destination
field has a width of two digit positions\&. Likewise, specifying a smaller value
sets the remaining (more significant) digits to 0:
.nf 

    Field<10, 3, 1>::set(12345, 9)    // returns 12095
        
.fi 

.PP 
The class templates themselves are unaware of bases of number systems\&. Since
0xdeaf equals the decimal value 57007 and 0xd equals 13, calling the above
function as
.nf 

    Field<16, 1, 0>::set(76007, 13)
        
.fi 
returns the hexadecimal value \fI0xdead\(cq\&\fP\&.
.PP 
The \fIField\fP class template requires three non\-type numeric arguments:
.IP o 
\fIbase\fP, specifying the base of the number system;
.IP o 
\fIend\fP, specifying the 0\-based offset of the digit position where the
field has ended;
.IP o 
\fIbegin\fP, specifying the 0\-based offset of the digit position where the
field begins;

.PP 
The class template is specialized for situations where \fIbase\fP is a mere
power of 2 (like 2, 4, 8, 16, \&.\&.\&.) because in those cases bit\-operations can
be used which are faster than multiplications, divisions and modulo
computation which are required when other number system bases are used\&.
.PP 
.SH "NAMESPACE"
\fBFBB\fP
.br 
All constructors, members, operators and manipulators, mentioned in this
man\-page, are defined in the namespace \fBFBB\fP\&.
.PP 
.SH "INHERITS FROM"
\-
.PP 
.SH "MEMBER FUNCTIONS"
.IP o 
\fBuint64_t Field<base, end, begin>::get(uint64_t value)\fP:
.br 
\fIvalue\fP is interpreted as a value in the \fIbase\fP number system, and
using digit positions in that number system the value of the digits from
offset \fIbegin\fP to (but not including) offset \fIend\fP is returned;
.IP 
.IP o 
\fBuint64_t Field<base, end, begin>::set(uint64_t value, uint64_t field)\fP:
.br 
\fIvalue\fP is interpreted as a value in the \fIbase\fP number system, and
using digit positions in that number system the digits from
offset \fIbegin\fP to (but not including) offset \fIend\fP are replaced by
\fIfield\(cq\&s\fP value\&. When the number of \fIfields\(cq\&s\fP digits (also using number
system \fIbase\fP) exceeds \fIend \- begin\fP then those excess digits are
ignored\&.

.PP 
.SH "EXAMPLE"
See the examples in the \fBDESCRIPTION\fP section
.PP 
.SH "FILES"
\fIbobcat/field\fP \- defines the class interface
.PP 
.SH "SEE ALSO"
\fBbobcat\fP(7)
.PP 
.SH "BUGS"
None Reported\&.
.PP 
.SH "BOBCAT PROJECT FILES"

.PP 
.IP o 
\fIhttps://fbb\-git\&.gitlab\&.io/bobcat/\fP: gitlab project page;
.IP o 
\fIbobcat_6\&.04\&.00\-x\&.dsc\fP: detached signature;
.IP o 
\fIbobcat_6\&.04\&.00\-x\&.tar\&.gz\fP: source archive;
.IP o 
\fIbobcat_6\&.04\&.00\-x_i386\&.changes\fP: change log;
.IP o 
\fIlibbobcat1_6\&.04\&.00\-x_*\&.deb\fP: debian package containing the
libraries;
.IP o 
\fIlibbobcat1\-dev_6\&.04\&.00\-x_*\&.deb\fP: debian package containing the
libraries, headers and manual pages;

.PP 
.SH "BOBCAT"
Bobcat is an acronym of `Brokken\(cq\&s Own Base Classes And Templates\(cq\&\&.
.PP 
.SH "COPYRIGHT"
This is free software, distributed under the terms of the
GNU General Public License (GPL)\&.
.PP 
.SH "AUTHOR"
Frank B\&. Brokken (\fBf\&.b\&.brokken@rug\&.nl\fP)\&.
.PP