Decoded: OpenTTD (2003) v1.8 (2018)
Source file: overflowsafe_type.hpp
Line-by-line code walkthrough by MaiZure

overflowsafe_type.hpp defines overflow-proof integer madness. This really only
means that the value will stick at the maximum or minimum value and not wrap

Original code:
https://github.com/MaiZure/OpenTTD-1.8/blob/master/src/core/overflowsafe_type.hpp





1     COMMENT (*)
2     BLANK (-)
3     *
4     *
5     *
6     *
7     *
8     *
9     -
10    *
11    -
12    Header guard
13    Header guard
14    -
15    Includes the OpenTTD math function header
16    -
17    *
18    *
19    *
20    *
21    *
22    *
23    *
24    *
25    Sets up a class template with three parameters: data type, a maximum integer
      value and a minimum integer value
26    Defines OverflowSafeInt class (hereby called OFSint)
27    BLOCK START - OverflowSafeInt, Integer-type that won't overflow.
28    Begin the private section of OverflowSafeInt
29    *
30    Declare the backend storage value that's not overflow safe
31    Begin the public section of OverflowSafeInt
32    Default constructor initializes the value to zero
33    -
34    Copy constructor initializes the value with the previous object's value
35    Parameterized constructor sets the value to the input value
36    -
37    Defines an overloaded assignment operator for input objects to match backend
      values
38    -
39    Defines an overloaded unary minus operator to return a new OFSint with
      a negated value.
40    -
41    *
42    *
43    *
44    *
45    *
46    *
47    Defines an overloads the add assignment operator 
48    BLOCK START - OverflowSafeInt += operator overload
49    If the space remaining is less than the space to add...
50    ...and the source values have matching signs...
51    Then an overflow occurred so check sign and peg value to MIN/MAX
52    Otherwise no overflow occurred...
53    Add the values normally
54    End check for overflow
55    Return a pointer to the updated object
56    BLOCK END - OverflowSafeInt += operator overload
57    -
58    *
59    Defines an overloaded addition operator with another OFSint
60    Defines an overloaded addition operator with a signed int
61    Defines an overloaded addition operator with an unsigned int
62    Defines an overloaded subtraction assignment operator with another OFSInt
63    Defines an overloaded subtraction operator with another OFSint
64    Defines an overloaded subtraction operator with a signed int
65    Defines an overloaded subtraction operator with an unsigned int
66    -
67    Defines an overloaded prefix increment operator
68    Defines an overloaded prefix decrement operator
69    Defines an overloaded postfix increment operator
70    Defines an overloaded postfix decrement operator
71    -
72    *
73    *
74    *
75    *
76    *
77    *
78    Defines an overloaded multiplication assignment operator
79    BLOCK START - OverflowSafeInt *= operator overload
80    If the operation would result in an overflow...
81    Check for matching signs of value and factor and clamp to MIN/MAX
82    Otherwise no overflow occurred
83    Perform normal multiplcation
84    End check for overload
85    Return the updated object
86    BLOCK END - OverflowSafeInt *= operator overload
87    -
88    *
89    Defines an overloaded mult operator for 64-bit signed factors
90    Defines an overloaded mult operator for 32-bit signed factors (platform
      specific!)
91    Defines an overloaded mult operator for 32-bit unsigned factors
92    Defines an overloaded mult operator for 16-bit unsigned factors
93    Defines an overloaded mult operator for 8-bit unsigned factors
94    -
95    *
96    Defines an overloaded division operator for 64-bit signed divisors
97    Defines an overloaded division operator for other OFSint instances
98    Defines an overloaded division operator for 32-bit signed divisors
99    Defines an overloaded division operator for 32-bit unsigned divisors
100   -
101   *
102   Defines an overloaded modulus assignment operator
103   Defines an overloaded modulus operator
104   -
105   *
106   Defines an overloaded left-shift assignment operator
107   Defines an overloaded left-shift operator
108   Defines an overloaded right-shift assignment operator
109   Defines an overloaded right-shift operator
110   -
111   *
112   Defines an overloaded equality operator against other OFSints
113   Defines an overloaded inequality operator against other OFSints
114   Defines an overloaded greater-than operator against other OFSints
115   Defines an overloaded greater-than or equal operator against other OFSints
116   Defines an overloaded less-than operator against other OFSints
117   Defines an overloaded less-than or equal operator against other OFSints
118   -
119   *
120   Defines an overloaded equality operator against a constant
121   Defines an overloaded inequality operator against a constant
122   Defines an overloaded greater-than operator against a constant
123   Defines an overloaded greater-than or equal operator against a constant
124   Defines an overloaded less-than operator against a constant
125   Defines an overloaded less-than or equal operator against a constant
126   -
127   Defines an overloaded cast operator to return the value
128   BLOCK END - OverflowSafeInt
129   -
130   *
131   Defines addition operator overloads for inverted operands of 64-bit OFSints
132   Defines subtraction operator overloads for inverted operands of 64-bit
      OFSints
133   Defines multiplication operator overloads for inverted operands of 64-bit
      OFSints
134   Defines division operator overloads for inverted operands of 64-bit OFSints
135   -
136   *
137   Defines addition operator overloads for inverted operands of 32-bit OFSints
138   Defines subtraction operator overloads for inverted operands of 32-bit
      OFSints
139   Defines multiplication operator overloads for inverted operands of 32-bit
      OFSints
140   Defines division operator overloads for inverted operands of 32-bit OFSints
141   -
142   *
143   Defines addition operator overloads for inverted operands of 32-bit unsigned
      OFSints
144   Defines subtraction operator overloads for inverted operands of 32-bit
      unsigned OFSints
145   Defines multiplication operator overloads for inverted operands of 32-bit
      unsigned OFSints
146   Defines division operator overloads for inverted operands of 32-bit unsigned
      OFSints
147   -
148   *
149   Defines addition operator overloads for inverted operands of 8-bit unsigned
      OFSints
150   Defines subtraction operator overloads for inverted operands of 8-bit
      unsigned OFSints
151   Defines multiplication operator overloads for inverted operands of 8-bit
      unsigned OFSints
152   Defines division operator overloads for inverted operands of 8-bit unsigned
      OFSints
153   -
154   Creates a typedef for 64-bit OFSints for ease of use
155   Creates a typedef for 32-bit OFSints for ease of use
156   -
157   Header guard end