txt: ## dist_zef-thundergnat-FixedInt.md
  [![Actions Status](https://github.com/thundergnat/FixedInt/actions/workflows/test.yml/badge.svg)](https://github.com/thundergnat/FixedInt/actions)
  
  # NAME
  
  FixedInt - Unsigned fixed sized Integers
  
  # SYNOPSIS
  
  ```
  use FixedInt;
  
  my \fixedint = FixedInt.new(:8bit);
  
  say fixedint; # 0
  
  say fixedint -= 12;   # 244
  say fixedint.signed;  # -12
  say fixedint.bin;     # 0b11110100
  say fixedint.hex;     # 0xF4
  
  say fixedint += 2500; # 184
  say fixedint.signed;  # -72
  say fixedint.bin;     # 0b10111000
  say fixedint.hex;     # 0xB8
  
  ```
  
  # DESCRIPTION
  
  FixedInt provides an easy way to work with fixed-sized unsigned integers in Raku. Rakus Integers by default are unfixed, arbitrary size. Doing unsigned fixed-size bitwise operations requires a bunch of extra bookkeeping. This module hides that bookkeeping behind an interface.
  
  One major caveat to be aware of when using this module. The class instance **may not** be instantiated in a $ sigiled variable.
  
  Raku $ sigiled scalar variables do not implement a STORE method, but instead do direct assignment; and there doesn't seem to be any easy way to override that behaviour.
  
  An implication of that is that classes that **do** implement a STORE method can not be held in a $ sigiled variable. (Well, they **can**, they just won't work correctly. The first time you try to store a new value, the entire class instance will be overwritten and disappear.)
  
  There are two work-arounds. One is to use an unsigiled variable. Unsigiled variables have no preconception of what may or may not be allowed, so don't override a STORE method. They work well, but if you really want a $ sigiled container, your only real option is to fake it using a constant term (rather than a variable.)
  
  ```
  my \int32 = FixedInt.new; # unsigiled constant
  
  # or
  
  constant term:<$int32> = FixedInt.new; # "sigiled" constant term
  
  # looks like a variable but is really a constant term
  
  ```
  
  The FixedInt module allows creating and working with **any** sized fixed size Integer. Not only the "standard" sizes: 8, 16, 32, 64, etc., but also: 11, 25, 103, whatever. Once instantiated, it can be treated like any other variable. You can add to it, subtract from it, multiply, divide, whatever; the value stored in the variable will always stay the specified bit size. Any excesses will "roll over" the value. Works correctly for any standard bitwise or arithmatic operator, though you must remember to assign to the variable to get the fixed sized properties.
  
  Provides some bit-wise operators that don't make sense for non-fixed size integers. Provides a few "format" operators that return a formatted IntStr; useful for display but also directly usable as an integer value.
  
  ## Methods
  
  Note that most of the method examples below show binary representations of the value. That's just for demonstration purposes. Returns decimal numbers by default. All of the method examples below assume an 8 bit fixedint.
  
  ### .new()
  
  Specify the number of bits. May be any positive integer. Defaults to 32 bit. Accepts :bit or :bits. Defaults to value of 0; will not accept a Nil value.
  
  ```
  my \fixedint = FixedInt.new(:8bit);
  
  # or
  
  my \fixedint = FixedInt.new(:bits(8));
  
  # or
  
  my \fixedint = FixedInt.new(bits => 8);
  
  ```
  
  ### .ror (Int $bits)
  
  Rotate right by the given number of bits (default 1)
  
  ```
  # before 00000011 (3)
  fixedint.=ror(1);
  # after 10000001  (129)
  
  ```
  
  ### .rol (Int $bits)
  
  Rotate left by the given number of bits (default 1)
  
  ```
  # before 10000001 (129)
  fixedint.=rol(3);
  # after 00001100 (12)
  
  ```
  
  ### .C1
  
  Ones complement. Every bit is negated.
  
  ```
  # before 00001100 (12)
  fixedint.=C1;
  # after 11110011  (243)
  
  ```
  
  ### .C2
  
  Twos complement. A "negated" integer.
  
  ```
  # before 00001100 (12)
  fixedint.=C2;
  # after 11110100 (244)
  
  ```
  
  ### .signed
  
  Treats the fixed size unsigned integer as a signed integer, returns negative numbers for FixedInts with a set most significant bit.
  
  ```
  say fixedint        # 244
  say fixedint.signed # -12
  
  ```
  
  ### .bin
  
  Returns a binary formatted IntStr;
  
  ```
  say fixedint     # 244
  say fixedint.bin # 0b11110100
  
  ```
  
  ### .oct
  
  Returns a octal formatted IntStr;
  
  ```
  say fixedint     # 244
  say fixedint.oct # 0o364
  
  ```
  
  ### .hex
  
  Returns a hex formatted IntStr;
  
  ```
  say fixedint     # 244
  say fixedint.hex # 0xF4
  
  ```
  
  # AUTHOR
  
  Steve Schulze (thundergnat)
  
  # COPYRIGHT AND LICENSE
  
  Copyright 2020 Steve Schulze
  
  This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.
  