octet.sa


Generated by gen_html_sa_files from ICSI. Contact gomes@icsi.berkeley.edu for details
 
------------------------->  GNU Sather - sourcefile  <-------------------------
-- Copyright (C) 2000 by K Hopper, University of Waikato, New Zealand        --
-- This file is part of the GNU Sather library. It is free software; you may --
-- redistribute  and/or modify it under the terms of the GNU Library General --
-- Public  License (LGPL)  as published  by the  Free  Software  Foundation; --
-- either version 2 of the license, or (at your option) any later version.   --
-- This  library  is distributed  in the  hope that it will  be  useful, but --
-- WITHOUT ANY WARRANTY without even the implied warranty of MERCHANTABILITY --
-- or FITNESS FOR A PARTICULAR PURPOSE. See Doc/LGPL for more details.       --
-- The license text is also available from:  Free Software Foundation, Inc., --
-- 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA                     --
-------------->  Please email comments to <bug-sather@gnu.org>  <--------------


immutable class OCTET < $BIT_PATTERN{OCTET}

immutable class OCTET < $BIT_PATTERN{OCTET} is -- This class is the first basic immutable class which has eight bits, -- but otherwise may have any meaning. Only equality and bit operations -- are specified. -- Version 1.2 Dec 97. Copyright K Hopper, U of Waikato -- Development History -- ------------------- -- Date Who By Detail -- ---- ------ ------ -- 1 May 96 kh Original 'char' based version -- 11 Dec 96 kh Now bit-based. -- 22 Dec 97 kh Added binary string conversion routines. include AVAL{BIT} asize-> ; include COMPARABLE ; include BINARY ; const asize : CARD := 8 ; const Octet_Bits : CARD := asize ; const Octet_Max : CARD := 255 ; -- It IS eight bits only! const maxnum : CARD := Octet_Max ; -- This is the largest unsigned exact number representable using the -- number of bits contained. private const Masks : ARRAY{SAME} := | create(1), create(3), create(7), create(15), create(31), create(63), create(127), create(255) | ; create : SAME is -- This creates a new object with all bits zero! me : SAME := void ; return me end ; null : SAME is -- Merely a renamed version of create above! return create end ; create( binstr : BINSTR ) : SAME pre binstr.size = 1 is -- This creates a new object with the given 'bit-pattern'! return binstr[0] end ; build( cursor : BIN_CURSOR ) : SAME pre cursor.remaining > 0 post (result = initial(cursor.item)) is -- This routine 'trivially' returns the next octet on the indexed string. return cursor.get_item end ; create( val : CARD ) : SAME pre (val <= Octet_Max) is -- This produces a new octet which takes the value val as a bit-pattern -- provided that the pre-condition is met. It relies on the built-in -- conversion CARD_OCTET operation builtin CARD_OCTET end ; create( val : CHAR ) : SAME pre (val.code.card <= Octet_Max) is -- This produces a new octet which takes the value val as a bit-pattern -- provided that the pre-condition is met. It relies on the built-in -- conversion CARD_OCTET operation builtin CHAR_OCTET end ; binstr : BINSTR is -- This routine returns the octet as a single element binary string. return BINSTR::create(self) end ; octet : SAME is -- This routine returns a copy of self. This is included for symmetry -- with the other bit-pattern classes. return (self) end ; hextet : HEXTET is -- This routine returns the octet object which contains the low eight -- bits of self. builtin OCTET_HEXTET end ; quad : QUADBITS is -- This routine returns the four octet object which contains self in -- the lower sixteen bits. builtin OCTET_QUADBITS end ; char : CHAR is -- This routine converts the octet into a character. builtin OCTET_CHAR end ; card : CARD is -- This converts the octet into a number-sized numeric value. builtin OCTET_CARD end ; bool : BOOL is -- This feature converts the octet into a truth value where no bits set -- is the value false. return ~card.is_zero end ; hash : CARD pre true post true is -- This routine returns a hash value composed from the bit-pattern -- contained. return NUM_BITS::create(card).hash end ; int : INT is -- This converts the octet into a number-sized numeric INTEGER value. return card.int end ; is_eq( other : SAME ) : BOOL is -- This and its inverse are the only two relational operations valid -- on an octet. builtin OCTET_IS_EQ end ; bit( index : CARD ) : BIT pre index < Octet_Bits post result = [index] is -- This routine returns the value of the individual bit indicated as -- either setbit or clearbit as appropriate. return aget(index) end ; alter( index : CARD, val : BIT ) : SAME pre index < Octet_Bits post result[index] = val is -- This routine sets to val the value of the indexed bit of the octet -- self. aset(index,val) ; return (self) end ; slice( lsb : CARD, count : CARD ) : SAME pre lsb < Octet_Bits and count > 0 and (lsb + count) <= Octet_Bits post true is -- This routine returns the octet containing the indicated slice in the -- lowest count bits. loc_mask : SAME := Masks[count - 1].left(lsb) ; return self.bit_and(loc_mask).right(lsb) end ; slice( lsb : CARD, count : CARD, val : SAME ) : SAME pre lsb < Octet_Bits and count > 0 and (lsb + count) <= Octet_Bits post true is -- This routine returns the hextet containing the indicated slice in the -- bits starting at lsb. loc_chunk : SAME := val.bit_and(Masks[count - 1]).left(lsb) ; loc_mask : SAME := Masks[count - 1].left(lsb).bit_invert ; return self.bit_and(loc_mask).bit_or(loc_chunk) end ; set( index : CARD ) : BOOL pre index < Octet_Bits post (result = ([index] = setbit)) is -- This returns true if and only if the indexed bit of this octet is -- set. If the value of index is greater than or equal to Octet_Bits -- or less than zero then false is returned -- since the bit does not exist. return bit(index).set end ; clear( index : CARD ) : BOOL pre index < Octet_Bits post (result = ([index] = clearbit)) is -- This returns true if and only if the indexed bit of this octet is -- clear. If the value of index is greater than or equal to Octet_Bits -- or less than zero then false is returned -- since the bit does not exist. return bit(index).clear end ; bit_and( other : SAME ) : SAME is -- This built-in primitive returns the result of anding together each bit -- of self and other builtin OCTET_AND -- compiler primitive end ; bit_or( other : SAME ) : SAME is -- This built-in primitive returns the result of oring together each bit -- of self and other builtin OCTET_OR -- compiler primitive end ; bit_invert : SAME is -- This built-in primitive returns the result of inverting self. builtin OCTET_INVERT -- compiler primitive end ; bit_xor( other : SAME ) : SAME is -- This built-in primitive returns the result of xoring together each bit -- of self and other builtin OCTET_XOR -- compiler primitive end ; private shift( places : INT ) : SAME is -- This built-in primitive returns the result of shifting the bits in -- the octet by the specified number of places (left if +ve). Note that -- the pre-conditions necessary are satisfied by the right and left public -- routines. builtin OCTET_SHIFT -- compiler primitive end ; left( places : CARD ) : SAME pre places <= Octet_Bits post ((places.abs.card = Octet_Bits) and (result = create)) or (result[places] = initial([0])) is -- This built-in primitive returns the result of shifting the bits in -- the octet left by the specified number of places. if (places = Octet_Bits) then return create else return shift(places.int) end end ; right( places : CARD ) : SAME pre places <= Octet_Bits post ((places = Octet_Bits) and (result = create)) or (result[Octet_Bits - 1 - places] = initial([Octet_Bits - 1])) is -- This built-in primitive returns the result of shifting the bits in -- the octet right by the specified number of places. if (places = Octet_Bits) then return create else return shift(-(places.int)) end end ; highest( val : BIT ) : CARD pre true post (result = CARD::nil) or (result < Octet_Bits) is -- This routine returns the index of the highest bit in the octet which -- has the value val. If no bits are set then the value CARD::nil is -- returned. loop index : CARD := (Octet_Bits - 1).downto!(0) ; if ([index] = val) then return index end end ; return CARD::nil end ; lowest( val : BIT ) : CARD pre true post (result = CARD::nil) or (result < Octet_Bits) is -- This routine returns the index of the lowest bit which has the same -- value as val - or CARD::nil if there are no such bits. loop index : CARD := 0.upto!(Octet_Bits - 1) ; if ([index] = val) then return index end end ; return CARD::nil end ; highest : CARD pre true post (result = CARD::nil) or (result < Octet_Bits) is -- This routine returns the index of the highest set bit in the octet. -- This is used in logarithmic and exponential routines for numbers. If -- no bits are set then the value CARD::nil is returned. loop index : CARD := (Octet_Bits - 1).downto!(0) ; if set(index) then return index end end ; return CARD::nil end ; lowest : CARD pre true post (result = CARD::nil) or (result < Octet_Bits) is -- This routine returns the index of the lowest set bit in the octet. -- This is used in logarithmic and exponential routines for numbers. If -- no bits are set then the value CARD::nil is returned. loop index : CARD := 0.upto!(Octet_Bits - 1) ; if set(index) then return index end end ; return CARD::nil end ; hex_str( lib : LIBCHARS ) : STR pre true post create(CARD::build_based(result.cursor,16)) = self is -- This routine yields a hexadecimal string representation of the octet -- using the specified encoding and repertoire. res : STR := self.card.hex_str(lib,2) ; return res end ; hex_str : STR pre true post create(CARD::build_based(result.cursor,16)) = self is -- This routine yields a hexadecimal string representation of the octet -- using the default encoding and repertoire. return self.card.hex_str(LIBCHARS::default,2) end ; str( lib : LIBCHARS ) : STR pre ~void(lib) post result.size = hex_str.size + 2 is -- This routine yields a string representation of the octet -- in the given encoding and repertoire. return STR::create(lib) + lib.digit(0).char + lib.Hex_Prefix.char + hex_str(lib) end ; str : STR pre true post result.size = hex_str.size + 2 is -- This routine yields a string representation of the octet -- in the default encoding and repertoire. return str(LIBCHARS::default) end ; end ; -- OCTET