Lists of Tests, Seeds and Log Lines

Part I · Module 5 · Chapter 5.1 · Lists of Tests, Seeds and Log Lines

1. You Have Already Met One

Chapter 4.8 split a line into fields and got this back:

line = "axi_smoke 4210 PASS 182.4"
print(line.split())

['axi_smoke', '4210', 'PASS', '182.4']

At the time that chapter said the minimum — the pieces, in order — and promised the full account here. This is it.

Those square brackets are Python showing you a list: one value that holds several values in a definite order.

2. Writing One Down

You do not need split() to make a list. You write one directly, and the notation is exactly what the output above looks like:

tests = ["smoke", "reset", "interrupt"]
print(tests)

['smoke', 'reset', 'interrupt']

Read the right-hand side one piece at a time:

• [ opens the list.
• "smoke", "reset", "interrupt" are three ordinary string values, exactly as Module 4 taught them.
• Commas separate one element from the next.
• ] closes the list.

The individual values inside are called elements or items, and that is the term this module uses throughout.

The important part is what that whole thing is. ["smoke", "reset", "interrupt"] is an expression in the full Module 3 sense, and it evaluates to one value — a single list, which happens to contain three strings. The name tests then refers to that one value, exactly as Chapter 2.3 described for every other kind of value.

tests = ["smoke", "reset", "interrupt"]
print(type(tests))
print(len(tests))

<class 'list'>
3

Type list, length 3. One value, three elements.

3. Order Is Part of the Value

A list keeps its elements in the order you wrote them, and that order is part of what the value is. Two lists with the same elements in a different order are not equal:

a = ["smoke", "reset"]
b = ["reset", "smoke"]
print(a == b)

False

Same two strings, different order, different value. Put them in the same order and they are equal:

a = ["smoke", "reset"]
c = ["smoke", "reset"]
print(a == c)

True

That is == from Chapter 3.4 behaving exactly as it always has: it asks whether two values are the same, and for lists that means the same elements in the same positions.

Duplicates are allowed too, and they are real elements rather than being collapsed:

statuses = ["PASS", "FAIL", "PASS"]
print(statuses)
print(len(statuses))

['PASS', 'FAIL', 'PASS']
3

Three elements, two of which happen to be the same string. That matters: a list of results from three tests should have three entries even when two tests agreed.

4. The Empty List

A list with no elements is written with nothing between the brackets:

failures = []
print(failures)
print(len(failures))
print(type(failures))

[]
0
<class 'list'>

This is not a placeholder or an error state. It is an ordinary list value that happens to contain nothing, with a length of zero and the same type as any other list.

It is worth being precise about what empty does not mean, because Chapter 2.8 set up exactly this distinction for text:

failures = []
print(failures == None)
print(failures == [])

False
True

An empty list is not None. None means there is no value here; an empty list is a perfectly real collection that currently holds nothing — the same difference Chapter 2.8 drew between "" and None.

The empty list is how most accumulating work starts: you begin with no failures found, and add to the list as you find them. Chapter 5.3 is where adding happens.

5. Lists Hold Any Kind of Value

Nothing about a list requires its elements to be strings. Numbers work exactly as well:

seeds = [4210, 9124, 77]
runtimes = [12.4, 8.7, 19.2]
print(seeds)
print(runtimes)

[4210, 9124, 77]
[12.4, 8.7, 19.2]

Python also permits a single list to hold different types at once:

record = ["axi_smoke", 4210, True]
print(record)

['axi_smoke', 4210, True]

That is genuinely allowed, and you should know it is, because you will meet it. But permitted and advisable are different questions, and this is worth a moment of engineering judgment rather than a shrug.

Lists of paths and signal names are the everyday cases:

paths = ["rtl/top.sv", "tb/top_tb.sv"]
print(paths)
print(len(paths))

['rtl/top.sv', 'tb/top_tb.sv']
2

6. Length and Membership Carry Straight Over

You already know both of these from Chapter 4.6, and neither needs re-teaching — only applying:

tests = ["smoke", "reset", "interrupt"]
print(len(tests))
print("reset" in tests)
print("stress" in tests)
print("stress" not in tests)

3
True
False
True

len() counts the elements, not the characters. Three test names, length 3 — even though those names contain sixteen characters between them. This is exactly why Chapter 4.6 made the point that len() is a built-in function rather than a string method: the same function measures a list with nothing new to learn.

Membership works too, and here there is something genuinely new worth a moment:

tests = ["smoke", "reset", "interrupt"]
print("smoke" in tests)
print("smo" in tests)

True
False

"smoke" in tests is True because "smoke" is one of the elements. "smo" in tests is False — even though "smo" is a substring of an element.

That is the difference from strings. On a string, in asked "does this run of characters appear inside". On a list, in asks "is this one of the elements", and it compares whole elements. "smo" is not an element of tests, so the answer is False.

7. What Makes Lists Different From Everything So Far

One more property, and it is the reason this module has nine chapters rather than two.

Chapter 4.11 established that a string is immutable — there is no operation anywhere in Python that changes an existing string, which is why every string method returns a new one.

A list is mutable. A list value can be changed after it is created: you can replace an element, add one, remove one, and the list you already have becomes different. The name still refers to the same list; the list itself is now different.

That single difference is what the rest of Module 5 is about, and it is worth naming now even though the demonstration belongs to Chapter 5.3:

Everything in the first five rows is transfer from Module 4. The last row is the new idea, and it changes how you have to think about a value.

8. Predict, Run, Observe

Predict all six before reading on.

jobs = ["smoke", "reset", "smoke"]
print(len(jobs))
print("smoke" in jobs)
print("SMOKE" in jobs)
print("res" in jobs)
print(jobs == ["smoke", "smoke", "reset"])
print([] == [])

The verified output:

3
True
False
False
False
True

Length is 3 — duplicates count as separate elements. "SMOKE" is False on case alone, exactly as Chapter 4.6 established for strings. "res" is False because membership on a list matches whole elements rather than substrings, which is Section 6's point arriving in a place where it is easy to get wrong.

The fifth is False because the order differs: jobs is smoke, reset, smoke and the comparison list is smoke, smoke, reset. Same three strings, different arrangement, different value.

The sixth is True — two empty lists are equal, because they have the same elements, namely none.

9. Exercises

Exercise 1 — write three lists. Create and print a list of four signal names, a list of three seeds as numbers, and an empty list of failures. Print the length of each.

Exercise 2 — predict equality. Without running anything, say True or False for each, then verify: (a) ["a", "b"] == ["a", "b"] (b) ["a", "b"] == ["b", "a"] (c) ["a"] == "a" (d) [] == [] (e) ["a", "a"] == ["a"]

Exercise 3 — length or characters. For signals = ["clk", "reset_n", "valid"], predict len(signals), then explain in one sentence why it is not 15.

Exercise 4 — membership. Given paths = ["rtl/top.sv", "tb/top_tb.sv"], say True or False for each and explain the two that differ from what a string would give: (a) "rtl/top.sv" in paths (b) "top.sv" in paths (c) "rtl" in paths (d) "tb/top_tb.sv" not in paths

Exercise 5 — empty or nothing. Explain in two sentences the difference between failures = [] and failures = None, and say which one you would use for "no failures have been found yet".

Exercise 6 — the mixed list. A colleague writes run = ["axi_smoke", 4210, "PASS", 182.4]. Say what Python thinks of it, then give one sentence of engineering judgment about whether you would approve it and what question you would ask them.

Exercise 7 — count the value. For data = ["smoke", "reset"], how many values are there in total, and how many of them does the name data refer to? Explain your answer in one sentence.

10. Summary

• A list is one value that holds several values in a definite order. tests refers to that one list value.
• Write one with square brackets and commas. The whole literal is an expression that evaluates to a single list.
• The values inside are called elements. Type list.
• Order is part of the value. ["a", "b"] and ["b", "a"] are not equal.
• Duplicates are real elements and are counted.
• [] is an empty list — zero elements, and not None. It is where accumulating work starts.
• A list can hold any types, including mixed ones — but most useful lists hold one kind of thing.
• len() counts elements, not characters, and it is the same function you used on strings.
• in on a list matches a whole element, not a substring. "smo" in ["smoke"] is False.
• A list is mutable — unlike a string, it can be changed after it is created. That is the subject of the rest of this module.

The next chapter reaches into a list, using position rules you already know.