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_5.11.01-x.dsc: detached signature;

       o      bobcat_5.11.01-x.tar.gz: source archive;

       o      bobcat_5.11.01-x_i386.changes: change log;

       o      libbobcat1_5.11.01-x_*.deb: debian package containing the libraries;

       o      libbobcat1-dev_5.11.01-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).