掩码（Python实现）

关于掩码

什么是标志flag

在掩码的语境下，标志flag，是只有1位的掩码，取值范围 $range(\mathrm{flag})$ 满足：

range(\mathrm{flag}) = \{0, 1\}

。

flag可以是一个单纯的取值范围为 $\{0,1\}$ 的二值的状态量，也可以是相对于另一个取值范围是 $\{s_1, s_2\}$ 的二值的状态量state，所建立一一映射

\mathrm{flag}: \{s_1, s_2\} \leftrightarrow \{0,1\}

。

Note 更一般而且常见的，标志flag是一个离散的状态量，取值范围是自然数集 $\N$ 的子集。它可以是单纯的状态量，也可以是：设存在一个状态量state，它的取值范围 $range(\mathrm{state})$ 是离散的，flag是 $range(\mathrm{state})$ 到自然数集 $\N$ 的映射
$\mathrm{flag}: range(\mathrm{state}) \to \N$
。也即，使用不同的自然数来分别枚举和指代状态量state的各个状态值。

什么是掩码mask

掩码mask，是一个二进制的位模式，取值范围 $range(\mathrm{mask})$ 满足：

range(\mathrm{mask}) = \{0, 1\}^n, n \in \N

。

mask是一个状态量，或者状态映射：给定状态向量state，是一组二值的状态量 $\{\mathrm{state}_i \big| 0 < i \le n, n \in \N\}$ 的序列，分别有取值范围 $range(\mathrm{state}_i)=\{s_{i, 1}, s_{i, 2}\}$ ，mask是相对于state，所建立一一映射

\mathrm{mask}: \underset{i=1}{\overset{n}{\times}}\{s_{i, 1}, s_{i, 2}\} \leftrightarrow \{0,1\}^n

。

Note 标志flag的值域是标量scalar，掩码mask的值域是向量vector，两者都是状态量或者状态映射。
可以认为，mask是建立在 $\{0,1\}^n,n \in \N$ 上的线性空间，给定它的一组基 $\{\bold{u}_i \in \{0,1\}^n \big| 0 < i \le n;\forall 0 < i, j \le n,\bold{u}_i[j] = 1 \iff i = j\}$ ，也即分别有 $\bold{u}_i$ 对应于mask的第 $i$ 位。令标志 $\mathrm{flag}_i$ 对应于 $\mathrm{mask}$ 的第 $i$ 位的值，即有 $\mathrm{flag}_i = \mathrm{mask}[i]$ 且有线性组合
$\mathrm{mask} = \sum_{i=1}^n \mathrm{flag}_i \cdot \bold{u}_i$
。总而言之，mask的每一位分别对应一个flag，mask是多个占据不同位的flag的线性组合，因此mask是一个状态向量或者组合状态映射。

实现：标志Flag

class Flag:

    def __init__(self):
        self._value = 0

    @property
    def flag(self) -> int:
        return self._value

    def set(self):
        'set the flag to 1'
        self._value = 1

    def clear(self):
        'set the flag to 0'
        self._value = 0

    def reverse(self):
        'reverse/invert the flag, 0 to 1, 1 to 0'
        self._value ^= 1

    def isset(self) -> bool:
        'Is flag = 1?'
        return self._value is 1

实现：掩码Mask

Note 因为在Python中，int是不可变类型，操作的结果往往会产生新的int对象，这是低效的。建议使用C扩展或者某些可改动内存的结构，至少保证位操作可以复用原来的内存区域。

mask.pyfrom typing import TypeVar, Generic, Union


T = TypeVar('T')


class MaskOpMixin(Generic[T]):

    def __eq__(self, o: Union[int, T]) -> bool:
        if isinstance(o, type(self)):
            o = o._value
        return self._value == o

    def __invert__(self):
        return type(self)(~self._value)

    def __and__(self, o: Union[int, T]) -> T:
        cls = type(self)
        if isinstance(o, cls):
            o = o._value
        return cls(self._value & o)

    def __or__(self, o: Union[int, T]) -> T:
        cls = type(self)
        if isinstance(o, cls):
            o = o._value
        return cls(self._value | o)

    def __xor__(self, o: Union[int, T]) -> T:
        cls = type(self)
        if isinstance(o, cls):
            o = o._value
        return cls(self._value ^ o)

    __rand__ = __and__
    __ror__ = __or__
    __rxor__ = __xor__

    def __iand__(self, o: Union[int, T]) -> T:
        if isinstance(o, type(self)):
            o = o._value
        self._value &= o
        return self

    def __ior__(self, o: Union[int, T]) -> T:
        if isinstance(o, type(self)):
            o = o._value
        self._value |= o
        return self

    def __ixor__(self, o: Union[int, T]) -> T:
        if isinstance(o, type(self)):
            o = o._value
        self._value ^= o
        return self

    def __sub__(self, o: Union[int, T]) -> T:
        cls = type(self)
        if isinstance(o, cls):
            o = o._value
        # 🤔 l & ~r == (l | r) ^ r
        return cls(self._value & ~o)

    def __isub__(self, o: Union[int, T]) -> T:
        if isinstance(o, type(self)):
            o = o._value
        self._value &= ~o
        return self


class MaskBase:

    def __init__(self, mask: int = 0) -> None:
        self._value = mask

    @property
    def mask(self) -> int:
        return self._value

    @property
    def binmask(self) -> str:
        return bin(self._value)

    def __repr__(self) -> str:
        return f'{type(self).__name__}({bin(self._value)})'

    def set(self, m: int) -> None:
        'set mask by offset m'
        self._value |= 1 << m

    def clear(self, m: int) -> None:
        'clear mask by offset m'
        self._value &= ~(1 << m)

    def reverse(self, m: Union[int, MaskBase]) -> None:
        'reverse/invert mask by offset m'
        self._value ^= 1 << m

    def test(self, m: int) -> bool:
        'test mask by offset m'
        return bool(self._value & 1 << m)


class Mask(MaskBase, MaskOpMixin[MaskBase]):

    def set(self, m: Union[int, MaskBase]) -> None:
        'set mask by mask m'
        self |= m

    def clear(self, m: Union[int, MaskBase]) -> None:
        'clear mask by mask m'
        self -= m

    def reverse(self, m: Union[int, MaskBase]) -> None:
        'reverse/invert mask by mask m'
        self ^= m

    def test(self, m: Union[int, MaskBase]) -> bool:
        'clear mask by mask m'
        return self & m == m

测试结果如下：

>>> from mask import *
>>> EVENT0 = 1 << 0
>>> EVENT1 = 1 << 1
>>> EVENT2 = 1 << 2
>>> EVENT3 = 1 << 3
>>> m = Mask(EVENT1)
>>> m.set(EVENT0 | EVENT3)
>>> m
Mask(0b1011)
>>> m.test(EVENT0 | EVENT1)
True
>>> m.clear(EVENT0 | EVENT1)
>>> m
Mask(0b1000)
>>> m.reverse((1 << 4) - 1)
>>> m
Mask(0b111)