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