NAME

       FBB::Field - sets and retrieves offset based number fields

SYNOPSIS

       #include <bobcat/field>

DESCRIPTION

       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.

       The Field class template provides facilities for  retrieving  and  assigning  position  based  values  of
       existing numeric values of (currently) at most 64 bits.

       To represent such fields the following format is used:

           Field<base, end, begin>::function(argument(s))

       where base specifies the number system’s base value, end specifies the (0-based) index position where the
       number  field  ends,  and  begin specifies the index position where the number field begins. Here are two
       examples, using the decimal number system:

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

       The decision to specify the end offset  before  (i.e.,  left  of)  the  begin  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.

       Values of fields can be retrieved, but they can also be set: to set a field’s value the following  format
       is used:

           Field<10, 3, 1>::set(12345, 99)   // returns 12995
           Field<10, 1, 0>::set(12345, 0)    // returns 12450

       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:

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

       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

           Field<16, 1, 0>::set(76007, 13)

       returns the hexadecimal value 0xdead’.

       The Field class template requires three non-type numeric arguments:

       o      base, specifying the base of the number system;

       o      end, specifying the 0-based offset of the digit position where the field has ended;

       o      begin, specifying the 0-based offset of the digit position where the field begins;

       The class template is specialized for situations where base 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.

NAMESPACE

       FBB
       All constructors, members, operators and manipulators, mentioned in this man-page,  are  defined  in  the
       namespace FBB.

INHERITS FROM

       -

MEMBER FUNCTIONS

       o      uint64_t Field<base, end, begin>::get(uint64_t value):
              value  is  interpreted  as  a  value  in the base number system, and using digit positions in that
              number system the value of the digits from offset begin to  (but  not  including)  offset  end  is
              returned;

       o      uint64_t Field<base, end, begin>::set(uint64_t value, uint64_t field):
              value  is  interpreted  as  a  value  in the base number system, and using digit positions in that
              number system the digits from offset begin to (but not  including)  offset  end  are  replaced  by
              field’s  value.  When  the number of fields’s digits (also using number system base) exceeds end -
              begin then those excess digits are ignored.

EXAMPLE

       See the examples in the DESCRIPTION section

FILES

       bobcat/field - defines the class interface

SEE ALSO

       bobcat(7)

BUGS

       None Reported.

BOBCAT PROJECT FILES

       o      https://fbb-git.gitlab.io/bobcat/: gitlab project page;

       o      bobcat_6.04.00-x.dsc: detached signature;

       o      bobcat_6.04.00-x.tar.gz: source archive;

       o      bobcat_6.04.00-x_i386.changes: change log;

       o      libbobcat1_6.04.00-x_*.deb: debian package containing the libraries;

       o      libbobcat1-dev_6.04.00-x_*.deb: debian package containing the libraries, headers and manual pages;

BOBCAT

       Bobcat is an acronym of `Brokken’s Own Base Classes And Templates’.

COPYRIGHT

       This is free software, distributed under the terms of the GNU General Public License (GPL).

AUTHOR

       Frank B. Brokken (f.b.brokken@rug.nl).

libbobcat-dev_6.04.00                               2005-2023                                FBB::Field(3bobcat)