1 % API
   2 
   3 # Builtins
   4 
   5 # Byte
   6 ## Byte.get_bit
   7 
   8 ```tomo
   9 Byte.get_bit : func(i: Byte, bit_index: Int -> Bool)
  10 ```
  11 
  12 In the binary representation of a byte, check whether a given bit index is set to 1 or not.
  13 
  14 The bit index must be between 1-8 or a runtime error will be produced.
  15 
  16 Argument | Type | Description | Default
  17 ---------|------|-------------|---------
  18 i | `Byte` | The byte whose bits are being inspected.  | -
  19 bit_index | `Int` | The index of the bit to check (1-indexed, range 1-8).  | -
  20 
  21 **Return:** Whether or not the given bit index is set to 1 in the byte.
  22 
  23 
  24 **Example:**
  25 ```tomo
  26 assert Byte(6).get_bit(1) == no
  27 assert Byte(6).get_bit(2) == yes
  28 assert Byte(6).get_bit(3) == yes
  29 assert Byte(6).get_bit(4) == no
  30 
  31 ```
  32 ## Byte.hex
  33 
  34 ```tomo
  35 Byte.hex : func(byte: Byte, uppercase: Bool = yes, prefix: Bool = no -> Text)
  36 ```
  37 
  38 Convert a byte to a hexidecimal text representation.
  39 
  40 Argument | Type | Description | Default
  41 ---------|------|-------------|---------
  42 byte | `Byte` | The byte to convert to hex.  | -
  43 uppercase | `Bool` | Whether or not to use uppercase hexidecimal letters.  | `yes`
  44 prefix | `Bool` | Whether or not to prepend a `0x` prefix.  | `no`
  45 
  46 **Return:** The byte as a hexidecimal text.
  47 
  48 
  49 **Example:**
  50 ```tomo
  51 assert Byte(18).hex(prefix=yes) == "0x12"
  52 
  53 ```
  54 ## Byte.is_between
  55 
  56 ```tomo
  57 Byte.is_between : func(x: Byte, low: Byte, high: Byte -> Bool)
  58 ```
  59 
  60 Determines if an integer is between two numbers (inclusive).
  61 
  62 Argument | Type | Description | Default
  63 ---------|------|-------------|---------
  64 x | `Byte` | The integer to be checked.  | -
  65 low | `Byte` | One end of the range to check (inclusive);  | -
  66 high | `Byte` | The other end of the range to check (inclusive);  | -
  67 
  68 **Return:** `yes` if `a <= x and x <= b` or `b <= x and x <= a`, otherwise `no`
  69 
  70 
  71 **Example:**
  72 ```tomo
  73 assert Byte(7).is_between(1, 10) == yes
  74 assert Byte(7).is_between(10, 1) == yes
  75 assert Byte(7).is_between(100, 200) == no
  76 assert Byte(7).is_between(1, 7) == yes
  77 
  78 ```
  79 ## Byte.parse
  80 
  81 ```tomo
  82 Byte.parse : func(text: Text, base: Int? = none, remainder: &Text? = none -> Byte?)
  83 ```
  84 
  85 Parse a byte literal from text.
  86 
  87 Argument | Type | Description | Default
  88 ---------|------|-------------|---------
  89 text | `Text` | The text to parse.  | -
  90 base | `Int?` | The numeric base to use when parsing the byte. If unspecified, the byte's base will be inferred from the text prefix. After any "+" or "-" sign, if the text begins with "0x", the base will be assumed to be 16, "0o" will assume base 8, "0b" will assume base 2, otherwise the base will be assumed to be 10.  | `none`
  91 remainder | `&Text?` | If non-none, this argument will be set to the remainder of the text after the matching part. If none, parsing will only succeed if the entire text matches.  | `none`
  92 
  93 **Return:** The byte parsed from the text, if successful, otherwise `none`.
  94 
  95 
  96 **Example:**
  97 ```tomo
  98 assert Byte.parse("5") == Byte(5)
  99 assert Byte.parse("asdf") == none
 100 assert Byte.parse("123xyz") == none
 101 
 102 remainder : Text
 103 assert Byte.parse("123xyz", remainder=&remainder) == Byte(123)
 104 assert remainder == "xyz"
 105 
 106 ```
 107 ## Byte.to
 108 
 109 ```tomo
 110 Byte.to : func(first: Byte, last: Byte, step: Int8? = none -> func(->Byte?))
 111 ```
 112 
 113 Returns an iterator function that iterates over the range of bytes specified.
 114 
 115 Argument | Type | Description | Default
 116 ---------|------|-------------|---------
 117 first | `Byte` | The starting value of the range.  | -
 118 last | `Byte` | The ending value of the range.  | -
 119 step | `Int8?` | An optional step size to use. If unspecified or `none`, the step will be inferred to be `+1` if `last >= first`, otherwise `-1`.  | `none`
 120 
 121 **Return:** An iterator function that returns each byte in the given range (inclusive).
 122 
 123 
 124 **Example:**
 125 ```tomo
 126 iter := Byte(2).to(4)
 127 assert iter() == Byte(2)
 128 assert iter() == Byte(3)
 129 assert iter() == Byte(4)
 130 assert iter() == none
 131 
 132 assert [x for x in Byte(2).to(5)] == [Byte(2), Byte(3), Byte(4), Byte(5)]
 133 assert [x for x in Byte(5).to(2)] == [Byte(5), Byte(4), Byte(3), Byte(2)]
 134 assert [x for x in Byte(2).to(5, step=2)] == [Byte(2), Byte(4)]
 135 
 136 ```