The prerequisites are modest. You should know how quicksort partitions around a pivot, what Big-O notation means, what logarithms are, and the basic idea of probability. You do not need a discrete mathematics course. When we use a tool that may be new, such as expected value, I will spell out what it means.

We will assume the array contains $n$ distinct values and that quicksort chooses its pivot uniformly at random from the current slice each time it partitions. If your implementation always chooses the first item as pivot, this is the same kind of analysis you get after randomly shuffling the input first.

Quicksort sorts by partitioning around a pivot: values smaller than the pivot go to one side, values larger than the pivot go to the other, and then quicksort recursively sorts the two sides. Almost all of the algorithmic work we care about here is in comparisons: each partition step compares values against the pivot. So we will count comparisons, averaged over all the random pivot choices.

The final answer will be that random-pivot quicksort makes

$$2(n+1)H_n-4n$$

comparisons on average, where

$$H_n=1+\frac{1}{2}+\frac{1}{3}+\cdots +\frac{1}{n}.$$

For large $n$, that is about

$$1.39n\lg n.$$

So the familiar $O(n\log n)$ average-case running time is not just a slogan. It comes from a precise count of the comparisons quicksort is likely to make.

Averaging a sum one pair at a time

The total number of comparisons is hard to track directly, because it depends on the whole sequence of pivots. Instead of trying to follow the whole run at once, we will look at one pair of values at a time.

Number the values by their place in sorted order. Let $z_1$ be the smallest value, $z_2$ the next smallest, and so on up to $z_n$, the largest. This numbering is not the array index during the algorithm. It is the value's rank in sorted order.

Take any two values, $z_i$ and $z_j$, with $i<j$. During one run of quicksort, this pair is either compared exactly once or never compared at all.

It cannot be compared more than once. Two values are compared only when one of them is the pivot in a partition step. Once a value is chosen as a pivot, it is placed in its final sorted position and is never used in another partition. So the same two values cannot meet again later as pivot and non-pivot.

Now define a small counter for this pair:

$$X_{ij}=\{\begin{array}{ll}1& \text{if }{z}_i\text{ and }{z}_j\text{ are compared},\\ 0& \text{otherwise.}\end{array}$$

The total number of comparisons in the whole run is the sum of these little counters over all pairs:

$$X=\sum _{i<j}{X}_{ij}.$$

For example, if $z_2$ and $z_6$ are compared, then $X_{2,6}$ contributes $1$ to the total. If they are not compared, it contributes $0$.

Now we average. The expected value of a random quantity is its long-run average: if you ran the same randomized algorithm many times and averaged the result, the average would approach the expected value. We write $E[X]$ for the expected value of $X$.

The key rule we need is that the expected value of a sum is the sum of the expected values:

$$E[X]=E\left[\sum _{i<j}{X}_{ij}\right]=\sum _{i<j}E[X_{ij}].$$

In words: to find the average total number of comparisons, we can add up the average contribution of each pair. This rule works even though the different pair counters are not independent.

Each $X_{ij}$ is only $0$ or $1$. Its average is therefore just the probability that it is $1$. If a pair is compared with probability $p$, then over many runs it contributes $1$ about a $p$ fraction of the time and $0$ the rest of the time, so its average contribution is $p$.

Therefore

$$E[X_{ij}]=\mathrm{Pr}[z_i\text{ and }{z}_j\text{ are compared}],$$

and the expected total number of comparisons is

$$E[X]=\sum _{i<j}\mathrm{Pr}[z_i\text{ and }{z}_j\text{ are compared}].$$

Now we need that probability.

When are two values compared?

Consider the values $1$ through $8$, already in sorted order, so $z_i=i$. Take the pair $2$ and $6$, and look at the block of values between them, ends included: $\{2,3,4,5,6\}$.

The key fact is this: $2$ and $6$ are compared if and only if the first pivot chosen from that block is either $2$ or $6$.

To see why, follow what happens as pivots are chosen. As long as no pivot comes from the block $\{2,3,4,5,6\}$, all five of those values stay together in one slice. A pivot from outside the block cannot separate them. A pivot of $1$ is smaller than all five, so they all go to its right. A pivot of $7$ or $8$ is larger than all five, so they all go to its left. Either way, the block stays whole.

So the first pivot that falls inside the block is the first one to touch these values, and there are three cases:

• The first such pivot is $2$. Then $2$ is compared against every value in its slice, and $6$ is still in that slice, so $2$ and $6$ are compared.
• The first such pivot is $6$. By the same reasoning, $6$ is compared against $2$.
• The first such pivot is a middle value, $3$, $4$, or $5$. Say it is $4$. Partitioning around $4$ sends $2$ and $3$ to its left and $5$ and $6$ to its right. Now $2$ and $6$ sit in different slices, and nothing ever brings them back together, so they are never compared. Each is compared against $4$, but not against each other.

So $2$ and $6$ are compared exactly when the first pivot from the block is one of the two ends, not one of the middle values.

The probability

The same reasoning works for any pair. The block between $z_i$ and $z_j$ is

$$\{z_i,z_{i+1},\dots ,z_j\}.$$

This block has

$$j-i+1$$

values: it starts at position $i$, ends at position $j$, and includes both ends.

The values in this block stay together until one of them is chosen as a pivot. Once the first pivot from this block is chosen, there are two possibilities:

• If the first pivot from the block is $z_i$ or $z_j$, then the pair is compared.
• If the first pivot from the block is one of the values strictly between them, then the pair is separated and is never compared.

Because pivots are chosen at random, the first value chosen from this block is equally likely to be any of the $j-i+1$ values in the block. One way to picture this is to imagine that the values in the block are waiting in a random order to become pivots. The one that appears first in that random order is equally likely to be any of them.

There are $j-i+1$ possible first pivots from the block. Exactly two of them, $z_i$ and $z_j$, make the pair get compared. Therefore

$$\mathrm{Pr}[z_i\text{ and }{z}_j\text{ are compared}]=\frac{2}{j-i+1}.$$

The closer two values are in sorted order, the more likely they are compared. Neighbors, where $j=i+1$, have a block of two and are compared with probability $2/2=1$, always. The smallest and largest values have a block of $n$ and are compared with probability only $2/n$.

Adding it up

Now put that probability into the expected-value sum:

$$E[X]=\sum _{i<j}\frac{2}{j-i+1}.$$

We could add this by looping over all choices of $i$ and $j$, but it is cleaner to group pairs by how far apart they are in sorted order.

Let

$$d=j-i.$$

This $d$ is the gap between the two values. If $d=1$, the values are neighbors in sorted order. If $d=2$, there is one value between them. In general, a gap of $d$ means the block from $z_i$ to $z_j$ has $d+1$ values, so each such pair is compared with probability

$$\frac{2}{d+1}.$$

How many pairs have gap $d$? The smaller value can be $z_1,z_2,\dots ,z_{n-d}$. After that, the larger value is forced: it must be $d$ positions later. So there are $n-d$ pairs with gap $d$.

Therefore

$$E[X]=\sum _{d=1}^{n-1}(n-d)\frac{2}{d+1}.$$

This formula is already the exact average number of comparisons. Now we simplify it.

Set $k=d+1$. When $d=1$, $k=2$. When $d=n-1$, $k=n$. Also, since $d=k-1$,

$$n-d=n-(k-1)=n+1-k.$$

So the sum becomes

$$E[X]=2\sum _{k=2}^n\frac{n+1-k}{k}.$$

Split the fraction:

$$\frac{n+1-k}{k}=\frac{n+1}{k}-1.$$

Then

$$E[X]=2\sum _{k=2}^n\left(\frac{n+1}{k}-1\right).$$

There are two pieces here:

$$\sum _{k=2}^n\frac{n+1}{k}=(n+1)\left(\frac{1}{2}+\frac{1}{3}+\cdots +\frac{1}{n}\right),$$

and

$$\sum _{k=2}^{n}1=n-1.$$

Therefore

$$E[X]=2\left((n+1)\left(\frac{1}{2}+\frac{1}{3}+\cdots +\frac{1}{n}\right)-(n-1)\right).$$

The sum

$$1+\frac{1}{2}+\frac{1}{3}+\cdots +\frac{1}{n}$$

is called the $n$th harmonic number and is written $H_n$. Since

$$\frac{1}{2}+\frac{1}{3}+\cdots +\frac{1}{n}=H_n-1,$$

we get

$$E[X]=2\left((n+1)(H_n-1)-(n-1)\right).$$

Expanding the expression gives the standard exact formula:

$$E[X]=2(n+1)H_n-4n.$$

That is the average number of comparisons made by random-pivot quicksort on $n$ distinct values.

Why this is O(n log n)

The exact formula contains $H_n$, so we need to know how fast $H_n$ grows.

The harmonic number

$$H_n=1+\frac{1}{2}+\frac{1}{3}+\cdots +\frac{1}{n}$$

grows like $\ln n$. Intuitively, this sum is a discrete version of the area under the curve $1/x$. The area under $1/x$ from $1$ to $n$ is $\ln n$, so the sum $1+1/2+\cdots +1/n$ grows at the same logarithmic rate.

That means

$$H_n=O(\log n).$$

So from the exact formula,

$$E[X]=2(n+1)H_n-4n,$$

the main term grows like $n\log n$. The $-4n$ part is only linear, and the $2(n+1)$ factor in front of $H_n$ is proportional to $n$. Therefore the expected number of comparisons is

$$O(n\log n).$$

This is the formal version of the intuition from the course notes: random pivots tend to produce enough reasonably balanced splitting that the average cost is logarithmic levels of partitioning, with about $n$ comparison work per level.

The leading constant

The exact formula also tells us the leading constant. Since $H_n$ grows like $\ln n$, the dominant part of

$$2(n+1)H_n-4n$$

is

$$2n\ln n.$$

Computer science usually writes sorting lower bounds and comparison counts with base-two logarithms. Since

$$\ln n=(\ln 2)(\lg n),$$

we get

$$2n\ln n=2\ln 2\cdot n\lg n.$$

And because

$$2\ln 2\approx 1.386,$$

random-pivot quicksort makes about

$$1.39n\lg n$$

comparisons on average, ignoring lower-order terms.

No comparison sort can average fewer than about $n\lg n$ comparisons in the leading term, so quicksort's random-pivot average is only about forty percent above that floor. That is the precise sense in which quicksort is fast on average, and it stands well clear of the $O(n^2)$ behavior that bad pivot choices can produce.

The prerequisites are modest. You should know what a hash table is, what a hash collision is, and what the remainder operation does. You should also be comfortable with binary numbers at the level of "multiplying by 2 shifts bits left." You do not need a discrete mathematics course. When we use words such as factor, prime, or relatively prime, I will explain them.

A hash table stores a value under a key by turning the key into an array index. For string keys, one common way to get that index is to fold the string down into a single integer, then reduce that integer to a slot.

The fold reads the characters one at a time. Each character has a numeric code ('A' is 65 in the usual encoding, 'B' is 66, and so on up the alphabet). Keep a running integer h, start it at 0, and for each character multiply h by a fixed number, the base, and add the character's code:

int h = 0;
for (int i = 0; i < s.length(); i++) {
  h = base * h + s.charAt(i);
}

At the end, h is the string's hash code. To turn it into a slot in an array of capacity slots, reduce it modulo capacity. Mathematically, that means choosing a number from 0 through capacity - 1 with the same remainder as h. In Java, % can be negative when h is negative, so real code has to correct for that or use a power-of-two mask. The mathematical idea is still "use the remainder to choose a slot."

This hash is called a polynomial hash because, if you expand the loop, the characters are weighted by powers of the base. For a three-character string with codes $c_1$, $c_2$, and $c_3$, the loop computes

$$((c_1)b+c_2)b+c_3=c_1{b}^2+c_{2}b+c_3,$$

where $b$ is the base.

The base can be any number bigger than 1. With a base of 1, multiplying does nothing, so the fold just adds the character codes. Then every rearrangement of the same characters gets the same hash, which is terrible for strings.

But not every base above 1 is a good choice. The most important practical rule is that the base should be odd. A second rule is that the base should avoid sharing factors with the table size; choosing a prime base is a common way to help with that, but it is not a magic requirement. We will look at both rules.

Why the base should be odd

Start with what multiplying does to the bits of h. Multiplying a binary number by 2 shifts every bit one place to the left and puts a 0 in the rightmost place. This is like multiplying a decimal number by 10: the digits shift left and a 0 appears at the end.

Multiplying by 4 shifts two places left and puts two 0s at the bottom. More generally, multiplying by an even number always puts a 0 in the lowest bit of the product, because every even number has a factor of 2.

That matters because many hash tables use a power-of-two capacity. If the table has 4 slots, the slot is determined by the last two bits of the hash. If the table has 8 slots, the slot is determined by the last three bits. In general, reducing modulo $2^k$ keeps only the lowest $k$ bits.

Take a base of 4 and a table of 4 slots. To keep the arithmetic short, use small character codes: A is 1, B is 2, and X is 3. Hash the two strings "AB" and "XB", which differ only in their first letter:

base 4:
 "AB":  h = 0; 4*0 + 1 = 1;  4*1 + 2 = 6    ->  6  mod 4 = 2
 "XB":  h = 0; 4*0 + 3 = 3;  4*3 + 2 = 14   ->  14 mod 4 = 2

Both land in slot 2. In fact, with base 4 and capacity 4, every two-character string that ends in B lands in slot 2, no matter what the first character is. The reason is that multiplying the first character by 4 makes it a multiple of 4, and multiples of 4 leave remainder 0 when divided by 4. So the first character disappears from the slot calculation.

The same problem happens more generally with even bases and power-of-two capacities. The repeated multiplications push earlier characters out of the low bits, and the low bits are exactly what a power-of-two table reads.

Now change the base to 5, an odd number, and keep everything else the same:

base 5:
 "AB":  h = 0; 5*0 + 1 = 1;  5*1 + 2 = 7    ->  7  mod 4 = 3
 "XB":  h = 0; 5*0 + 3 = 3;  5*3 + 2 = 17   ->  17 mod 4 = 1

The two strings land in different slots, 3 and 1. Since 5 mod 4 is the same as 1 mod 4, the first character still affects the final remainder.

That is the reason for the odd rule. An even base loses information in the low bits, especially when the table size is a power of two. An odd base does not automatically make the hash good, but it avoids this particular failure: earlier characters can still influence the low bits that choose the slot.

Why shared factors are dangerous

An odd base fixes the low-bit problem, but on its own it is not enough. A base can be odd and still line up badly with the table size.

A factor of a number is a number that divides it evenly. For example, 5 is a factor of 10. Two numbers are relatively prime if they share no factor bigger than 1. For example, 3 and 10 are relatively prime, but 5 and 10 are not.

The trouble appears when the base and the capacity share a factor. Take a table of 10 slots and a base of 5. Five is odd, but it shares the factor 5 with 10.

Hash a two-letter string with character codes $c_1$ and $c_2$. The hash is

$$5c_1+c_2,$$

and the slot is

$$(5c_1+c_2)\mathrm{mod}10.$$

Focus on the first character's contribution:

$$5c_1\mathrm{mod}10.$$

If $c_1$ is even, $5c_1$ is a multiple of 10, so the contribution is 0. If $c_1$ is odd, $5c_1$ leaves remainder 5. Those are the only two possibilities. So the first character can shift the slot by only 0 or 5; it cannot help spread keys across all ten slots.

Change the base to 3, which shares no factor with 10. Now

$$3c_1\mathrm{mod}10$$

runs through

3, 6, 9, 2, 5, 8, 1, 4, 7, 0

as $c_1$ runs from 1 through 10. It reaches every possible remainder. The first character can now move the hash anywhere in the table.

That is the real rule: the base should not share factors with the capacity. If the base and capacity are relatively prime, multiplication by the base does not trap a character's contribution inside a smaller set of slots. If they share a factor, some contributions get trapped.

So does the base need to be prime?

A prime number is a number greater than 1 whose only positive factors are 1 and itself. Examples are 3, 5, 31, and 16777619. Composite numbers, such as 4, 10, and 33, have additional factors.

Choosing a prime base is a useful habit because a prime has very few factors. A prime base can share a factor with the capacity only when the capacity is a multiple of that prime. That is less likely than with a composite base.

But "prime" is not the exact requirement. The exact requirement is about the relationship between the base and the table size.

If the capacity is a power of two, then every odd base is relatively prime to the capacity. In that setting, 31, 33, and 37 all avoid the shared-factor problem because none of them has a factor of 2. This is one reason DJB2 can use 33 even though 33 is not prime.

If the capacity is a prime number, then almost any smaller base is relatively prime to it. The base itself does not need to be prime; it just needs not to be a multiple of the capacity.

So the careful version is:

• The base should be odd, especially for power-of-two table sizes.
• The base should be relatively prime to the table sizes you use.
• Choosing a prime base is a common way to reduce shared-factor problems, but it is a heuristic, not a proof that the hash is best.

The bases real hashes use

Java's String.hashCode() uses a base of 31:

h = 31 * h + c;

The number 31 has several useful properties. It is odd, so it avoids the low-bit failure. It is prime, so it has very few shared-factor risks. It is also one less than 32, and 32 is $2^5$, so

$$31h=32h-h=(h\ll 5)-h.$$

That means a multiply by 31 can be implemented as a left shift by five bits followed by a subtraction. This mattered more on older processors, where a general multiplication was relatively expensive, but the tradition remains.

For a long string, the running value grows past what a 32-bit int can hold and wraps around, sometimes becoming negative. Java integer arithmetic is deterministic, so the same string still gets the same hash code every time. The hash code is not meant to preserve the original number; it is meant to produce a repeatable, well-spread integer.

DJB2, by Dan Bernstein, uses a base of 33 and usually starts h at 5381 instead of 0. The base 33 is odd, but it is not prime:

$$33=3\cdot 11.$$

It is still popular because it is fast and has tested well on many ordinary string sets:

$$33h=32h+h=(h\ll 5)+h.$$

This is a useful reminder that "prime" is not an absolute law. DJB2 follows the odd rule and performs well in practice despite using a composite base.

FNV-1a is another well-known string and byte hash. In its 32-bit version, it starts from the offset basis 2166136261; for each byte, it XORs the byte into the hash and then multiplies by the FNV prime 16777619:

h = h xor byte
h = h * 16777619

Here the multiplier is odd and prime, and it was chosen for good bit behavior under repeated multiplication and XOR.

The specific numbers 31, 33, 5381, 16777619, and 2166136261 do not fall out of one simple formula. They come from a mix of arithmetic properties, speed, and testing on real data. A hash constant survives because it spreads typical keys well, not because one theorem declares it perfect.

A note on the table size

The base and the table size interact, so one more point is worth making.

If the capacity is a power of two, reducing modulo the capacity keeps only the low bits of h. Dividing by $2^k$ leaves the last $k$ bits. This is fast because it can be done with a bit mask instead of a division. The cost is that all the responsibility falls on the low bits. An even base is especially bad here because it repeatedly clears or weakens those low bits.

If the capacity is prime, the modulo operation depends on more of the whole integer instead of only the lowest bits. That can forgive some weaker low-bit behavior, but division by an arbitrary prime is usually slower than a bit mask.

Java's HashMap takes the first road. It uses power-of-two capacities for speed, then applies an extra spreading step to the key's hash code so that some high-bit information is mixed down into the low bits before the slot is chosen.

So the practical answer is:

• Use an odd base.
• Avoid sharing factors with the table sizes you use.
• Treat prime bases as a good tradition, not a magic shield.
• Trust testing over numerology when choosing exact constants.

That is why 31, 33, and large FNV primes can all make sense in their own contexts. The base is not good by itself; it is good because it works well with the update rule, the table size, the slot calculation, and the kinds of keys you expect to store.

The prerequisites are modest. You should know what a hash table slot is, what a collision is, and what it means for a hash function to spread keys evenly. You should also be comfortable with fractions, percentages, and the basic idea of probability. You do not need a discrete mathematics course. When we use notation such as $\left(\genfrac{}{}{0ex}{}{n}{2}\right)$ or expected value, I will explain what it means.

We will use a simplified model called uniform hashing. The table has $m$ slots, numbered $0$ through $m-1$, and each key is equally likely to land in any one of those slots. Real hash functions are not perfectly random, but this model is the right starting point: it tells us what happens when the hash function is doing its job well.

A collision happens when two different keys receive the same slot number. You might expect collisions to become likely only when the table is close to full, with nearly $m$ keys competing for $m$ slots. They start much sooner than that. A table with thousands of empty slots can already be likely to contain at least one collision.

A warm-up: shared birthdays

Set hash tables aside for a moment and think about birthdays. There are 365 possible birthdays, ignoring leap years. Put some people in a room and ask whether two of them share a birthday. How many people do you need before a shared birthday is more likely than not?

The common guess is around 180, about half of 365. The real answer is 23. With 23 people, the chance that two of them share a birthday is already about 51%. With 50 people, it is about 97%. Shared birthdays appear far sooner than intuition expects, and this is known as the birthday paradox.

The reason is that a shared birthday is not about one particular pair of people. It is about any pair among all of them.

With 23 people, there are 253 different pairs of people. The notation for this is

$$\left(\genfrac{}{}{0ex}{}{23}{2}\right)=253.$$

The symbol $\left(\genfrac{}{}{0ex}{}{n}{2}\right)$ means "the number of ways to choose 2 things from $n$ things." In this setting, it counts pairs. The formula is

$$\left(\genfrac{}{}{0ex}{}{n}{2}\right)=\frac{n(n-1)}{2}.$$

Why divide by 2? Because $A$ paired with $B$ and $B$ paired with $A$ are the same pair. The product $n(n-1)$ counts both orders, so we divide by 2 to remove the duplicate counting.

With 23 people, every one of the 253 pairs is a chance for a birthday match. That is a lot of chances, and they add up quickly.

Hashing is the same situation with different labels. The people are the keys, and the 365 birthdays are the $m$ slots. Two people sharing a birthday is two keys sharing a slot, which is a collision. So the birthday paradox tells us that collisions appear far sooner than the table filling up would suggest.

Counting the chance of no collision

Here is the calculation behind that number 23, and it works for any number of slots.

Place keys into $m$ slots one at a time, and assume each key is equally likely to land in any slot. Follow the probability that no collision has happened yet, meaning every key so far sits in a slot of its own.

• The first key lands in some slot. There is nothing to collide with, so this step is certain. Its probability is $1$.
• The second key collides only if it hits the one occupied slot. It avoids that slot with probability $1-\frac{1}{m}$.
• The third key must avoid the two occupied slots, which happens with probability $1-\frac{2}{m}$.
• In general, the $i$-th key must avoid the $i-1$ slots already taken, with probability $1-\frac{i-1}{m}$.

For all $k$ keys to land in separate slots, every one of these steps has to succeed. We multiply the probabilities because each line is asking for the next key to avoid the slots already occupied, assuming all previous keys have avoided collisions.

So the exact probability of no collision among $k$ keys is

$$P(\text{no collision})=\left(1-\frac{1}{m}\right)\left(1-\frac{2}{m}\right)\cdots \left(1-\frac{k-1}{m}\right).$$

The first key's probability of $1$ is not written because multiplying by $1$ does not change the product.

The chance of at least one collision is whatever is left:

$$P(\text{collision})=1-P(\text{no collision}).$$

Each factor is a little less than $1$, and multiplying many numbers that are each a little less than $1$ pulls the product down quickly. That is why the no-collision probability drops so fast as $k$ grows.

If $k>m$, then a collision is guaranteed: there are more keys than slots. The surprising part is what happens much earlier, when $k$ is still much smaller than $m$.

Putting numbers in

With $m=365$, the product gives these chances of a collision for a few values of $k$:

By 23 keys, the odds have already crossed one half. At least 342 of the 365 possible birthdays are still unused, and possibly more if a collision has already happened. The table is only about 6% full, yet a collision is already about as likely as not.

The square-root rule

There is a useful shortcut for where the halfway point lands, and it works for any $m$.

The exact no-collision probability is

$$\left(1-\frac{1}{m}\right)\left(1-\frac{2}{m}\right)\cdots \left(1-\frac{k-1}{m}\right).$$

When $i$ is small compared with $m$, the number $i/m$ is small, and

$$1-\frac{i}{m}$$

is close to

$$e^{-i/m}.$$

This is a standard approximation: for small $x$, $1-x$ is close to $e^{-x}$. You do not need the proof here; the point is that it turns a product into something easier to simplify.

Using that approximation,

$$P(\text{no collision})\approx e^{-(1+2+\cdots +(k-1))/m}=e^{-k(k-1)/(2m)}.$$

The exponent contains

$$1+2+\cdots +(k-1).$$

That sum is

$$\frac{k(k-1)}{2}.$$

One way to remember this formula is to use "number of terms times average term." There are $k-1$ terms, from $1$ through $k-1$. Their average is halfway between the first and last term:

$$\frac{1+(k-1)}{2}=\frac{k}{2}.$$

So the sum is

$$(k-1)\frac{k}{2}=\frac{k(k-1)}{2}.$$

Now ask when a collision becomes about as likely as not. That happens when the no-collision probability is about $1/2$:

$$e^{-k(k-1)/(2m)}\approx \frac{1}{2}.$$

Take natural logs of both sides:

$$-\frac{k(k-1)}{2m}\approx \ln \left(\frac{1}{2}\right).$$

Since $\ln (1/2)=-\ln 2$, this becomes

$$\frac{k(k-1)}{2m}\approx \ln 2.$$

So

$$k(k-1)\approx 2m\ln 2.$$

For large $k$, $k(k-1)$ is close to $k^2$, so

$$k\approx \sqrt{2m\ln 2}.$$

Because $\sqrt{2\ln 2}\approx 1.18$, this is often written as

$$k\approx 1.2\sqrt{m}.$$

That is the square-root rule: a collision becomes likely after roughly $\sqrt{m}$ keys, not $m$ keys. For $m=365$, this gives

$$1.2\sqrt{365}\approx 23,$$

which matches the birthday table. For a table with one million slots, the halfway point is only about

$$1.2\sqrt{1,000,000}=1200$$

keys.

Load factor and keeping collisions rare

The birthday calculation explains when the first collision becomes likely. Hash table performance is a slightly different question. A real hash table does not need zero collisions. It needs collisions to stay controlled.

To see what "controlled" means, count colliding pairs. Among $n$ keys, there are

$$\left(\genfrac{}{}{0ex}{}{n}{2}\right)=\frac{n(n-1)}{2}$$

pairs of keys. For any one pair, the probability that both keys land in the same slot is $1/m$.

The expected value of a random quantity is its long-run average: if you built many hash tables under the same assumptions and averaged the number of colliding pairs, that average would approach the expected value. Since each pair has probability $1/m$ of colliding, adding those probabilities over all pairs gives the expected number of colliding pairs:

$$\frac{n(n-1)}{2m}\approx \frac{n^2}{2m}.$$

This number grows quickly if $m$ is fixed and $n$ keeps increasing. But hash tables do not keep $m$ fixed forever. They grow the array as more keys are inserted.

The quantity that controls the average crowding is the ratio of keys to slots, called the load factor:

$$\alpha =\frac{n}{m}.$$

The load factor is the average number of keys per slot. If $\alpha$ is a small constant, each slot holds only a constant number of keys on average. In a chaining hash table, that means a lookup goes to one slot and checks a short list on average. In an open-addressing hash table, the details are different, but the same principle remains: performance depends strongly on keeping the table from becoming too crowded.

If $\alpha$ is allowed to grow with $n$, slots get crowded and lookups slow down. If $\alpha$ is kept below a fixed bound, such as $0.75$, the average amount of crowding stays bounded. That is what supports average-case $O(1)$ lookup under the uniform hashing assumption.

So a hash table watches its load factor. When $n$ grows and $\alpha$ passes the chosen bound, the table allocates a larger array and re-inserts every key, which drops $\alpha$ back down.

This does not mean the total number of collisions in a large table is constant. If the table stores many keys, there may be many colliding pairs overall. The important point is local: the average amount of work per operation stays small because each key only has to deal with a bounded amount of crowding on average.

What this means for a hash table

Collisions are not a rare accident to be handled as an afterthought. The birthday paradox shows that the first collision appears while the table is still mostly empty. The pair count shows why crowding grows quickly if the table size is fixed. Load factor explains why resizing works: as the number of keys grows, the table grows too, keeping the average crowding per slot under control.

A working hash table needs both pieces. It needs a way to resolve collisions when they happen, and it needs a resizing rule that keeps the load factor bounded. Neither one alone is enough.

In the previous post, I set up the database module: a connect() function that opens a SQLite file and an init_db() function that creates the papers table. The module could create the table, but it could not yet do anything with it.

In this post, I want to add the first real database operations: inserting a paper record and reading it back. I am still going to pass the fingerprint in by hand, like I did before. Computing a real fingerprint from a PDF is its own topic, and I want to get the read-and-write path working first.

There is one decision in this post that is more interesting than it looks, and it is the reason I am doing insert before anything else: what should happen when I add the same paper twice?

Adding a paper

Let's start with the insert. Add this function to src/literature_vault/db.py:

def add_paper(
    connection: sqlite3.Connection,
    fingerprint: str,
    path: str,
    title: str | None = None,
    year: int | None = None,
) -> bool:
    cursor = connection.execute(
        """
        INSERT INTO papers (fingerprint, path, title, year)
        VALUES (:fingerprint, :path, :title, :year)
        ON CONFLICT (fingerprint) DO NOTHING
        """,
        {
            "fingerprint": fingerprint,
            "path": path,
            "title": title,
            "year": year,
        },
    )
    connection.commit()
    return cursor.rowcount == 1

The function takes the connection and the fields for one paper. The title and year are optional, because there will be papers where I do not have that metadata yet. It runs an INSERT, commits, and returns a boolean.

A couple of things here are worth slowing down on.

The first is how I pass the values. Instead of putting the data directly into the SQL string, I use named placeholders like :fingerprint and hand the actual values in a separate dictionary. SQLite fills them in for me. This is the standard way to avoid SQL injection, and it also means I do not have to worry about quoting strings or escaping characters myself. The same idea works with ? placeholders and a tuple, but I find the named version easier to read once there are more than two or three columns.

The second is the ON CONFLICT (fingerprint) DO NOTHING clause, which is the heart of this post.

What happens when I add the same paper twice

Back in the overview, I said I wanted lv add to be idempotent: if I add the same paper twice, the system should notice it has seen it before and skip it. The papers table already has the piece that makes this possible, which is the UNIQUE constraint on fingerprint. SQLite will not let me store two rows with the same fingerprint.

The question is what happens when I try anyway. By default, SQLite treats it as an error and raises an exception. That is not what I want for ingestion. Adding a paper I already have is a normal thing to do, not a failure.

So I have a few options:

• Catch the exception. Let the INSERT fail and wrap it in a try/except for sqlite3.IntegrityError. This works, but it uses an exception for something that is not really an error, and it makes the normal "already seen" path go through error handling.
• Use INSERT OR IGNORE. This tells SQLite to silently skip the row on any constraint violation. It is short, but it is also blunt: it ignores every constraint, so if I later add a constraint I actually want to hear about, this would swallow it too.
• Use ON CONFLICT (fingerprint) DO NOTHING. This says exactly which conflict I am choosing to ignore. If a row with this fingerprint already exists, do nothing. Any other problem still raises.

I went with the last one. It is the most explicit: anyone reading the function can see that the duplicate-fingerprint case is handled on purpose, and that nothing else is being quietly swallowed.

That leaves one loose end. If the insert quietly does nothing on a duplicate, how does the caller know whether the paper was new or already there? That is what the return value is for. After the statement runs, cursor.rowcount tells me how many rows were actually inserted: 1 if it was new, 0 if the conflict skipped it. So add_paper returns True when it added a new paper and False when the paper was already in the vault. Later, the add command can use that to print "added" or "already in vault" without doing a separate lookup first.

Reading a paper back

I also want to read a paper back out, so I can confirm it is really there and so the rest of the app has a way to look one up. Add this function next:

def get_paper(
    connection: sqlite3.Connection, fingerprint: str
) -> sqlite3.Row | None:
    return connection.execute(
        """
        SELECT id, fingerprint, path, title, year, created_at
        FROM papers
        WHERE fingerprint = :fingerprint
        """,
        {"fingerprint": fingerprint},
    ).fetchone()

This looks a paper up by its fingerprint and returns the row, or None if there is no match. The fetchone() call returns the first matching row, and since fingerprint is unique there is at most one. Because I set row_factory = sqlite3.Row back in connect(), the row I get back lets me read columns by name, so the caller can write paper["title"] instead of counting column positions.

Returning None when the paper is not found keeps the function simple. The caller decides what a missing paper means, which is usually different in different places: a lookup might want to print an error, while an "is this already here?" check just wants the absence.

Testing it

Now I can test the two functions together, since reading back is how I check that writing worked. Add these to src/tests/test_db.py.

First, the basic round trip: add a paper, read it back, and check the fields survived.

def test_add_paper_inserts_and_reads_back(tmp_path: Path) -> None:
    db_path = tmp_path / "vault.db"
    connection = connect(db_path)

    try:
        init_db(connection)

        is_new = add_paper(
            connection,
            fingerprint="abc123",
            path="/papers/attention.pdf",
            title="Attention Is All You Need",
            year=2017,
        )

        assert is_new is True

        paper = get_paper(connection, "abc123")

        assert paper is not None
        assert paper["fingerprint"] == "abc123"
        assert paper["path"] == "/papers/attention.pdf"
        assert paper["title"] == "Attention Is All You Need"
        assert paper["year"] == 2017
    finally:
        connection.close()

This uses the same tmp_path fixture as the previous post, so each test gets its own throwaway database file. It adds one paper, checks that add_paper reported it as new, then reads it back and checks every field.

The next test is the one I actually care about: adding the same fingerprint twice.

def test_add_paper_is_idempotent(tmp_path: Path) -> None:
    db_path = tmp_path / "vault.db"
    connection = connect(db_path)

    try:
        init_db(connection)

        first = add_paper(
            connection,
            fingerprint="abc123",
            path="/papers/attention.pdf",
            title="Attention Is All You Need",
            year=2017,
        )
        second = add_paper(
            connection,
            fingerprint="abc123",
            path="/papers/moved.pdf",
            title="A Different Title",
            year=2020,
        )

        assert first is True
        assert second is False

        # The second add was ignored, so the original row is untouched.
        paper = get_paper(connection, "abc123")

        assert paper is not None
        assert paper["path"] == "/papers/attention.pdf"
        assert paper["title"] == "Attention Is All You Need"
        assert paper["year"] == 2017
    finally:
        connection.close()

The second add uses the same fingerprint but different values for everything else. Two things should be true. The first add returns True and the second returns False, so the function correctly reports that it had seen the paper before. And the row in the database still has the original values, not the second set. That second part matters: DO NOTHING means exactly that. It does not update the existing row with the new values, it leaves it alone. If I ever want adding a known paper to update its metadata, that would be a different choice (DO UPDATE), and I would make it on purpose.

The last test covers the miss: looking up a fingerprint that was never added.

def test_get_paper_returns_none_when_missing(tmp_path: Path) -> None:
    db_path = tmp_path / "vault.db"
    connection = connect(db_path)

    try:
        init_db(connection)

        assert get_paper(connection, "does-not-exist") is None
    finally:
        connection.close()

Run the tests:

uv run pytest

The tests from the earlier posts should still pass, and now there are three new ones for the database operations.

9 passed

This is another small step, but the database can now do the two things it could not do at the end of the last post: store a paper and find it again. And it does it in a way that already matches the idempotent behavior I want from lv add, before there is an lv add to speak of.

I have still been passing the fingerprint and path in by hand, and these functions still live only in the database layer. Nothing in the CLI or the MCP server touches them yet. In the next post, I will wire these operations up through the core layer and expose the first real command, so that adding and listing papers works from the terminal the way greet does now.

In the previous post, I set up the basic dependencies for Literature Vault. In this post, I want to do the same thing for the database.

The goal is not to build the full storage layer yet. I am not going to parse PDFs, extract metadata, create a full-text index, or store embeddings in this post. For now, I just want to make sure the app can create a local SQLite database, write a paper record to it, and read that record back through the same kind of clean application boundary I used for the CLI and MCP examples.

I already decided in the project overview that Literature Vault should use SQLite. Python has built-in support for SQLite; it has a standard library module called sqlite3. That is enough for a simple database, and it is the right choice for a local application that does not need to scale to multiple users or servers.

sqlite3 requires no extra installation, but it is also a very low-level interface. We would have to write SQL statements by hand, and we would have to manage the database connection and transactions ourselves. I'm fine with that!

Creating the Database Module

The first thing I want is a small database module. Not the whole storage layer, just enough structure so the rest of the app does not have to know where the database lives or how the tables are created.

Create a new file called src/literature_vault/db.py:

from pathlib import Path
import sqlite3


def connect(db_path: Path) -> sqlite3.Connection:
    connection = sqlite3.connect(db_path)
    connection.row_factory = sqlite3.Row
    return connection


def init_db(connection: sqlite3.Connection) -> None:
    connection.execute(
        """
        CREATE TABLE IF NOT EXISTS papers (
            id INTEGER PRIMARY KEY,
            fingerprint TEXT NOT NULL UNIQUE,
            path TEXT NOT NULL,
            title TEXT,
            year INTEGER,
            created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
        )
        """
    )
    connection.commit()

Let's walk through this code.

• The import statements are straightforward. I need Path to work with file paths, and I need sqlite3 to interact with the database.

• The connect() function takes a Path to the database file and returns a sqlite3.Connection object. This function is responsible for opening the connection to the database. It also sets the row_factory to sqlite3.Row, which allows us to access columns by name instead of by index (see the discussion below).

• The init_db() function takes a sqlite3.Connection and creates the necessary tables if they do not already exist. In this case, it creates a papers table with the specified columns.

There are two small choices here that are worth pointing out.

First, connect() takes a Path instead of hard-coding a database location. This keeps the function easy to test, because tests can create a temporary database file and throw it away afterward. Later, the CLI can decide where the real database should live.

Second, I set connection.row_factory = sqlite3.Row. By default, SQLite rows come back as tuples, so you have to access values by position. With sqlite3.Row, the rows still behave like lightweight row objects, but I can access columns by name: so you can write row["title"] instead of row[3].

The string passed to execute() in init_db() is a SQL statement. It creates a table called papers with the following columns:

• fingerprint, a unique identifier for the paper
• path, the location of the PDF on disk
• title, if I know it
• year, if I know it
• created_at, when the row was created

The fingerprint is the important part. Eventually, this will be a hash of the PDF contents. In this post, I am going to pass it in manually so I can focus on the database layer. The UNIQUE constraint means SQLite will not allow the same fingerprint to be inserted twice, which is exactly what I want for idempotent ingestion later.

Before adding more application code, I want to test this module. We already have a test setup from the previous post, so the next step is to add a database test file.

Create src/tests/test_db.py:

from pathlib import Path
from literature_vault.db import connect, init_db


def test_init_db_creates_papers_table(tmp_path: Path) -> None:
    db_path = tmp_path / "vault.db"
    connection = connect(db_path)

    try:
        init_db(connection)

        row = connection.execute(
            """
            SELECT name
            FROM sqlite_master
            WHERE type = 'table' AND name = 'papers'
            """
        ).fetchone()

        assert row is not None
        assert row["name"] == "papers"
    finally:
        connection.close()


def test_connect_returns_rows_with_named_columns(tmp_path: Path) -> None:
    db_path = tmp_path / "vault.db"
    connection = connect(db_path)

    try:
        row = connection.execute("SELECT 'hello' AS message").fetchone()

        assert row["message"] == "hello"
    finally:
        connection.close()

These tests do not insert papers yet. They only check the behavior of the database module as it exists right now:

• connect() opens a SQLite database and returns rows that can be accessed by column name
• init_db() creates the papers table

Run the tests:

uv run pytest

The existing tests should still pass, and now there should be two new database tests as well.

This is a small step, but it gives me a useful boundary: the database module can create the first table, and the tests can verify that without touching the CLI or MCP layer yet.

I will stop here for this post. In the next one, I will add the first actual database operation: inserting a paper record and reading it back.

In this post, I will set up the basic dependencies of Literature Vault and create a simple "Hello World" example to demonstrate that the dependencies are working correctly.

We decided to:

• Use Python as the programming language for this project
• Use Typer for building the CLI
• Use FastMCP for building the MCP interface
• Use SQLite for storage, with the sqlite-vec extension for vector search

I'm going to use uv as the Python package manager. It is a modern alternative to tools like pip and poetry, and it has some nice features like fast dependency resolution and built-in support for virtual environments.

If you want to follow along, make sure you have Python and uv installed on your machine. I'm on macOS, so I installed both of them using Homebrew:

brew install python uv

You can check that you have them installed by running:

python --version
uv --version

On my machine, this shows:

Python 3.13.12
uv 0.11.21

I created a new directory for the project and initialized a git repository. I suggest you do the same and add a reasonable .gitignore file for Python projects:

# Python
__pycache__/
*.py[cod]
*$py.class
*.so
.Python
build/
dist/
*.egg-info/
*.egg
.eggs/
develop-eggs/
downloads/
eggs/
lib/
lib64/
parts/
sdist/
var/
wheels/
share/python-wheels/
MANIFEST

# Virtual environments
.venv/
venv/
env/
ENV/
.env
.env.*

# uv
.uv/

# Testing / coverage
.pytest_cache/
.coverage
.coverage.*
htmlcov/
.tox/
.nox/
coverage.xml
*.cover
.hypothesis/

# Type checkers / linters
.mypy_cache/
.dmypy.json
dmypy.json
.ruff_cache/
.pyre/
.pytype/

# Jupyter
.ipynb_checkpoints/

# IDEs / editors
.idea/
.vscode/
*.swp
*.swo
*~

# OS
.DS_Store
Thumbs.db

Next, I initialized a new Python project using uv:

uv init --package --name literature-vault

This creates this directory structure:

.
├── pyproject.toml
├── README.md
└── src
    └── literature_vault
        └── __init__.py

The pyproject.toml file is where uv tracks the project metadata and dependencies. Let's install the dependencies we need for this project:

uv add typer fastmcp

We need a few development dependencies too, for testing and linting:

uv add --dev pytest ruff

pytest is a popular testing framework for Python, and ruff is a fast Python linter and code formatter.

We can do a quick test from the terminal to make sure this all works:

uv run python -c "import typer, fastmcp; print('stack ok')"

On my machine, this prints: stack ok, which means the dependencies are installed correctly and we can import them without any issues.

In my case, uv set a very new Python requirement in pyproject.toml, so I changed it:

- requires-python = ">=3.14"
+ requires-python = ">=3.12"

The >=3.14 requirement is surprisingly aggressive. Python 3.14 is not a stable baseline for a normal project yet. Python 3.12 is a much more reasonable minimum version, and it still has all the features we need for this project.

Now run uv sync to update the lock file with this change.

Next, run the project using uv run:

uv run literature-vault

The literature-vault command is created automatically by uv based on the package name. In pyproject.toml, uv wires that command to a Python function:

[project.scripts]
literature-vault = "literature_vault:main"

That means the command imports the literature_vault package and calls its main function. For now, that function lives in src/literature_vault/__init__.py, which uv also created automatically:

def main() -> None:
    print("Hello from literature-vault!")

So when you run uv run literature-vault, it executes the main function and prints "Hello from literature-vault!" to the terminal.

Hello CLI

Let's wire up the Typer CLI now. The idea is to keep the application logic separate from the CLI code, so that we can reuse the logic in different contexts (e.g., in the MCP server) without duplicating it.

Create a new file, src/literature_vault/core.py, and put this in it:

def hello(name: str = "world") -> str:
    return f"Hello, {name}!"

Now create another file, src/literature_vault/cli.py, with the following content:

import typer
from literature_vault.core import hello

app = typer.Typer()


@app.callback()
def main() -> None:
    """Literature Vault command line interface."""


@app.command()
def greet(name: str = typer.Argument("world")) -> None:
    typer.echo(hello(name))

This is the Typer layer. It imports the plain function and decides how to expose it in the terminal. Let's break down the file:

• We import typer and the hello function from core.py.
• We create a Typer app instance.
• We define a callback using the @app.callback() decorator. This gives the CLI a top-level entry point and makes Typer treat the app as a group of commands.
• We define a command using the @app.command() decorator. The function greet is the command handler, and it takes a name argument that defaults to "world".
• The typer.Argument("world") part tells Typer the command will take an argument called name, and if the user doesn't provide it, it will default to "world". This also allows Typer to generate help text for the command.
• Inside the command, we call the hello function and print its result using typer.echo().

The callback may look unnecessary right now, but it gives us the CLI shape we want for this project. Literature Vault will eventually have commands like lv add, lv search, and lv list, so it is better to start with an explicit command group instead of a single top-level command.

Now open pyproject.toml and change this:

  [project.scripts]
- literature-vault = "literature_vault:main"
+ lv = "literature_vault.cli:app"

I made two changes here:

• I changed the command name from literature-vault to lv, which is the name I wanted for the CLI.
• I changed the target from literature_vault:main to literature_vault.cli:app, which tells uv to import the app object from literature_vault/cli.py and run it when someone runs lv.

Now run:

uv run lv greet Ali

You should see:

Hello, Ali!

Also try:

uv run lv --help

You should see the top-level help text generated by Typer, including the greet command.

 Usage: lv [OPTIONS] COMMAND [ARGS]...

 Literature Vault command line interface.

╭─ Commands ────────────────────────────────────────────────────────╮
│ greet                                                             │
╰───────────────────────────────────────────────────────────────────╯

You can also ask for help for the greet command:

uv run lv greet --help

That help text shows the name argument and its default value.

 Usage: lv greet [OPTIONS] [NAME]

╭─ Arguments ───────────────────────────────────────────────────────╮
│   name      [NAME]  [default: world]                              │
╰───────────────────────────────────────────────────────────────────╯
╭─ Options ─────────────────────────────────────────────────────────╮
│ --help          Show this message and exit.                       │
╰───────────────────────────────────────────────────────────────────╯

That is the first real payoff from Typer: because the function has a typed parameter, Typer can generate command-line help from it.

Hello MCP

Now let's expose the same hello function through MCP. This is the reason we put the application logic in core.py instead of writing it directly inside the Typer command. The CLI and the MCP server should both be thin wrappers around the same underlying Python function.

Create a new file, src/literature_vault/mcp_server.py, with the following content:

from fastmcp import FastMCP

from literature_vault.core import hello

mcp = FastMCP("Literature Vault")


@mcp.tool
def greet(name: str = "world") -> str:
    return hello(name)


if __name__ == "__main__":
    mcp.run()

This should feel very similar to the Typer file:

• We import the same hello function from core.py.
• We create a FastMCP server named Literature Vault.
• We decorate a normal Python function with @mcp.tool to expose it as an MCP tool.
• Inside the tool, we call the same core function that the CLI uses.

At this point, the structure is exactly what we wanted:

src/literature_vault
├── __init__.py
├── cli.py
├── core.py
└── mcp_server.py

The important part is that core.py does not know anything about Typer or FastMCP. It is just Python code. The interface-specific files import that code and expose it in different ways.

Now let's test the MCP server with the official MCP Inspector. The Inspector is a local browser UI for testing and debugging MCP servers. It lets us see the tools exposed by the server and call them manually, without wiring the server into Claude Desktop, Cursor, or another MCP host yet.

The Inspector runs through npx, so you need Node.js installed.

Then launch the Inspector from the project directory:

npx -y @modelcontextprotocol/inspector uv run python -m literature_vault.mcp_server

This opens the Inspector UI in your browser.

The left sidebar should already be filled in with:

Transport Type: STDIO
Command: uv
Arguments: run python -m literature_vault.mcp_server

Click Connect. This starts the MCP server process and connects the Inspector to it.

After it connects, use the Inspector to call the tool:

• Open the Tools tab.
• Click List Tools if the tools are not shown yet.
• Select the greet tool.
• Enter Ali for the name argument.
• Run the tool.

You should see the tool return:

Hello, Ali!

Now the same application logic works through two different interfaces:

uv run lv greet Ali

and:

MCP Inspector -> Tools -> greet

That is the architectural pattern I want for the rest of Literature Vault.

You can stop the MCP server by pressing Ctrl+C in the terminal where you ran the npx command. The Inspector will show that the connection was lost.

Hello Tests

We also installed pytest, so let's add a small test before wrapping up.

Create a new directory called tests. For this project, I want the tests to follow the same boundaries as the source code:

• core.py contains application logic, so it gets its own tests.
• cli.py contains the Typer interface, so it gets its own tests.
• mcp_server.py contains the MCP interface, so it gets its own tests.

The test directory should look like this:

.
├── src
│   └── literature_vault
│       ├── __init__.py
│       ├── cli.py
│       ├── core.py
│       └── mcp_server.py
└── tests
    ├── test_cli.py
    ├── test_core.py
    └── test_mcp_server.py

This does not need to mechanically copy the full src/literature_vault directory structure yet. For now, a flat tests directory with one test file per source module is simple and readable. If the project grows much larger, I can always move to a nested structure like tests/literature_vault/test_core.py.

Put this in tests/test_core.py:

from literature_vault.core import hello


def test_hello_default() -> None:
    assert hello() == "Hello, world!"


def test_hello_with_name() -> None:
    assert hello("Ali") == "Hello, Ali!"

These tests check the plain Python function directly. They do not know anything about Typer or MCP.

Now put this in tests/test_cli.py:

from typer.testing import CliRunner

from literature_vault.cli import app

runner = CliRunner()


def test_greet_command() -> None:
    result = runner.invoke(app, ["greet", "Ali"])

    assert result.exit_code == 0
    assert result.output == "Hello, Ali!\n"

This test checks the Typer layer. It does not call hello directly. It calls the CLI the way a user would: through the greet command.

Finally, put this in tests/test_mcp_server.py:

import asyncio

from fastmcp import Client

from literature_vault.mcp_server import mcp


def test_greet_tool() -> None:
    async def call_tool() -> str:
        async with Client(mcp) as client:
            result = await client.call_tool("greet", {"name": "Ali"})
            return result.data

    assert asyncio.run(call_tool()) == "Hello, Ali!"

This test checks the MCP layer. The MCP Inspector is great for manual testing, but for an automated test suite we want something that can run in the terminal. FastMCP's test client lets us call the MCP tool directly without opening a browser.

Now run the tests:

uv run pytest

You should see all four tests pass:

4 passed

This is still a tiny test suite, but it is enough for this stage. It verifies the main design decision of this post: the same core function can be used directly, through the CLI, and through MCP. Later, when hello turns into real functionality like add and search, we can keep this same testing pattern.

I have not touched SQLite yet. That is intentional. This post was about getting the Python project, CLI, MCP server, and tests in place. In the next post, I will start the storage layer and bring in the SQLite-related pieces when there is actually something to test against.

I'm planning to build "Literature Vault" — a local search engine for research papers stored as PDFs on my machine. It is meant to ingest and index the content of these PDFs and allow search with keywords or natural language through a simple CLI and MCP. It would be ideal for agentic flows.

If I were doing my PhD again, I would be building something like this. I recently signed a contract to write a book on AI and STEM education, so I'm building this to help with the research for the book, for my own use. I'll document the process of building it here too, in case it's useful to others, and I'll share the code on GitHub when it's ready.

This is not a "chat-with-your-PDF" tool. Those tools exist! For example, Google's NotebookLM lets you upload your PDFs and then ask questions about them. But NotebookLM is more of a synthesis tool, and that is a layer one can build on top of my literature vault. Besides, I prefer to do that kind of work myself (let the human do some of the work).

I want to be able to run this entirely on-device, without relying on any AI service providers. I know it's possible, but at the moment I'm not sure whether it's feasible on modest hardware. I'll figure it out as I go, and I'll try to build it in a modular way so that I can swap out components as needed.

There are two main components to this system: the ingestion pipeline and the search engine. I'm going to jot down some thoughts on each of these components here, since it helps me organize my ideas. These may change as I go, and that's fine.

Search

I want three modes of search: keyword, semantic, and hybrid.

The keyword search is plain full-text search. This is the classic approach, from before embeddings, and it's still the standard today. It is not just the exact string match that you get when you press Ctrl+F in a PDF viewer. It will be more like the search you get in Google Scholar, which includes stemming, stop-word removal, and other NLP techniques to make it more effective.

The semantic search is what we got in the era of LLMs. The process is to break the papers into smaller chunks (e.g., paragraphs), turn those into a numerical representation (embedding) using a language model, and then store those embeddings in a vector database. The idea is that the "vector" (a numerical representation of the text) captures the meaning (semantics) of the text, so that similar meanings will have similar vectors, even if they use different words. When I search, I will also turn my query into an embedding and then find the passages whose embeddings are closest to the query embedding in the vector space (vector search). This is the part that lets you search in natural language.

So you might think: now that we can do semantic search, why do we need keyword search? Well, semantic search can miss some things that keyword search would catch. For example, if I search for exact phrases or specific technical terms, keyword search will certainly find those, while semantic search might not if those terms get diluted in the embedding. So the common wisdom is to use hybrid search, which combines the keyword and semantic search. It runs both of them and then combines the rankings. For example, it might take the top 100 results from each search and then re-rank them based on some combination of their keyword relevance and their semantic relevance to the query.

I don't want three separate commands for this. They're really the same thing: I type a query, I get back a ranked list of passages. So I'll make it one search command with a --mode flag.

lv search "attention in transformers"        # hybrid by default
lv search --mode keyword "transformer architecture"
lv search --mode semantic "how models handle long context"

The lv is the tentative name for the CLI tool.

A few things I'm deciding early:

• Hybrid is the default, so a plain lv search "..." just does the sensible thing without me picking a mode.
• The results are passages with some ID that we can use to retrieve the paper (its metadata and location on disk) later.
• We should have --json and --files output formats that are more machine-readable, for use in agentic flows.
• We should have some other flags for controlling the search, like how many results to return, whether to restrict the search based on certain metadata (e.g., only papers from 2020-2022), etc.

Ingestion

Before I can search anything, I need to get the papers into the vault. This is the ingestion side.

The first thing is to figure out what a paper is, as far as the system is concerned. I think the right move is to give each paper a fingerprint by hashing its content. That gives me a stable ID, and it also solves a practical problem: if I add the same paper twice, the system can tell it has seen it before and skip it. So lv add becomes idempotent almost for free. The fingerprint is also what lv remove and lv list refer to when they talk about a paper.

The next thing is to get the text out of the PDF. This is harder than it sounds, because PDFs are messy, but it's a solved problem and I don't need to solve it myself. I'll treat text extraction as a component I plug in, so I can start with something simple and swap in a better extractor later without touching the rest of the system. The same goes for pulling out metadata like the title, authors, and year, which I'll need for lv list and for the metadata filters on search.

Once I have the text, the rest of ingestion is a pipeline that turns it into the things search needs. It chunks the paper into passages, builds the keyword index over them, computes the embeddings, and stores everything alongside the paper's fingerprint and the location of each passage. When that pipeline finishes, the paper is searchable. That's really all "ingested" means here: the paper has been fingerprinted, its text extracted, and its passages indexed for both kinds of search.

Tech stack

I'm going to build this in Python, since the libraries for embeddings, PDF handling, and everything on the ingestion side mostly live there.

For storage, I'll use a single SQLite file. SQLite has full-text search built in, and with the sqlite-vec extension it can store and search vectors too. So both the keyword index and the embeddings live in the same file, next to the paper metadata and fingerprints. One file, no server to run, everything on disk. That fits the on-device goal nicely, and it's easy to swap out later if I outgrow it.

For the embeddings, I'll use a small local embedding model that runs on CPU. The exact model is a detail I'll figure out later; the point is that it runs on my machine and nothing leaves it.

For the CLI, I'll use Typer. It lets me write each command as a plain function with type hints, which keeps things small and readable. And for the MCP server, I'll use FastMCP, which works the same way: a tool is just a typed function with a decorator.

That last bit is the part I'm most happy about. Because both Typer and FastMCP wrap plain typed functions, I can write the core logic once and expose it through both the CLI and the MCP server without duplicating anything. And if I ever want to put a web API in front of it, the same logic is right there to wrap again. So the searching and ingesting live in one place, and the CLI, the MCP server, and a future API are all just thin layers on top.

That's the plan for now.

Start with the problem it solves. Conceptually, every object your program creates has to live somewhere in memory, in a region called the heap. The heap is not infinite. Every object takes a chunk of it, and once the program can no longer use an object, that chunk has to be handed back, or the heap fills up and the program runs out of memory. The question is who hands it back, and when. C, C++, and Java answer that question in three different ways, and comparing the three is the clearest way to understand what garbage collection is.

C: you free memory by hand

In C, you manage the heap yourself. You ask for memory with malloc, and you give it back with free:

int *p = malloc(sizeof(int));   // reserve a chunk of heap, get its address
*p = 5;                         // use it
free(p);                        // hand the chunk back

The rule is simple: every successful malloc must eventually be matched by exactly one free, no more and no less. If you get that wrong, you hit one of three common bugs.

The first is a memory leak. You allocate, you forget to free, and that chunk stays reserved until the program ends. One small leak in a short-lived program may not matter much. A leak inside a loop, in a program that runs for a long time, accumulates until the program runs out of memory.

The second is a dangling pointer. You free a chunk, but you still hold a pointer to it, and later you use that pointer. The memory may have already been handed out to something else by then, so you are reading or writing data that no longer belongs to you. These bugs are hard to reproduce and are a common cause of crashes and security vulnerabilities.

The third is a double free: calling free twice on the same chunk, which corrupts the heap's bookkeeping.

C does not catch any of these for you. You have full control over memory and full responsibility for managing it correctly.

C++: cleanup tied to scope

C++ keeps everything C has. It has new and delete, which are the C++ equivalents of malloc and free, and the same three bugs are still possible. But C++ also provides a way to avoid freeing memory by hand.

The idea is to tie the lifetime of a heap object to the lifetime of an ordinary stack variable. When a C++ object with automatic storage duration goes out of scope, C++ guarantees that a special method called its destructor runs automatically. If that stack object owns heap memory, its destructor can free that heap memory, so cleanup happens automatically when the owner goes out of scope. This pattern is called RAII ("resource acquisition is initialization"), but the idea is just to let scope exit do the freeing.

In modern C++ you rarely write delete yourself. You use smart pointers that apply this pattern for you:

std::unique_ptr<int> p = std::make_unique<int>(5);
// use *p ...
// no delete needed: when p goes out of scope, the int is freed

A unique_ptr owns its object and destroys it when it goes out of scope. A shared_ptr lets several owners share one object and destroys it when the last owner goes away, by keeping a count of how many owners there are.

The important property is that the cleanup is deterministic. You know what event triggers cleanup: a unique_ptr destroys its object when the owner goes out of scope, and a shared_ptr destroys its object when the last owner goes away. There is no background process. You still decide who owns what, and you can still get it wrong — two shared_ptrs that point at each other form a cycle that keeps each other alive and is never freed — but the common case is handled predictably.

Java: the runtime frees memory for you

Java takes the responsibility away from you. You allocate with new, and there is no second step. There is no free and no delete. You never reclaim memory yourself.

Employee e = new Employee(1);
// ... use it ...
// no free, no delete; you simply stop using it

Instead, the JVM runs a garbage collector: a process that, from time to time, determines which objects are still in use and reclaims the rest. The question it has to answer is which objects are still in use, and the answer is based on references — the links a variable holds to an object, and that object holds to another.

An object is live if it is reachable: if you can get to it by starting from a set of roots — the local variables currently on the stack, the static fields of your classes, and a few others — and following references from object to object. If no chain of references leads to an object, then nothing in your program can name it or use it again. It is garbage, and the collector can reclaim its memory.

This changes how you free something. You do not free it; you make it unreachable by dropping the references to it:

Employee e = new Employee(1);
e = null;   // if no other reachable reference points to that object, it is now eligible for collection

You are not telling the runtime to delete the object. You are telling it that you no longer hold a reference to the object, and at some later point the collector reclaims it. (Letting a local variable go out of scope does the same thing, without writing null.)

In exchange for giving up control, you avoid all three C bugs. You cannot have a dangling pointer, because you never free anything that a live reference still points to. You cannot double-free. And the "forgot to free" leak is mostly gone, because the collector reclaims objects once they are no longer reachable. This safety is a large part of why Java has no C/C++-style pointers: with no manual free, no raw addresses, and no pointer arithmetic, dangling-pointer and double-free bugs are removed from ordinary Java code.

Tracing collection has another benefit. Because the collector works by tracing what is reachable, it handles cycles automatically. Two Java objects that refer to each other but that nothing else points to are still unreachable from the roots, so they are collected. This is the case that reference-counting smart pointers in C++ do not handle.

Garbage collection also has costs.

The main cost is that collection is non-deterministic. Unlike C++'s scope-based cleanup, you do not know when an object will be collected, or even whether it will be collected before the program ends. The collector runs on its own schedule, and when it runs it may briefly pause your program to do its work — a "stop-the-world" pause. Modern collectors are designed to keep these pauses small, but pause behavior depends on the collector and workload, so for latency-sensitive software they are still a concern. Garbage-collected programs often need extra memory headroom, because memory is usually reclaimed in batches rather than immediately at the moment an object becomes unreachable.

There is also a subtler problem. Java can still leak, not in the C sense, but in a logical one. If you keep a reference to an object you no longer need (a common cause is an object left in a long-lived collection or cache), it stays reachable, so the collector will never reclaim it. The collector reclaims the unreachable; it cannot know that a still-reachable object is one you are done with. Java leaks are leaks of unintended reachability, not of forgotten frees.

One more consequence: because the collector may move objects around in memory to reduce fragmentation, an object's address is not stable over its lifetime. This is one reason Java does not show you raw addresses or let you do pointer arithmetic — the address you saw a moment ago might no longer be correct. And because collection timing is unpredictable, Java does not give you a reliable destructor the way C++ does. (Java historically had finalizers, but they are unreliable and deprecated; they are not a substitute for deterministic cleanup.) That is fine for memory, which the collector handles, but not for other resources like open files or network sockets, which need to be closed promptly. For those, Java provides try-with-resources: a scope-based cleanup mechanism for objects that implement AutoCloseable, where Java calls close() automatically at the end of the block.

The trade-off

The three languages form a spectrum that trades control against safety:

• C gives you full manual control. You have precise control over when memory is freed, and full responsibility for getting it right.
• C++ keeps the control but automates the work. With RAII and smart pointers, cleanup happens deterministically at scope exit, and you mostly stop writing delete by hand.
• Java gives the job to the runtime. Whole categories of bugs are removed, at the cost of determinism, some memory overhead, and occasional pauses.

No point on this spectrum is universally correct. A database engine or an operating-system kernel may need C's control; a large business application is usually better off with Java's safety. Each language makes a different choice.

The short version

• In C, you free memory by hand with free, and you own every mistake: leaks, dangling pointers, double frees.
• In C++, you can tie cleanup to scope with destructors and smart pointers, so owned memory is reclaimed automatically and deterministically when the owner is destroyed. You control when, and the language does the work.
• In Java, a garbage collector reclaims whatever your references no longer reach. You stop managing memory and start managing reachability: safer, but you give up knowing exactly when cleanup happens.

You never call free in Java. But you are still responsible for letting go of references you no longer need.

Part of what makes this confusing is that the word "reference" means different things in different languages. There are three separate ideas that get lumped together: the C pointer, the C++ reference, and the Java reference. Let's look at them one language at a time.

Pointers in C

In C, you work with memory addresses directly.

Start with an ordinary variable:

int x = 5;

x is a name for a block of memory that holds the value 5. That block has an address — a number that tells you where it is in memory. In C, you can get that address with the & ("address-of") operator:

int *p = &x;

p is a new variable, and its type is int *, which means "pointer to an int." p does not hold an integer; it holds an address: the location of x. If x lives at address 0x1234, then p holds the number 0x1234.

A pointer is a variable like any other. It has its own block of memory, its own address, and it holds a value. The only difference is that the value it holds is meant to be used as the location of something else.

To go from the pointer to the thing it points at, you dereference it with the * operator:

printf("%d", *p);   // prints 5
*p = 10;            // now x is 10

*p means "go to the address stored in p and use whatever is there." Writing through *p changes x, because p holds x's address.

Because a pointer is just a variable holding a number, you can do with it what you can do with any variable. You can point it somewhere else:

int y = 99;
p = &y;   // p now holds the address of y instead

You can set it to point at nothing:

p = NULL;

You can also have a pointer to a pointer, since a pointer has its own address. C does not protect you from mistakes: if you dereference a pointer that holds an invalid address, the program has a bug, and C will not catch it for you.

To summarize C: a pointer is a variable that holds an address, you take addresses with &, and you follow them with *. Everything is explicit.

References in C++

C++ keeps C's pointers exactly as they are. It also adds a second, separate thing, and it calls that thing a reference.

Here is a C++ reference:

int x = 5;
int &r = x;

r is declared as int &, which means "reference to an int." It does not behave like a pointer. r is not a variable that holds an address. r is another name for x — an alias. After this line, r and x refer to the same block of memory.

You do not use & or * to work with it:

r = 10;   // x is now 10

You use r as if you had written x, because it is x.

This is the part that confuses people. A reference has two rules that a pointer does not:

• It must be bound when it is created. You cannot write int &r; with nothing on the right. A reference has to be an alias for something from the start.
• It can never be re-bound. Once r is an alias for x, it stays an alias for x. If you later write r = y;, that does not make r refer to y. It copies y's value into x, because r is another name for x. There is no way to make an existing reference refer to a different object.

A pointer is different: you can re-seat it as often as you like, and it can be NULL. A reference cannot be re-seated, and in a correct program it cannot refer to nothing.

So C++ has two distinct tools:

• A pointer is a variable that holds an address. It can be re-seated, it can be null, it has its own address, and you work with it through & and *.
• A reference is an alias — a second name for an object that already exists. It is bound once, cannot be re-seated, is not nullable in correct C++ code, and needs no special syntax.

A C++ compiler usually implements a reference using a pointer internally, but the language treats them as different things with different rules.

Passing arguments: the swap example

The difference shows up when you pass something to a function.

Suppose you want a function that swaps two integers. In C, you use pointers, because the function needs the addresses of the caller's variables to change them:

void swap(int *a, int *b) {
    int tmp = *a;
    *a = *b;
    *b = tmp;
}

swap(&x, &y);   // pass the addresses

In C++, you can do the same thing with references. The parameters become aliases for the caller's variables:

void swap(int &a, int &b) {
    int tmp = a;
    a = b;
    b = tmp;
}

swap(x, y);   // no & needed; a and b are x and y

Inside this function, a and b are not copies. They are the caller's x and y under different names, so the swap takes effect in the caller.

Java cannot do this, as we will see next.

References in Java

Java has no C/C++-style pointers. There is no &, no *, no pointer arithmetic, and no way to get the numeric address of an object. So when Java says "reference," the natural assumption, especially coming from C++, is that it means the C++ reference: an alias, bound once, never null.

That assumption is wrong, and it is the main source of confusion. A Java reference is not a C++ reference. In its behavior it is closer to a C++ pointer, with some restrictions.

Here is what a Java reference can do:

Employee e1 = new Employee(1);
Employee e2 = new Employee(2);
e1 = e2;       // re-seated: e1 now refers to the second object
e1 = null;     // and it can refer to nothing

A Java reference can be re-seated and can be null. A C++ reference can do neither; those are pointer behaviors. What Java takes from the C++ reference is the syntax: there is no * to dereference. When you write something like e1.getId(), Java follows the reference for you before calling the method. The dereference is implicit, but it still happens.

So a Java reference is pointer-like: you can think of it as pointing to an object, but Java does not expose it as a raw memory address. You cannot do arithmetic on it, cannot read it as a number, and cannot dereference it explicitly. It has the behavior of a pointer, with the unsafe operations removed and the dereference made implicit. The name "reference" can make people think of C++ references, but the behavior is much closer to a restricted pointer.

The swap function shows this clearly. Here it is in Java:

static void swap(Employee a, Employee b) {
    Employee tmp = a;
    a = b;
    b = tmp;
}

swap(e1, e2);   // e1 and e2 are unchanged afterward

This does nothing to the caller's e1 and e2. Java passes the reference by value: a and b are copies of the references e1 and e2. Swapping the copies inside the function does not affect the originals. This is how a copied pointer behaves, and it is not how a C++ reference behaves; a C++ reference would have made the swap take effect.

There is one more point to be clear about, because it is a common source of confusion. Even though you cannot re-seat the caller's variable, you can change the object it points at:

static void giveRaise(Employee a) {
    a.setSalary(a.getSalary() + 1000);   // this does affect the caller's object
}

Here a is a copy of the reference, but the copy points at the same object as the caller's reference. Changing that object through a is visible outside the function. What you cannot do is make the caller's variable point at a different object.

This settles the common question of whether Java is pass-by-value or pass-by-reference. Java is always pass-by-value. For objects, the value being copied is the reference, not the object. You can follow the reference and change what is at the other end, but you cannot change the caller's reference itself.

The short version

• A C pointer is a variable that holds an address. It is explicit, can be re-seated, can be null, and uses & and *.
• A C++ reference is an alias — a second name for an object that already exists. It is bound once, cannot be re-seated, is not nullable in correct C++ code, and uses no special syntax.
• A Java reference uses the syntax of a C++ reference (no *, implicit dereference) but has behavior closer to a C pointer (can be re-seated, can be null, passed by value). It is pointer-like, but Java does not expose it as a raw address.

The word "reference" can be misleading: a Java reference is not a C++ reference. In the ways that matter for this discussion, it behaves much more like a restricted pointer.

Primitive types include int, double, boolean, etc. They store their values directly. For example, if you have an int x = 5;, the variable x directly holds the value 5. When your program runs, it allocates memory for x and stores the value 5 in that memory location. When you try to print x, the program has a lookup table that tells it where x is stored in memory (let's say at address 0x1234), and it goes to that address, reads the raw data stored there (which is in binary), converts it to an integer (because it knows x is an int), and then prints the result (5).

There is a lot of machinery that happens under the hood to make this work, but the key point is that for primitive types, the variable directly holds the value.

Reference types, on the other hand, do not hold the actual data. Instead, they hold a reference (or pointer) to the location in memory where the actual data is stored.¹ Let's walk through an example to illustrate this. Suppose you write Employee e1 = new Employee(1);. This statement is actually doing a few things:

• First, it creates a new Employee object in memory. Let's say this object is stored at address 0x5678.
• Then, it initializes the fields of that Employee object (e.g., setting id to 1).
• Then, it creates a variable e1. This variable also has a memory location (let's say 0x1234).
• Finally, it stores the reference (the address 0x5678) in the variable e1. So e1 does not hold the actual Employee object; it holds a reference to where that object is stored in memory.

When you access e1.getId() (to print the employee's id as an example), the program does the following:

• It looks up the variable e1 and finds that its memory location is 0x1234.
• It goes to that memory location and reads the value stored there, which is some binary data.
• It interprets that binary data as a reference (because e1 is of type Employee). Here, "reference" simply means an address in memory where the actual Employee object is stored. So it reads the reference and finds that it points to 0x5678.
• It then goes to the memory location 0x5678 where the actual Employee object is stored.
• It then reads the id field from that object, which is 1, returns it from getId(), and prints it.

I've glossed over some details here, but the key point is that it has to follow the reference from e1 to get to the actual object in memory. This is what it means for e1 to be a reference type. It does not hold the actual data; it holds a reference to where the data is stored.

But why do we have two types of variables? The answer is more interesting than "because Java says so." It has to do with how variables are stored in memory. Let's explore that next.

What Is a Variable, Really?

You can think of computer memory as a long row of tiny boxes, each box holding a fixed number of bits (usually 8 bits, which is called a byte). Each box has its own address, which is just a number that tells you where it is in the row. The memory is divided into regions, and the regions are used for different purposes and as such have different characteristics.

One of those regions is where your program's variables live. When you declare a variable in your program, the compiler sets aside a block of those boxes (memory units) for it. The variable's name is just a label for that block, so when you use the variable in your code, the program knows to go to that specific location to read or write its value.

Here is the part that matters. The region where variables live has a strict rule: each variable gets a block of a fixed size, decided before the program runs. When your code is compiled, the compiler has to know exactly how much room to reserve for each variable. Why must it be fixed in advance? Because the blocks are laid out next to each other in one continuous row. If variable x is followed by y in memory, the program needs to know where x ends and y begins. If x could grow or shrink while the program ran, it would crash into y. So the size is settled up front, and it never changes.

How much room? That depends on the type. This is, in fact, what the type tells the compiler. When you write int x;, the int says "reserve 4 bytes." A double says "reserve 8 bytes." The type is not just a label for you, the programmer — it is an instruction to the compiler about how big the block must be and how to read the bits inside it.

If the value is something small with a known, fixed size — a whole number, a decimal number, a single character, a true-or-false — then it fits nicely in a fixed-size block. This is exactly what a primitive type is.²

But what if the value cannot be fit into a fixed-size block? What if it is something that can vary in size?

When the Value Doesn't Fit

Let's say we define a variable to hold a person's name: String name;

How big a block should the compiler set aside for name?

An int was easy — every int is exactly 4 bytes, today and forever, so the compiler reserves 4 bytes and moves on. But a name? It could be a small 3-character string like my name, Ali, or a much longer name. The type String can store the entirety of this blog post (or any other text, however long). Moreover, you can change which string the variable refers to while the program runs: assign it a short name now, then assign it a longer name later. There is no single number of bytes the compiler can pick ahead of time that is right for every possible string.

This runs straight into the rule stated earlier: the block reserved for a variable has a fixed size, decided up front, and it never changes. A String has no fixed size. So a string simply cannot live inside the variable's reserved block the way an int does. The two facts are in direct conflict.

So what do we do? The solution is to stop trying to put the string itself in the block. Instead, we put the string somewhere else in memory — in a different region (often called the heap) where objects can be allocated at runtime with whatever size they need. (The program creates a new object of whatever size is needed, and the variable can later point to a different object.)

So what does go into the block reserved for name? We put the address of that somewhere else. The block does not hold the string. It holds a note that says "the string you want is over there, at address 0x5678."

Look at what this buys us. The string itself can be 2 bytes or 2 million; it lives elsewhere, so its size is no longer our problem. And the block corresponding to name stays small and fixed — it only ever holds an address, and an address is the same size no matter how big the thing it points to is (typically 8 bytes on a 64-bit machine). The fixed-size block and the variable-size value can finally coexist, because we stopped trying to hold the value in the block and started holding directions to the value.

That address-sitting-in-a-block is what we call a reference. The block holds a reference to the value; the value lives somewhere else in memory.

You might reasonably push back here. If there is a region of memory that can hold a string of any size, why the detour? Why not let the variable name refer to that region directly, and skip the little fixed block in the middle?

The answer is that the block is the variable, and the variable has to stay put while the thing it refers to does not.

Think about what the name name actually is. When your code is compiled, name becomes one specific block in the variable region — the place the rest of your compiled code reaches every single time it uses name, for the whole life of the variable. That block has to be settled before the program runs, which is the fixed-size rule again.

Now think about the string. It is created while the program runs, not before. At compile time there is no address to point at yet — the string does not exist, and the compiler has no way to know where it will eventually land. And it gets worse: you can point name at a different string later. Write name = "Ali" on one line and name = <something far longer> on the next, and you now have two different strings, of two different sizes, at two unrelated addresses.

So we have a fixed thing — the variable's block, pinned down at compile time — that has to refer to a moving target: a value created at runtime that can be swapped out at any moment. You cannot wire the name directly to the string's address, because when the wiring is decided there is no address yet, and even once there is one, the next line might change it. The block never moves; what changes is the address written inside it. That is what the indirection is for: the block is a stable handle you can always find, and its contents are free to point wherever the variable currently refers.

So here is one important reason Java has two kinds of types. Some values have a small, fixed, known size and can be stored directly in the variable's block — those are the primitives. Objects, on the other hand, are stored elsewhere, and the variable's block stores only a fixed-size reference to the object — those are the reference types. This keeps the variable's block small and fixed even when the object is created at runtime, replaced by a different object, shared by multiple variables, or connected to other objects.

How Big Is an Employee?

Variable size is the first reason references exist, but it is not the only one. There is a second reason, and it is about a problem that has no solution at all without references.

Go back to the Employee class, and assume it has the following definition:

public class Employee {
    private int id;
    private Employee manager;
    // Other fields (like name, title, etc.) are omitted for simplicity
    // Constructor, getters, setters, other methods are omitted for simplicity
}

Pay attention to the manager field. It is of type Employee. Interesting: one employee has a reference to another employee. This allows us to create a chain of employees, where each employee can have a manager, and that manager can have their own manager, and so on. You can imagine a junior employee who reports to a mid-level manager, who reports to a senior manager, who reports to the CEO. Each of those employees can be represented as an Employee object, and the manager field can point to the next employee in the chain. You might wonder about the CEO, who has no manager. We can represent that by setting the manager field to null for the CEO.

Let's ask a question that sounds almost too simple: how big is an Employee object? How many bytes must the compiler set aside for one?

We can try to add it up. The id field is an int, so that is 4 bytes. Then there is the manager field, which is an... Employee. So to know how big an Employee is, we first need to know how big an Employee is.

Read that again — it is not a slip. Suppose the manager field stored an entire Employee object inside it, the whole thing laid out inline. Then the size of an Employee would be:

size(Employee) = 4 bytes (id) + size(Employee)

And the size(Employee) on the right has its own manager, which is another Employee, which has its own manager, which is another Employee, with no end in sight. The block would need room for an employee, who holds an employee, who holds an employee, forever. No number of bytes satisfies this. The compiler cannot lay out even a single Employee in memory. The object is, quite literally, infinitely large.

So storing an Employee object directly inside another Employee object, by value, is not merely a bad idea — it is impossible. A type cannot contain a full inline copy of itself.

Now watch what a reference does to this.

If manager holds a reference to an Employee instead of an Employee itself, then manager is just an address. An address has a fixed, known size — the same handful of bytes whether it points to a junior hire, the CEO, or nothing at all. The infinite regress collapses:

size(Employee) = 4 bytes (id) + 8 bytes (a reference)

Around twelve bytes — the JVM adds a little bookkeeping of its own, but the point is that it is a fixed, finite number, known before the program runs. The compiler can lay it out without trouble. And that manager reference can point to another Employee who lives elsewhere in memory, who has their own manager reference pointing to yet another Employee elsewhere, and so on up to the CEO, whose manager reference is simply null.

This is the second reason references have to exist. Without them, no value could ever contain another value of its own type, and an entire family of structures would be impossible to build. This is also why Java never gives you the choice: a field whose type is a class is always a reference, never the object itself laid out inline. The language closes the trap before you can fall into it.

With references, a type can refer to its own kind — and that single capability is the foundation of a whole family of data structures, including linked lists, trees, graphs, and more.

What lives where in Java

In Java, the standard conceptual rule of thumb is short:

• A method call's local variables and parameters are stored in its stack frame.
• Objects — anything you create with new — conceptually live on the heap.

These two facts interact for reference types. Suppose we have a small class:

public class Employee {
    private int id;
    // constructor, getter, etc.
}

Now consider this line:

Employee e = new Employee(1);

This involves two separate pieces of memory. The object — the actual Employee, with its id field — is created on the heap. The variable e is a local variable, so its reference value is stored in the stack frame, and that reference points to the object on the heap.

A primitive local variable is different. With int count = 5;, the local-variable slot for count holds its value, 5, directly in the stack frame. There is no separate object anywhere.

        Stack                                Heap
   ┌─────────────────┐              ┌──────────────────────┐
   │ e   ■───────────┼────────────▶ │ Employee             │
   │                 │              │   id = 1             │
   │ count = 5       │              │                      │
   └─────────────────┘              └──────────────────────┘

The stack

The stack holds the data for method calls. Each time a method is called, Java sets aside a block of memory called a frame for that call. The frame holds the method's local-variable slots, its parameters, and some bookkeeping.

The frames are arranged as a stack in the data-structure sense: last in, first out. When method A calls method B, a frame for B is pushed on top of A's frame. When B returns, its frame is popped off, and control goes back to A. If B had called C, C's frame would sit on top of B's and would be popped first.

This has one important consequence: the storage for a method call is automatic and tied to that call. The frame comes into existence when the method is called, and it is gone the moment the method returns and its frame is popped. A local variable may be in scope for only part of the method, but in any case you do not free it; its stack storage goes away on its own when the call ends.

The stack is cheap to use. Allocating a frame is essentially moving a pointer, and popping it is moving the pointer back. But the stack has limits: the size of each frame is known in advance, and the total stack space is limited.

Recursion and the call stack

Recursion is the clearest way to see the call stack at work. A recursive method calls itself, and each call gets its own frame, with its own copy of the parameters and local variables.

Take a method that computes a factorial for positive inputs:

static int factorial(int n) {
    if (n == 1) return 1;          // base case
    return n * factorial(n - 1);
}

When you call factorial(3), the calls do not all run at once. Each one calls the next and waits for it to return:

• factorial(3) is called. A frame is pushed with n = 3. To finish, it needs the result of factorial(2).
• factorial(2) is called. A frame is pushed on top, with n = 2. It needs factorial(1).
• factorial(1) is called. A frame is pushed on top, with n = 1. This is the base case: it returns 1, and its frame is popped.
• factorial(2) resumes, computes 2 * 1 = 2, returns 2, and its frame is popped.
• factorial(3) resumes, computes 3 * 2 = 6, returns 6, and its frame is popped.

At the deepest point, all three frames are on the stack at the same time:

        ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
top ──▶ ┃ factorial(1)  n=1  return 1  (n == 1)       ┃
        ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
        ┌─────────────────────────────────────────────┐
        │ factorial(2)  n=2  waiting for factorial(1) │
        ├─────────────────────────────────────────────┤
        │ factorial(3)  n=3  waiting for factorial(2) │
        └─────────────────────────────────────────────┘

Each frame has its own n, which is why the calls do not interfere with one another. The frames build up until the base case is reached, then unwind in reverse order as each call returns.

This also explains stack overflow. If a recursive method has no base case, or never reaches it, the frames keep getting pushed and none are ever popped. Eventually the stack space runs out, and the program fails with a StackOverflowError.

The heap

The heap holds objects, and it is not tied to method calls. Conceptually, when you write new, the object is created on the heap, and it stays there until it becomes unreachable and the garbage collector reclaims it, regardless of which method created it.

This is the key difference from the stack. An object created inside a method does not disappear when the method returns. It can outlive the call, as long as it remains reachable:

static Employee createEmployee() {
    Employee local = new Employee(1);  // object on the heap; local reference in the stack frame
    return local;                      // return the reference
}

Employee e = createEmployee();         // e refers to the same heap object

When createEmployee returns, its frame is popped off the stack, and the local variable local is gone. But the Employee object on the heap is still reachable, because the reference was returned and is now held by e in the caller. The object outlived the method that created it.

The heap is more flexible than the stack. Objects can have different sizes, their lifetimes can extend beyond the method call that created them, and they can be referred to from many places at once. The cost of that flexibility is that the heap needs separate management to reclaim objects that are no longer reachable — the cleanup that the stack gets for free by popping frames.

Why two regions

A reasonable question is why a program needs both. The stack's automatic lifetime is cheap and safe, but it only works for data whose storage can disappear when the call returns. Two situations do not fit that pattern:

• The data must outlive the method that created it. The createEmployee example returns an object that has to exist after the method returns. A stack frame cannot hold it, because the frame is gone once the method returns.
• The data needs to be shared or to vary in size. Objects can be referred to from several reachable places at once and can have sizes chosen at runtime; tying them to a single frame would not work.

For data that fits the call pattern — ordinary local-variable values and parameters — the stack is ideal, because cleanup is automatic and free. For object data with independent lifetime, the program uses the heap.

C and C++

The stack and the heap are not specific to Java. C and C++ have the same two regions, with the same basic roles: local variables go on the stack, and dynamically allocated memory goes on the heap. There are two differences worth noting.

First, C and C++ let you choose where an object goes. A local struct or object declared in the normal way lives on the stack and is destroyed automatically when it goes out of scope. An object you allocate with malloc (in C) or new (in C++) lives on the heap. In Java you do not make this choice in source code: objects are treated as heap objects in the standard model, and local variables and parameters hold primitive values or references in stack frames.

Second, the heap has to be reclaimed somehow. In C you do it by hand with free. In C++ you usually tie it to scope with destructors and smart pointers. In Java, a garbage collector reclaims heap objects that are no longer reachable. In all three languages, the stack reclaims itself automatically by popping frames.

A caveat

"Objects on the heap, local-variable values in stack frames" is the standard model for reasoning about a Java program, and it is the right model for understanding lifetimes and behavior. But it describes the conceptual runtime model, not a word-for-word rule about how every JVM must represent every value internally. The JVM is allowed to optimize. For example, with a technique called escape analysis, it may avoid a heap allocation, or represent an object as separate pieces, if it can prove the object never escapes the method that created it.

The short version

• The stack holds method-call frames, including local-variable slots and method parameters. Frames are pushed when a method is called and popped when it returns, so stack storage is cleaned up automatically when the call ends. The stack is fast but limited in size.
• The heap holds objects created with new in the standard Java model. Objects live independently of method calls and can outlive the method that created them, for as long as they remain reachable. The heap is flexible but needs separate cleanup.
• A reference-typed local variable has its reference value stored in the stack frame, and that reference points to an object on the heap.
• C and C++ have the same two regions. The main differences are that they let you choose the stack or the heap for an object in source code, and that they reclaim the heap by hand or by scope rather than with a garbage collector.

I noticed that when we speak of exceptions, students immediately think of try/catch blocks, which are only one part of the story. In fact, when designing and implementing data structures, we will be more concerned with the other part of the story: how to signal an error condition by throwing an exception. The try/catch mechanism is how a client can handle that exception, but that is not our focus when we are implementing the data structure itself. So I will start with the throwing part of the story, and then cover the catching part at the end.

Signaling an Error Condition

Suppose we are implementing a list backed by an array. The interface offers a method to get the element at an index:

public interface List<T> {
    T get(int index);
    // add, remove, size, ...
}

The implementation keeps the elements in an array data, with an int size counting how many are in use. Now, what should get do when the index is invalid — negative, or past the end of the list? There are a few options, and most of them are bad.

One option is to assume the caller never passes a bad index. This is the precondition approach: the method documents "the index must be in range" and then trusts the caller.

public T get(int index) {
    return data[index]; // assumes index is valid
}

The problem is that the method now has no way to report a bad index. It can only avoid the question. Every caller has to check the index before calling:

if (index >= 0 && index < list.size()) {
    String value = list.get(index);
} else {
    // now what? return null? a default? crash?
}

This check gets repeated in every caller, written slightly differently each time, and there is no good answer for the else branch — the interface has not said what should happen when the index is invalid. And if a caller forgets the check, the bad index reaches the backing array. Sometimes that produces a cryptic failure:

Exception in thread "main" java.lang.ArrayIndexOutOfBoundsException: 10
	at ArrayList.get(ArrayList.java:42)

That message names an internal array index, not the problem the caller cares about. Even worse, if the backing array has extra capacity, an index that is past size but still inside data.length might not throw at all; it might return an unused slot instead. The method has failed to enforce the list's abstraction.

Another option, if this were a list of integers, is to return a special value to signal failure — an error code:

public int get(int index) {
    if (index < 0 || index >= size) {
        return -1; // error code
    }
    return data[index];
}

But -1 might be a perfectly valid element the list is storing, so the caller cannot tell an error from real data. And, as before, the caller has to remember to check every return value.

What we want is a way for the method itself to check the index and, when it is invalid, signal that clearly — without overloading the return value, and without relying on the caller to remember. That is what an exception is for.

An exception is an object that represents an error condition during program execution. It is a regular Java object, with a type and a place in a class hierarchy. When a method detects a condition it cannot proceed with, it can throw an exception: the method stops executing, and Java looks for code elsewhere that knows how to handle the situation.

Throwing (or Raising) an Exception

A method throws an exception when it detects an error condition it should not handle silently. The syntax is throw, followed by a new exception object:

public T get(int index) {
    if (index < 0 || index >= size) {
        throw new IndexOutOfBoundsException(
            "Index " + index + " out of bounds for size " + size);
    }
    return data[index];
}

Two things to notice. First, the check now lives inside the method, written once, instead of in every caller. Second, the message names the abstraction the caller understands — "size 5", not an internal array index. A message like "Index 7 out of bounds for size 3" tells the next developer exactly what happened; a bare exception with no message tells them nothing.

Java ships with many built-in exception types, and you should reach for them before inventing your own. A few common ones:

• IndexOutOfBoundsException — an index is outside the valid range.
• IllegalArgumentException — a method received an argument it cannot accept.
• IllegalStateException — the object is in a state where the operation does not make sense.
• NullPointerException — a null reference was used where an object was required.

For example, if our list does not allow null elements, add can reject a null argument:

public void add(T element) {
    if (element == null) {
        throw new IllegalArgumentException("Cannot add null element to list");
    }
    // ... rest of implementation
}

IllegalArgumentException is a conventional choice when the offender is a bad argument. For a null argument specifically, many Java APIs use NullPointerException; the important point is to choose the exception type that says what contract was violated.

Moving the validation into the method changes the contract. Instead of "the index must be in range" (a rule the caller has to remember), the contract becomes "if the index is out of range, you get an IndexOutOfBoundsException." The method takes on the checking, every caller gets simpler, and the error points back at the call that caused it.

Propagating an Exception

When a method throws an exception and does not catch it, the exception does not disappear and the whole program does not necessarily stop immediately. The current method stops, and the exception travels up the call stack, one method at a time, until something catches it or it reaches the top.

Consider a chain of calls:

public void processAll(List<String> names, int index) {
    analyze(names, index);       // (3) exception passes through here
}

public void analyze(List<String> names, int index) {
    processOne(names, index);    // (2) and here
}

public void processOne(List<String> names, int index) {
    String name = names.get(index); // (1) exception thrown here
}

If get throws an IndexOutOfBoundsException:

1. processOne has no try/catch, so the exception leaves it and propagates up.
2. analyze has no handler either, so it keeps going up.
3. processAll does not catch it, so it goes up again.
4. If main does not catch it, the main thread terminates and prints the stack trace.

Each method on the stack gets a chance to handle the exception, and each one here declines. Where to catch is a design decision: catch it in the method that actually knows what to do about it.

The exception object carries the information you need to make that decision. You can ask it for its message, its type, and its stack trace:

catch (IndexOutOfBoundsException e) {
    e.getMessage();               // "Index 5 out of bounds for size 3"
    e.getClass().getSimpleName(); // "IndexOutOfBoundsException"
    e.printStackTrace();          // where it was thrown, frame by frame
}

Catching an Exception

To handle an exception, wrap the risky code in a try block and handle the failure in a catch block:

public void process(List<String> names, int index) {
    try {
        String name = names.get(index);
        System.out.println("Processing: " + name);
    } catch (IndexOutOfBoundsException e) {
        System.out.println("Error: " + e.getMessage());
    }
    System.out.println("This still runs.");
}

Once the exception is caught, if the catch block completes normally, the method continues after the try/catch.

A single try block can throw more than one kind of exception, and you can write one catch per type:

try {
    names.add(element);
    names.remove(index);
} catch (IndexOutOfBoundsException e) {
    System.out.println("Index problem: " + e.getMessage());
} catch (IllegalArgumentException e) {
    System.out.println("Bad argument: " + e.getMessage());
}

Java runs the first catch whose type matches. This means order matters: list specific exceptions before general ones. If a general catch comes first, it would handle everything the specific catch could handle, so Java rejects the specific catch below it as unreachable code.

try {
    names.get(index);
} catch (IndexOutOfBoundsException e) { // specific first
    // ...
} catch (RuntimeException e) {           // general last
    // ...
}

Sometimes there is cleanup that must happen whether or not an exception was thrown — closing a file, releasing a lock. That is what finally is for; in ordinary control flow, it runs before control leaves the try/catch/finally statement:

FileReader reader = null;
try {
    reader = new FileReader(filename);
    // read the file
} catch (IOException e) {
    System.out.println("Error reading file: " + e.getMessage());
} finally {
    if (reader != null) {
        try { reader.close(); } catch (IOException e) { /* report */ }
    }
}

For resources that implement AutoCloseable, modern Java offers try-with-resources, which calls close() for you at the end of the block and replaces most uses of finally.

Two habits are worth forming. Catch specific types, not the blanket Exception, so you can respond to each failure on its own terms. And do not swallow exceptions: a catch block that does nothing hides the bug and lets the program limp along as if nothing happened. You do not have to solve the problem in the catch block, but you should at least report it.

Java's Checked vs. Unchecked Exceptions

Every exception in Java is part of a class hierarchy rooted at Throwable:

                         Throwable
                             |
              ┌──────────────┴──────────────┐
            Error                        Exception
     (OutOfMemoryError)                       |
     (StackOverflowError)        ┌────────────┼────────────┐
                           RuntimeException  IOException  SQLException
                                 |                 |           |
                   (NullPointerException)        ...         ...
                   (IndexOutOfBoundsException)
                   (IllegalArgumentException)

Error covers system-level problems we usually cannot recover from, such as running out of memory; we do not normally catch these. The exceptions we usually write and handle are under Exception, and Exception splits into two camps.

An unchecked exception, in everyday discussion, is any class that extends RuntimeException. More precisely, Java's unchecked throwables are RuntimeException, Error, and their subclasses. The compiler does not force you to catch or declare unchecked throwables; you can let them propagate without writing anything. In data-structure code, unchecked exceptions usually signal a programming error — a null you forgot to check, an index off the end. The compiler cannot detect these for you, so it stays quiet and lets them surface at runtime.

A checked exception extends Exception but not RuntimeException. The compiler tracks these: if a method can throw one, you must either catch it or declare it on the method signature with throws. Checked exceptions usually signal a problem from outside the program — a missing file, a dropped network connection, an unreachable database.

// will not compile: FileReader's constructor can throw FileNotFoundException,
// which is a kind of IOException
public void read() {
    FileReader file = new FileReader("data.txt");
}

// handle it locally
public void read() {
    try (FileReader file = new FileReader("data.txt")) {
        // read from file
    } catch (IOException e) {
        System.out.println("Could not read file: " + e.getMessage());
    }
}

// or declare it and let the caller deal with it
public void read() throws IOException {
    try (FileReader file = new FileReader("data.txt")) {
        // read from file
    }
}

The choice between them usually comes down to the source of the failure. Programming errors — a bad index, a null argument, a precondition violation — point back at the code, and we use unchecked exceptions for those. Failures from the environment — file, network, database — are conditions a correct program should anticipate, and checked exceptions are often used for those. Java forces you to handle or declare checked failures and stays quiet about unchecked bugs.

For the data structures in this course, we use unchecked (runtime) exceptions. An out-of-bounds index, or a remove on an empty list, is a programming error: the client called us incorrectly. That is exactly what unchecked exceptions are for.

Custom Exceptions

The built-in exceptions work, but they are generic:

throw new IllegalArgumentException("Invalid index");
throw new IllegalStateException("List is empty");

Sometimes a domain-specific exception reads more clearly, and the name alone tells the story in a stack trace. To write one, extend RuntimeException (since these are programming errors) and, optionally, carry structured data beyond the message. These are shown together for compactness; in a real Java project, each public exception class would usually live in its own file.

public class InvalidIndexException extends RuntimeException {
    private final int index;
    private final int size;

    public InvalidIndexException(int index, int size) {
        super("Index " + index + " out of bounds for size " + size);
        this.index = index;
        this.size = size;
    }

    public int getIndex() { return index; }
    public int getSize() { return size; }
}

public class EmptyListException extends RuntimeException {
    public EmptyListException(String operation) {
        super("Cannot perform " + operation + " on empty list");
    }
}

public class NullElementException extends RuntimeException {
    public NullElementException() {
        super("List does not allow null elements");
    }
}

The message is for humans reading a stack trace; the getIndex() and getSize() accessors let a caller inspect what happened in code. Distinct types also let a caller respond to each failure on its own terms:

try {
    String name = names.get(index);
} catch (InvalidIndexException e) {
    System.out.println("Bad index " + e.getIndex() + " for size " + e.getSize());
} catch (EmptyListException e) {
    System.out.println("List is empty: " + e.getMessage());
}

The caller branches on the kind of failure, not on the text of a message.

Code Contracts

Consider this simple abstraction:

public class CheckingAccount {
  private double balance;

  // Pre: amount >= 0
  // Post: balance is increased by amount
  public void deposit(double amount) {
    // implementation omitted
  }

  // Pre: amount >= 0 && amount <= balance
  // Post: balance is decreased by amount
  public void withdraw(double amount) {
    // implementation omitted
  }

  // Inv: balance >= 0
  public double getBalance() {
    return balance;
  }
}

The "Pre" and "Post" comments are called preconditions and postconditions, respectively. They specify what must be true before a method is called (preconditions) and what will be true after the method is called (postconditions). The "Inv" comment is an invariant, which specifies a condition that must always be true for the object. We use this to describe our code contract: the obligations of the client and the guarantees of the implementation.

For example, the preconditions for deposit and withdraw specify what the client must ensure before calling these methods, and the postconditions specify what the implementation guarantees after the method is called. If the client violates the preconditions (e.g., by trying to deposit a negative amount or withdraw more than the balance), then the implementation is not obligated to fulfill the postconditions.

A contract written only as comments still relies on the client to honor it. A robust method goes further: it enforces its own preconditions and signals a violation with an exception, so a broken contract fails loudly instead of silently corrupting state.

Robust Methods

A robust method does not trust the caller to have checked its preconditions; it checks them itself, and it does so before it changes any state. Validate everything first, then do the work:

public void add(int index, T element) {
    // validate first
    if (element == null) {
        throw new NullElementException();
    }
    if (index < 0 || index > size) {
        throw new InvalidIndexException(index, size);
    }
    // then perform the operation
    // ... implementation
}

The order matters. If a check fails, the method throws now, before any write, so the list is never left half-modified. A method that validates partway through its work can leave the object in an inconsistent state.

The other half is the message. When you throw, report both what went wrong and what you saw. Passing the offending index and the size produces "Index 7 out of bounds for size 4," which is far more useful than "invalid index."

This is the idea behind defensive programming: the data structure protects itself rather than trusting every caller to be careful. Validation lives in one place, inside the structure; the error surfaces immediately, at the call that caused it, instead of three operations later when some other method trips over the corrupted state; and every implementation of the same interface reports the same failure in the same way. The goal is an interface that is easy to use correctly and hard to use incorrectly.

T[] data = new T[capacity];   // does not compile

It feels like it should work. You can write new String[capacity] and new int[capacity], so why not new T[capacity]? The answer is a single design decision Java made back in 2004, and once you understand it, a whole cluster of generic "gotchas" stops being mysterious. That decision is called type erasure. Let's work up to it.

The generic array problem

Say we're building a small generic container, the kind of thing you write once and use with any element type:

public class Box<T> {
  private T[] data;

  public Box(int capacity) {
    data = new T[capacity];   // we'd love to write this
  }
}

The compiler stops us cold on that new T[capacity]. The usual fix is to allocate an array of Object and cast it to T[]:

@SuppressWarnings("unchecked")
public Box(int capacity) {
  data = (T[]) new Object[capacity];
}

The cast is unchecked, the compiler can't verify it, so it warns us, and we suppress the warning because data is private and we control every value that goes into it. From the outside, the box behaves exactly as if it held a real T[].

This is the standard idiom. Java's own ArrayList does exactly this: it stores its elements in an Object[] and casts on the way out. But it raises an obvious question. Why can't we just write new T[capacity] and skip the dance?

Type erasure

Here's the rule that explains it. Type erasure means generic type parameters exist only at compile time. The compiler uses them to check your code, and then it throws them away before your program runs.

So when you write this:

Box<String> b = new Box<String>(10);

the compiler checks every use of b against String, and then erases the type argument. At runtime, what's left behaves as if you'd written:

Box b = new Box(10);

The angle brackets are gone. The running program has no idea that b was ever a "box of String." And that is precisely why new T[capacity] is illegal: building an array requires knowing its component type at runtime, and by the time the program runs, T has been erased. There's no concrete type left for the array creation to use, so the language disallows the syntax outright rather than let you create something unsound.

What else erasure explains

The array restriction is the one people hit first, but it's not alone. Several of Java's generic limitations are the same fact wearing different hats:

• All instantiations share one class. Box<String> and Box<Integer> compile to the same bytecode. There is only one Box class at runtime, not one per type argument.
• instanceof can't ask about a type parameter. You can't write x instanceof T, and you can't write b instanceof Box<String>. The type argument isn't there at runtime to test against, so the check is meaningless and the compiler rejects it.
• You can't do new T() either, for the same reason new T[] fails: there's no concrete type to construct.

None of these are arbitrary rules someone added to make your life harder. They all fall out of one decision: the type argument is not around at runtime to act on.

Why Java erases

Other languages made different choices. C# keeps generic type information at runtime; C++ templates generate a separate concrete class for each type you use. So why did Java erase?

Because of history. Generics arrived in Java 5, in 2004, nearly a decade after the language shipped. By then there was already an enormous body of pre-generic code in the wild, code full of raw types like List and ArrayList with no angle brackets at all. The language designers wanted new generic code and old raw code to keep working together, in the same program, without a painful migration. Erasure made that possible: because Box<String> and a raw Box are the same type underneath, the new and the old interoperate seamlessly.

The limitations we walked through, the array problem, the missing runtime type, the broken instanceof, are the price Java paid for that backward compatibility. Whether it was the right call is a fun thing to argue about. But knowing that it was the call, and why, turns a pile of confusing compiler errors into a single idea you can reason about.

So the next time new T[capacity] won't compile, you'll know it isn't the compiler being difficult. It's just type erasure, doing exactly what it was designed to do.

What a logarithm actually is

A logarithm is the inverse of exponentiation. That single sentence is the whole game.

Exponentiation asks: start with a base, raise it to a power — what do you get? A logarithm runs that backwards: you know the base and the result; what was the power?

We write it like this:

$${\log }_{b}x=y\text{means}{b}^y=x.$$

Read ${\log }_{b}x$ as "the power you raise $b$ to in order to get $x$." The $b$ is the base.

Let's pin this down with one concrete case we'll come back to throughout this page. Take base $2$ and $x=8$:

$${\log }_{2}8=3\text{because}{2}^3=8.$$

That's it. ${\log }_{2}8$ is just the answer to "two to the what gives eight?" — and the answer is three. Whenever a logarithm looks intimidating, translate it back into that question.

(Two small print conditions, so nothing surprises you later: the base $b$ must be positive and not equal to $1$, and you can only take the log of a positive $x$. You can't raise a positive base to any power and land on zero or a negative number, so those inputs have no answer.)

Two values fall straight out of the definition:

$${\log }_{b}1=0\text{because}{b}^0=1,$$

$${\log }_{b}b=1\text{because}{b}^1=b.$$

Anything to the zero power is one, so the log of one is always zero. And the base raised to the first power is itself, so the log of the base is always one.

The laws of logarithms

There are three laws you'll lean on, plus a fourth for switching bases. Here they are together; we'll derive each one in the next section.

$$\begin{array}{rlrl}{\log }_b(xy)& ={\log }_{b}x+{\log }_{b}y& & \text{(product)}\\ {\log }_b\left(\frac{x}{y}\right)& ={\log }_{b}x-{\log }_{b}y& & \text{(quotient)}\\ {\log }_b(x^k)& =k{\log }_{b}x& & \text{(power)}\\ {\log }_{b}x& =\frac{{\log }_{c}x}{{\log }_{c}b}& & \text{(change of base)}\end{array}$$

These laws use the same conditions as before: the bases are positive and not equal to $1$, and every quantity inside a logarithm must be positive.

Notice the shape of the first three: multiplication on the inside turns into addition on the outside, division turns into subtraction, and a power turns into multiplication. A logarithm often knocks an operation down one level. That is exactly what made logarithms useful for hand calculation centuries ago, and it is why they tame the multiply-heavy counting we do when we analyze algorithms.

Before deriving anything, let's just check the product law on numbers we can verify by hand:

$${\log }_2(4\times 8)={\log }_{2}32=5,{\log }_{2}4+{\log }_{2}8=2+3=5.✓$$

Same answer both ways. Good. Now let's see why.

Where the laws come from

Every law here is an exponent law wearing a disguise. The trick is the same each time: name the logs we're working with, rewrite everything as powers of $b$, and use the exponent rule we already know.

The product law

We want to understand ${\log }_b(xy)$. Start by naming the two logs on the right:

$$m={\log }_{b}x,n={\log }_{b}y.$$

By the definition of a logarithm, that's the same as saying:

$$b^m=x,b^n=y.$$

Now multiply $x$ and $y$ by multiplying their power-of-$b$ forms:

$$\begin{array}{rl}xy& =b^m{b}^n\\ & =b^{m+n}.\end{array}$$

The second line is the one exponent law we need: multiplying same-base powers adds the exponents. Now read that result back through the definition of a logarithm — $xy$ equals $b$ raised to $m+n$, so the log of $xy$ is $m+n$:

$${\log }_b(xy)=m+n={\log }_{b}x+{\log }_{b}y.$$

That's the product law. Multiplication inside became addition outside, because multiplying powers adds their exponents.

The quotient law

Same setup, division instead of multiplication. With $b^m=x$ and $b^n=y$:

$$\begin{array}{rl}\frac{x}{y}& =\frac{b^m}{b^n}\\ & =b^{m-n}.\end{array}$$

Dividing same-base powers subtracts the exponents. Reading it back:

$${\log }_b\left(\frac{x}{y}\right)=m-n={\log }_{b}x-{\log }_{b}y.$$

The power law

Now ${\log }_b(x^k)$. Name the inner log, $m={\log }_{b}x$, so $b^m=x$. Then:

$$\begin{array}{rl}{x}^k& =(b^m{)}^k\\ & =b^{mk}.\end{array}$$

Raising a power to a power multiplies the exponents. So $x^k$ is $b$ raised to $mk$, which means:

$${\log }_b(x^k)=mk=k{\log }_{b}x.$$

A power inside comes out front as a plain multiplier. This is the law that lets us pull an exponent down — we'll use it in a moment to switch bases.

Change of base

Calculators and the laws above are happy in any base, but the log on your calculator is usually base $10$ or base $e$, while in algorithms we almost always want base $2$. So we need a way to compute ${\log }_{b}x$ using some other base $c$ we can evaluate.

Let $y={\log }_{b}x$, which means $b^y=x$. Both sides are equal, so their logs in base $c$ are equal too:

$$\begin{array}{rl}{\log }_c(b^y)& ={\log }_{c}x\\ y{\log }_{c}b& ={\log }_{c}x.\end{array}$$

The second line is just the power law applied to the left side — it pulled the exponent $y$ out front. Now solve for $y$ by dividing:

$$y=\frac{{\log }_{c}x}{{\log }_{c}b}.$$

And $y$ was ${\log }_{b}x$ all along, so:

$${\log }_{b}x=\frac{{\log }_{c}x}{{\log }_{c}b}.$$

Let's confirm it on our running example, getting ${\log }_{2}8$ out of base-$10$ logs:

$${\log }_{2}8=\frac{{\log }_{10}8}{{\log }_{10}2}\approx \frac{0.903}{0.301}=3.✓$$

There's a quiet payoff hiding here. Changing the base only ever divides by a constant (${\log }_{c}b$ doesn't depend on $x$). So ${\log }_{2}n$, ${\log }_{10}n$, and $\ln n$ differ only by a constant factor. When we care about how a cost grows rather than its exact value, the base of the logarithm stops mattering — which is why you'll often see people write just "$\log n$" and not fuss over the base.

Where this shows up in algorithm analysis

Two quick examples, both built on the same observation: doubling and halving are the operations logarithms count.

Binary search: counting halvings

Binary search looks for a value in a sorted array by checking the middle, then throwing away the half that can't contain the target. Each comparison either finds the target or cuts the remaining range roughly in half. Start with $n$ candidates:

$$n\to \frac{n}{2}\to \frac{n}{4}\to \cdots \to 1.$$

After $x$ halvings the range has size about $n/2^x$. Ignoring the small off-by-one details for the moment, the search is down to a single candidate when:

$$\begin{array}{rl}\frac{n}{2^x}& =1\\ 2^x& =n\\ x& ={\log }_{2}n.\end{array}$$

The middle line just multiplies both sides by $2^x$; the last line reads $2^x=n$ through the definition of a logarithm — $x$ is the power of $2$ that gives $n$. So binary search takes on the order of ${\log }_{2}n$ comparisons. The exact worst-case count has a small rounding/off-by-one term, but the growth is logarithmic.

Check it against our running case. With $n=8$: $8\to 4\to 2\to 1$ is three halvings, and ${\log }_{2}8=3$. Depending on exactly when the target is found, binary search may use one more comparison than the number of halvings, but the logarithm is the part that controls the growth. That's the whole reason a sorted array is worth the trouble — searching a million elements costs about ${\log }_{2}1,000,000\approx 20$ comparisons, not a million.

Counting bits: the inverse direction

Here's the same idea running the other way. For a positive integer $n$, how many binary digits — bits — do you need to write the number $n$?

Each bit you add doubles how many values you can represent. With $d$ bits you can write $2^d$ different numbers, namely $0$ through $2^d-1$. So to have a code for every value from $0$ through $n$, you need enough bits that $2^d\ge n+1$. Solving the rough version, $2^d\approx n$, for $d$ gives $d\approx {\log }_{2}n$ — the same log, because doubling-per-bit is just halving-per-step read backwards.

Pinned to a number: $8$ in binary is $1000$, which is $4$ bits. The exact count is $\lfloor {\log }_{2}n\rfloor +1$ for $n\ge 1$, so for $8$ we get $\lfloor {\log }_{2}8\rfloor +1=3+1=4$. (The floor and the $+1$ are bookkeeping for the off-by-one; the ${\log }_{2}n$ is the part that matters.)

The take-home message

A logarithm answers one question: what power gives this number? Every law is an exponent law read through that lens — products become sums, powers become multipliers, and changing the base only ever costs a constant factor. In this course, ${\log }_{2}n$ captures the number of times you can halve $n$ before reaching $1$ (exactly when $n$ is a power of $2$, and up to rounding otherwise). Keep that picture in mind and the cost of binary search, balanced trees, and good sorting algorithms will all read the same way.

How important is full stack development given that AI coding tools can now generate full stack applications fairly reliably? If it's still worth pursuing, which stack would you recommend learning?

It's a fair question. I teach a course called Full-Stack JavaScript, and I'd be concerned too if I were a student watching AI agents generate complete applications. Let me give you an honest answer, even if it's not entirely reassuring.

The short version: Yes, I still think learning full-stack development is valuable. But the landscape is changing in ways that are uncomfortable to acknowledge.

Why This Course Exists

First, let's be clear about something. I didn't create Full-Stack JavaScript out of love for JavaScript or passion for full-stack development. I created it to help students be job ready. That was my sole intention—to give you the skills needed to work as software developers, particularly building applications that businesses actually need.

The question is whether that preparation still makes sense when AI can do much of what we teach in that course.

The Complexity Spectrum

To understand where AI fits, think about software projects along multiple axes of difficulty:

• Problem familiarity: conventional → novel
• Algorithmic complexity: low → high
• Specification clarity: precise → ambiguous
• Architectural scope: localized → distributed
• External integrations: none → many
• Environment complexity: simple → complex (setup, build, deployment)
• State and data complexity: stateless → heavy state management
• Concurrency requirements: single-threaded → highly concurrent
• Non-functional constraints: minimal → strict (performance, security, compliance)
• Robustness requirements: basic → mission-critical
• Tool/API volatility: stable → rapidly changing
• UI/UX complexity: simple forms → complex flows
• Backward compatibility: greenfield → legacy integration
• And more...

The simpler a project is on each axis, the better AI coding agents do. As complexity rises along any of these dimensions, they struggle more, the same way a human developer would.

Where AI Stands Today

The hard part to admit is this: AI coding agents are excellent at the simpler-to-moderate levels of this spectrum. They can do very well what a junior software developer can do. Everything I teach in Full-Stack JavaScript—setting up servers, creating REST APIs, building React frontends, connecting to databases, deploying applications—AI can do with flying colors, much better than students just learning these skills. (And these tools keep getting better, with no sign of slowing down.)

But it hasn't bridged the gap to become completely autonomous. It's not yet at the "build me X and it shall be" stage. You still need a human co-pilot to guide it, validate its decisions, catch its mistakes, and handle the ambiguous parts.

Current evidence suggests that AI copilots work best with senior developers. Senior + AI is more productive than Senior + Junior. This creates an obvious incentive: replace junior developers with AI.

The Market Reality

This isn't speculation. The data (see [1] and [2]) is already showing the shift:

Junior roles are shrinking. Studies across 250,000 firms show that headcount for early-career software developers (ages 22-25) has been dropping steadily, right as AI coding tools spread.

Senior roles are growing. Headcount for developers aged 31 and up keeps expanding, and companies struggle to find enough senior engineers, poaching talent or buying whole companies just to secure capable developers.

And firms are cutting junior hiring on purpose. They're reducing the roles they expect to automate, because they see it as cheaper than future layoffs: cut the hiring now rather than lay people off later.

The Paradox

Here's the problem: you can't create a course that directly turns someone into a senior developer. Senior developers are made through years of experience, starting as juniors and growing through mistakes, projects, and mentorship.

This creates two possible futures:

Scenario 1: You start learning now, but before you develop senior-level skills, AI closes the gap. It becomes fully autonomous, handles complex projects, and junior-to-mid-level developers are no longer needed. You're out of luck.

Scenario 2: You start learning now, but AI fails to close the gap. The industry suffers from its reduction in junior roles. As current seniors retire, there aren't enough people to replace them because we stopped training juniors. You become extremely valuable.

I hope the second scenario happens. Unfortunately, major companies seem to be betting on the first.

So Should You Take the Course?

Despite all this, my answer is still yes—but with clear eyes about what you're getting into.

You need to understand the fundamentals. Even if AI is writing the code, someone has to know whether that code makes sense, whether the architecture is sound, whether the security implications have been considered. You can't guide an AI copilot well if you don't understand what you're asking it to build.

The complexity spectrum matters here. The full-stack development we teach sits at the simpler end on purpose, but you need those fundamentals before you can tackle the complex problems AI still can't handle on its own. You have to crawl before you walk.

Speed matters. If you're going to beat the AI gap, you can't take the leisurely four-year path. Learn intensively, build real projects, contribute to meaningful work, and move from junior to mid-level as fast as you can. The clock is ticking.

Depth still beats breadth. Don't try to learn every framework and stack. Pick one, learn it deeply, understand the principles, and get good at solving real problems. The ability to think through hard technical challenges is what will set you apart from AI. (Think about that the next time you're signing up for another humanities course!)

What About Which Stack?

You might be tempted by another angle: since AI coding agents are better at popular stacks (trained on more data, better documentation, more Stack Overflow answers), maybe you should learn something esoteric to gain an edge. This is a mistake. You're trying to compete with AI, and you can't win that game. AI will eventually cover the esoteric stacks too, and you'll have spent your time learning technologies with smaller job markets and fewer resources. You'll have optimized for being different from AI rather than being good at building software.

Put AI aside. Don't make your technology choices based on what AI can or can't do. Make them based on what you need to learn to build real applications and get real jobs. If you want to build web applications, learn JavaScript and its popular frameworks and libraries—that's where the jobs are. If you want to work on machine learning or data science, learn Python and its ecosystem. Pick something practical with real market demand, go deep, and build things that matter.

Whatever stack or domain you choose, learn to use AI well within it. The future isn't about competing with AI; it's about working alongside it. Learn the fundamentals deeply enough that you can guide AI tools, validate their output, and catch their mistakes. Use AI to accelerate your development, not to replace your understanding. The developers who thrive won't be the ones who avoid AI or try to outrun it; they'll be the ones who understand their craft well enough to make AI a force multiplier.

There's a catch, though: using AI while you're still learning can get in the way of that learning if you're not careful. There's a real tension between learning to use AI and using AI to learn. I'll write more about how to navigate this in a future post, but for now, be mindful of the difference between using AI as a tutor and using it as a ghost writer.

The Honest Bottom Line

I can't promise that learning full-stack development will help you get a job in five years. The industry is changing too rapidly, and the AI capabilities are advancing too quickly for anyone to make that promise honestly.

What I can say is this: understanding how to build software systems, even if AI is doing the typing, remains valuable. The question is whether that value translates to employment opportunities at the junior level, or whether you'll need to accelerate past that tier before the market for junior developers disappears entirely.

It's a gamble. But it's a more informed gamble than going in blind.

If you're going to make this bet, make it count. Don't just complete the assignments. Build real things. Contribute to open source. Work on projects that challenge you. Aim to be mid-level capable by the time you graduate, not entry-level.

The industry is changing. How you adapt to that change will matter more than which stack you choose to learn.

References:

• [1] Hosseini Maasoum, Seyed Mahdi and Hosseini Maasoum, Seyed Mahdi and Lichtinger, Guy, Generative AI as Seniority-Biased Technological Change: Evidence from U.S. Résumé and Job Posting Data (August 31, 2025). Available at SSRN: https://ssrn.com/abstract=5425555 or http://dx.doi.org/10.2139/ssrn.5425555
• [2] Brynjolfsson, Erik, Bharat Chandar, and Ruyu Chen. "Canaries in the coal mine? six facts about the recent employment effects of artificial intelligence." Stanford Digital Economy Lab. Published August (2025). Available at: https://digitaleconomy.stanford.edu/wp-content/uploads/2025/08/Canaries_BrynjolfssonChandarChen.pdf

My advice is simple: take fewer courses. Focus on depth over breadth. Choose challenge over convenience. For most undergraduates, fewer courses done thoroughly is the wiser default.

Graduating early: Taking more courses can let you finish in three years and save on tuition and housing. If you face serious financial constraints, consider this path. For most students who can afford the standard four years, the depth and time for advanced work outweigh the cost savings; graduating early often means sacrificing depth of learning—the real value of your undergraduate education.

If you can afford the full four years (for example, because you're on a full scholarship), you may still feel pressure to overload on courses and extracurriculars. There is a pervasive belief that more is better—that piling on courses, majors, and activities will lead to a richer experience and more opportunities after graduation. After all, whether you take 12 credits or 21+ credits, you still pay the same tuition. Why not get the most out of it? Course registration can start to resemble an all‑you‑can‑eat buffet. That's where the logic falters. Here's the case for less being more.

The Math Doesn't Work

Let's start with basic arithmetic. The federal definition of a credit hour is this: one hour of classroom instruction plus a minimum of two hours of out-of-class work per week equals one credit hour. That's three hours total per credit, per week (in a typical semester), as a minimum. So, for example, if you're taking a 3-credit course, you should expect to spend at least 9 hours per week on that course (3 hours in class + 6 hours studying at home). There are exceptions, of course! For example, a lab course may require much less outside work, while a project-based course may require much more. But as a general rule of thumb, this is the standard.

A full-time student is one whose primary occupation is studying. Full-time employment is typically considered to be around 40 hours per week. Therefore, a full-time student should be dedicating approximately 40 hours per week to their studies. At 12 credits (the minimum for full-time status at Hopkins), that's 36 hours per week. At 15 credits (a typical course load of 3–4 courses), you're at 45 hours—already above the 40-hour mark.

If you take 18–21 credits, that's 54–63 hours per week just for coursework. Now add in extracurriculars (research projects, student clubs, applying for internships, etc.), personal responsibilities, and perhaps a part-time job. It becomes unsustainable. Something has to give, and what gives is depth of learning.

While it's true that some courses require less work, that's usually at the expense of rigor and depth. An easy or superficial course can help you check a box, satisfy a requirement, or boost your GPA, but it won't grow you intellectually the way a hard one will. And that growth is the point of an undergraduate education, especially in engineering. Paying tuition for an easy A that amounts to busywork, while skipping the advanced courses that demand real effort (the ones you're unlikely to study on your own, outside the scaffolding of a class), is a poor trade when time is zero-sum. I'd take the B+ in a rigorous course over the easy A.

The credit-hour math is a minimum. In practice, most technical courses routinely exceed it, so you'll likely spend more time than that. And even if you push well past 50–60 hours a week, there's a ceiling on how much a person can absorb: the brain has finite attention and processing capacity, and piling on more courses past that point just lowers the quality of what you learn.

The Multiple Major Trap

It's common to see students major in two or more fields, often adding a minor or two for good measure. In principle, in fields with shared cores (e.g., CS + Applied Math), a second major or minor can formalize complementary depth and perhaps open doors for interdisciplinary work. In practice, however, when you commit to multiple majors within a fixed timeframe (typically four years and within a fixed credit cap), each additional major forces you to optimize for breadth over depth. Your learning becomes a series of requirements to satisfy rather than a coherent intellectual journey. You take the courses you must take, not necessarily the ones you should take.

What's worse is that many programs have adjusted their requirements to make double majors feasible. As multiple majors become common, the marginal signaling value of an additional major declines. What stands out beyond credential inflation is actual evidence of mastery: a thesis, research paper, open-source contributions, or performance in advanced electives—outcomes that require slack in the schedule.

The Extracurricular Paradox

On top of an overloaded course schedule or multiple majors, you may try to maintain research positions in labs, participate in independent studies, lead clubs, and engage in various other activities—all simultaneously. The intent is admirable. The execution is often superficial.

When you spread yourself this thin, you can't give any single activity the attention it deserves. You do the bare minimum to put a checkmark next to each item on your resume. You're present, but you're not really engaged. You're participating, but you're not making meaningful contributions. Concentrated effort on fewer, harder things yields artifacts, references, and real competence.

A Better Path

Here's what I recommend instead.

Take three or four courses a semester, and make them count. This fits both the federal credit-hour definition and the reality of deep learning. It gives you time to actually understand the material, to struggle with hard concepts, to go past the minimum.

Commit to a single major. Take the advanced courses. Take the ones that scare you a little. Build real expertise in your field. You can always take electives outside your major to explore other interests, without the pressure of satisfying a second major's requirements. No one ever got hired because they had two majors; they got hired because they were good at what they did.

Use summers for extracurriculars. If you want to do research, an independent study, or anything else, do it over the summer when you're not taking courses. Give each one the attention it deserves instead of spreading yourself thin. Take on one or two meaningful things across your whole degree, and stick with them rather than dabbling in many.

Choose challenge over convenience. Take the courses you wouldn't study on your own, where you'll learn from the professor's expertise and your classmates' perspectives. Take the ones that matter for the field you care about and genuinely challenge you. Avoid the "easy A" that doesn't stretch you. The goal is to grow, not to collect a good grade.

Plan for four years. Unless you have serious financial constraints, there's no prize for finishing early, especially if finishing early means you learned less. Many students who rush through in three years end up adding a master's year anyway. Slow down, take your time, and make it count.

The Real Value

The value of higher education isn't in the number of degrees you collect, the majors and minors you accumulate, the courses you cram into each semester, or the activities you juggle. It's in the transformation that happens when you engage deeply with challenging material—when you have time to think, question, and connect ideas across domains. That transformation, not the transcript, is what will serve you for the next forty years of your career.

That's what I want for my students. Not more courses, more majors, more activities—but deeper learning, genuine challenge, and the time and space to become truly competent in your field.

Sometimes less really is more.

If you want a feed, here it is.