Text is not what you think

Think about the last time your phone changed a word you didn't want changed. Or a website that said your password was too short. Or a game that turned your guess green, one letter at a time. Every one of those is a program taking text apart and looking at the pieces. Text feels like the easy bit of programming, because you've been reading since you were four. It isn't. Java's text hides a rule so odd that most people lose an afternoon to it the first time. You'll meet that rule in about twenty minutes, and you'll see it happen in front of you.

What you'll be able to do

• Pull any single letter out of any word, and glue letters back into text.
• Chop up, search inside and compare pieces of text — the exact toolkit you need to build Wordle next chapter.
• Say why .length and .length() are different, and read the compiler error when you swap them.
• Explain why toUpperCase() on a line of its own does absolutely nothing.

Section 1A String is a row of letters

You've just spent a whole chapter on arrays. One name, a row of numbered slots, counting from zero. Now the good news. A String is that same idea wearing different clothes. It's a row of letters, numbered from 0, with a size you can ask for. So you already know most of how text works. Nobody has told you yet.

Since 0.2 you've used String as if it were one single thing, like a number. It isn't. A String is a row of characters, in order. And in 0.2 you learned a char is a number in disguise. So the first letter of a word sits at index 0, exactly like the first slot of an array.

That's why word.charAt(3) needs no explaining. It means what slots[3] meant in 0.5. Four steps along, counting the first letter as nought. One idea, two spellings.

The toolkit, live

A list of nine methods is just a list. So here they are as a machine instead. The box starts with the word Wordle. Each row shows what one method really hands back for whatever the box holds.

Type your own name in and watch every row change at once. Then try a single letter, like a. One row turns red: substring(1, 3) cannot reach slots that don't exist. The same nine methods in real Java are in src/StringTour.java.

That's your reference — poke at it whenever you forget one. Three of those rows carry a real idea, so let's do those properly.

substring stops before the second number

Two numbers go in. The first says where to start. The second says where to stop before. So substring(1, 3) hands you slots 1 and 2, and slot 3 is left out.

That feels like a mistake until you spot the payoff. The number of characters you get back is exactly end - start. Three minus one is two. With one number, substring(7) means "from slot 7 to the end".

"rd"

indexOf says "not found" with -1

indexOf("e") hands back the slot number where it found your text. Type a word with no e into the widget. That row reads -1.

Why a negative? Because 0 is a real answer. In "egg" the e sits at slot 0. So "not found" needs a number no real slot could have. Every index is 0 or bigger, which leaves -1 free.

One method hands you an array back

split(" ") chops your text wherever it sees a space, and hands back an array of the pieces. Text in, array out. That's how a sentence becomes a list of words, and you'll use it in the project.

One catch. split doesn't read what you give it as plain text. It reads it as a pattern — a tiny search language. A space means a space, so split(" ") behaves. But a full stop means "any character at all", so split(".") hands back nothing. Patterns get a proper chapter in Phase 1. Until then, I'll say in words what any pattern I show you does.

From String to char and back

Next chapter you build Wordle, and Wordle is entirely about single letters. So you need to move between text and characters comfortably. Watch the quotes as you read: single quotes mean a char, double quotes mean a String.

String word = "crane";

char[] letters = word.toCharArray();   // text  -> array of chars
for (char c : letters) {
    System.out.print(c + "-");
}

char first = word.charAt(0);
String asText = "" + first;                  // char -> text, the quick way
String alsoText = String.valueOf(first);      // char -> text, the clear way

System.out.println(first + 1);              // ?
System.out.println((char) (first + 1));     // ?

toCharArray() takes your text apart into a real char[] — an array, with a .length and everything. From there the for-each loop walks the letters. Going the other way: stick a char onto an empty String with + and it turns into text. String.valueOf does the same job with a clearer name.

The last two lines are the trick from 0.2, where 'A' + 1 came out as 66. Do arithmetic on a char and you get a plain number back. Put (char) in front — a cast — to read that number as a letter again.

Here's what this chapter adds. charAt hands you a char, so you can do sums with it. c - 'a' gives 0 for 'a', 1 for 'b', up to 25 for 'z'. Twenty-six letters, twenty-six slots — perfect for an int[26]. That's how you walk a word letter by letter and tally what you find. You'll do exactly that in the project.

Section 2Two kinds of length, one letter apart

Chapter 0.5 told you an array's size is .length, with no round brackets, and promised text was different. Here's the payoff. It's a trap that catches people for months, and it can only trap you now that you know both forms.

int[] marks = {10, 20, 30, 40};
String word = "banana";

System.out.println("array  -> " + marks.length);    // no brackets
System.out.println("String -> " + word.length());   // brackets

Line one makes an array of four numbers. Line two makes a piece of text. Line three asks the array its size with .length and no round brackets. Line four asks the text its size with .length() and round brackets.

array  -> 4
String -> 6

Four slots. Six letters. Both right, asked two different ways.

Why the difference? An array's size is a field — a value stored on the thing itself. Think of a label stuck on a box. You just read it. A String's size comes from a method — a small piece of work Java runs for you. They are exactly like the methods you wrote in 0.4. Round brackets always mean "run this". No brackets means "read this". Arrays are built into the language at a very low level. String is an ordinary thing with methods. Not elegant. Just true.

LengthMistake.java:9: error: cannot find symbol
        System.out.println(marks.length());  // wrong: arrays have no length() method
                                ^
  symbol:   method length()
  location: variable marks of type int[]
LengthMistake.java:10: error: cannot find symbol
        System.out.println(word.length);     // wrong: String has no length field
                               ^
  symbol:   variable length
  location: variable word of type String
2 errors

Read the second error again. It doesn't say "you forgot the brackets". It says variable length. Without brackets you asked for a stored value, and String hasn't got one by that name. The compiler is describing your request back to you. That's the habit worth building: read the symbol: line as a sentence about what you typed.

Section 3Nothing you do to a String ever changes it

This is the big one. If you take one thing from this chapter, take this. Beginners lose whole afternoons to it, and the code that causes it looks completely reasonable.

String s = "wordle";
s.toUpperCase();
System.out.println("after calling toUpperCase(): " + s);

Three lines. Make a piece of text. Call toUpperCase() on it. Print it. The file carries on for a few more lines after these, and you'll see their output in a second.

after calling toUpperCase(): wordle
s      is still: wordle
shouty is now:   WORDLE
after s = s.toUpperCase(): WORDLE

The proper word for this is immutable — "cannot be changed". Once a piece of text exists in memory, those exact characters stay that way. trim(), substring(), toLowerCase(), replace() — every one hands you back something new and leaves the original alone.

Watch it happen slot by slot:

The hidden cost of gluing text in a loop

Immutability has a price, and you can measure it. Both loops below end up with 60,000 x's.

String glued = "";
for (int i = 0; i < 60000; i++) {
    glued = glued + "x";
}

StringBuilder box = new StringBuilder();
for (int i = 0; i < 60000; i++) {
    box.append("x");
}
String built = box.toString();

The first loop starts with empty text and glues an x on 60,000 times. But Strings can't change — so glued + "x" can't add to glued. It has to copy the whole thing into a new, one-longer piece of text. On round 50,000, Java copies 50,000 characters to add one. Over a billion character copies in total.

The second loop uses StringBuilder — a thing that is a whiteboard. append writes at the end of what's there, no copying. At the end, toString() takes one photograph of the result.

glued length: 60000
built length: 60000
String +=      took 144 ms
StringBuilder  took 2 ms

Why == lies about text

One more, and it's the nastiest, because it works right up until it doesn't. In 0.3 you compared numbers with ==. It's natural to reach for it with text too.

String a = "java";
String b = "java";
System.out.println(a == b);

String half = "ja";
String built = half + "va";      // same letters, made while running
System.out.println(built == a);
System.out.println(built.equals(a));

String copy = new String("java");   // a deliberate second copy
System.out.println(copy == a);
System.out.println(copy.equals(a));

The first three lines make two pieces of text, both typed out as "java". Then they compare them with ==. The next three build the same word a different way: take "ja", glue "va" on the end. Identical letters — j, a, v, a. Then compare with ==, and again with .equals. The last three do it a third way, with new String. That forces Java to make a genuinely separate copy.

two plain literals with ==      : true
built at run time, with ==      : false
built at run time, with .equals : true
new String("java") with ==      : false
new String("java") with .equals : true
printed side by side: java java

Watch the second string appear

This is the part that costs beginners hours, so here it is as a picture you can drive. On the left are the names in your program. On the right are the actual pieces of text sitting in memory. Press the button and watch carefully — count the objects before and after.

One object before, two after — and ① reads the same in both.

Section 4Project: count the letters and words in a real file

Time to put arrays and Strings together on real text. Your src/ has a small file called sample.txt — eight lines about a boy counting waves. You'll count every letter in it, draw a bar chart out of # characters, and find the most-used word.

One genuinely new tool first. Until now all your text came from your own code or a Scanner. Reading a file needs this:

import java.nio.file.Files;
import java.nio.file.Path;

String text = Files.readString(Path.of("sample.txt"));

The two import lines tell Java where to find these tools. They're not switched on by default, so you name them at the top of the file. Path.of("sample.txt") turns a filename into something Java can use to find the file. Files.readString(...) reads the whole file and hands it back as one String, newlines and all. It looks in the folder you ran java from, so run it from inside src/.

Part one: counting letters with 26 slots

String lower = text.toLowerCase();
int[] letterCounts = new int[26];

for (int i = 0; i < lower.length(); i++) {
    char c = lower.charAt(i);
    if (c >= 'a' && c <= 'z') {
        int slot = c - 'a';
        letterCounts[slot] = letterCounts[slot] + 1;
    }
}

Line 1 makes an all-lower-case copy, so T and t get counted together. It's a copy — text is untouched, because Strings never change. Line 2 makes 26 counters in one go, one per letter. All of them start at 0, because that's the default a fresh int[] gets.

The loop walks every character position from 0 up to length() - 1. Note the round brackets on length() — this is text, not an array. charAt(i) pulls out the character there. The if checks it's really a letter between 'a' and 'z'. That comparison works because chars are numbers, so spaces, commas and full stops fall outside the range and get skipped. Then the clever line. c - 'a' gives 0 for 'a', 1 for 'b', up to 25 for 'z'. That is exactly the 26 valid indexes. The last line adds one to that counter. Twenty-six named variables would be unbearable. One array makes it four lines.

Part two: counting words without a single new idea

lower.split("[^a-z]+") means "chop wherever you see one or more things that are not letters a-z". So spaces, commas, full stops and newlines all become cut points. Out comes a String[] of words.

Now count how often each word appears, using only what you know. The trick is two arrays that travel together. uniqueWords holds each different word once. wordCounts holds its tally at the same index. Word at index 4, its count at index 4. For each word from split, look through the words already seen. If it's there, add one to its count. If not, add it at the end and start its count at 1. That's the whole program, and there's nothing in it you haven't met.

One detail worth pointing at. The search uses uniqueWords[i].equals(word), not ==. Every one of these words was built while the program ran, by split. Use == here and the program finds nothing and reports every word as new.

Characters in the file: 327

-- letters --
a 27  ###########################
b 7  #######
c 9  #########
d 7  #######
e 32  ################################
...
s 27  ###########################
t 31  ###############################
u 8  ########
v 4  ####
w 1  #
y 4  ####

-- words --
Different words: 30
Most common word: "the" appears 11 times

-- words used more than twice --
the -> 11
sea -> 5
does -> 3
not -> 3
it -> 3
boy -> 4
counts -> 3
and -> 4
is -> 3

e wins at 32, then t at 31, then a and s tied at 27. That is roughly the order of letter frequency in English generally. That's the sort of thing you only notice once a program counts it for you.

Section 5Two more questions

Section 6What broke, and what surprised you

Open a plain text file and note anything from this chapter where your prediction and reality parted ways. Especially:

• Did substring(2, 4) give you three characters in your head?
• Did you reach for .length on a piece of text, or .length() on an array?
• Did you believe, even for a second, that toUpperCase() changes the String? Write that one in capitals.
• Did the == result feel wrong when you saw java java printed side by side?

Those four aren't trivia. They're the four things that will bite you next chapter. That is when you build Wordle and compare a typed guess against a secret word, letter by letter. You now have every tool that needs. An array to hold the letters. charAt to pull them out. equals to compare them honestly. And the knowledge that none of your Strings will change behind your back.