CSC 151: Functional Problem Solving

• Instructors: Peter-Michael Osera (sections 01 and 02), Leah Perlmutter (section 03)
• Class Meeting Location and Times: Noyce 3813
  • Section 01: 8:30–9:50 AM CT
  • Section 02: 10:00–11:20 AM CT
  • Section 03: 2:30–3:50 PM CT
• Instructor Office Hours
  • Peter-Michael Osera: Noyce 2811, by appointment: https://osera.cs.grinnell.edu
  • Leah Perlmutter: Noyce 3811, by appointment: https://calendly.com/leahperl
• Mentors: Jacob Bell (section 01), Owen Block (section 02), Tiffany Yan (section 03)
• Mentor sessions: TBD
• Evening Tutors: Caelan Bratland, Ethan Hughes, Ishita Sarraf, Boston Gunderson, Dieu Anh Trinh, Alma Ordaz, Charles Wade, Tiffany Tang, Avaash Bhattarai
• Evening Tutor Sessions: TBD

Welcome to CSC 151! In this class, you will learn computer programming using the Scamper programming language. You do not need any prior knowledge of computer science or programming.

Acknowledgements

Materials found in this course have been adapted from prior CSC 151 offerings from many instructors over the years: Eric Autry, Charlie Curtsinger, Sarah Dahlby Albright, Janet Davis, Nicole Eikmeier, Fahmida Hamid, Priscilla Jiménez, Barbara Johnson, Titus Klinge, Peter-Michael Osera, Leah Perlmutter, Samuel A. Rebelsky, John David Stone, Anya Vostinar, Henry Walker, and Jerod Weinman.

CSC 151 (Functional Problem Solving, Fall 2024)

About

• Instructors: Peter-Michael Osera (sections 01 and 02), Leah Perlmutter (section 03)
• Class Meeting Location and Times: Noyce 3813
  • Section 01: 8:30–9:50 AM CT
  • Section 02: 10:00–11:20 AM CT
  • Section 03: 2:30–3:50 PM CT
• Instructor Office Hours
  • Peter-Michael Osera: Noyce 2811, by appointment: https://osera.cs.grinnell.edu
  • Leah Perlmutter: Noyce 3811, by appointment: https://calendly.com/leahperl
• Mentors: Jacob Bell (section 01), Owen Block (section 02), Tiffany Yan (section 03)
• Mentor sessions: Sunday 6-7 pm in Noyce 3813, Thursday 8-9 pm in Noyce 3819
• Evening Tutors: Caelan Bratland, Ethan Hughes, Ishita Sarraf, Boston Gunderson, Dieu Anh Trinh, Alma Ordaz, Charles Wade, Tiffany Tang, Avaash Bhattarai
• Evening Tutor Sessions: Sundays, 3–5 PM; Sundays through Thursdays, 7–10 PM in Science 3813 and 3815

Welcome to CSC 151! In this class, you will learn computer programming using the Scamper programming language. You do not need any prior knowledge of computer science or programming.

Learning Objectives

This course covers 18 learning objectives (LOs).

• Unit 1 (Weeks 1–4)
  • Decomposition. Decompose a computational problem into smaller sub-problems amendable to implementation with functions.
  • Procedural abstraction. Take a concrete implementation in Racket and create a procedure that generalizes that behavior.
  • Tracing. Trace the execution of a Racket program using a substitutive model of computation.
  • Primitive types. Express basic computations over primitive values and their associated standard library functions.
  • Conditionals. Use Boolean expressions and conditional operations to produce conditional behavior.
  • Testing. Test programs according to good software engineering principles.
• Unit 2 (Weeks 5–8)
  • Documentation. Document programs according to good software engineering principles.
  • Local bindings. Refactor redundancy and add clarity in computations with let-bindings.
  • Lists. Manipulate lists with fundamental higher-order list functions.
  • List recursion. Design and write recursive functions over lists.
  • Numeric recursion. Design and write recursive functions over the natural numbers.
  • Higher-order programming. Write procedures that take procedures as parameters and return procedures as results.
• Unit 3 (Weeks 9–13)
  • Lambda-free anonymous procedures. Use section and composition to simplify computations.
  • Dictionaries. Design and write functions that use dictionaries.
  • Vectors. Design and write functions (potentially recursive functions) that use vectors.
  • Data abstraction. Design data structures to separate interface from implementation.
  • Tree recursion. Design and write recursive functions over trees.
  • Running time. Use a mental model of computation to count the relevant number of operations performed by a function.

Communication

Course Website : This website contains all courses policies. Course materials and homework deadlines will be posted here as they become available. Familiarize yourself with the website so you know where to find everything.

Email : Your instructor will send course announcements via email. You are responsible for reading all email from your instructor.

Microsoft Teams : Our class has a Teams channel for Q&A shared by all three sections. If you have a question and others in the class could benefit from its answer, please post in the teams Q&A channel.

Getting in touch with your instructor : If you need to get in touch with me privately, use email or teams. We try to reply to messages within about 24 hours, excluding weekends and holidays. If you do not hear back within that amount of time, please send a reminder.

Gradescope : You will submit assignments via gradescope. Please confirm that you have been added to this class on gradescope.

Class related meetings and help resources

Class meetings : Most days of class are lab days. Your instructor will make announcements and might briefly present concepts. Most of the time, you will collaborate with your lab team on programming practice problems.

Evening tutors : 5 days per week, peer educators will be available in our classroom during certain hours to help you with homework questions. You can drop in at any time to work on your homework or ask a question.

Mentor sessions : 3 times per week, a peer educator will hold a supplementary session where they might offer a review of concepts from class or practice problems. You should show up at the start of the session and stay until the end.

Informal time : You are encouraged to come to our classroom to study and work at any time that the room is not reserved for class or a meeting. This is an opportunity to studycollaborate with peers and form community.

Office hours : Your instructor will hold office hours each week. This time is for you to meet with your instructor and talk about any course related matter that you like!

Individual tutors : If you are taking advantage of the resources above and need more help, contact your instructor to request an individual tutor to meet with you one-on-one.

Academic advising : Grinnell offers academic coaches available to you as a resource to help you develop learning strategies and support you in your learning.

Deliverables

Reading responses : Prior to each class meeting, you will read an online reading assignment about computing concepts, work through code examples in a programming environment, and answer a few questions about the reading

Labs : During each class meeting, you will work with a partner to complete programming exercises to practice the concepts from the readings

Take-Home Assessments Homeworks : About once per week you will complete an individual programming assignment where you apply and extend concepts from readings and labs. No programming assignment on midterm exam weeks.

Final project : The final programming assignment will be more open ended and completed in teams.

Quizzes : About once per week, you will complete an individual, 15-minute quiz in class on paper (time extended according to any accommodations)

Exams : 4 times during the semester, you will complete an individual midterm exam in class on paper, lasting the entire class period (time extended according to any accommodations)

Pre-reflections : Before each take-home assessment homework and each exam, you will answer some reflection questions to help you prepare and feel confident to dive in.

Post-reflections : After each take-home assessment homework and each exam, you will answer some reflection questions to help you understand what went well and what went poorly.

Collaboration and Resources

• Outlook
  • Do collaborate in your learning
  • Collaborate in ways that support rather than undermining your learning
    • We'll talk about this throughout the semester!
  • On individual assignments
    • Don't do somebody else's work for them or let them do yours
  • Don't turn in the same or highly similar work
• Deliverables
  • Reading responses
    • Encouraged to work with others to understand the readings
    • Write your own answers to the reading response questions
    • You can get help from others but make sure you are able to explain your answers yourself
  • Labs
    • Typically completed in teams of 2
    • Both partners should contribute equally to all parts of the lab
    • You may ask other teams for help
    • Make sure every team member can explain your team's answers
  • Take-home Assessments Homeworks
    • Individually completed
    • As additional resources, use only what you find on the course website
    • You may get help from course staff, including evening tutors, mentors and instructors
    • You may not discuss the assessment or get help from peers, inside or outside the class
  • Quizzes
    • Completed individually in class
    • No form of collaboration is permitted
  • Exams
    • Completed individually in class
    • No form of collaboration is permitted
  • Final project
    • Completed in groups of 3–4
    • All members should contribute equally to the project
    • You may ask others for help

Grading

Deliverables

• Reading responses
  • Graded S/N based on whether you answered the assigned questions with a good faith effort
  • S = satisfactory, N = Not satisfactory
• Labs
  • Graded S/N based on whether you answered the assigned questions with a good faith effort
  • S = satisfactory, N = Not satisfactory
• Take-home Assessments and the Final Project
  • Graded EMRN based on correctness and following instructions
    • E = Exceeds expectations
    • M = Meets expectations
    • R = Needs revision
    • N = Not complete (did not make a good faith effort)
  • Criteria for each letter grade are given on the homework instructions for each assessment.
• Learning Objectives (Quizzes and Exams)
  • You will demonstrate your mastery of each Learning Objecive (LO) in assessments (quizzes or exams).
  • Each quiz gives you an opportunity to demonstrate mastery of one LO.
  • Each exam gives you an opportunity to demonstrate mastery of every LO that has been covered in class up until the date of the exam. There will be one exam problem for each LO.
  • Each LO is graded S/N
    • S = Satisfactory (demonstrated mastery)
    • N = Not Yet Satisfactory (did not yet demonstrate mastery)
  • Once you have demonstrated mastery of a certain LO, you do not need to be assessed on that LO again. That is, you can skip exam problems about LOs you have already mastered.

Final grade

Major letter grades for the course are determined by tiers, a collection of required grades from your demonstration exercises and core exams. You will receive the grade corresponding to the tier for which you meet all of the requirements. For example, if you qualify for the A tier in one category and the C tier in another category, then you qualify for the C tier overall as you only meet the requirements for a C among all the categories.

• D: two of the requirements of a C are met.
• F: zero or one of the requirements of a C are met.

Plus/minus grades

To earn a plus/minus grade, you must have completed one tier’s requirements and partially meet the next tier’s requirements. This will arise in two situations: C/B and B/A. For example, you may completely meet the requirements of a C and meet the requirements of a B for take-home assessments but not for core learning outcomes.

• If you have completed two of the upper tier's requirements, then you earn a minus grade for the higher tier, i.e., B- if you are between a C and B.
• If you have completed one of the upper tier's requirements, then you earn a plus grade for the lower tier, i.e., C+ if you are between a C and B.

Be aware that if you are at an A tier for one deliverable category but at a C tier for another, then you fully qualify for the C tier and partially meet the requirements of the B tier and thus would be considered for plus/minus grades in the B/C range.

Timely Work

You may miss turning in at most six timely work deliverables (reading questions, labs, pre- and post-reflections) without penalty. After the first six deliverables, your overall letter grade will lower by one-third of a letter grade (i.e., A becomes A-, B- becomes a C+, C becomes a D) for every two additional deliverables you miss. The following table summarizes this policy for concrete numbers of missed timely work deliverables through 12, although the policy extends to any number of missed assignments.

Deadlines and Late Days

Check the schedule to see your assignments. Check Gradescope to see the time of day that each assignment is due. Due times are typically as follows:

Readings : 10 pm the day BEFORE it appears on the schedule

Labs : 10 pm on the next lab day (except around breaks and exams)

Take-Home Assessments : 10 pm the day it appears as "due" on the schedule

Reflections : 10 pm the day it appears on the schedule

Late Days

• Late days are a currency that you can spend to turn in assignments late.
• You start the semester with 10 late days.
• You are responsible for keeping track of your own late days.
• You may spend late days on reading responses, labs, pre-reflections, post-reflections, take-home assessments, and take-home assessment revisions.
• You may spend one late day to submit any of the named assignments up to 24 hours late.
• You may spend up to two late days on any given assignment, for a maximum lateness of 48 hours on that assignment.

Redo and Revision Opportunities

• Learning Objectives (Quizzes and Exams)
  • When you earn an N on an LO, you can attempt to demonstrate mastery on that LO again on every following exam.
  • The final exam allows you to redo past LOs but does not introduce new LOs, ensuring that you get a minimum of 2 tries to earn an S on every LO.
• Take-Home Assessments
  • You may revise and resubmit take-home assessments after receiving feedback.
    • You may submit up to 2 revision assessments in each weeklong revision period.
    • Revision periods are shown in the revision form below.
  • When revised work is graded, the new grade, if higher, replaces the old grade. Submitting revised work cannot lower your grade.
  • To be eligible for resubmission, you must have completed the assessment homework in good faith on your first attempt, earning at least an R. Redo opportunities cannot be used as a way to skip take-home assessments and do them later.
  • Resubmit an assessment by filling out the Take-Home Assessment Revision Request Form and resubmitting your work on gradescope. The form also clarifies some nuances of the revision policy.
• Reading responses, labs, and reflections are graded based on good faith engagement with the assigned questions and cannot be revised for credit.

Attendance

We expect you to attend class every day because collaborative learning is such an integral part of the class. If you need to be absent, talk to your instructor as soon as you know. This means a week or more in advance for planned absences such as religious observances and sporting events.

Sick Policy

Please stay home when you are sick. Wait to come back to class until you truly feel well enough to learn. Each day that you will miss class due to illness, contact your instructor before class (or as soon as possible).

When coming back to class, wear a mask until there is no more than a normal concern of contagion. Protecting the people around you from your illness is a matter of professionalism and personal respect.

Late Work due to Illness and Time Away

You are responsible for checking the course website to see what is assigned while you are out and for completing all assigned work.

The late day and redo policies are designed to offer flexibility so that late work resulting from one or two minor to moderate illnesses or unforseen circumstances will not lower your grade in the class. If you find yourself needing to take lots of time away, please talk to your instructor about getting additional late days or increasing the number of late days you can spend on a given assignment.

Access Needs

To ensure that your access needs are met, I encourage individual students to approach me so we can have a discussion about your distinctive learning needs and how to meet them within the context of this course. In addition, Grinnell College makes formal accommodations for students with documented disabilities. Students with disabilities partner with the Office of Disability Resources to make academic accommodation letters available to faculty via the accommodation portal. You can reach Disability Resources staff via email at access@grinnell.edu, by phone 641-269-3089, or by stopping by their offices on the first floor of Steiner Hall.

Title IX and Pregnancy Related Conditions

Grinnell College is committed to compliance with Title IX and to supporting the academic success of pregnant and parenting students and students with pregnancy related conditions. If you are a pregnant student, have pregnancy related conditions, or are a parenting student (child under one-year needs documented medical care) who wishes to request reasonable related supportive measures from the College under Title IX, please email the Title IX Coordinator at titleix@grinnell.edu. The Title IX Coordinator will work with Disability Resources and your professors to provide reasonable supportive measures in support of your education while pregnant or as a parent under Title IX.

Course Tools (Fall 2024)

Development Tools

• Scamper

Communication

• Microsoft Teams
• Gradescope (section 01)
• Gradescope (section 02)

Core Exam Preparation

Core exams for the course are _timed, in-person, paper examinations. While you are not allowed to bring notes, the exam questions will contain references to appropriate library functions when appropriate.

Because the exams are paper-based, we encourage you to be intentional in your studying. Programming on a computer is different from paper where you have nothing in the way of syntax highlighting and error checking. While we are somewhat forgiving when it comes to little syntax issues, e.g., missing parentheses, you will not have time to mince over the syntax of a lambda! Subsequently, you should be comfortable in writing down the basic constructs of our language on paper.

To prepare for the course's core exams, you should:

1. Review the list of course learning outcomes for the exam found in the course syllabus.
2. Review any quiz and exam questions that you missed as they will appear on the next exam!
3. Take problems from previous assignments, e.g., reading problems, labs, and take-home assessments, and see if you can redo them on paper without support.
4. Bring any questions that arise to the course staff!

Additionally, Professor Perlmutter's course website has examples of previous exam questions for you to review if you would like to know the format of a question for a particular learning outcome.

Assessment #1: image composition and decomposition

In the first few days of class, you have received a crash-course introduction to programming in Scheme, in particular with images. Furthermore, you also learned about algorithmic decomposition and its importance in computer programming. In this project, we'll practice these techniques further by playing around with images.

On Collaboration

Each student should submit their own responses to this project. You may not consult other students in the class as you develop your solution, but you may consult members of the course staff and tutors. If you receive help from anyone, make sure to cite them in your responses.

External and internal correctness

In this course, we're concerned about writing good code. What does that look like? Good programs have two qualities we're looking after:

• External correctness: Does the program behave correctly according to its specification?
• Internal correctness: Is the program designed well?

External correctness is observable in the sense that we can run a program and determine that its behavior is correct. In contrast, internal correctness concerns the design of our program: Is it readable? Does it follow the design guidelines outlined in the exercise write-up and otherwise adhere to good coding conventions?

External correctness is often a given---we always want to write programs that do the right thing. However, we'll find in this course that internal correctness is just as important! Computer programs are not just "consumed" by computers. Other people will read and even modify our programs. In particular, you will find that in three months (or perhaps sooner), you will feel like "another person", forgetting what you were thinking when you were designing the program. So it is important that we build habits that are conducive to writing readable code.

Playing around

As we may have discussed previously, programming is not a spectator sport (really, few things are in this world). You need to write programs to learn how to program. You often need to write programs to learn to think computationally. The labs and projects will be you primary vehicle for this sort of practice. This alone may be enough for some of you to master Racket programming. But for many people, you will need additional practice to truly master these concepts.

One way to do this is through "playing around." What we mean by this is programming for the purposes of exploring a programming language or its libraries, rather than a specific end-product. This is how many of us approach learning a new language. We may have a few starting points in our back pockets, but as we write, we are less concerned about finishing the task at hand as we are about understanding the new environment. This exploration usually involves investigating and answering questions such as "How do I do X in this language?" or "How does feature X that I don't understand compare to feature Y that I do understand?" or even "How does this language lead me to think differently about algorithm design?"

Because you are beginning programmers, your questions will likely be markedly simpler: "How can I even make a thing happen?" and "how do I type a thing?". But nevertheless, "playing around" lets you tackle some of those ideas. You might start with one our lab exercises that you developed with a peer as a starting point and then change the code in ways that are novel to you. Or you might start from scratch and try to reproduce something you have seen or written before. There is no right way to go about "play". Its the attitude that's important: one of exploration and asking and answering questions rather than focusing on the final product.

Turn-in details

For this mini project, you will create three files: spaceship.scm, freestyle.scm, and my-image-utils.scm. The particular contents of each are detailed below.

Part the first: Rainbow spaceship

For this first part of the demo, your goal is to define an image called rainbow-spaceship that looks like this:

Here are the details of the rainbow-spaceship image:

• The spaceship composed of a collection of colored stripes, each of which are 100 pixels wide and 25 pixels tall.
• As the spaceship grows in height from left to right, a new colored stripe is added in rainbow order from top to bottom. The order of colors of the rainbow are red, orange, yellow, green, blue, and violet.
• The spaceship then shrinks in height past its center-point, losing a stripe from bottom-to-top order.

The "horizontal pyramid" effect is due to how the image library places sub-images with beside when they are different heights. Smaller images are automatically centered vertically relative to the taller images. For example the left-most red stripe is vertically centered relative to the red-orange two-stack of stripes next to it.

Make sure that the definition of rainbow-spaceship mimics its structure. Also pay special attention to remove redundancy from your code using define and, as appropriate, functions. We do not yet have the machinery to elegantly capture the growing, symmetric nature of the columns of the spaceship. However, note the relationship between the stripes of each successive column. How can you capture this relationship in code?

Please put your definition in the file spaceship.scm

Part the second: Freestyle

Now that you've had a taste for manipulating images and using define and functions to reduce redundancy, you will now get the opportunity to play around making images of some complexity. As discussed, this is open-ended: we have no particular image for you to draw and only some requirements about how you design your program. Feel free to try the following starting points:

• Take our image drawing / decomposition lab and improve on the pictures there.
• Find an image on the Internet and do you best to replicate it using the limited image functions we've discussed in the course. Keep in mind that your final image will likely be impressionistic in nature!
• Doodle! Start with a few shapes and try to build up interesting patterns from there.

To encourage you to practice algorithmic decomposition, your program must follow these design requirements:

• Your image should contain no fewer than five smaller sub-images that you identify and codify in your program using the define command. These sub-images should be independent of each other (i.e., not defined in terms of each other), but can then be combined together.

• Your image should employ at least one user-defined function that has at least one parameter that is employed in cutting down the code redundancy of your image in some way.

• The names you define should be evocative of what the image is. It should be pithy, a few words at most, but at the same time descriptive. Racket programming conventions say that these names should be in all lowercase with dashes between words, e.g., names-like-this.

• Your program should include a define that is the overall image, which you should call my-image.

• Your program should include introductory documentation, as below. (All of your Racket files should include similar documentation.)

  (import image)
  
  ; freestyle.scm
  ;
  ; An amazing image of <....> I've created.
  ;
  ; CSC-151 Fall 2024
  ; Homework 1, Part 2
  ; Author: Stu Dent
  ; Date: 2024-09-31
  ; Acknowledgements: ...
  
  ; (...code below here...)
  ;
  
  (define my-image...)
  

Other than this, there are no minimum requirements regarding limits, code size, or complexity. Have fun with it!

Please put your definitions in the file freestyle.scm.

Part three: Your own library functions

As you have likely noted, as your images and programs grow in complexity, it is helpful to write procedures (functions, subroutines) that encapsulate and parameterize a piece of code. For example, you may find that you regularly want to build "blocks" by overlaying an outline on a solid figure.

;;; (block size color) -> image?
;;;   size : non-negative-integer?
;;;   color : color?
;;; Create a square block of the specified size and color
(define block
  (lambda (size color)
    (overlay (square size "outline" "black")
             (square size "solid" "color"))))

Write five (5) procedures that you think will be useful in building more complex images.

Create a list of five images, one build from each procedure, and call that list examples.

(define examples (list (block 20 "red") ...))

Once again, there are no minimum requirements regarding limits, code size, or complexity.

Please put our procedures and the examples list in the file my-image-utils.scm

Part four: Generalizing images

Take the image you generated in part two and turn it into a procedure, generate-my-image, with at least two parameters (e.g., color and size) so that someone can easily make variants of that image.

Provide a call to your procedure that generates the same image you used in part 2. Call it my-image-alt.

(define my-image-alt (generate-my-image ...))

Provide a call to your procedure that generates a substantially different image. Call it my-other-image.

(define my-other-image (generate-my-image ...))

All three new definitions (for generate-my-image, my-image-alt, and my-other-image) should go in the file freestyle.scm.

A note on additional complexity

You are under no obligation to use additional functions or language features beyond what we have introduced in the first week or so of the class. However, You may feel limited by the functions we have discussed so far. If so, you are free to reference the Scamper documentation for the image library for some of the functions available (see the "Reference" link at the top of the page). Note that that both the library and the documentation are "in process". If there's something you'd like, you might ask Prof. Osera about it.

Note that this documentation may not be entirely comprehensible to you yet! That is fine. If you choose to explore this library in more detail, we recommend experimenting with these functions in a separate file and figure out how they work before throwing them into your code. Remember, if you adapt any code from this library's documentation, you should cite that you did so in a comment in your code!

Partial rubric

In grading these assignment, we will look for the following for each level. We may also identify other characteristics that move your work between levels.

You should read through the rubric and verify that your submission meets the rubric.

Redo or above

Submissions that lack any of these characteristics will get an I.

[ ] Includes the three specified files (correctly named).
[ ] Includes an appropriate header on each file that indicates the course, author, etc.
[ ] Code runs in Scamper.

Meets expectations or above

Submissions that lack any of these characteristics will get an R or below.

[ ] In Part 1, creates the correct spaceship.
[ ] In Part 2, includes at least five sub-images.
[ ] In Part 2, includes at least one procedure.
[ ] In Part 2, the image is correctly named `my-image`.
[ ] In Part 3, includes five helper procedures.
[ ] In Part 3, each helper procedure has at least one parameter.
[ ] In Part 3, includes the required `examples` list, which has the required form.
[ ] In Part 4, the procedure has at least two parameters.
[ ] In Part 4, the procedure is correctly named `generate-my-image`.
[ ] In Part 4, there is a call to generate `my-image-alt`.
[ ] In Part 4, there is a call to generate `my-other-image`.

Exemplary / Exceeds expectations

Submissions that lack any of these characteristics will get an M or below.

[ ] In Part 1, code is concise and avoids repetition.
[ ] In Part 2, image is particularly interesting or creative.
[ ] In Part 3, one or more of the helper procedures is especially innovative.
[ ] In Part 4, `my-image-alt` appears the same as `my-image`.
[ ] In Part 4, `my-other-image` appears different from `my-image`.
[ ] In Part 4, decomposes the procedure.

MathLAN: Grinnell's GNU/Linux environment

Introduction

This course is conducted using a workshop format (a.k.a. a constructivist, collaborative, computing format); on most class days you will find yourself working on the computers in our classroom. You will quickly discover that while these computers have many similarities to the computers you have used in the past, there are also some differences. (When we started teaching this course, many students hadn't used computers at all and we had to teach things like how to use a Web browser and what the Web was. You will occasionally find comments in the readings and labs that reflect that different perspective.) In this document, we will explore some of the key issues you may need to consider as you work with the GNU/Linux computers that we prefer in computer science.

Operating systems and graphical user interfaces

A modern computer is much more than a bunch of circuitry. Most of us think of computers in terms of the operating system that they run and the graphical user interface that accompanies the operating system. Those terms may be new to you, so let us consider them briefly.

As its name suggests, an operating system (also "OS") is the system used for operating the computer. It is a large computer program that manages and simplifies most of the underlying hardware. The operating system is responsible for managing files, managing other programs, dealing with the keyboard, screen, and other peripherals, and much more.

In the old days of computing (e.g., when the more senior of the CSC 151 instructors started programming), you interacted with the operating systems almost exclusively by typing on a keyboard and seeing results on a screen (yes, we had evolved beyond punchcards). There was no mouse. To us, the operating system referred to the underlying capabilities.

These days, you interact with computers through a graphical user interface (also "GUI"). Its name is similarly clear: A GUI is an interface through which you use the computer, and it's a graphical (as opposed to textual or auditory) interface. Modern graphical user interfaces stem from work at Xerox PARC, although they were introduced to the broader consumer world through the Apple Macintosh. To most modern users, the GUI is indistinguishable from the OS. (Programmers may still find it useful to distinguish between them.)

The GNU/Linux operating system

In Grinnell's computer science department, we use an operating system called GNU/Linux. GNU/Linux is distinguished by being an Open operating system, which means that anyone who has the knowledge and desire to make modifications to the program code of the operating system is permitted to do so, and a Free operating system, which means that it doesn't have to cost you anything to install it on your computer, in contrast to the Macintosh OS, which used to have a list price of about $100andwhichyoucanonlylegallyinstallonaMacintoshcomputer,ortheMicrosoftWindowsOS,whichstillhasalistpriceofabout$100. In fact, the GNU/Linux community uses "Free" in two ways, in the way we used it above (as in "Free Lemonade") and in the way we used "Open" (as in "Freedom").

Why do we use GNU/Linux rather than Macintosh OS or Windows, particularly since ITS seems to prefer Windows? One reason is that we consider GNU/Linux to be technically superior: It is less likely to crash, it is freer from viruses and other irritants, it has a much longer history of separating what the average user can do from what the administrator can do. More importantly, it is much more portable. You can sit down at any GNU/Linux computer on our network and have the same set of files naturally available. (Think about how many times you save a file on one Windows box on campus, forget to move it to your OneDrive, and then cannot access it elsewhere on campus. That will never happen on the GNU/Linux network.)

Many members of the department also have a philosophical preference for the Open Source and Free Software movements, of which GNU/Linux is an important part. We believe that good software should be free, in both senses of the word.

Xfce

GNU/Linux, unlike Macintosh OS X or Microsoft Windows, permits you to use a variety of GUIs on top of the same underlying OS. Our system administrator has chosen to use a GUI called Xfce as the default. Our experience suggests that Xfce provides an appropriate balance of power, configurability, and usability.

Xfce, like Microsoft Windows, provides a taskbar at the bottom of the screen. You will click icons on the taskbar to start applications. You may use a popup menu on the taskbar to "log out" when you are done with your work.

If you want to explore other GUIs (sometimes called Window managers), you can select your GUI when you log in to the MathLAN. Do so with caution, as some Window managers are very strange, and it may be difficult to figure out how to escape from them.

If you are interested, you can also find many ways to modify Xfce, such as moving the taskbar elsewhere.

Using GNU/Linux

So, what does this all mean for you, other than that the computer scientists at Grinnell worry about these things? It means that you will have to use an unfamiliar GUI in this course and in most future computer science courses you take. Fortunately, our configuration of Xfce is similar enough to other operating systems, particularly to Microsoft Windows, that you should find it fairly natural to use.

Like the Microsoft Windows workstations on campus, the GNU/Linux workstations require you to log in to use them. Although our GNU/Linux network once used an independent password system, it now uses the same system as the other computer systems on campus. The password system is designed so that no one, not even the MathLAN system administrator or your faculty member, will have access to your password.

Important GNU/Linux programs

In this course, you will be using a variety of programs. There are three that we consider particularly important.

• Firefox is the preferred Web browser in this course. You should be able to access Firefox through the icon in the taskbar that shows a small red animal holding a sphere.
• The terminal window supports textual interaction with the operating system. That is, it provides a kind of "textual user interface" (TUI) rather than a graphical user interface. At times, the terminal window provides the most convenient way to interact. You should be able to access the terminal window through the picture of the screen in the taskbar.

Making the most of the GNU/Linux environment

This is a class in computer science, not in using GNU/Linux. Hence, we will provide you with only the basic instructions for using GNU/Linux. It is, of course, possible to use the GNU/Linux system in more advanced ways. You may find it useful to talk to other folks who use the systems to learn particular tricks that they find valuable. We will also point out a few from time to time.

Here's one: Xfce supports multiple desktops. You can see a two-by-two grid of desktops in your taskbar, with small representations of each window. You can switch desktops by clicking on any of the four. You can also drag windows between desktops. Many people find it helpful to use separate desktops for separate tasks, such as one desktop for documentation and information and another desktop for programming. It's also useful to keep one desktop clear, so you can use it for looking at files. The corresponding lab will give you some opportunities to explore desktops.

Self checks

Self check 1: Terminology

Make a list of three important terms we used in this document and their meanings.

Self Check 2: Free and Freedom

What are the two meanings of "Free" associated with GNU/Linux? Why is each important?

Algorithm building blocks

Introduction

An algorithm is a set of instructions to accomplish a problem. As you might expect, the way we express an algorithm depends, in large part, on the audience for the algorithm. Consider the problem of making a set of chocolate chip cookies. For a beginning cook, we would have to carefully explain what it means to sift flour, the steps involved in creaming together butter and sugar, how to determine whether a cookie is done, and such. For an intermediate cook, we might not need to provide those details, but we would likely need to give an order in which ingredients are combined. For an expert cook, we might only list the ingredients and the recommended oven temperature and could assume that they would be able to figure out the rest.

Despite the wide variety of audiences and kinds of algorithms, you will find that there are a few basic "building blocks" that you will use as you construct algorithms, whether in a natural language or in a programming language. As you learn a new programming language, make sure to pay attention to how you express these blocks.

In this section, we will introduce these blocks conceptually. We'll spend the remainder of the course exploring how to realize these ideas in a computer program.

Basic building blocks (Predefined values and operations)

Even when you are writing an algorithm for a novice, you have to build upon some basic assumptions. In teaching someone to make a cookie, you can assume that they know what the different ingredients are (e.g., flour, sugar) and that they know some basic actions to do with those ingredients (e.g., stir). In teaching someone how to compute a square root, you assume that they know about numbers (including, for example, zero and one) and that they know how to work with those numbers (e.g., add, multiply). In teaching someone how to analyze a text computationally, you might assume that they know the parts of speech and, perhaps, how to parse a sentence.

Behind the scenes, computers "know" very little. But most programming languages and environments provide a rich infrastructure of values and operations on those values. We call these the predefined values and operations.

In most programming languages, you will be able to work not only with numbers, but also strings (sequences of characters), files, images, ordered collections of values, and much more. Of course, not all operations apply to all kinds of values: You would not expect to sift water or to compute the square root of a word. Hence, we often group similar kinds of values into what computer scientists refer to as a type, a collection of values and valid operations on those values.

Sequencing: ordering the operations

Most algorithms involve multiple steps. As you might expect, the order in which we perform steps can have a significant impact on the outcome of our algorithm. If we bake the ingredients of a cookie before mixing them together then we are likely to get something much less satisfactory than what we get when we mix before baking. Hence, a core aspect of most algorithms is the way we sequence the steps in the algorithm.

In some cases, you will find that you explicitly sequence the steps, telling the reader (often, the computer) to do one task, then the next, then the next. For example, you might tell a baker to shift together the dry ingredients before adding them to the liquid ingredients.

In other cases, you will express the order implicitly. For example, if you ask someone to compute 3+4x5, they should know to multiply 4x5 before adding three, even if you don't make that explicit. (Common practice suggests that on computers, we'll generally write "*" rather than "x" for the multiplication operation.)

You will discover that most programming languages have multiple ways to express both explicit and implicit ordering. Frequently, you make ordering explicit by placing the instructions in order; the computer executes them from first to last. In other cases, the ordering will be implicit, as in the computation of 3+4*5.

Variables: naming values

As you write algorithms, you will find it convenient to name things. In natural language algorithms, names are often implicit, such as "the dry ingredients" in a baking recipe. In computer languages, you will find that you more frequently need to explicitly name things, as in "let 'dry ingredients' refer to the combination of flour, baking soda, and salt". And, just as we care about the type of the built-in values, we might also specify the type of variables, using some variables to represent numbers and others to represent strings.

Computer scientists tend to refer to named values as variables, even though they don't always vary. We try to choose descriptive names for our variables to help the human reader of our programs understand their purpose. For example, a reader might be momentarily confused if we used my-name to refer to the number 5 or if we tried to multiple my-name by 2.

Subroutines: naming helper algorithms

In writing longer algorithms, you will often find that you have to explain similar processes again and again. For example, to teach someone how to make a nut-butter and preserve sandwich, you might need to explain how to open a jar twice, once for the nut butter and once for the jar of preserves. Rather than repeating the instructions, we will find it helpful to make a separate algorithm that we can refer to in our main algorithm. For that particular example, we might have an "open jar" subroutine that we can use in our sandwich algorithm.

Computer scientists use a wide variety of names for these helper algorithms. Some just call them algorithms. Many refer to them as subroutines to emphasize that they are subordinate to the primary algorithm. In programming languages, we usually call them procedures or functions.

Like the functions you've encountered in your study of mathematics, subroutines often take inputs (e.g., a closed jar) and return a newly computed value (e.g., an open jar). We tend to refer to those inputs as parameters or arguments.

Some computer scientists are careful to distinguish between functions (whose primary purpose is to compute a value) and procedures (whose primary purpose is something other than computing a value) and between parameters (what we call the inputs to a subroutine when we define the subroutine) and arguments (what we call the inputs to a subroutine when we use the subroutine). We will be a bit more casual in our usage.

Conditionals: making decisions

We've considered four basic components of algorithms: the built-in operations, sequencing, named values, and subroutines. By themselves, those three components let you write some algorithms, but only fairly straightforward algorithms. To write more complex algorithms, you need more complex algorithm structures. One of the most important kinds of structures is the conditional, which lets you make decisions based on some condition. For example, if we are writing a program that generates sentences, even after choosing the verb, we'll have to use a different form of that verb depending on whether the subject is singular or plural. Those of a more mathematical mindset might consider the problem of computing the absolute value of a number: If the number is negative, we return negative one times the number. If the number is not negative, we just return the number.

Most conditionals take one of two forms. The most basic conditional performs an action only if a condition holds.

if <some condition> holds then
  perform some actions        

For example,

if your baking powder is old then                 
  double the amount of baking powder in the recipe

More frequently, though, we use the conditional to choose between one of two options.

if <some condition> holds then      
  perform some actions              
otherwise                           
  perform a different set of actions

For example,

if you are at an elevation below 3000 feet then     
  set the oven temperature to 325 degrees Fahrenheit
otherwise                                           
  set the oven temperature to 350 degrees Fahrenheit

or

To compute the absolute value of a real number, n
  if n < 0 then                                  
    return -1*n                                  
  otherwise                                      
    return n                                     

Once in a while, you'll find that you want to decide between more than two possibilities. In those situations, we often organize those into a sequence of conditions, which we often refer to as guards.

Scheme has a variety of conditionals that we will explore once we have mastered the basics.

Repetition: repeating tasks

We've seen that subroutines provide one mechanism for repeating a series of actions. If you want to do the same thing again, but with a different input, you just call the subroutine again. However, we frequently find that we want to repeat actions a large number of times and would find it inconvenient, at best, to write the call to the subroutine again and again and again. For situations like this, most programming languages provide structures that let us concisely write algorithms that perform a task multiple times.

• We might do work until we reach a desired state. For example, in baking, we often stir solids and liquids together until the solids are fully dissolved. And, in teaching me to make bagels, my mother taught me to knead the dough until it reaches a consistency close to that of an earlobe. Many computer scientists refer to these as while loops.

• We might do work for a specified number of repetitions. For example, some recipes call for you to beat for 100 strokes. Many computer scientists refer to these as for loops.

• We might do work for each element in a collection. For example, many text analysis routines process each word in a text in turn. Many computer scientists refer to these as for-each loops. Others refer to the process of doing something to each element in a collection as mapping.

You'll discover that there are multiple ways to express each kind of repetition, as well as some more general forms of repetition.

Input and output: communicating with others

Finally, we need a way for our program to communicate with the outside world. Programs may take input from a variety of places (e.g., the keyboard, a file, a network connection) and may provide output (results) somewhere else (e.g., the screen, a file, a network connection).

Some programming systems, including Scamper, let us run programs interactively, typing expressions and seeing the results. But others will explicitly prompt for input and explicitly generate output. You will find reasons to use both the "interactive computing" mode that Scamper provides and the more general mechanisms for input and output.

Self Checks

Check 1: Reflecting on basic algorithms

Pick a non-trivial algorithm, such as a recipe for making chocolate chip cookies, and identify examples from that algorithm for each of the different algorithmic building blocks. If you wrote an algorithm on the first day of class, use that algorithm.

Check 2: Conditionals, subroutines, and repetition

Suppose we want to have the computer "read" a text and decide whether it expresses a positive or negative worldview. In what ways would conditionals, subroutines, and repetition help with this task?

An abbreviated introduction to Scamper

Introduction: Algorithms and programming languages

While our main goals in this course are for you to develop your skills in "algorithmic thinking" and apply algorithmic techniques to problems in the digital humanities, you will find it equally useful to learn how to direct computers to perform these algorithms. Programming languages provide a formal notation for expressing algorithms that can be read by both humans and computers. We will use the Scheme programming language, itself a dialect of the Lisp programming language, one of the first important programming languages. More specifically, we'll use Scamper, a derivative of Scheme custom-built for CSC 151, but we'll frequently use "Scheme" and "Scamper" interchangeably throughout the course.

One thing that sets these languages apart from most other languages is a simple, but non-traditional, syntax. To tell the computer to apply a procedure (subroutine, function) to some arguments, you write an open parenthesis, the name of the procedure, the arguments separated by spaces, and a close parenthesis. For example, here's how you add 2 and 3.

(+ 2 3)

One advantage of this parenthesized notation is that it eliminates the need for the reader or the computer to know a set of precedence rules for operations. Consider, for example, the expression 2+3x5. Do you add first or multiply first? Different programming languages may interpret it differently. On the other hand, we have to explicitly state the order, writing either (+ 2 (* 3 5)) or (* (+ 2 3) 5), using * as the multiplication symbol.

(+ 2 (* 3 5))

(* (+ 2 3) 5)

As this example suggests, we have already started to explore both basic operations (addition and multiplication) and sequencing (through nesting) in Scheme. You should keep three points in mind when writing and reading Scheme expressions.

• Parenthesize all non-trivial expressions. Parentheses tell Scheme that you want to apply a procedure to some values.
• Do not parenthesize basic values. Since there's no procedure call involved with a basic value, we do not write parentheses.
• Write expressions in prefix order. That is, you write the procedure (function, operation, subroutine) before the arguments, even if it's something like + that you would normally put between arguments.
• Sequence computations by nesting. If you have intermediate computations that you need to do, you can parenthesize them and put them within another expression.

Beyond numeric expressions

Of course, you can use Scheme for more than arithmetic computations. Here are some examples of computations with involve text.

We can find the length of a string.

(string-length "Jabberwocky")

We can break a string apart into a list of strings.

(string-split "Twas brillig and the slithy toves" " ")

We can find out how many words there are once we've split it apart.

(length (string-split "Twas brillig and the slithy toves" " "))

This operation returned a list, an ordered collection of values. In line with the parenthesized nature of the language, list values have the form (list ...) where the values of the list appear, in order, separated by spaces.

Once we have a list of words, we can find out how long each word is.

(map string-length
     (string-split "Twas brillig and the slithy toves" " "))

Computing with images

You've already seen a few of Scheme's basic types. Scamper supports numbers, strings (text), and lists of values. Of course, these are not the only types it supports. Some additional types are available through separate libraries. For example, it is comparatively straightforward to get Scheme to draw simple shapes if you add (import image) to the top of your program.

(import image)

(circle 60 "outline" "blue")

(circle 40 "solid" "red")

We can also combine shapes by putting them above or beside each other.

(import image)
(above (circle 40 "outline" "blue")
       (circle 60 "outline" "red"))
(beside (circle 40 "solid" "blue")
       (circle 40 "outline" "blue"))
(above (rectangle 60 40 "solid" "red")
        (beside (rectangle 60 40 "solid" "blue")
                (rectangle 60 40 "solid" "black")))

As you may have discovered in your youth, there are a wide variety of interesting images we can make by just combining simple colored shapes. You'll have an opportunity to do so in the corresponding lab.

"Scheme" versus "Racket" versus "Scamper"

You may hear about another programming language, Racket, from peers who have taken prior versions of CSC 151 or from the various course readings and labs. Racket is a dialect of Scheme. That is, it is a language derived from Scheme that shares many of the same language constructs and libraries, but also improves on the language in various ways.

In the past, CSC 151 has used Racket as it is a modern, full-featured take on Scheme. However, in order to support the themes of the course, we developed our own implementation of Scheme, Scamper. In many ways, Scamper draws on modern Racket-isms, but it isn't truly a descendent of Racket as it tries to retain the simplicity of Scheme and thus doesn't adhere precisely to Racket's language standard.

For our intents and purposes as beginning programmers, Scheme, Racket, and Scamper, are all interchangeable names describing the same "functional language with parentheses" that we use in this course. So don't fret too much if you hear a different name from a peer or see a different name in a reading! However, if want to be precise, we are using:

A dialect of Scheme, custom-built for CSC 151, called Scamper.

Self Checks

Check 1: Reflect on procedures (‡)

Make a list of five or so procedures you've encountered in this reading, the number of parameters, the types of those parameters (e.g., do they require numbers or strings), and their behavior.

For example,

The length procedure takes one parameter, which must be a list, and returns the number of elements in the list.

Check 2: Some other examples (‡)

Predict the output for each of the following expressions. Be prepared to discuss them in class. Do not try them on your own.

(* (+ 4 2) 2)
(- 1 (/ 1 2))
(string-length "Snicker snack")
(string-split "Snicker snack" "ck")
(circle 10 'solid "teal")

Check 3: Precedence (‡)

Consider the expression 3 - 4 × 5 - 6{:.language-text}.

If we did not have rules for order of evaluation, one possible way to evaluate the expression would be to subtract six from five (giving us negative one), then subtract four from three (giving us negative one), and then multiply those two numbers together (giving us one). We'd express that in Scheme as

(* (- 3 4) (- 5 6))

{:type="a"}

1. What is the "official" way to evaluate that expression?

2. How would you express that in Scheme?

3. Come up with at least two other orders in which to evaluate that expression.

4. Express those other two orders in Scheme.

Getting started with GNU/Linux

Introduction

This lab gives you the opportunity to explore (or at least configure):

• Logging In
• The Xfce window environment
• Firefox
• Working with multiple desktops
• Finishing up and logging out

Please don't be intimidated! Although this lab contains many details which may seem overwhelming at first, these mechanics will become familiar rather quickly. Feel free to talk to the instructor or with a CS tutor if you have questions or want additional help!

Logging in

Short version

• On the computer in front of you, you should see a small window that asks you to log in. If you don't see such a window, try hitting a key on the keyboard or clicking the power button on the monitor.
• Enter your user name. Press the Enter key.
• Enter your password (which won't appear on the screen). Press the Enter key.
• Get help if those previous two steps don't work.

Detailed version

To use any of the computers on Grinnell's GNU/Linux network, one must log in, identifying oneself by giving a user name and a password. MathLAN workstations are configured to use the same username and password as other Grinnell services. If you do not know your Grinnell username or password please tell the instructor soon; we will need to contact ITS to reset your account information.

When a GNU/Linux workstation is not in use, it will display a login screen with a space into which one can type one's user name and, later, one's password. (If the workstation's monitor is dark, move the mouse a bit and the login screen will appear.) This window belongs to xdm, the Xwindows Display Manager. Now, move the pointer onto any part of the box containing the login box. Type in your user name, in lower-case letters, and press the Enter key. The login screen will be redrawn to acknowledge your user name and to ask for your password; type it into the space provided and press Enter. (Because no one else should see your password, it is not displayed on screen as you type it.)

At this point, a computer program that is running on the workstation contacts the College's authentication server to validate the user name and password. If it does not find the particular combination that you have supplied, it prints a brief message saying that the attempt to log in was unsuccessful and then returns to the login screen -- inviting you to try again. Consult the instructor or the system administrator if your attempts to log in are still unsuccessful. (Make sure that you don't have any spaces before your username; that's one of the most common errors.)

The Xfce window environment

Short version

• You'll see something that looks somewhat like Microsoft Windows, but also somewhat different.
• Icons at the bottom of the screen can be used to start programs.

Detailed version

Once you have logged in, a panel will appear at the bottom of the screen. Some other windows also may be visible in other parts of your screen. All of these areas are managed by a special program, called a window manager. On our network, login chores and other administrivia are handled by a program or operating system, called GNU/Linux, and the primary user interaction is handled by a window manager (GUI), called Xfce.

Firefox

Short version

• Start Firefox by clicking on the picture of the small red creature grasping a blue sphere. If Firefox doesn't work, feel free to use Chrome.
• Agree to any dialog boxes that appear. They shouldn't appear again. You also may not see any dialog boxes.
• Navigate to the course website, available at <{{ site.url }}>.

Detailed version

While some materials for this course will be available in paper, almost everything for this course (including electronic versions of paper materials) will be available on the internet. To use Firefox to view materials, such as this course's syllabus and this lab, you may follow these steps:

Click the Firefox icon on the panel, next to the Applications menu. The Firefox icon is a small red creature (presumably a fox) holding a bluish sphere.

If you do not see the Firefox icon, then move the pointer onto the Applications Menu icon at the bottom left of the panel (in Xfce, it looks like a creature on a blue X) and click once with the left mouse button. The applications menu will pop up. Move the mouse over Internet, then Firefox. Click the left mouse button once to launch Firefox.

Some students have discovered that Firefox doesn't launch. If that happens, it may be that the launcher references the wrong version of Firefox. Ask one of the class staff to change the launcher from firefox-esr %u to just firefox. Or just do it yourself.

The materials for this course will walk you through using the Firefox web browser, but a version of Google Chrome is available on MathLAN workstations as well in the Applications menu under the Internet section. You can add this browser your panel if you prefer. (You can add something to your panel by dragging it from the menu to the panel.)

The first time you run Firefox on our network, two message boxes might appear.

• One box might ask you to consent to the terms of a licensing agreement.
• One box might request permission to create some configuration files in your home directory.

You should approve of any requests by clicking on the appropriate word. The pop-up boxes then disappear; you should not see them on subsequent uses of Firefox. It's also okay if the boxes don't appear; Firefox's behavior keeps changing.

Initially, Firefox displays a document containing some default information. You should navigate to the course website at <{{ site.url }}>.

We expect that most of you are already familiar with a Web browser. If not, please consult with one of us or with one of your colleagues.

Firefox options

Short version

• Click on the menu icon (a set of three lines) in the upper-right-hand corner of the screen.
• Click on the Settings menu.
• Click on Home.
• Next to "Homepage and new windows", click on Firefox Home (Default).
• Select Custom URLs....
• Update your home page to something reasonable like this course's website at or the Grinnell Office365 page.
• Quit and restart Firefox to verify that your new home page appears. If you see something other than your home page (e.g., the Grinnell College home page), then ask for help.

Detailed version

Each GNU/Linux user can configure Firefox to reflect her, his, zir, or their own preferences. Between logins, these preferences are stored in a file in the user's home directory; when Firefox is started during a later session, they are reinstated from that file.

Every user of Firefox in this class should establish a base page, a starting point for browsing. Here are the Uniform Resource Locators or URLs of some good choices:

• The main page for this course: <{{ site.url }}>
• The computer science department website: https://www.cs.grinnell.edu
• Grinnell College's main page: https://www.grinnell.edu
• Grinnell's Office365 website: https://office365.grinnell.edu
• GrinnellShare: https://grinco.sharepoint.com
• A page you create.

To establish your base page within Firefox, bring up the primary Firefox menu from the menu bar by clicking on the icon with three lines in the upper-right-hand corner of the window. Then select the Settings operation. You should then see a new screen that permits you to configure many aspects of Firefox. Click the Home button on the left. In the home settings screen, you should see a section labeled New Windows and Tabs, the first entry of which is "Homepage and new windows". Click on Firefox Home (Default). Select Custom URLs.... Paste in one of the recommended URLs. (This does not have to be a permanent change; you can change your mind about this configuration at any time within Firefox.)

To erase the current contents of the Home Page Location(s) box, move the mouse pointer to the left of the first character in the box, press the left mouse button and hold it down, and drag the mouse pointer rightwards until the entire URL is displayed in reverse video, white letters on a black background. Then release the left mouse button and type the new URL; the old one will vanish as soon as you start typing. Once you have entered the new URL, move the mouse pointer onto the button marked OK at the bottom of the pop-up window and click on it with the left mouse button.

You can, of course, simply navigate to the page you want to use as your home page and then click on Use Current Pages.

You may note that the button says "Pages" (plural) rather than "Page" (singular). Since Firefox permits tabbed browsing (that is, you can have "tabs" within the same window that you switch between), you can have a home set of tabs. Particularly obsessive people might want to set up a sequence of tabs with say, links to labs, readings, and beyond.

Note that some folks have a default launcher for Firefox that is configured to start the web browser on a specific page, regardless of the home page you choose. If you don't see your new home page when you restart Firefox, then ask for help.

Working with multiple desktops

If you've kept all those windows open, you'll notice your screen is getting a bit crowded. Fortunately, a tool called the workspace switcher lets you uncrowd your windows by moving them among multiple desktops.

Short version

• Find the workspace switcher icon in the workspace toolbar.
• Click on the switcher to move to a different desktop.
• Drag windows within the switcher to move them to other desktops.

Detailed version

In the toolbar at the bottom of the screen, you should see an icon that looks like a box containing four smaller boxes. (If you don't see it, ask for help.) This is the workspace switcher, a tool that lets you keep your application windows on several different desktops or workspaces.

The upper-left-hand box represents the desktop you are working on right now. It contains a number of still smaller boxes of varying shapes and sizes, which represent the windows you have open. When you move or resize the a window on the desktop, you should see the window's representation in the switcher move as well. Give it a try by wiggling one of your windows around.

Now, click in one of the other three boxes. You should see a new, blank desktop with no windows on it. Where did they go? If you look at the switcher, you'll see they are still in the desktop you started on. Switch back to that desktop.

You can also use the switcher to move windows from one desktop to another. Find the switcher again and identify the box that corresponds to your Firefox window. Click that box and drag it a little ways to the right, onto the next desktop. The window should disappear from the first desktop. If you click onto the desktop to the right, you should see it there.

In this class, you'll usually need to work with multiple windows: The DrRacket window for your programs, a terminal window or two, and a Web browser to read the laboratory exercises and reference materials. As you get settled in over the next few weeks, consider how you might use the switcher to help you organize your workspace efficiently.

By default, the workspace switcher presents four workspaces arranged in two rows of two each. If you want to change this configuration, right-click on the workspace switcher and select Properties to change the number of rows. Clicking on Workspace settings... will let you change the number of workspaces.

Caution: If you use the mouse scroll wheel while your cursor is over the empty desktop area, you will switch workspaces. This sometimes alarms students as it appears to have closed all of your running applications. You can switch back to the correct workspace by clicking in the workspace switcher. If this bothers you, you may want to reduce the number of workspaces to just one.

Finishing up and logging out

If you've successfully logged in, started Firefox, selected your home page, tried DrRacket, configured your account, and played with multiple desktops, you've completed the lab and you can finally stop.

Short version

• To log out, click on the icon at the lower right corner of the screen, and select Log Out.
• Do not turn off the monitor or computers.

Detailed version

When you are done using a workstation, you must log out in order to allow other people to use it. To log out, move the pointer onto your username, at the lower right corner of the screen, and click the left mouse button. A menu will pop up giving several options. Move the pointer onto the words Log Out at the bottom of the menu and click the left mouse button. A confirmation dialog will appear, giving you 30 seconds to change your mind. Click the Log out to log out immediately. The Xfce window manager vanishes, and after a few seconds the login screen reappears; this confirms that you're really logged out.

Please do not turn off the workstation when you are finished. The GNU/Linux workstations are designed to operate continuously; turning them off and on frequently actually shortens their life expectancy. Modern computers use very little power when they are sitting idle, so this is not a significant waste of resources.

An introduction to Scamper

In this laboratory, you will begin to type Scamper expressions. Scamper is the language in which we will express many of our algorithms this semester. Scamper is a particular implementation of Scheme (which varies a bit from the Scheme standard).

Introduction

Many of the fundamental ideas of computer science are best learned by reading, writing, and executing small computer programs that illustrate those ideas. One of our most important tools for this course, therefore, is a program-development environment, a computer program designed specifically to make it easier to read, write, and execute other computer programs. The Scamper language that we use in the course is also an in-browser integrated development environment (IDE for short). Scamper is a dialect of a language called Scheme, which is itself a dialect of a language called Lisp. Although Scamper is a dialect of Scheme, we will often refer to our language of choice as either "Scamper" or "Scheme." (And you may hear us also mistakenly refer to the language as "Racket" which is a more full-featured dialect of Scheme that was used in previous version of the course!)

In this lab, we explore the Scamper language and its associated program development environment.

Preparation

Scamper is available online and works on any machine with access to a modern web browser (i.e., Chrome, Firefox, Safari, or Edge):

• https://scamper.cs.grinnell.edu

Unlike many other web applications you have encountered, Scamper exists as a pure front-end web application. This means that your files are saved locally in your browser rather than on a server. The corollary to this fact is that if you move between web browsers or machines, you will need to manually shuffle your programs around!

Right now, this isn't an issue, but later in the course once we have writte a number of programs, we'll talk about backing up and transferring your work between machines.

Exercises

For many of our in-class lab activities, you will work with a partner. To help you manage the work between yourself and your partner, the lab instructions will specify how you should work with your partner for each exercise.

• When working collaboratively, make sure to actively engage your partner. Ask questions, share thoughts, and come to a common consensus on the problem. We will have more to share about productive collaborative work in future labs. For now, keep in mind the golden rules of collaborative learning:

  Create an environment where your partner feels comfortable sharing, failing, and ultimately learning. You will find that you will also learn better in this environment, even if you think you know the answers already!

The technique we use in this class is a variant of "pair programming", a commonly used technique for programming and for learning computer science. In pair programming, we designate the person at the keyboard as the "driver" and the person working with them as the "navigator". As in most driver/navigator situations, both driver and navigator play important roles. You should designate one of the two of you "A" and one of you as "B". Each problem will designate whether A or B drives.

You should plan to spend about five minutes on each exercise, perhaps a little less. If you begin to exceed this estimated time for an exercise, grab your instructor or class mentor and ask for help.

In this lab, you will work in a Scamper source file that you create and save called shapes.scm. When turning in your work for this lab, you only need to turn in one copy of this file to Gradescope. However, you should make sure to include both your name and your partner's name in the Gradescope submission!

Exercise 1: Writing Scamper code

Driver: A

In Scamper, programs exist as text written in a source file, i.e., a program. The Scamper IDE let's you create and manage source files entirely within the web browser. As we shall see by the end of this lab, these files are separate from the files on your computer and must be downloaded to be submitted to Gradescope, sent to your partner, etc.

• Navigate to the Scamper IDE: https://scamper.cs.grinnell.edu
• Click on "Create a new program" to create a new source file and name it shapes.scm. .scm is the filename extension traditionally associated with Scheme program files.

This will open up the Scamper editor pointed at your new file shapes.scm.

Next, let's write a few examples in our new source file. Type each of the following code snippets, called expressions, into shapes.scm. After you type each expression, run your program by clicking on the run button (▶) in the toolbar. See if you get the same values as us!

(Note: make sure to type these snippets rather than copy-pasting them in. It is important to get a programming language, literally speaking, in you fingertips rather than just in your head!)

(sqrt 144)

(+ 3 4)

(+ 3 (* 4 5))

(* (+ 3 4) 5)

(string-append "Hello" " " "World!")

(string-split "Twas brillig and the slithy toves" " ")

(length (string-split "Twas brillig and the slithy toves" " "))

Of course, one should not just thoughtlessly type expressions and see what value they get. Particularly as you learn Scamper, it is worthwhile to think a bit about the expressions and the values you expect. The self-check in the reading asked you to predict some values. Determine whether your prediction matches what Scamper computes.

(* (+ 4 2) 2)

(- 1 (/ 1 2))

(string-length "Snicker snack")

(string-split "Snicker snack" "ck")

(circle 50 "solid" "teal")

If you get an unexpected error message in one or more cases, that may be part of the intent of this exercise! Feel free to go on to the next exercise, but if you are confused by any of the output that you get, ask the instructor!

Exercise 2: Libraries

Driver: A

As you may have noted, you get an error when you try to make a circle.

(circle 50 "solid" "teal")

Why do you get an error? Because the circle procedure is not immediately available in Scheme! Some library functions are automatically included in every program. The set of these functions is typically called the language's prelude or standard library. Instead, circle and other image-drawing functions are part of the image library. We need to tell Scamper that we would like to include this module with a import statement. At the top of your shapes.scm file, add the following line:

(import image)

Click the run button and try making the circle again. If you get an error message still make sure to ask for help!

Note in the examples below, we'll include this import statement in each code snippet. This is because each code snippet on this page is treated as an individual program by the Scamper runtime. So we need to duplicate the import statement for each snippet. In contrast, you are writing all of your work within a single file, shapes.scm, so you only need to include the import statement once at the top of the file.

Exercise 3: Experimenting with images

Driver: B

Now that we've told Scheme to load the image library, let's check the image examples from [the reading]({{ "/readings/scamper.html" | relative_url}}). Enter each of the following expressions into the bottom of your shapes.scm file. After entering each expression, rerun your program and observe that your output matches what you see in this writeup.

; Remember: this import statement only needs to appear once at the top of the file!
(import image)

(above (circle 40 "outline" "blue")
       (circle 60 "outline" "red"))

(beside (circle 40 "solid" "blue")
        (circle 40 "outline" "blue"))

(above (rectangle 60 40 "solid" "red")
       (beside (rectangle 60 40 "solid" "blue")
               (rectangle 60 40 "solid" "black")))

Why did we have you check these examples, given that they already appear in the reading? For a few reasons:

1. To remind you that you should not always trust what you read. (We will generally not intentionally deceive you, but there may be times in which we make a mistake.)
2. The same program may not behave the same for all users, depending on how their system is configured.
3. You learn a bit by typing the text by hand and reminding yourself of what you expect. Part of learning how to program is getting the language "under your fingers" in a very tactile, physical sense.

Exercise 4: Reflection: How do you know a result is correct?

Driver: B

Of course, the computer is using some algorithm to compute values for the expressions you enter. How do you know that the algorithm is correct? One reason that you might expect it to be correct is that Scheme is a widely-used programming language (and one that we've asked you to use). However, there are bugs even in widely-used programs. For example, a number of years ago, a bug was discovered that was causing a common computer chip to compute a few specific values incorrectly triggering a costly recall of the silicon. Another bug in Microsoft Excel produced the wrong output for a few values. And you may have some evidence that your faculty like to trick you. Hence, you might be a bit suspicious.

Each time you do a computation, particularly a computation for which you have designed the algorithm, you should consider how you might verify the result. (You need not verify every result, but you should have an idea of how you might do so.) When writing an algorithm, you can then also use the verification process to see if your algorithm is right.

Let's start with a relatively simple example. Suppose we ask you to ask Scamper to compute the square root of 137641. You should be able to do so by entering an appropriate Scheme expression:

(sqrt 137641)

Scamper will give you an answer. How can you test the correctness of this answer? What if you don't trust Scamper's multiplication procedure?

Discuss this question with your partner and come up with common definition of how to test your answer in this context. Once you have a common definition, check your answer with a member of the course staff. (Note: for this exercise, you do not need to write anything in your file!)

Exercise 5: Writing Scheme source code

Driver: B

So far, we have written singular expressions into our source file, each of which produce a single output. More generally, our programs contain a collection of definitions that can be used in a top-down fashion. In other words, earlier definitions can be used in later definitions.

{:type="a"}

1. Enter the following definitions from the reading into your program:

   (define trial01 11.2)
   (define trial02 12.5)
   (define trialO3 8.5)
   (define trial04 10.6)
   

2. Now, let's use these definitions in an expression. Add the following expression to your program. What do you think will happen? Try to predict the result before hitting Enter!

   (* 0.25 (+ trial01 trial02 trialO3 trial04))
   

3. It is likely that you got an error message. Discuss with your partner why this might be the case.

4. As you've likely hypothesized, the definition for trial03 was mistakenly typed as trialO3. (That is, it contains the letter "O" rather than the numeral "0".) Correct the definition in your file, reopen the exploration panel, and try entering the expression again.

5. Congratulations, you've successfully computed the average trial score! (At least you should have.) If not, review the error and try to fix it on your own with your partner's help. If you get stuck, hail down an instructor or mentor!

6. Observe that you've copied code from elsewhere! That means that you have a responsibility to insert a comment that cites the original authors. A comment is a part of a program that has no effect on the execution of the program. We use comments in programs to explain our code or document different aspects of it, an important part of the software engineering process that we will discuss in more detail later in the semester.

   In Scheme (and Scamper, too), comments start with a semicolon and extend to the end the line. Here's one possible citation.

   ; From the CSC 151 course materials:
   ;   _URL_.
   

   Insert that citation into shapes.scm, using the appropriate URL for this webpage.

Note: You may encounter different expectations about the appropriate form of citations. Make it a habit to start by copying and pasting the URL of a document whenever you copy and paste code. Doing so shows that you have the appropriate intent. If you are expected to provide a full citation, you can go back later and add it.

Exercise 6: Definitions, revisited

Driver: A

Let's try another definition. Define name as your name in quotation marks. For example,

(define name "Student")

(Replace Student with your own name for the proper effect.) Enter the expression below in your file and run your program to determine what this expression does with your name.

(string-append "Hello " name)

Next, find the number of characters in the string with the following expression.

(string-length name)

Note how this definition acts as shorthand: where ever name appears in the code, the string "Student" is substituted instead. We'll discuss these definitions---which define variables---in detail in a subsequent class!

Exercise 7: Image definitions

Driver: A

{:type="a"}

1. Clear the current contents of your shapes.scm file.

2. In shapes.scm, write definitions for blue-circle, a solid circle of radius 40, red-square, a solid red square of edge-length 80, and black-rectangle, an outlined black rectangle of width 120 and height 40.

   (import image)
   ; shapes.scm
   ; A file from the first lab for CSC-151-NN SEMESTER
   ; Authors: 
   ;   STUDENT ONE
   ;   STUDENT TWO
   ; Acknowledgements:
   ;   Any help you got
   
   (define blue-circle
     ??)
   
   (define red-square
     ??)
   
   (define black-rectangle
     ??)
   

3. Run the program and verify the output is what you expect. If you run into any issues, please make sure to ask a member of the course staff.

4. You may recall that we can combine images with above and beside. Predict the output of each of the following.

   (beside blue-circle red-square)
   
   (beside red-square blue-circle)
   
   (beside blue-circle blue-circle)
   
   (beside blue-circle red-square blue-circle red-square blue-circle)
   
   (beside red-square black-rectangle)
   
   (above blue-circle black-rectangle)
   
   (beside red-square (above black-rectangle black-rectangle) red-square)
   
   (above black-rectangle (beside red-square blue-circle))
   

   After you have made your predictions, add each line to your program and observe the results. Were you correct in your predictions? If not, try to identify the cause of your mistake. Ask your partner questions or ask the instructor!

Exercise 8: Another image definition

Driver: A

Define a simple image (which you define as image using define) by combining those three basic shapes with above and beside. Feel free to experiment and have fun with it!

Exercise 9: Exporting files

Driver: B

Let's make sure that you can save your work and export your program to turn in, share with your partner, etc. Clicking the "Scamper" link in the top-left corner of the Scamper IDE will send you back to your list of files. From this list, you can save your program as a file on disk by hovering over the shapes.scm file and clicking on the download icon (the left-most icon).

By default, this file is saved to the Downloads folder of your home directory. Use Linux's file explorer to navigate to this file and verify that it has been downloaded. At the end of this lab, you should donwload your completed file and email it to your partner, so they have a copy of your work.

Exercise 10: Other notations

Driver: B

As you've learned, Scheme expects you to use parentheses and prefix notation when writing expressions. What happens if you use more traditional mathematical notation? Let's explore that question.

Type each of the following expressions at the Scheme prompt and see what reaction you get.

• (2 + 3)
• 7 * 9
• sqrt(49)
• (+ (87) (23))

You may wish to read the notes on this problem for an explanation of the results that you get.

Turning it in

Turn in the shapes.scm file to Gradescope under the appropriate lab assignment. When doing so, please make sure that you submit the assignment as a group assignment and include your partner's name in the submission!

For those with extra time

If you find that you have finished this laboratory before the end of class, you may try any of the following exercises.

Extra 1: Compound images

Add code to shapes.scm to make an image of a simple house. If you are so inclined, you can use the (triangle edge-length 'solid "color") procedure to create a triangle for the roof.

Extra 2: Definitions, revisited

As you observed in the primary exercises for this laboratory, you can use the definitions pane to name values that you expect to use again (or that you simply find it more convenient to refer to with a mnemonic). So far, the only numbers we've named are simple values. However, you can also name the results of expressions.

{:type="a"}

1. In shapes.scm, write a definition that assigns the name seconds-per-minute to the value 60.

2. In shapes.scm, write a definition that assigns the name minutes-per-hour to the value 60.

3. In shapes.scm, write a definition that assigns the name hours-per-day to the value 24.

4. In shapes.scm, write a definition that assigns the name seconds-per-day to the product of those three values. Note that you should use the following expression to express that product.

   (* seconds-per-minute minutes-per-hour hours-per-day)
   

5. Run your definitions and confirm in the exploration panel that seconds-per-day is defined correctly.

Notes on the exercises

Notes on Exercise 10: Other notations

When entering an arithmetic expression in the "natural way," i.e., (2 + 3), Scamper reports the following error:

(2 + 3)

When Scamper sees the left parenthesis at the beginning of the expression (2 + 3), it expects the expression to be a procedure call, and it expects the procedure to be identified right after the left parenthesis. But 2 does not identify a procedure; it stands for a number. (A "procedure application" is the same thing as a procedure call.) Instead, Scamper tries to interprets the 2 as a variable, but a number cannot be a variable!

Parentheses in Scamper (and Scheme) are surprisingly important! Observe the following code snippet, 7 * 9, similar to the snippet above but without parentheses.

7 * 9

In the absence of parentheses, the Scamper sees 7 * 9 as three separate and unrelated expressions -- the numeral 7; *, a name for the primitive multiplication procedure; and 9, another numeral. It interprets each of these as a command to evaluate an expression: "Compute the value of the numeral 7! Find out what the name * stands for! Compute the value of the numeral 9!" So it performs the first of these commands and displays 7; then it carries out the second command, reporting that * is a function; and finally it carries out the third command and displays the result, 9. This behavior is confusing, but it's strictly logical if you look at it from the computer's point of view (remembering, of course, that the computer has absolutely no common sense).

For example, consider how you might call the sqrt function in other languages, sqrt(49):

sqrt(49)

As in the preceding case, Scamper sees sqrt(49) as two separate commands: sqrt means "Find out what sqrt is!" and (49) means "Call the procedure 49, with no arguments!" Scamper responds to the first command by reporting that sqrt is the primitive procedure for computing square roots and to the second by pointing out that the number 49 is not a procedure.

Return to the problem

Simple Images in Scamper

Introduction

In addition to supporting "standard" data types, such as numbers and strings, Scamper also includes libraries that support a number of more sophisticated data types, including a type that the designers call "images". The image data type supports the creation, combination, and manipulation of a variety of basic shapes. Readers of an earlier generation might consider Scamper's picture type an extension of the ColorForms that they played with as children.

In considering a new data type (and images are effectively a new data type), we should ask ourselves the standard set of five questions:

• What is the name of the type?
  • "image".
• What is the purpose of the type?
  • To allow people to make interesting images.
• How do you express values in this type?
  • We've seen a few ways, including the circle and rectangle procedures. There are more.
• How does Scamper display values?
  • As the "expected" images.
• What procedures are available?
  • We've seen that we can use above and beside. Once again, there are more.

There's also one other question to ask for this type, since it's not a standard type:

• How does one gain access to the type?
  • The answer is straightforward: You add the following line to the top of your program:

(import image)

Basic shapes

You've already seen a few procedures for creating basic shapes:

• (circle raidus fill color) creates a circle with the specified radius.
• (rectangle width height fill color) creates a rectangle with the specified width and height.

The fill argument to both shape procedures determines whether the shape is filled in. Passing "solid" creates a solid (filled in) shape and "outline" creates an outlined (not filled in) shape.

The color argument specifies the color of the shape, e.g., "red" or "cyan". You can use any of the named colors supported by most browsers; see this w3schools.com list to see which named colors are available.

(import image)

(circle 100 "outline" "red")

(rectangle 100 75 "solid" "blue")

In addition, you can draw ellipses, squares, and generalized polygons:

(import image)

(ellipse 80 60 "solid" "purple")

(square 100 "solid" "orange")

(ellipse 50 100 "outline" "green")

Polygons are created via the path function. They are a bit more complicated. We won't discuss all the details yet, but a few examples might be of interest. Note that (pair x y) creates an x/y point on an upside-down coordinate system.

(import image)

(path 100 50 (list (pair 0 0) (pair 100 20) (pair 30 50)) "solid" "blue")

(path 100 100 (list (pair 0 0) (pair 100 20) (pair 50 50) (pair 100 70) (pair 0 100) (pair 0 0))
              "outline" "red")

You can (eventually) find information on more ways to make images in the Scamper library reference.

Combining images

By themselves, the basic images (ellipses, rectangles, etc.) do not permit us to create much. However, as some of the examples above suggest, we gain a great deal of power by combining existing images into a new image. You're already seen three basic mechanisms for combining images.

• beside places images side-by-side. If the images have different heights, their vertical centers are aligned.
• above places images in a stack, each above the next. If the images have different widths, their horizontal centers are aligned.
• overlay places images on top of each other. The first image is on top, then the next one, and so on and so forth. Images are aligned according to their centers.

(import image)
(define small-gray (circle 20 "solid" "gray"))
(define medium-red (circle 30 "solid" "red"))
(define large-black (circle 40 "solid" "black"))
(beside small-gray medium-red large-black)
(above small-gray medium-red large-black)
(overlay small-gray medium-red large-black)

When overlaying images, order matters. The first is on top of the second, the second is on top of the third, and so on and so forth.

(import image)
(define small-gray (circle 20 "solid" "gray"))
(define medium-red (circle 30 "solid" "red"))
(define large-black (circle 40 "solid" "black"))
(overlay large-black medium-red small-gray)

What if we don't want things aligned on centers? The Scamper image library provides alternatives to these three that provide a bit more control.

• (beside/align alignment i1 i2 ...) allows you to align side-by-side images at the top or bottom (using "top" and "bottom"). You can also align at the center, mimicking beside, using "center"
• (above/align alignment i1 i2 ...) allows you to align vertically stacked images at the left, right, or middle (using "left", "right", and 'middle).
• (overlay/align halign valign i1 i2 ...) allows you to align overlaid images.

(import image)
(define small-gray (circle 20 "solid" "gray"))
(define medium-red (circle 30 "solid" "red"))
(define large-black (circle 40 "solid" "black"))
(beside/align "top" small-gray medium-red large-black)
(beside/align "bottom" small-gray medium-red large-black)
(above/align "left" small-gray medium-red large-black)
(above/align "right" small-gray medium-red large-black)
(overlay/align "left" "top" small-gray medium-red large-black)
(overlay/align "left" "center" small-gray medium-red large-black)
(overlay/align "left" "bottom" small-gray medium-red large-black)
(overlay/align "right" "top" small-gray medium-red large-black)
(overlay/align "right" "top" large-black medium-red small-gray)

As the overlay examples suggest, the alignment is based on the "bounding box" of each image, the smallest rectangle that encloses the image.

You can (eventually) find information on more ways to combine images in the CSC-151 library reference. (If you want others, and ask Prof. Rebelsky nicely, he might implement them.)

Colors

While we often think of colors by name (e.g., "red", "violet", or "burnt umber"), one of the great advantages of computational image making is that it is possible to describe colors that do not have a name. Moreover, it is often better to use a more precise definition than is possible with a name. After all, we may not agree on what precisely something like "springgreen" or "burlywood" means. (One color scheme that we've found has both "Seattle salmon" and "Oregon salmon". Would you know how those two colors relate?)

In fact, it may not only be more accurate to represent colors non-textually, it may also be more efficient, since color names may require the computer to look up the name in a table.

The most popular scheme for representing colors for display on the computer screen is RGB. In this scheme, we build each color by combining varying amounts of the three primary colors, red, green, and blue. (What, you think that red, yellow, and blue are the primary colors? It turns out that primary works differently when you're transmitting light, as on the computer screen, than when you're reflecting light, as when you color with crayons on paper.)

So, for example, purple is created by combining a lot of red, a lot of blue, and essentially no green. You get different purple-like colors by using different amounts of red and blue, and even different ratios of red and blue.

When we describe the amount of red, green, and blue, we traditionally use integers between 0 and 255 to describe each component color. Why do we start with 0? Because we might not want any contribution from that color. Why do we stop with 255? Because 255 is one less than 28 (256), and it turns out that numbers between 0 and 255 are therefore easy to represent on computers. (For those who learned binary in high school or elsewhere, if you have exactly eight binary digits, and you only care to represent positive numbers, you can represent exactly the integers from 0 to 255. This is akin to being able to count up to 999 with three decimal digits.)

If there are 256 possible values for each component, then there are 16,777,216 different colors that we can represent in standard RGB. Can the eye distinguish all of them? Not necessarily. Nonetheless, it is useful to know that this variety is available, and many eyes can make very fine distinctions between nearby colors.

In Scamper's image model, you can use the color procedure to create RGB colors. (color 0 255 0 1) makes a bright green, (color 0 128 128 1) makes a blue-green color, and (color 64 0 64 1) makes a relatively dark purple.

The color procedure also takes a fourth parameter, which is often called the "alpha" value, and which you can think of as the opacity of the color. A color with an opacity of 0 is transparent; a color with an opacity of 1 obscures anything below it. Less opaque colors also appear lighter.

(import image)
(beside (circle 40 "solid" (color 0 255 0 1))
        (circle 40 "solid" (color 0 128 128 0.25))
        (circle 40 "solid" (color 64 0 64 0.75)))

(import image)
(beside
  (rectangle 25 40 "solid" (color 0 0 255 1))
  (rectangle 25 40 "solid" (color 0 0 255 0.75))
  (rectangle 25 40 "solid" (color 0 0 255 0.50))
  (rectangle 25 40 "solid" (color 0 0 255 0.25)))

Opacity will be especially important as we start to overlay shapes.

(import image)
(define circles 
  (beside
    (circle 50 "solid" (color 255 0 0 1))
    (circle 50 "solid" (color 255 0 0 0.75))
    (circle 50 "solid" (color 255 0 0 0.50))
    (circle 50 "solid" (color 255 0 0 0.25))))
(above
  (overlay circles (rectangle 60 20 "solid" (color 0 0 255 1)))
  (overlay circles (rectangle 60 20 "solid" (color 0 0 255 0.75)))
  (overlay circles (rectangle 60 20 "solid" (color 0 0 255 0.50)))
  (overlay circles (rectangle 60 20 "solid" (color 0 0 255 0.25))))

Self Checks

Check 1: A simple checkerboard

Write instructions for making a two-by-two checkerboard.

Check 2: Iconic images

Write instructions for making a simple smiley face.

Acknowledgements

Even though we no longer use the HtDP library, this section draws upon The DrRacket HtDP/2e Image Guide.

The discussion of colors is based on a reading from the 2017 spring section of Grinnell's CSC 151.

In this reading, we discuss one of the fundamental problem-solving techniques in computing: algorithmic decomposition

Algorithmic Decomposition

As we learned in a previous reading, an algorithm is a step-by-step procedure for solving a problem. These problems vary in scope from simple one-off tasks to complicated, generalized tasks that form the core of large, complex systems. For example, consider the problem of going through a web page and finding the links it contains. It turns out that a web page is plain text in a format known as hypertext markup language (HTML), so we can search the web page source file for occurrences of the text <a href="...">...</a> which correspond to links. For example, the beginning of this paragraph is rendered with the following HTML:

<p>As we learned in previous reading, an algorithm is a step-by-step procedure for solving a problem.
These problems vary in scope from simple one-off tasks to complicated, generalized tasks that form the core of large, complex systems.
For example, consider the problem of going through a web page and finding the links it contains.
It turns out that a web page is plain text in a format known as hypertext markup language (HTML), so we can search the web page source for for occurrences of the text <code class="language-drracket highlighter-rouge"><span class="nv">&lt;a</span> <span class="nv">href=</span><span class="s">"..."</span><span class="nv">&gt;&lt;/a&gt;</span></code> which correspond to links.
For example, the beginning of this paragraph is rendered with the following HTML:</p>

The paragraph contains one link corresponding to the text yesterday's reading. We will eventually learn how to do operations like this in Scheme, but even though we can't write a program to do this yet, we can imagine that with proper library support that this is a simple task.

In contrast, the task of scraping web pages for links forms the basis of the algorithms that search engines use to rank webpages. For example, Google's famous PageRank algorithm ranks the relevance of a webpage by the number of webpages that link to it. In order to do this, Google's servers comb the Internet for webpages and scrapes their links, recording where they point to in a database.

PageRank itself is a complicated algorithm with many parts. However, what we should take away from this example is the fact that this complicated algorithm boils down to a simple task: scraping webpages for links. The process by which we take a complicated problem like ranking all webpages and distill it into a collection of smaller, easier-to-solve problems is called algorithmic decomposition.

Algorithmic decomposition is the lifeblood of a computer scientist. It is the primary skill that we employ to manage complexity in the problems that we solve. As such, we introduce this concept in this first week of the course to start getting you thinking with this mindset:

The problem that I am trying to solve can be decomposed into these smaller problems...

Visual Decomposition with Pictures

While we haven't seen much of the Scheme programming language yet, we know enough to introduce the basics of algorithmic decomposition with the image library introduced in yesterday's reading. As a reminder, I encourage you not to read this passively; instead, enter the code interactively as you cover it in your reading. This will not only help you get used to typing out Scheme code but also encourage you to play around and experiment with the language.

From last class period's class, recall that we must include a import statement in our program so that Scheme knows we're using the image library.

(import image)

Our [initial reading on the Scheme language]({{ "/readings/scamper.html" | relative_url }}) introduce us to functions for drawing circles and rectangles:

(import image)

(circle 50 "outline" "blue")
(rectangle 75 50 "solid" "red")

As well as functions that allow us to place images above and beside each other.

(import image)

(above (circle 35 "outline" "blue")
       (circle 35 "outline" "red"))
(beside (rectangle 50 50 "solid" "blue")
        (rectangle 50 50 "solid" "red"))

Let's consider the problem of drawing the following more complex figure:

(import image)

(define top-row
  (beside (circle 50 "outline" "red")
          (circle 75 "solid" "blue")))

(define bottom-row
  (beside (circle 75 "outline" "blue")
          (circle 50 "solid" "red")))

(define circles
  (above top-row bottom-row))

circles

How might we approach this problem? We might start trying to cobble together random combinations of the functions we've seen so far, and we might stumble on a program that works. But such an approach---haphazardly trying stuff out until success is achieved---will not scale well when our problems get more complex!

Algorithmic decomposition is our primary problem solving strategy for systematically tackling complex problems. Rather than blundering into a solution, we proceed by:

1. Breaking up the original, complex problem into smaller, easier sub-problems to solve.
2. Solving each of those sub-problems in turn if they are easy enough to tackle directly, or further decomposing the sub-problems if they themselves are too complex!
3. Taking the solutions to each of those sub-problems and composing them together to form a solution to the original problem.

For example, we might decompose the problem of computing a student's average assignment grade for a course as follows:

• Compute the sum of the student's assignment grades (assuming they are all out of the same point total).
• Count the number of total assignments.
• Combine the two quantities via division to arrive at the final average.

We perform this process naturally in many situations, almost without thinking about it. However, when put into a novel situation, e.g., computer programming, you might neglect to go through these steps. It is therefore instructive to be explicit about your decomposition---luckily, this coincides with excellent programming practices, so your diligence is well-rewarded in this context.

Coming back to the proposed picture, let's tackle the problem of drawing the image by breaking it down into smaller pieces. One way to do this is to analyze the image by row:

• The top row of shapes is a small, red circle outline followed by a large, blue filled-in circle.
• The bottom row of shapes is a large, blue circle outline followed by a small, red filled-in circle.
• The top and bottom rows are combined by stacking them on top of each other.

Now, when we go to write the code to produce this figure, we can translate this decomposition into code using the image library function and the define command to explicitly name each of the parts.

We can approach decomposition in either a bottom-up or top-down style of design. In a bottom-up style, we first implement the individual of pieces of the program and then we combine them to form the complete program. In a top-down style of design, we first partially implement the complete program and then implement the individual pieces. We'll illustrate both styles of design below.

Bottom-up Design

Let's begin with the top row. We'll define top-row to be the top row of circles using the circle and beside functions. Note that this define command should go into your program below your import statement rather than in the explorations window:

(import image)

(define top-row
  (beside (circle 50 "outline" "red")
          (circle 75 "solid" "blue")))

We can now go to the explorations window and test our code. The practical effect of the define command is to make top-row an alias for the image, so we can simply type in top-row as an additional statement in the explorations window to check our work:

(import image)

(define top-row
  (beside (circle 50 "outline" "red")
          (circle 75 "solid" "blue")))

top-row

Next, we'll define bottom-row to be the bottom row of circles.

(import image)

(define bottom-row
  (beside (circle 75 "outline" "blue")
          (circle 50 "solid" "red")))

And we'll check our work in the explorations window:

(import image)

(define bottom-row
  (beside (circle 75 "outline" "blue")
          (circle 50 "solid" "red")))

bottom-row

Finally, let's put it all together. As we discussed, the overall picture is obtained by stacking the top-row with the bottom-row which we can do with the above function. We can then check that circles is the image that we wanted in explorations window. (Make sure that you re-run the explorations window to update it with updates to your program!)

(import image)

(define top-row
  (beside (circle 50 "outline" "red")
          (circle 75 "solid" "blue")))

(define bottom-row
  (beside (circle 75 "outline" "blue")
          (circle 50 "solid" "red")))

(define circles
  (above top-row bottom-row))

circles

Top-Down Design

With top-down design, rather than starting with top-row and bottom-row, we start with the overall program circles. We have identified that circles is a stack of two rows of images, so we know that the definition of circles will involve above. However, we have not defined top-row and bottom-row yet---what do we fill in for the arguments to above?

Scamper defines a special value {??} which represents an undefined value in the program. {??} acts as a syntactically valid placeholder, reminding us that we should replace {??} with an eventual implementation.

Let's do that for top-row first.

(define top-row
  {??})

Note that we can use our hole value as a placeholder to be able to write out the syntax of a define correctly and ensure that we get it right. Of course, when we run this code, we the Hole encountered! Fill me in! error, but we at least know that we have all the keywords and parentheses in the right place.

Once we define top-row as before:

(import image)

(define top-row (beside (circle 50 "outline" "red")
                (circle 75 "solid" "blue")))

We can now fill in the corresponding hole in circles:

(import image)

(define top-row (beside (circle 50 "outline" "red")
                (circle 75 "solid" "blue")))

(define circles
  (above top-row {??}))

Finally, we can define bottom-row just like before and then complete the definition of circles:

(import image)

(define top-row (beside (circle 50 "outline" "red")
                (circle 75 "solid" "blue")))

(define bottom-row
  (beside (circle 75 "outline" "blue")
          (circle 50 "solid" "red")))

(define circles
  (above top-row bottom-row))

circles

Top-down vs. Bottom-up Design

You might wonder which sort of design---top-down or bottom-up---to use when writing your programs. The short answer is that it depends on the kind of problem you are tackling and your own personal preference. Sometimes you might see how to immediately implement the smaller pieces of a program in which you can start with those pieces and then build up to the overall program. In other cases, you might not see the pieces and want to essentially outline how the program ought to behave in code, similar to the bulleted list we identified for the design of shapes. In this case, you can use top-down design to write this outline and then fill it in incrementally. Either strategy is valid---be willing to experiment early on with both styles to discover your preferences and be flexible in how you design your code!

Decomposition In Code

Finally, let's look at the big picture. Take a look at the complete program that we wrote in the definitions pane:

(import image)

(define top-row
  (beside (circle 50 "outline" "red")
          (circle 75 "solid" "blue")))

(define bottom-row
  (beside (circle 75 "outline" "blue")
          (circle 50 "solid" "red")))

(define circles
  (above top-row bottom-row))

Note how our decomposition strategy has been enshrined in the code. That is, our approach to solving the problem of drawing the grid of circles is evident in the code:

circles is defined to be a stack of a top-row and bottom-row. Each of the rows contain two circles of varying color, shape, and sizes.

By employing algorithmic decomposition in our problem solving and programming, we not only gain the able to make tangible progress in solving the problem; our code is much more readable as a result! As we move forward in the course, always approach problems with decomposition in mind even if they are easy to solve at first. Honing this skill early on in your programming journey will prepare you well for the complex problems will encounter later in the semester!

Self Checks

Check 1: Readability (‡)

Here is an alternative version of the code to produce the image of this reading.

(import image)

(define circles
  (above (beside (circle 50 "outline" "red")
                 (circle 75 "solid" "blue"))
         (beside (circle 75 "outline" "blue")
                 (circle 50 "solid" "red"))))

Paste this code into a fresh .scm source file and verify that circles produces the same image as before.

Compare and contrast the final version of the code the reading with this version. Answer each of the following questions in a few sentences each.

• Which version is more concise? Why?
• Which version do you find more understandable? Why?
• Which version allows you to better predict the results without running the program? Why?

Check 2: Alternative Decomposition (‡)

There are many ways to decompose a problem, many of which are equivalent, but many produce subtlety different solutions. The decomposition we chose in the reading was one where we recognized the image was two rows stacked on top of each other. Try writing the code corresponding to a decomposition where we think of the image as two columns placed side-by-side. Does this result in an identical image? Why or why not?

Image and algorithmic decomposition

In this laboratory, you will practice algorithmic decomposition by analyzing and writing code to draw basic pictures in Scamper. Previously we introduced the foundational technique of algorithmic decomposition where we express a complex problem in terms of smaller, easier-to-solve problems. We can decompose any problem, no matter the domain. However, the image-drawing facilities of Scamper give us a natural way of visualizing decomposition. We will, therefore, begin our journey into programming by practicing algorithmic decomposition with images. This lab will give you some experience decomposing problems as well as typing out basic Scamper code.

Introducing Pair Programming

For these next four exercises, we will continue to try out pair programming. Pair programming is a particular discipline of collaborative programming that we will be using extensively in our lab work. We'll have more to say in the coming weeks about the nitty-gritty of working in pairs, but we would like you to dive head-first into the experience.

• One person, the driver, will be in control of keyboard.
  They will often take the lead on designing and coding a solution, speaking aloud about their design thoughts as they work.
• The other person, the navigator, helps keep them from going too far off track. They observe and consider strategic design issues. They look for potential problems and raise them with the driver. If they happen to have a separate computer, they can serve as a resource to look things up, such as the syntax of an operation. They try to keep track of time.

Between each exercise, you will swap driver and navigator roles so that you and your partner get experience with both roles. If you are in a group of three, you will have two navigators and one driver! Make sure to rotate roles so that everyone gets a turn as the driver.

To encourage appropriate swapping, we have labeled each problem as "A" and "B" for pairs. Whoever is closer to the board is partner "A" Whoever is further from the board is partner "B". Partner A or Partner B drives as indicated in the lab. If there is a third partner, ignore the labels and rotate appropriately.

You should begin by copying and opening the file decomposition.scm (click on it) which contains spaces to answer the instructions you will find here. In future labs, the file may contain instructions, code, and places to enter your answers.

In general, you will find that all of the instructions for the lab are in the linked file or files. However, we'd prefer not to include images in Scheme files. Hence, for this lab, you'll need to have this file up, too.

Images for the Exercises

Exercise 1: Party

Here's the sample image that you should try to replicate. It is fine if your party people do not exactly match ours.

Exercise 2: Cottage

Here's the sample image. It is fine if your cottage in the woods does not exactly match ours.

Exercise 3: The planets

Here's the sample image, which is an abstract representation of the planets of the solar system! Once again, it's fine if you don't match exactly. However, you should emulate the drop shadows behind each planet and try to approximate the relative size and colors of the planets.

Exercise 4: Triangles

Yup, it's another image!

Writing your own procedures

In today's reading, we explore why and how to define your own procedures in Scheme.

Introduction

As you may recall from the introduction to algorithms, the ability to write subroutines is one of the key components of algorithm design. Subroutines typically have a name that we use to refer to the subroutine, zero or more parameters that provide the input to the subroutine, and a set of instructions (an expression in Scheme) for doing the computation. That is, a subroutine is just an algorithm that has been named and "parameterized".

For example, we might want to define a procedure, square, that takes as input a number and computes the square of that number.

(square 5)
(square 1.5)
(square 0.333)
(+ (square 0.5) (square 0.333))
(square (square 2))

As you may have noted, square can have multiple meanings. If we're making drawings, it could also mean "make a square". Let's consider an example.

(import image)

(square 50 "solid" "red")
(square 25 "solid" "blue")
(above (square 60 "solid" "red")
       (beside (square 40 "solid" "blue")
               (square 40 "solid" "purple")))

As you may recall, the image library already defines a square procedure, so it's unlikely to be a good idea for us to define our own square procedure, whether for numbers or images. More generally, when we choose names in Scheme, we should try not to conflict with existing names. Sometimes Scheme will stop us from reusing a name; other times it will blithely move along, letting us break things through such reuse.

So, how do we define these procedures? Read on and see.

Defining procedures with lambda

Scheme provides a variety of mechanisms for defining procedures. We will start with the most general, which uses the keyword lambda, which means "procedure". The lambda mechanism is relatively straightforward.

As you may recall, we typically think of a procedure as having three main aspects: The name we use to refer to the procedure, the names of the parameters (inputs) to the procedure, and the instructions the procedure executes.

Here is the general form of procedure definitions in Scheme, at least as we will use them in this class. Scheme does not require the indentation, but it makes it much easier to read and we will require it in this course.

(define <identifier>
  (lambda (<parameters>)
    <expression>))

You've already seen the define; we use define to name things. In this case, we're naming a procedure, rather than a value.

The <identifier> part is straightforward; it's the name we will use to refer to the procedure. The "lambda" is a special keyword in Scheme to indicate that "Hey! This is a procedure!". Lambda has a special place in the history of mathematical logic and programming language design and has meant "function" or "procedure" since the early days of formal logic. Lambda is special enough that the designers of Scamper chose it for the icon.)

The <parameters> are the names that we give to the inputs. For example, we might use the names side-length and color for the inputs to our "make a square of s certain color" procedure. Similarly, we might use the name x for the input to the "square a number" procedure.

Finally, the <expr> is a Scheme expression that is the computation that the function performs when called.

Let's look at a simple example, that of squaring a number.

(define square-number
  (lambda (x)
    (* x x)))

Mentally, most Scheme programmers read this as something like

square-number names a procedure that takes one input, x, and computes its result by multiplying x by itself.

Let's also look at some examples of using our new procedure.

(define square-number
    (lambda (x)
      (* x x)))
(square-number 5)
(square-number 0.5)
(square-number (square-number 2))
square-number

You may note in the last line that when we asked Scamper for the "value" of square-number, it told us that it's a function. Compare that to other values we might define.

(import image)
(define x 5)
x
(define phrase "All mimsy were the borogoves")
phrase
(define red-square (rectangle 75 75 "solid" "red"))
red-square
(define multiply * )
multiply

In every case, Scamper is showing us the value associated with the name. In some cases, it's a number. In some cases, it's a string. In some cases, it's an image. And, in some cases, it's a procedure.

How does the procedure we've just defined work? Here's one way to think about it: When you call a procedure you've defined with lambda, Scamper substitutes in the arguments in the procedure call for the corresponding parameters within the instructions. After substituting, it evaluates the updated instructions.

For example, when you call (square-number 5), Scamper substitutes 5 for x in (* x x), giving (* 5 5). It then evaluates the (* 5 5), computing 25.

What about a nested call, such as (square-number (square-number 2))? As you may recall, Scheme evaluates nested expressions from the inside out. So, it first computes (square-number 2). Substituting 2 in for x, it arrives at (* 2 2). The multiplication gives a value of 4. The (square-number 2) is then replaced by 4. Scamper is then left to evaluate (square-number 4). This time, it substitutes 4 in for the x, giving it (* 4 4). It does the multiplication to arrive at a result of 16.

We might show the steps as follows, with the --> symbol representing the conversion that happens at each step.

    (square-number (square-number 2))
--> (square-number (* 2 2))
--> (square-number 4)
--> (* 4 4)
--> 16

What about the colored squares?

If we want a procedure to make squares, we'll just call the rectangle procedure, using the same value for the width and height.

(import image)

(define color-square
  (lambda (side color)
    (rectangle side side "solid" color)))

What happens if we call color-square on inputs of 50 and "red"? Scheme substitutes 50 for side and "red" for color, giving us (rectangle 50 50 "solid" "red").
And, as we saw in the examples above, that's a red square of side-length 50.

(import image)

(define color-square
  (lambda (side color)
    (rectangle side side "solid" color)))

(color-square 50 "red")

Another example

The square is a relatively simple example. Consider, for example, the following definition of a simple drawing of a house.

(import image)

(overlay/align "middle" "bottom"
             (overlay/align "left" "center"
                            (circle 3 "solid" "yellow")
                            (rectangle 15 25 "solid" "brown"))
             (above (triangle 50 "solid" "red")
                    (rectangle 40 50 "solid" "black")))

What if we want to make houses with different sizes or colors? We could copy and paste the code. However, if we changed our mind about how to structure our houses, we'd then have to update every copy. We'd be better off writing a procedure that takes the size and color as parameters.

How would we write house? That's a question for another day. Or perhaps for the lab.

For now, let's consider a simpler version, one that does not include the door. Remember: Decomposition is your friend! If we did not care about resizing the house, we might just write an expression like the following.

(import image)

(above (triangle 50 "solid" "red")
       (rectangle 40 50 "solid" "black"))

But we'd like to "parameterize" the code to take the size as an input. Let's say that the size corresponds to the side-length of the triangle (or the height of the main body of the house). We will replace each 50 by size and replace 40 by (* 4/5 size). Let's see how that works.

(import image)

(define simple-house
  (lambda (size)
    (above (triangle size "solid" "red")
           (rectangle (* 0.80 size) size "solid" "black"))))
(simple-house 20)

(simple-house 30)

The next step might be to add parameters for the color of the body and the color of the roof.

Zero-parameter procedures

We've written procedures so that they take one or more parameters. However, there are also advantages to writing procedures that take no parameters. For now, just remember it's a possibility. In the future, you'll see what it's useful.

Some benefits of procedures

As you may have figured out by now, there are many benefits to defining your own procedures. One of the most important is clarity or readability. Another programmer will likely spend less effort understanding (simple-house 20) than they will trying to understand the more complex above expression involving triangles and rectangles. The should be able to see that the first is intended to be a house. The second could be anything, at least until you see it. (As you may recall from the decomposition lab, the code to make a simple tree and the code to make a simple house look very similar.)

As importantly, the other programmer may also find it easier to write programs using simple-house than the much longer series of expressions.

By using a name for a set of code, we are employing the concept of abstraction. That is, because the person calling the procedure knows what the procedure does rather than how it achieves that result, we have abstracted away some of the details. Of course, for someone to know what the procedure does, you need to choose a good name. img1 tells us very little, other than that it's an image. house or tree gives us much more of a sense of what the procedure does. Be thoughtful in your choice of procedure names. (Also be thoughtful in your choice of parameter names---and any names, for that matter.)

There are benefits to abstraction and the use of procedures other than readability. For example, it may be that you discover a more efficient way to do a computation. If you've written the same code for the computation throughout your program, you'll have a lot of code to update. But if you've created a procedure, you need only update one place in your code, the place you've defined the procedure.

There are other ways in which procedures make us more efficient. For example, if we decide to change what our houses are like---say, by making the roof wider than the body of the house---we only have one place in our program to update.

As these examples suggest, using procedures to parameterize and name sections of code provides us with a variety of advantages. First, we can more easily reuse code in different places. Rather than copying, pasting, and changing, we can simply call the procedure with new parameters. Second, others can more easily read the code we have written, at least if we've chosen good names. Third, we can more easily update the procedures we've written, either to make them more efficient or to change behavior universally.

Using lambda without define

Scheme and related languages differentiate themselves from most other languages in that you can use lambda (or, more generally, subroutines) to define a procedure without bothering to name the procedure. Recall, for example, that (lambda (x) (* x x)) represents "a procedure that takes one input, x, and computes x times x". Since that's a procedure, Scheme permits us to write it in the "procedure slot" in an expression, as in

    ((lambda (x) (* x x)) 5)

What does that mean? It means "take a procedure that takes one input, x, and computes x times x and apply it to 5, substituting the 5 for the x.

    ((lambda (x) (* x x)) 5)
--> ((lambda (x) (* x x)) 5)
--> (* 5 5)
--> 25

That doesn't seem very useful, does it? And it's much harder to read, at least for now. But it's worth it. The power comes in when we use these "anonymous" procedures along with other tools. For example, the map procedure which we covered briefly and will return to applies a procedure to each element of a list.

    (map (lambda (x) (* 3 x)) (list 1 2 3))
--> (list ((lambda (x) (* 3 x)) 1)
          ((lambda (x) (* 3 x)) 2)
          ((lambda (x) (* 3 x)) 3))
--> (list (* 3 1)
          (* 3 2)
          (* 3 3))
--> (list 3 6 9)
--> '(3 6 9)

Don't worry if you don't quite get this section! We'll return to the concepts in a week or two.

Self Checks

Check 1: A simple procedure

Write a procedure, (subtract2 val), that takes a number as input and subtracts 2 from that number.

> (subtract2 5)
3
> (subtract2 3.25)
1.25
> (subtract2 "hello")
-:  Runtime error:
    A number? was expected, but a str was found
    In program: "hello"

Check 2: Building blocks (‡)

Write a procedure, (block color), that takes a color as input and builds a 40x20 "block" of the given color (a solid rectangle).

Check 3: Exploring steps

Show the steps involved in computing (square (subtract2 5)) and (subtract2 (square 5)).

Q&A

These are questions gathered from previous reading responses.

Do we have to use they keyword lambda every time we want a procedure that takes in a parameter?

Yes. In fact, you have to use lambda if you want a procedure with no parameters.

What would be the difference between a zero parameter procedure and defined variable?

Right now, the biggest difference between a zero-parameter procedure and a defined variable are that you use them differently. The variable you use with its name; the procedure you put in parentheses.

Later in the semester, we'll see some differences. One difference is when the associated code is executed.

Acknowledgements

This section draws upon a reading entitled "Defining your own procedures" and an earlier reading entitled "Writing your own procedures" from Grinnell College's CSC 151.

It was updated in Spring 2022 to remove much of the discussion of zero-parameter procedures and to add a short section on anonymous procedures.

The house drawing was inspired by a more sophisticated house drawing from the Scheme Image Guide.

Practice with procedures

In this lab, we explore techniques for writing procedures in Scheme.

Syntax to remember

• Defining names: (define <name> <expression>).
• Function expressions: (lambda (<parameters>) <expression>).
• Defining functions: (define <name> (lambda (<parameters>) <expression>))

The lab

As in the previous lab (and future labs), you will work with a randomly assigned partner using a starter file.

• procedures.scm

Remember to employ good pair programming practices as discussed in the previous lab!

• One person, the driver, is in control of keyboard. They focus on the immediate task of designing and coding a solution, speaking aloud about their design thoughts as they work.
• The other person, the navigator, acts as a reviewer. They observe and think more about strategic architectural issues. They look for potential issues and raise them with the driver. They are also responsible for keeping track of the time spent on the problem.

Work

All of the instructions are in the file. Switch to that now.

Acknowledgements

The checkerboard example comes from a very old version of CSC 151. We are no longer sure which member or members of the department wrote it.

Bits and parts of this lab come from procedure labs from other versions of CSC 151.

Assessment #2: working with the basic datatypes

In this mini-project, you will write a variety of procedures that explore various aspects of the basic datatypes you learned about this past week. For this project, you will submit one file: basic-datatypes.scm.

Some background

As our programs get more complicated, the structure of our code and good names and formatting are not enough to make our code readable and correct. We need to rely on extrinsic means to ensure these things. To ensure that our code is readable, we use documentation to capture aspects of our code that are not obvious upon inspection. To ensure that our code is correct, we use tests that codify the correctness our programs through concrete examples.

During our week on software engineering fundamentals, we'll discuss these concepts in more detail. For now, we'll employ some basic documentation and testing for our program.

Documentation

For each function that you write in this mini project, include a function comment that captures the types of the function as well as describes its output in a sentence or two. For example, here is a function comment for a function that finds the minimum of three numbers:

;;; (min x y z) -> real?
;;;   x : number?
;;;   y : number?
;;;   z : number?
;;; Returns the minimum of x, y, and z
(define min-of-three
  (lambda (x y z)
    (cond 
      [(and (<= x y) (<= x z))
       x]
      [(and (<= y x) (<= y z))
       y]
      [else
       z])))

The function comment is a stylized comment that consists of the following three components:

• (min x y z) -> number?: the signature of the function which names its arguments and describes the output type of the function. In Racket, we express the types with the predicate functions that we use in code to test whether an expression has that type. For example, this signature says that min has three arguments, x, y, and z and that it produces a number (as tested by the number? function).
• x : number? ...: the types of each of the parameters mentioned in the signature. Like the return type of the function, we document the types of the parameters with the predicates that we would use in code to test values of those types.
• Returns the minimum of x, y, and z: finally, we include a brief sentence or two description of the behavior and output of the function. Here, the behavior of the function is simple, so we comparatively have little to say: the function returns the minimum of its arguments.

Tests

Up until this point, we have asked you to experiment with the functions that you write in the explorations window to check for correctness. This has the upside of being fast, but if you change your code, you need manually type in all those tests again which is tedious (which in turn makes it less likely you'll recheck the correctness of your code). A better solution is to codify your tests in your code so that you can rerun the tests at will.

During our unit on software engineering fundamentals, we'll introduce you to a library that makes test authoring and execution a breeze. For now, we'll simply have you call your functions on a variety of inputs within your file. For example, the reading on [characters and strings]({{ "/readings/strings.html" | relative_url }}) introduced a function that tests whether a value is a lowercase character:

(define lower-case-char?
  (lambda (x)
    (and (char? x)
         (char-lower-case? x))))

To test this function, we can call this function on several inputs and verify that the function behaves as expected. Note that we should choose a variety of inputs that exercise the different possibilities that the code considers, for example:

(lower-case-char? 5)    ; #f
(lower-case-char? #\a)  ; #t
(lower-case-char? #\C)  ; #f
(lower-case-char? "a")  ; #f

Setting up your file

You will have one file for this assignment, basic-datatypes.scm. Here's the start of the file.

;; CSC-151-NN (TERM)
;; Mini-Project 2: Working with the basic datatypes
;; YOUR NAME HERE
;; YYYY-MM-DD
;; ACKNOWLEDGEMENTS:
;;   ....

(import image)
(import music)

Part 1: String Utilities

As you have likely discovered by now, the built-in Scheme procedures don't always immediately do what we want. For example, although we can use a combination of integer? and string->number to determine if a string contains only digits, we would prefer not to write (integer? (string->number str)) again and again and again, particularly since we might later realize that that solution is not perfect.

When most programmers discover that they need to do the same thing again and again? They create a library of utility procedures that they plan to use in other procedures. Although you are just beginning your experience as a Racket programmer, you will still find it useful to create your own set of utilities.

For each of the following functions, do the following:

{:type="a"}

1. Write several tests that describe how the function should work. Note that you haven't written the function yet! While this seems backwards, this test-driven design is useful in the design process to help you concretize the behavior of a function.
2. Write documentation for the function as outlined above. Again, you haven't written the function yet! Documenting before you implement a function is another useful technique to solidify a design before you go to implementation.
3. Finally, implement the function! In implementing your function, you will learn new things about the design, correct mistakes, etc., so you should update your tests and documentation accordingly.

In your tests, make sure to consider edge cases the exercise the "boundaries" of your code, e.g., the string is empty or the string contains an unexpected character.

• (increment-wrap n bound) takes a non-negative integer n as input and returns n+1 except if n+1 exceeds bound (also a non-negative integer), then it returns 0 instead.
• (slight-trim str) takes a string str as input and returns str and removes a single leading space and a single trailing space on the ends of str, if they exist.
• (starts-with? s1 s2) takes two strings s1 and s2 as input and determines if s1 start with s2.
• (ends-with? s1 s2) takes two strings s1 and s2 as input and determines if s1 ends with s2.

Part 2: Ehrenstein Illusions

(Credit to Marty Stepp and Stuart Reges from the University of Washington for creating the original version of this assignment!)

An Ehrenstein Illusion is an optical illusion consisting of a collection of concentric circles and a diamond contained in a box. While we write the code to create a diamond, the circles will cause the sides of the diamond to look wavy!

For this part of the mini-project, you will ultimately write the following function:

• (ehrenstein length n box-color circ-color outline-color): creates an image that contains a single Ehrenstein illusion with side length length, n circles, with the given box-color and circ-color for the box color and circle color, respectively. outline-color determines the color of the outline of the circles and the diamond.

With these functions, you should reproduce the following images as definitions in your program.

• ehrenstein-1: a single Ehrenstein illusion of length 200, 5 circles, a "red" box, "yellow" circles, and "black" outline.

  

• ehrenstein-2: a single Ehrenstein illusion of length 100, 10 circles, an "aqua" box, "orange" circles, and "black" outline.

  

• ehrenstien-3: a single Ehrenstein illusion of length 50, no circles, a "white" box and circle, and "green" outline.

  

1. Critical to your decomposition of an Ehrenstein image is capturing the repetitive concentric circles. To do this, we'll incrementally develop a function (ehrenstein-circles length n) that draws only the circle outlines of one Ehrenstein image. In doing so, we'll introduce how we can use the list datatype to perform repetitive computation.

2. First let's step away from the code for a bit and develop a formula to compute the radius of an Ehrenstein circle given its position in the image. As a starting point, let's look at ehrenstein-1 which has 5 equally spaced concentric circles in a box of length 200. Imagine assigning a number to each circle, an index, starting from 0 for the innermost circle and 4 for the outermost circle. Fill out the following table that lists each circle's index and that circle's corresponding radius.

   Circle Index	Radius
   0	?
   1	?
   2	?
   3	?
   4	?

   To do this, recall that the circles are evenly spaced apart and the length of the entire image is 200. What must the distance be between each circle so that the circles are spaced evenly?

   From this table, derive a formula for the size of an Ehrenstein circle in terms of its index. To check your work, manually create the circles from ehrenstein-1 by using your computed radii combined with a call to overlay to overlay each circle. To double-check your work, perform this exercise on the circles from ehrenstein-2 (10 circles, length 100) and see if your formula works for this case, too.

   (Note: you do not need to include your table in your code anywhere! This is merely a design aid to help you in the successive parts of this homework! Additionally, make sure to comment out or remove your check code for your formula once you are confident it works.)

3. Next, let's put your formula to use. Write a function, (circles-list length n) that creates a list of the n black, outlined concentric circles that appear in an Ehrenstein image of the given length. To do so, you will need to put the following tools together:

   • You first need to create a list containing the indices of the circles. To do so, the (range n) function will be useful. (range n) produces a list of numbers in the range 0 to n-1.

   • With a list of the indices in hand, you then need to transform each index into its corresponding Ehrenstein circle. To do so, you will need to use the (map func lst) function which takes two arguments as input:

     1. The first is a function func which takes an element of the list as input and transforms it in some way.
     2. The second is the list lst whose elements will be transformed by func.

     In other words, map takes a function that transforms a single element and uses it to transform an entire list of elements by applying the function to each element uniformally.

   I recommend before trying to write circles-list to try out examples of range and map on your own to get a sense of how they work. Importantly, keeping in mind that a lambda expression is exactly that, an expression, we can call map as follows to increment all the elements of a list:

   (map (lambda (n) (+ n 1))
        (list 1 2 3 4 5))
   

   In this example, the provided lambda takes its argument n and returns n+ 1. map will apply this function to every elements of the list containing the numbers 1 through 5. The result is the list (list 2 3 4 5 6).

   For our purposes, the lambda we provide to map ought to take an index i as input and produce a single Ehrenstein circle as output according to the formula you derived in the previous part.

4. At this point, we have a way to generate a list of circles of the correct size. We must now combine them using one of the appropriate image functions that combines images together into a single image. However, these functions, e.g., beside, expect the images to come in as individual arguments instead of a single argument that is a list. The function (apply func args) helps us use a list of values as the input to a function that takes multiple arguments. To use apply, we simply pass in the func that takes multiple arguments and the list of arguments args. For example, the call (apply beside (list circ1 circ2 circ3)) has the same effect as calling (beside circ1 circ2 circ3) for the images bound to circ1 through circ3. But now, we can call beside and other functions like with it with a list!

   Use apply along with circles-list to finally implement (ehrenstein-circles length n)!

5. Finally, use ehrenstein-circles to complete the implementation of ehrenstein as described at the beginning of this part!

In addition to writing these functions, you should:

• Demonstrate that your ehrenstein function works by calling the function at least three times at the end of basic-datatypes.scm with various inputs.
• Appropriately decompose your function into smaller functions as you identify different sub-components of the image.
• Give complete documentation strings for all functions that you write.

Submitting your work

Turn in your completed basic-datatypes.scm file to Gradescope.

Computation via Expressions

While it is tempting to start diving into hacking immediately, it is easy to "learn" a programming language by following our intuition, but then become lost when our intuition fails us. Instead, we should take some time to not only build cool stuff, but also understand:

1. The structure of the code we are writing and
2. How our programs execute.

This work in ultimately building a mental model of computation of how Scheme programs operate will pay dividends as we ramp up the complexity of our programs as well as begin transitioning to other languages at the end of the course.

Syntax and grammar

Consider the following two sequences of English words.

• The rain in Spain falls mainly on the plains
• In on the the falls plains rain mainly Spain

Which of these sequences do you understand? Why?

The sequences both contain the same words, just in different orders. However, we recognize the first sequence as a valid sentence in the English language, whereas the second sequence seems to be purely random. Because the first sequence is a sentence, we can figure out the meaning of the collection of words by the rules of sentence formation in English:

• Generally speaking, the subject of the sentence comes before the action that the subject performs. Thus, it is the "rain" that "falls" and not the other way around.
• We modify the subject and action with other fragments such as prepositional phrases ("in Spain") and adverbs ("mainly").

When words don't appear in the appropriate order, then it is at best, difficult, and at worst, impossible, to derive the intended meaning of the words.

The syntax of a language is its rules that govern whether a sequence of words is well-formed. You may have learned the syntax of English explicitly sometime during your prior education, or you may have picked it up experientially by observing others. Regardless, you adhere to the syntax of English so that others understand what you are saying.

The syntax of Scheme programs

While the second sequence of words above was in random order, you may have been able to understand the meaning of the words to some degree. This is because you are equipped with all sorts of cues and heuristics for infusing such sequences with meaning. Unfortunately, as we saw during our first day of class, computers are not natively equipped with such skills. Recall that:

Computers will do exactly what you tell them to do and nothing more!

Thus, we don't have the luxury of being lax in how we form programs. Our programs must adhere to the syntax of the programming language we are writing precisely!

This might be an impossible task in English because of the complexity and ambiguity of the language. Luckily, Scheme's syntax is much more compact and concise than English. So with some attention to detail, we can quickly learn how to form syntactically valid Scheme programs!

Expressions

The main syntactic form of Scheme programs is expressions.

You have encountered expressions before when studying elementary math: arithmetic features numeric expressions that evaluate to numeric values. For example:

• \( 1 + 1 \) is a numeric expression that evaluates to the value \( 2 \).
• \( 3 \times (5 - 2 + 1) \) is a numeric expression that evaluates to the value \( 12 \).
• \( 32 \) is a numeric expression that is, itself, a value.

What is the syntax of an arithmetic expression? Well, numbers, themselves, are valid arithmetic expressions such as \( 32 \). And we can "join" together two numbers together with an operator, e.g., \( 1 + 1 \). But we're not constrained to numbers---we can take any pair of arithmetic expressions and join them with an operator to form a larger expression. For example, \( 1 + 1 \) and \( 3 - 2 \) are both valid expressions, so \( 1 + 1 - 3 - 2 \) is also valid! Note that parentheses here are used to be clear about how the different operators and operands associate, so we can also write \( (1 + 1) - (3 - 2) \) to be explicit.

In general, we can write down the rules of valid arithmetic expressions concisely. An arithmetic expression is either:

• A number or
• Two arithmetic expressions joined by an arithmetic operator in the middle (\( + \), \( - \), \( \times \), and \( \div \)).

As you saw in the last class's reading, Scheme's expression forms are different than traditional arithmetic. Rather than writing the operator between expressions in infix style, we write the operator for Scheme expressions in prefix style:

• (+ 1 1) is a Scheme expression that computes the same value as \( 1 + 1 \).
• (* 3 (+ (- 5 2) 1)) is a Scheme expression that computes the same value as \( 3 \times (5 - 2 + 1) \).
• 32 is a Scheme expression that computes the same value as \( 32 \).

Note that unlike arithmetic, we always surround our non-number expressions with parentheses. This is both a blessing and a curse. It is a blessing because this makes the order operations of a Scheme expression clear. It is a curse in that we have to write a lot of parentheses! We'll talk about how we can manage the complexity parentheses with appropriate style choices in our source code in later readings.

This infix versus prefix distinction is the primary difference between Scheme and arithmetic expressions. The rules or syntax of valid Scheme expressions are as concise as their arithmetic variants. An arithmetic Scheme expression is either:

• A number or
• An arithmetic operator followed by two Scheme expressions surrounded by parentheses.

It might be difficult to follow the language of the second bullet precisely, so it is useful to write out a sort of template that captures what the rule is conveying:

(<operator> <expr1> <expr2>)

Here, <operator> is a placeholder for any arithmetic operator and <expr1> and <expr2> are placeholders for any Scheme expression. We call <expr1> and <expr2> sub-expressions of the overall expression.

Beyond arithmetic expressions

Of course, our last reading quickly moved from arithmetic to drawings, so we need our rules for Scheme expressions to generalize accordingly. Let's look at one of these expressions from our previous reading:

(circle 60 "outline" "blue")

What's different between this expression that produces a circle versus the arithmetic Scheme expression we studied earlier?

• The "operator" is no longer a symbol. Instead, it is a name or identifier.
• There are more than two operands to this circle operation.
• The operands are no longer just numbers, they also include these words-in-quotes, strings.

We'll learn more about strings next week when we look at the primitive types of Scheme. For now, think of them as another sort of value we can perform computation over.

Given these observations, how can we generalize our rules for Scheme expressions accordingly? We'll make the following changes:

• We will not restrict ourselves to only arithmetic operations, we will allow any identifier as the operation to be performed! Not all identifiers will be valid operations when we go to execute our program, but in terms of forming a syntactically valid Scheme expression, we will allow any identfier as the operation.
• We will allow any number of arguments to our operations in a syntactically correct expression. Again, some operations will have restrictions on the number of arguments given to it that we will discover when we execute our program.

Our template for describing expressions that perform operations now looks like this:

(<identifier> <expr1> ... <exprk>)

Where the <expr1> ... <exprk> represents a sequence of sub-expressions separated by whitespace. For example, in the example expression above:

• circle is the identifier.
• 60 is the first sub-expression.
• "outline" is the second sub-expression.
• "blue" is the third sub-expression.

Putting everything together, we can write down the syntax of well-formed Scheme expressions as follows:

Note that this isn't it! We have much more to learn about Scheme, and we will revisit this definition and add and modify it as needed.

A mental model of computation for Scheme expression

It is one thing to form a syntactically valid English sentence. It is another thing to form a coherent, meaningful sentence! For example, the sentence:

I hefted the dishes below the hippo's qubits.

Is grammatically correct but non-sensible. For example, "hefting" (or lifting) dishes below something is odd. Furthermore, hippos don't have qubits to the best of our knowledge!

Alongside our knowledge of English syntax, we also have a sense of how to extract meaning out of grammatically correct sentences. Likewise, knowing the syntax of Scheme expressions is not enough. We must also know the "meaning" of expressions, i.e., how they compute.

Returning to arithmetic, we know from elementary mathematics how arithmetic expressions compute via repeated evaluation. For example, consider the expression \( 3 \times (5 - 2 + 1) \). According to the order of operations of arithmetic, we know that:

• \( 5 - 2 \) evaluates first to \( 3 \) because it is inside of parentheses and \( - \) and \( + \) have the same precedence, so we evaluate them in left-to-right order.
• Next, we evaluate \( 3 + 1 \) to \( 4 \).
• Finally, we evaluate \( 3 \times 4 \) to \( 12 \).

We can write this sequence of steps more concisely as follows:

\begin{align} &\; 3 \times (5 - 2 + 1) \\\ \longrightarrow &\; 3 \times (3 + 1) \\\ \longrightarrow &\; 3 \times 4 \\\ \longrightarrow &\; 12. \end{align}

Observe that our procedure for evaluating an arithmetic expression is:

1. Find the next subexpression to evaluate according to the order of operation rules.
2. Evaluate that subexpression to a value.
3. Substitute the value for the subexpression that produced it in the overall expression.

These three steps taken together form a single step of evaluation. We repeatedly take steps of evaluation until the overall expression is a value. This model of arithmetic computation is also called a substitutive model of evaluation due to the last step where substitute value for subexpression.

Scheme expressions operate in the same way as arithmetic expressions. However, as mentioned above, Scheme's unique syntax makes evaluation easier: because everything is parenthesized, there is no ambiguity as to which subexpression evaluates next. We just find the innermost parenthesized expression and evaluate it! Let's see how the equivalent Scheme expression evaluates:

    (* 3 (+ (- 5 2) 1))
--> (* 3 (+ 3 1))
--> (* 3 4)
--> 12

Substitutive evaluation is our mental model of computation for Scheme expressions! In summary:

Self-Checks

Check 1: Syntax (‡)

Consider the following expression that produces a drawing:

(above (rectangle 60 40 "solid" "red")
       (beside (rectangle 60 40 "solid" "blue")
               (rectangle 60 40 "solid" "black")))

Write down a list of:

• The sub-expressions of the overall expression.
• All the identifiers in the expression.
• All of the numbers in the expression.
• All of the strings in the expression.

Check 2: Semantics (‡)

Write down the step-by-step evaluation of the following Scheme expression. Note that (expt x y) computes x raised to the y power, i.e., \( x^y \).

(expt (- (* 3 5)
         (/ 20 2))
      (- (+ 2 8)
         6))

Check your work in Scamper.

Mental models of Scheme programs

In the reading, we developed an initial mental model of computation for Scheme programs by examining how expressions compute. In today's lab, we'll gain practice using that model to predict the behavior of simple Scheme programs. We'll then enhance that model with the define construct that we have seen throughout our readings.

Logistics

You will do most labs on the computer. You will submit those labs on Gradescope. In most cases, we will ask you to upload a file or to copy a procedure you've written. It is fine if the code does not work perfectly (or at all). Just let us know that you're aware of the problems. Most of the time, you will only turn in a few of the exercises.

Other labs, such as this one, you will do some/most of your work on paper and submit the paper.

Whether electronic or paper, labs are due before the next class. You can use a token to submit a lab late, but it must be in before before the subsequent class.

While we would prefer that you finish the lab with your partner, if you decide to finish the lab separately, you may do so. Please make sure to cite your partner when submitting the lab.

In most labs, we will have distinguished driver/navigator roles where:

• The driver is the person "at the keyboard." In the context of a paper-based assignment, they should be the one writing down a final solution.
• The navigator is the person guiding the navigator and checking their work.

Each exercise will designate person A or person B to be the driver. Person A should be the person closest to the board.

Preparation

a. Introduce yourself to your partner.

b. Grab a piece of paper from the back of the room. If you don't have your own pen, feel free to grab a pen, too.

c. One partner should log in to the computer and start Scamper along with these instructions.

Exercises

Exercise 1: Tracing Scheme expressions (A drives, B navigates)

Consider the following Scheme expression.

(* (+ 1 2) (- (* 3 4) (* 2 (+ 1 1 1))))

a. Write down a step-by-step evaluation of this expression (we call this a trace or evaluation trace). If you're not sure what we're asking for, grab one of the course staff (professor or mentors).

b. Scamper's stepping tool allows you to trace the execution of a program using our mental model of computation. Try it out by entering the program into Scamper, running the stepping tool (the "path" button to the right of the "play" button used to run a program), and comparing your results to the stepper.

Exercise 2: From Math to Scheme (alternating drivers)

For this exercise, alternate drivers between each expression.

Consider the following arithmetic expressions.

1. \( 3 * (4 - \frac{1}{7}) \). (Driver A)
2. \( 1 + (-2 + (3 + (4 + -5))) \). (Driver B)

For each of these arithmetic expressions.

• Translate the expression into an equivalent Scheme expression.
• Give the step-by-step evaluation of that Scheme expression to a final value.
• Check your work with Scamper's stepping tool.

Exercise 3: Parts of Expressions

For this problem, alternate drivers between each expression.

In the reading, we introduced the syntax of expressions. It is easy to think of program constructs as fixed elements that must appear exactly as-presented in our programs. However, these program constructs are far more like highly-composable building blocks that, provided we understand how they connect, we can put together however we would like in order to express our computations.

In this problem, we'll take a look at identifying the various parts of expressions of significant complexity. For each of the following expressions, identify:

• The non-trivial sub-expressions of the overall expression.
• The identifiers of the overall expression.
• All of the numbers of the overall expression.
• All of the strings of the overall expression.

In addition to this information, try to "read" the expression and in a sentence, describe what you believe the expression evaluates to. Check your work in Scamper:

; (a) (Driver B)
(string-length
  (string-append "hello"
                 " "
                 "world!"))

; (b) (Driver A)
(+ 32 (* 8 60) (* (/ 1 2) 4 (expt 60 2)))

; (c) (Driver B)
(odd? (length (string-split "4,9,10,11,2,3" ",")))

Finally, with your partner, review your results for parts (a) and (c) and consider this statement:

When reading Scheme expressions, read them "inside-out" or "right-to-left."

Explain why this statement makes sense given what you know about how expressions evaluate and how they are syntactically formed.

Exercise 4: Making a Statement (Driver A)

In our first Scheme work, we learned that define is a construct that allowed us to introduce identifiers or named values into our programs. Each identifier/name is associated with ("bound to") a value. (Some people call these "variables"; since they don't vary, we will try to avoid that name.)

> (define x 10) ; binds the identifier/name x to the value 10
> (+ x 1)
11

Let's go through the process of trying to understanding how define in Scheme programs. Along the way we'll update our mental model of computation to account for what we observe in our experimentation. Note that this problem is a microcosm of the language-learning experience. As you learn new constructs and techniques, you'll find that your current understanding of how program works does not account for these things, and you will evolve your learning. Usually this evolution amounts to abstracting your understanding so that it applies to more scenarios than before!

At first glance the define construct above looks similar to the operator form or function call form of expressions we identified in the reading:

(<identifier> <expr1> ... <exprk>)

If this was the case, this implies that we can use define anywhere an expression is considered. For example, perhaps we can get the same effect as the code above by inlining the define into the addition:

> (+ (define x 10) 1)

• Try this example out in Scheme. What is the output that you receive or what errors are produced if the code is invalid?
• Develop two other examples of trying to use define as an expression, similar to the give example case. (You should write these down on the piece of paper.) For inspiration, try replacing a value in an expression you've written already with (define x <value>).
• Write down the output or errors that you get in each case.
• Answer the following question based on your experience: Is the define form an expression?

Exercise 5: The syntax of define (Driver B)

From the previous exercise, you should have concluded that define is not an expression! We certainly do not seem to be able to put a define form anywhere an expression is expected. Consequently, we must ask ourselves: what syntactic category is a define and how does it relate to expressions?

It turns out that define is an example of a syntactic category distinct from expressions; it is a statement!

A statement is a construct that produces an effect in our program.

We'll have more to say about "effects" in our programs later in the course. For now, we'll say that the "effect" of a define statement is simple: it binds a value to an identifier. In the example that started this problem, we bound 10 to the identifier x. Consequently, whenever we mention x in our program, we really mean the value that is bound to that identifier, 10 in this case.

First let's address the syntax of a define. So we far, we have seen that define takes the following form:

(define <??> <??>)

Where we haven't quite defined what goes in either <??> yet. We assumed that a define statements binds an identifier, so it stands to reason that the first placeholder should be an identifier:

(define <identifier> <??>)

With your partner, try out define statements with different potential identifiers and different things in the last position. You should try out various constructs that you've learned in the reading so far, in particular, the different forms of expressions. From your experimentation, describe in a sentence what can appear in the final position of a define statement and complete the syntax rule with the syntactic category allowed in that position.

Exercise 6: Potential complexities (alternating Drivers)

Now let's think about how define statements execute. In short, we execute statements in our program in sequential fashion. However, subtleties may arise in this execution model that we should consider.

For each of the following programs:

• Write down how you expect the following programs evaluate, step-by-step.
• Test your answers in Scamper.
• In a sentence or two, describe how the program executes and why the program ultimately behaves in the way that it does.

Note that some of these programs produce errors; that is intentional!

; (i) (Driver A)
(define x 5)
(define y (* 5 8))
(define z (+ 1 1))

(+ x y z)

; (ii) (Driver B)
(define x 20)
(define y (* x 20))
(define z (* y y))

(+ x y z)

; (iii) (Driver A)
(define x 10)
(define y (+ x z))
(define z (* x 2))

(+ x y z)

; (iv) (Driver B)
(define x 10)
(define y (+ x 1))
(define x (* y 2))

(+ x y)

Exercise 7: Explaining define

In your own words, explain how our Scheme interpreter deals with a sequence of (interleaved expressions and define statements).
That is, what does the Scheme interpreter do if you write some define statements and some expressions and some more define statements and some more expressions and so on and so forth?

For example, consider what it does with the following.

(define x 10)   ; define statement
(+ x x)         ; expression
(define y 11)   ; define statement
(sqr y)         ; expression
(sqr x)         ; expression
(define z 12)   ; define statement
(define a 1)    ; define statement
(+ x y z)       ; expression

Submitting your work

Write your names at the top of the page.

Hand the page to one of the course staff.

Mental models of computation

So far, we have introduced a number of features of the Scheme programming language including top-level definitions, procedure declarations, and procedure applications. We have also focused nearly exclusively on how to author programs using these tools, appealing to your intuition about these constructs to explain how they work.

We've also recently learned about the substitutive model of evaluation. Basically, to evaluate an expression, we evaluate all of the arguments to the function and then apply the function. For convenience, we've been doing this left-to-right. The self-referential nature of the model also means that we end up evaluating expressions from inner to outer.

As you might expect, procedures complicate matters. Our intuition and the model might not be enough when we run into some special situations (some folks call these "corner cases") that we may run into when writing Scheme programs.

For example, consider the following procedure definitions:

(define f (lambda (x) (+ x 1)))

(define g (lambda (y) (+ y 1)))

Are these two procedures equivalent? Textually, the procedures f and g are nearly identical, but the names of the parameters are different. Does this difference matter? Our intuition says no: parameter names don't seem to matter in this regard. For example, if we try out these procedures in the Interactions pane:

> (f 5)
6
> (g 5)
6
> (f -1)
0
> (g -1)
0

There's too many integers to test in this manner, but after a few checks of this sort, we feel pretty confident in our intuition.

However, what happens if we have the following situation:

(define x 100)

(define f (lambda (x) (+ x 1)))

What will (f 10) produce? Two possible answers are:

• 101 if the defineed version of x is used in the computation of f.
• 11 if the value of 10 that is passed to the procedure is used.

But maybe the code produces an error because there are two different x's, and the computer gets confused. Or even more bizarre, but not out of the realm of possibility: maybe the defineed x is now 10 or 11!

Which of these is the correct answer? We can, of course, run this code to find out:

> (f 10)
11
> x
100

But why is this the case? What rules govern the execution of Scheme programs and how can they explain this behavior?

Before going too much further, let's try a similar pair of procedures.

(define eff (lambda (x) (+ x x)))

(define gee (lambda (y) (+ x y)))

Once again, we have a pair of procedures that seem to differ primarily in the name of the parameter. Both add the parameter to x. But is it the same x? What do you expect to happen for each of the following?

> (eff 10)

> (gee 10)

Before reading on, come up with a hypothesis.

Did you do so?

Great. Try it in your Scheme interpreter (DrRacket or Scamper or ...). You may also want to look at our notes at the end.

(Pause inserted in document so that you can check your answer by entering it in a Scheme interpreter, looking at the notes, or both.)

Since x does not always have a value, (gee 10) results in an error that x is undefined.

However, if x is defined, things will work fine. The two functions will just be a bit inconsistent.

> (define x 100)
> (eff 10)
20
> (gee 10)
110

As you've likely concluded, understanding all that is going on is a bit complex.

In this reading, we'll consider a set of rules to help us better understand Scheme programs: a mental model of computation. This mental model will allow us to interpret many Scheme programs and accurately predict their results. Note that the mental model does not completely follow the implementation used in most Scheme interpreters; life is a bit too complex for that. However, it will help you understand most small programs. And we will extend the model throughout the semester.

Expressions

As we've seen, expressions lie at the core of Scheme. Expressions are syntactic constructs that evaluate to values. We are intimately familiar with expressions already: they form the basis of computation in arithmetic! For example, here is an arithmetic expression:

\[ 3 × (8 + 4 ÷ 2) \]

This expression evaluates to a final value, \( 30 \). We say that \( 30 \) is a value: it is an expression that no longer takes any steps of evaluation.

The analogous Scheme code is also an expression:

> (* 3 (+ 8 (/ 4 2)))
30

This extends to Scheme code that doesn't involve numbers at all!

(> (string-upcase (string-append "hello world" "!!!"))
"HELLO WORLD!!!"

Here the expression produces a string as output---the upper-case version of the string resulting from gluing "hello world" and "!!!" together.

A substitutive model of evaluation

The process of determining the value that an expression produces is called evaluation. The evaluation of expressions is the primary way that we perform computation in Scheme! But how do expressions evaluate? We determine how expressions evaluate by applying two basic sets rules:

1. Rules of precedence that tell the order in which to evaluate operators.
2. Associativity rules that tell us how the arguments to operators bind when chained together.

For arithmetic, we know that division and multiplication are evaluated before addition and subtraction. Furthermore, expressions in parentheses are evaluated first, irrespective of the operators involved. Finally, we typically expect that the arithmetic operators are left-associative resulting in a left-to-right evaluation order.

  3 × (8 + 4 ÷ 2)
= 3 × (8 +   2  )
= 3 ×     10
= 30

At every step of evaluation,

1. We determine the sub-expression to evaluate next based off of our rules.
2. We evaluate that sub-expression to a value.
3. We substitute the resulting value for that sub-expression to create a new, slightly simplified expression.

We then repeat this process until we arrive at a final value.

While we may find Scheme's syntax arcane at first, it has one major benefit: There is only one rule for determining order-of-operations for expressions! That rule is straightforward: evaluate the arguments to a procedure before appling the procedure! (Some of us say "evaluate the innermost parenthesized expression first".) There is nothing else to know. Or almost nothing else to know. Let's see how that works for the Scheme version of this arithmetic expression:

    (* 3 (+ 8 (/ 4 2)))
--> (* 3 (+ 8    2  ))
--> (* 3      10     )
--> 30

(Note that we use the symbol --> to denote that one expression in Scheme evaluates or steps to another expression.)

Perhaps it would've been better in grade school if you were introduced to Scheme-style infix notation for arithmetic operations first. There are fewer rules to memorize, after all.

Okay, perhaps it's not quite that simple. What happens if a a procedure is called with multiple arguments, each of which is an expression?

    (* (+ 1 2) (+ 4 1))

We need to evaluate the (+ 1 2) before we do the multiplication. We need to evaluate the (+ 4 1) before we do the multiplication. But which of those to should we do first? Generally, it doesn't matter. Let's check.

First, we'll evaluate the first argument first.

    (* (+ 1 2) (+ 4 1))
--> (* 3 (+ 4 1))
--> (* 3 5)
--> 15

Next, we'll evaluate the second argument first.

    (* (+ 1 2) (+ 4 1))
--> (* (+ 1 2) 5)
--> (* 3 5)
--> 15

You may not be surprised to discover that we got the same result in each case. But it turns out that we can't guarantee that in all programming languages. (We can't even guarantee it in Scheme, but we can guarantee it for most of the programs we write.) Nonetheless, for the time being, you can assume that the order in which we evaluate arguments does not matter, provided you evaluate arguments before you apply a procedure. And, even though the order does not matter, we will generally evaluate arguments left to right.

Definitions

We have a starting point. We know how to evaluate expressions. But expressions often involve identifiers (names). In Scheme, we bind values to identifiers using define statements. How should we mentally model define statements and the names they define?

One easy way to think about them is in terms of a table that tells us what value to use for each name. When we see a define statement, we first evaluate the expression and then we put the name and the value in the table. We tend to write that as name:value.

    ; Table: []
    (define x 5)
    ; Table: [x:5]
    (define y 17)
    ; Table: [x:5, y:17]
    (define z (* 2 3))
--> (define z 6)
    ; Table: [x:5, y:17, z:6]

What good is the table? The table informs how we evaluate expressions that consist only of variables (named values). When evaluating an expression, when the next expression to evaluate is a variable, we look in the table to find the value associated with the variables.

    ; Table: []
    (define x 10)
    ; Table: [x:10]
    (define y 2)
    ; Table: [x:10, y:2]
    (+ (* x 4) y))
    ; We need to evaluate the (* x 4) before we add
    ; We need to evaluate the x before we multiply.
    ; We look x up in the table
--> (+ (* 10 4) y)
    ; We need to evaluate the (* 10 x) before we add
--> (+ 40 y)
    ; We need to evaluate the y before we add
    ; We look y up in the table
--> (+ 40 2)
--> 42

Seems pretty straightforward. Right? What happens if we write an expression that involves a variable not in the table?

    ; Table: [x:10]
    (+ (* x 4) y))
--> (+ (* 10 4) y)
--> (+ 40 y)
    ; y is not in the table
    y: undefined

Note that these tables are mostly a notational convenience, designed to make it easier for us to figure out the value of expressions when we're tracing. However, most programming languages, including Scheme, also have a hidden form of table which basically does the same thing (that is, that associates values with variables names).

Procedures and the substitutive model

When we evaluate procedures, we have implicitly "carried out the behavior of the procedures" in our head and replaced the procedure call with the value. For example

    (+ 1 1)
--> 2

We know how addition works, so we can treat the evaluation of + as a single step. Of course, if the arguments to + required evaluation first, we would need to carry that out according to our evaluation rules:

    (+ (+ 1 1) 8)
--> (+    2    8)
--> 10

The step-by-step evaluation of an expression to a final value is called the execution trace or just trace of a particular expression.

However, what happens when our procedures are those we have defined ourselves? For example, something simple like double:

(define double
  (lambda (n) 
    (* 2 n)))

How does an expression like (double (/ 6 3)) evaluate? As a first order of business, we should evaluate its argument to a value.

    (double (/ 10 2))
--> (double 5)

Good! Now how does (double 5) evaluate? We proceed as follows:

1. We substitute the body of the procedure for the procedure call in question. The body of double is (* 2 n) so we would replace (double 5) with (* 2 n).
2. Note that, on its own, the parameter n is not defined! To patch this up, we also substitute each argument for its associated parameter in the body of the procedure. We pass 5 for n so we ultimately replace (double 5) with (* 2 5).

All of this occurs in one step of evaluation and afterwards, we continue evaluation of the expression as normal. So the complete evaluation of our original expression is:

    (double (/ 10 2))
--> (double    5)
--> (* 2 5)
--> 10

While this rule is simple, it covers almost all occurrences of procedures we'll see in Scheme! This is the beauty of a programming language at its core: a small set of rules governs a near, unimaginable set of behavior we can author in a computer program!

Definitions, tables, and procedures

We've separately considered models for the definitions that let us evaluate variables for procedures. Let's also consider them together. We know that (define var exp) evaluates the expression and the pairs it with the variable in a table. So what happens when we write (define var (lambda (params) body))?

It turns out that Scheme does something a bit special with lambda expressions (expressions that begin with lambda). Instead of evaluating them further, Scheme stops evaluating until you need to apply the lambda expression. Then, and only then, does it do what we described above: We substitute it in for the name and then replace its named parameters (the "formals", in CS parlance) with the values of the corresponding arguments (the "actuals", in CS parlance).

It turns out that these model of operation means we can use lambdas without defining them. We'll leave that issue for a bit later in your education.

Self-checks

Check 1: Code tracing (‡)

Assume the existence of the following Scheme definitions:

(define add-3
  (lambda (x y z)
    (+ (+ x y) z)))

(define triple
  (lambda (n)
    (add-3 n n n)))

With these definitions, give the step-by-step evaluation (i.e., evaluation traces) for each of the following expressions. Please do this by hand; don't rely on the tools that might be part of your Scheme interpreter. Make sure to write down all steps of evaluation as required by our substitutive model of computation!

1. (+ 3 (* 5 (/ 2 (- 10 5))))
2. (add-3 (* 2 3) (+ 8 3) (/ 1 2))
3. (triple (+ 5 0.25))

Make sure to check your work by entering these expressions into your Scheme interpreter!

Appendices

Appendix A: eff and gee

What should we get for (eff 10)? Presumably, x gets the value 10, we add the two 10 values together, and end up with 20.

Let's check.

> (eff 10)
20

But what happens when we try (gee 10)? In that case, y gets the value 10. What value does x have? Unless we've defined x with define, it has no value. Perhaps we'll get an error.

> (gee 10)
. . x: undefined;
 cannot reference an identifier before its definition

Expressions and types

From our discussion of mental models of computation, we know that Scheme programs are composed primarily of expressions, program fragments that evaluate to values. What are the different kinds of values that expressions can evaluate to? In other words, what kinds of data can our Scheme programs manipulate? We've seen some examples already, e.g.,

• Numbers:

  (* 3 (- 1 5) (+ 2 4))
  
  

• Strings:

  (string-append "hello" "world!")
  

• Images:

  (import image)
  
  (beside (circle 50 "solid" "blue") (square 25 "solid" "red"))
  

But are there others? What are the different categories of data we might operate over and how are they organized? In this reading, we focus on the different kinds of primitive values that we can manipulate in our Scheme programs.

Primitive vs. compound data

In computer programming, we can categorize the wide-range of data into two sorts:

• Compound data: data that is made up of other, smaller pieces of data.
• Primitive data: "indivisible" data, i.e., data that cannot be broken up into smaller pieces.

For example, consider representing a student in a computer program. A student has many potential pieces of data associated with them, e.g.,

• Name,
• Email,
• Student ID,
• Age,
• Hometown,
• Current GPA, and
• Current classes for the fall.

In this sense, students are examples of compound data. An individual student, from the perspective of a computer program, is made up of these parts.

In contrast, consider just the student's age. The student's age compromises of a single number, usually just a natural number, zero or a positive integer (non-fractional) quantity. At the level of abstraction we're working at, we think of numbers as indivisible units---unlike a student, a number isn't made up of small data. In this sense, numbers are examples of primitive data. Another term for primitive data are atomic data because they cannot be broken up any further.

Types

We intuitively recognize that these values:

3
0
-1
47

Are different from these values:

"hello!"
"csc151"
"world"
"47"

The primitive versus compound distinction allows us to categorize groups of data based on their "atomicity." However, within these buckets are different categories of data. We call such a category a type. For example, the first set of values are all numbers whereas the second set of values are all strings. We say that each of the values are instances of these types, e.g., 3 is an instance of the number type or 3 has type number.

Types of expressions

We assign types to particular values, e.g., 5 has type "number" (or, more precisely, "exact integer"). Recall that a value is an expression that takes no further steps of evaluation. We can define the type of any expression, not just values, as follows:

The type of an expression is the type of the value that the expression evaluate to.

Types of functions

For example (+ 1 1) is a non-value expression that has type number. We know this because (+ 1 1) --> 2 and 2 is a number.

When we perform operations over data, e.g., addition through the + function, we must provide values of the appropriate type. Here, + expects to be given at least one argument, all of which must be numbers:

(+ 1 3 5 7 9)

When a function is provided values of an appropriate type, a type error occurs when trying to run that function on those values. For example:

(+ 1 "hello")

Scheme realizes these type errors as contract violations when trying to execute the function. Intuitively, we can think of + as specifying the following contract:

If you provide me with values that are all numbers, I will give you back a number that is the sum of those input numbers.

From this contract, we say that the type of the function is the expected type of its inputs and output. For + the expected types of the inputs as numbers and the expected type of the output is a number.

For function types, the types of the inputs and outputs don't have to be the same, e.g.,

• (string-length "hello world") evaluates to 11. The type of the input to string-length is a string and the output is a number (exact integer).
• (substring "hello world" 2 5) evaluates to "llo"---substring returns the portion of the string starting with the character at the index (inclusive) denoted by the first argument and ends with the character at the index (exclusive) denoted by the last argument. substring takes a string and two numbers as input and produces a string as output. (Note: the indices of a string start at 0, so l is indeed the character at index 2!)

As you have likely noticed, keeping the type of a function in mind is really important for debugging your code. For example, consider the following erroneous call to circle:

(import image)

(circle "red" "solid" 500)

If we recall that the type of circle is:

• circle is a function that takes a number (the radius), a string or symbol (the fill), and string or symbol (the color) as input and produces an image as output.

We'll note that the problem with the code is that we've incorrectly interchanged the radius and the color!

Type mismatches of this sort are a common error in programming, especially when you start out. Whenever you write code, try to keep in mind:

What is the intended type of the expression that I am trying to write?

This mentality will bring you one step closer towards truly writing code in an intentional, purposeful fashion and not simply throwing random stuff at the wall and seeing if it works!

Primitive data in Scheme

The remainder of today's readings are broken up into readings for two of the major primitive types we see in Scheme:

• [Numbers]({{ "/readings/numbers.html" | relative_url }})
• [Characters and Strings]({{ "/readings/strings.html" | relative_url }})

For each of these primitives, we introduce the following concepts:

1. What does a datum of this type represent?
2. How do we make values of this type?
3. What library functions are available for manipulating values of these types?

You do not have to memorize all of this information in one go as it is a lot of stuff! Instead, you should look initially to get the big picture: what broad sorts of operations are possible with each type of data and what can I expect to do? From there, you can always refer back to these readings and Scamper reference found in VSCode to find particular functions to achieve the effect you are looking for.

Self-checks

The readings on primitive data have a number of self-checks. Please complete the following self-checks for your reading question set for this collection:

• (‡) Numbers: Check 1 (Exploring exponentiation)
• (‡) Collating Sequences: Check 2 (Collating sequences)

Numeric values

In this reading, we examine a variety of issues pertaining to numeric values in Scheme, including the types of numbers that Scheme supports and some common numeric functions.

Introduction

Computer scientists write algorithms for a variety of problems. Some types of computation, such as representation of knowledge, use symbols and lists. Others, such as the construction of Web pages, may involve the manipulation of strings (sequences of alphabetic characters). Even when working with text, a significant amount of computation involves numbers. And, even though numbers seem simple, it turns out that there are some subtleties to the representation of numbers in Scheme.

As you may recall from our first discussion of data types, when learning about data types, you should consider the name of teach type, its purpose, how Scamper displays values in the type, how you express those values, and what operations are available for those values.

While it seems like "numbers" is an obvious name for this type, Scheme provides multiple kinds of numeric values. In each case, the purpose is the same: to support computation that involves numbers.

Categories of numeric values

As you probably learned in secondary school, there are a variety of categories of numeric values. The most common categories are integers, (numbers with no fractional component), rational numbers (numbers that can be expressed as the ratio of two integers), and real numbers (numbers that can be plotted on a number line). You also learned about complex numbers (numbers that can include an imaginary component) that arose when you solved polynomials with real coefficients.

In traditional mathematics, each category is a subset of the next category. That is, every integer is a rational number because it can be expressed with a denominator of zero, every rational number is a real number because it can be plotted on the number line, and every real number is complex because it can be expressed with an imaginary component of zero.

In contrast, Scamper does not readily distinguish the rational and real numbers. Instead, like most conventional programming languages, Scamper distinguishes between two broad classes of numbers:

• Integral values, i.e., numbers without a fractional component, e.g., 427198.
• Floating-point values, i.e., numbers with a fractional component, e.g., 3.4170.

Importantly, because these numbers must be physically stored in a computer somewhere, they are necessary bounded values, i.e., there are limits to the sizes of values these numbers can represent.

Recall that some numbers, e.g., the irrational numbers such as \( \pi \), have infinite decimal expansions. A consequence of the bounded nature of numbers in a computer program is that we have to represent numbers like \( \pi \) as approximations. In other cases, when we perform some computations involving infinite fractional components, we may induce round-off error because we have to store these infinite values using a finite amount of space.

When Scamper displays a number that is a floating point value, it includes a decimal point, an exponential component in the result, or both.

(sqrt 2)
(expt 3.0 100)

Why is the square root of 2 approximated? Because it's impossible to represent precisely as a finite decimal number. That means that Scamper approximates it. And, because it's approximated, our calculations using that result will also be approximate.

(* (sqrt 2) (sqrt 2))

The decimal sign warns us that we are straying into the realm of estimations and approximations.

In contrast, integer computations are always exact provided that we don't produce numbers that are bigger than the maximum size of an integer in Scamper. In those cases, Scamper will automatically move to a floating-point representation which is approximate.

(+ 1 1)
(/ 10 2)
(* 426198421879421897412 4782147894721489712)

You can express values to Scamper using similar notation. That is, when you want a precise integer value, you do not include a decimal point or the exponent. When you want a floating-point number, you include the dot and/or exponent.

-3
0.5
(+ 1 1e-7)

In general, programmers tend to model objects in the world using integers because they provide precise, predictable results. When we use floating-point numbers, we have to be highly aware of their approximate nature and go out of our way to ensure our programs are correct in spite of those limitations. In fact, whole areas of mathematics, e.g., applied computational mathematics, are dedicated to studying algorithms that perform tasks with floating-point numbers that minimize errors!

When describing the procedures that work with numbers, we should try to describe how the type of the result depends on the type of the input. For example, the addition operator, ,+ provides an integer result only when all of its inputs are integers. Note that Scamper will gladly give an integral result if it can deduce that one of the arguments is actually integral, even when written as a floating-point number.

(+ 2 3 4)
(+ 2 3.0 4)
(+ 2 1e-3 5)
(+ 2 3.0 -3.1)

Numeric operations

You've already encountered the four basic arithmetic operations of addition (+), subtraction (-), multiplication (*), and division (/). But those are not the only basic arithmetic operations available. Scheme also provides a host of other numeric operations. We'll introduce most as they become necessary. For now, we'll start with a few basics.

Integer division

In addition to "real division", Scheme also provides two procedures that handle "integer division", quotient and remainder. Integer division is is likely the kind of division you first learned; when you divide one integer by a number, you get an integer result (the quotient) with, potentially, some left over (the remainder). For example, if you have to divide eleven jelly beans among four people, each person will get two (the quotient) and you'll have three left over (the remainder).

(quotient 11 4)
(remainder 11 4)
(quotient 15 5)
(remainder 15 5)

We also get sensible results when mixing floating-point and integer values.

(quotient 5.5 2)
(remainder 5.5 4)

Roots and exponents

As you've seen, Scheme provides ways to compute the square root of a number, using (sqrt x) and to compute "x to the n" using (expt x n). When given integer inputs, both return inexact results. Both will provide floating-point results if the output demands it or if the inputs are floating-point numbers.

(sqrt 4)
(sqrt 4.0)
(sqrt 2)
(expt 2 5)
(expt 0.3 0.8)

What happens when we take the square root of a negative number? Recall that the result is a complex number, a number with the imaginary number $$i$$.

(sqrt -2)

In Scamper, we get NaN which is a special number called Not a Number. NaNs are produced by our math operations when they would end up producing a non-real number.

Finding small and large values

Scheme provides the (max val1 val2 ...) and (min val1 val2 ...) procedures to find the largest or smallest in a set of values. Both of these procedures will produce an exact number only when all of the arguments are exact. As you might expect, the value produced will be an integer only when it meets the criterion of being largest or smallest.

(max 1 2 3)
(max 3 1 2)
(max 2 1 3)
(max 1 2 3 1.5)
(min 3 1 2 4 8 7 -1)

Rounding

Scheme provides four different ways to round real numbers to nearby integers. (round num) rounds to the nearest integer. (floor num) rounds down. (ceiling num) rounds up. (truncate num) throws away the fractional part, effectively rounding toward zero.

(round 3.2)
(round 3.8)
(floor 3.8)
(ceiling 3.8)
(truncate 3.8)
(floor -3.8)
(truncate -3.8)

Self Checks

Check 1: Exploring exponentiation (‡)

In the examples above, we gave a wide variety of examples of the expt procedure in action. Try expt on additional examples of your own design, and try to cover all the possible combinations of integer, negative/non-negative, and floating-point values to the function.

After you have done this, try to summarize as concisely as possible the situations in which expt will produce:

• An integral result and
• A floating-point result.

Characters and strings

Computer scientists refer to text in many ways. A text file is a document stored on the file system in a computer that contains text. A string is a piece of text available within a computer program. And a character is the basic building block that we use to create strings. In this reading, we explore the representation of characters and strings in Scheme. In a subsequent reading, we will consider files.

As you may recall, there are five issues we typically consider as we encounter a new type: The name of the type, the purpose of the type, the way you express elements of the type, the way Scamper displays elements of the type, and the operations of the type. In this reading, we consider characters and strings, two of the important primitive data types in many languages. Characters are the building blocks of strings. Strings, conversely, are combinations of characters. Both characters and strings are useful for input and output.

About characters

A character is a small, repeatable unit within some system of writing -- a letter or a punctuation mark, if the system is alphabetic, or an ideogram in a writing system like Han (Chinese). Characters are usually put together in sequences that computer scientists call strings.

Although early computer programs focused primarily on numeric processing, as computation advanced, it grew to incorporate a variety of algorithms that incorporated characters and strings. Some of the more interesting algorithms we will consider involve these data types. Hence, we must learn how to use this building blocks.

Characters in Scheme

We've covered the name of this type (character) and its purpose (to represent the individual components of a string or other piece of text). What's next? How to represent characters.

As you might expect, Scheme needs a way to distinguish between many different but similar things, including: characters (the units of writing), strings (formed by combining characters), symbols (which look like strings, but are treated as atomic and also cannot be combined or separated), and identifiers (names of values). Similarly, Schemes needs to distinguish between numbers (which you can compute with) and digit characters (which you can put in strings).

In Scheme, a name for any of the text characters can be formed by writing #\ before that character. For instance, the expression #\a denotes the lower-case a. Of course, lower-case a should be distinguished from the upper-case A character, (denoted by #\A), from the symbol that you obtain with 'a, from the string "a", and from the name a. Similarly, the expression #\3 denotes the character 3 (to be distinguished from the number 3) and the expression #\? denotes the question mark (to be distinguished from a symbol and a name that look quite similar).

In addition, some characters are named by pound, backslash, and a longer name. In particular, the expression #\space denotes the space character, and #\newline denotes the newline character (the one that is used to terminate lines of text files stored on Unix and Linux systems).

Collating sequences

In any implementation of Scheme, it is assumed that the available characters can be arranged in sequential order (the "collating sequence" for the character set), and that each character is associated with an integer that specifies its position in that sequence. In ASCII, the American Standard Code of Information Interchange, the numbers that are associated with characters run from 0 to 127; in Unicode, a more extensive character set intended to support most languages, they lie within the range from 0 to 65535. (Fortunately, Unicode includes all of the ASCII characters and associates with each one the same collating-sequence number that ASCII uses.) Applying the built-in char->integer procedure to a character gives you the collating-sequence number for that character; applying the converse procedure, integer->char, to an integer in the appropriate range gives you the character that has that collating-sequence number.

The importance of the collating-sequence numbers is that they extend the notion of alphabetical order to all the characters. Scheme provides five built-in predicates for comparing characters (char<?, char<=?, char=?, char>=?, and char>?). They all work by determining which of the two characters comes first in the collating sequence (that is, which one has the lower collating-sequence number).

The Scheme specification requires that if you compare two capital letters to each other or two lower-case letters to each other, you'll get standard alphabetical order: (char<? #\A #\Z) must be true, for instance. If you compare a capital letter with a lower-case letter, though, the result depends on the design of the character set. In ASCII, every capital letter (even #\Z) precedes every lower-case letter (even #\a). Similarly, if you compare two digit characters, the specification guarantees that the results will be consistent with numerical order: #\0 precedes #\1, which precedes #\2, and so on. But if you compare a digit with a letter, or anything with a punctuation mark, the results depend on the character set.

Handling case

Because there are many applications in which it is helpful to ignore the distinction between a capital letter and its lower-case equivalent in comparisons, Scheme also provides case-insensitive versions of the comparison procedures: char-ci<?, char-ci<=?, char-ci=?, char-ci>=?, and char-ci>?. These procedures essentially convert all letters to the same case before comparing them.

There are also two procedures for converting case, char-upcase and char-downcase. If its argument is a lower-case letter, char-upcase returns the corresponding capital letter; otherwise, it returns the argument unchanged. If its argument is a capital letter, char-downcase returns the corresponding lower-case letter; otherwise, it returns the argument unchanged.

More character predicates

Scheme provides several one-argument predicates that apply to characters: (We'll explain more about predicates in a subsequent reading.)

• char-alphabetic? determines whether its argument is a letter (#\a through #\z or #\A through #\Z, in English).
• char-numeric? determines whether its argument is a digit character (#\0 through #\9 in our standard base-ten numbering system).
• char-whitespace? determines whether its argument is a "whitespace character", one that is conventionally stored in a text file primarily to position text legibly. In ASCII, the whitespace characters are the space character and four specific control characters: tab, line feed, form feed, and carriage return. On most systems, #\newline is a whitespace character. On our Linux systems, #\newline is the same as line feed and counts as a whitespace character.
• char-upper-case? determines whether its argument is a capital letter.
• char-lower-case? determines whether its argument is a lower-case letter.

It may seem that it's easy to implement some of these operations. For example, you might want to implement char-alphabetic? using a strategy something like the following.

A character is alphabetic if it is between #\a through #\z or between #\A through #\Z

However, that implementation is not necessarily correct for all versions of Scheme: Since the Scheme specification does not guarantee that the letters are collated without gaps, it's possible that this algorithm treats some non-letters as letters. The alternative, comparing to each valid letter in turn, seems inefficient. It is also biased toward American English, making it inappropriate for languages with different alphabets. By making this procedure built-in, the designers of Scheme have encouraged programmers to rely on a correct (and, presumably, efficient) implementation.

(char<=? #\a #\n #\z)
(char-lower-case? #\n)
(char<=? #\a #\N #\z)
(char-lower-case? #\N)
(char<=? #\a #\ñ #\z)
(char-lower-case? #\ñ)

Note that all of these predicates assume that their parameter is a character. Hence, if you don't know the type of a parameter, you will need to first ensure that it is a character. For example,

(char-lower-case? #\a)
(char-lower-case? #\5)
(char-lower-case? 23)
(and (char? 23) (char-lower-case? 23))
(define lower-case-char? (lambda (x) (and (char? x) (char-lower-case? x))))
(lower-case-char? 23)
(lower-case-char? #\a)

String basics

We've now covered the five primary issues for the character type: Its name, purpose, representation and display (with pound and backslash), and some important operations. It is now time to turn our attention to strings, the longer pieces of text we can build with characters.

Once again, we've covered the name and the purpose quickly. Strings provide a mechanism for representing text by joining together a sequence of characters. (We even allow that sequence to have no characters; in that case, we call it the empty string.)

How do we express strings? Most strings can be expressed by enclosing the characters they contain between plain double quotation marks, to produce a string literal. For instance, "periwinkle" is the nine-character string consisting of the characters #\p, #\e, #\r, #\i, #\w, #\i, #\n, #\k, #\l, and #\e, in that order. Similarly, "" is the zero-character string (the null string or the empty string).

String literals may contain spaces and newline characters; when such characters are between double quotation marks, they are treated like any other characters in the string. There is a slight problem when one wants to put a double quotation mark into a string literal: To indicate that the double quotation mark is part of the string (rather than marking the end of the string), one must place a backslash character immediately in front of it. For instance, "Say \"hi\"" is the eight-character string consisting of the characters #\S, #\a, #\y, #\space, #\", #\h, #\i, and #\", in that order. The backslash before a double quotation mark in a string literal is an escape character, present only to indicate that the character immediately following it is part of the string.

This use of the backslash character causes yet another slight problem: What if one wants to put a backslash into a string? The solution is similar: Place another backslash character immediately in front of it. For instance, "a\\b" is the three-character string consisting of the characters #\a, #\\ , and #\b, in that order. The first backslash in the string literal is an escape, and the second is the character that it protects, the one that is part of the string.

String operations

Scheme provides several basic procedures for working with strings:

The (string? val){:.signature} predicate determines whether its argument is or is not a string.

The (make-string count char){:.signature} procedure constructs and returns a string that consists of count repetitions of a single character. Its first argument indicates how long the string should be, and the second argument specifies which character it should be made of. For instance, the following code constructs and returns the string "aaaaa".

(make-string 5 #\a)

The (string ch_1 ... ch_n){:.signature} procedure takes any number of characters as arguments and constructs and returns a string consisting of exactly those characters. For instance, (string #\H #\i #\!) constructs and returns the string "Hi!". This procedure can be useful for building strings with quotation marks. For example, (string #\" #\") produces "\"\"". (Isn't that ugly?)

The (string->list str){:.signature} procedure converts a string into a list of characters. The (list->string char-list){:.signature} procedure converts a list of characters into a string. It is invalid to call list->string on a non-list or on a list that contains values other than characters.

(string->list "Hello")
(list->string (list #\a #\b #\c))

(Note: it looks like there is a bug with the interpreter used in the reading. Individual characters are printed as $\h instead of #\h, i.e., with a dollar sign instead of a hash!)

The (string-length str){:.signature} procedure takes any string as argument and returns the number of characters in that string. For instance, the value of (string-length "magenta") is 7 and the value of (string-length "a\\b") is 3.

The (string-ref str pos){:.signature} procedure is used to select the character at a specified position within a string. Like list-ref, string-ref presupposes zero-based indexing; the position is specified by the number of characters that precede it in the string. (So the initial character in the string is at position 0, the next at position 1, and so on.) For instance, the value of (string-ref "ellipse" 4) is #\p -- the character that follows four other characters and so is at position 4 in zero-based indexing.

Strings can be compared for "lexicographic order", the extension of alphabetical order that is derived from the collating sequence of the local character set. Once more, Scheme provides both case-sensitive and case-insensitive versions of these predicates: string<?, string<=?, string=?, string>=?, and string>? are the case-sensitive versions, and string-ci<?, string-ci<=?, string-ci=?, string-ci>=?, and string-ci>? the case-insensitive ones.

The (substring str start end){:.signature} procedure takes three arguments. The first is a string and the second and third are non-negative integers not exceeding the length of that string. The substring procedure returns the part of its first argument that starts after the number of characters specified by the second argument and ends after the number of characters specified by the third argument. For instance: (substring "hypocycloid" 3 8) returns the substring "ocycl" -- the substring that starts after the initial "hyp" and ends after the eighth character, the l. (If you think of the characters in a string as being numbered starting at 0, substring takes the characters from start to end - 1.)

The (string-append str1 str2 ... strn){:.signature} procedure takes any number of strings as arguments and returns a string formed by concatenating those arguments.

(string-append "al" "fal" "fa")

The (number->string num){:.signature} procedure takes any Scheme number as its argument and returns a string that denotes the number.

(number->string 23)
(number->string 1.2)
(number->string pi)

The (string->number str){:.signature} procedure provides the inverse operation. Given a string that represents a number, it returns the corresponding number. On some implementations of Scheme, when you give string->number an inappropriate input, it returns the value #f (which represents "no" or "false"). You are then responsible for checking the result.

(string->number "23")
(string->number "1.2")
(string->number "0.000000000000000000000000001")
(string->number "")
(string->number "two")
(string->number "3 + 4i")
(string->number "3+4i")

The string-upcase and string-downcase procedures convert all of the letters in the string to uppercase or lowercase..

(string-upcase "aLpHaBeTiCAL")
(string-downcase "aLpHaBeTiCAL")

Appendix: Representing characters

When a character is stored in a computer, it must be represented as a sequence of bits ("binary digits", that is, zeroes and ones). However, the choice of a particular bit sequence to represent a particular character is more or less arbitrary. In the early days of computing, each equipment manufacturer developed one or more "character codes" of its own, so that, for example, the capital letter A was represented by the sequence 110001 on an IBM 1401 computer, by 000001 on a Control Data 6600, by 11000001 on an IBM 360, and so on. This made it troublesome to transfer character data from one computer to another, since it was necessary to convert each character from the source machine's encoding to the target machine's encoding. The difficulty was compounded by the fact that different manufacturers supported different characters; all provided the twenty-six capital letters used in writing English and the ten digits used in writing Arabic numerals, but there was much variation in the selection of mathematical symbols, punctuation marks, etc.

ASCII

In 1963, a number of manufacturers agreed to use the American Standard Code for Information Interchange (ASCII), which is currently the most common and widely used character code. It includes representations for ninety-four characters selected from American and Western European text, commercial, and technical scripts: the twenty-six English letters in both upper and lower case, the ten digits, and a miscellaneous selection of punctuation marks, mathematical symbols, commercial symbols, and diacritical marks. (These ninety-four characters are the ones that can be generated by using the forty-seven lighter-colored keys in the typewriter-like part of a MathLAN workstation's keyboard, with or without the simultaneous use of the Shift key.) ASCII also reserves a bit sequence for a "space" character, and thirty-three bit sequences for so-called control characters, which have various implementation-dependent effects on printing and display devices -- the "newline" character that drops the cursor or printing head to the next line, the "bell" or "alert" character that causes the workstation to beep briefly, and such.

In ASCII, each character or control character is represented by a sequence of exactly seven bits, and every sequence of seven bits represents a different character or control character. There are therefore 2⁷ (that is, 128) ASCII characters altogether.

Unicode

Over the last quarter-century, non-English-speaking computer users have grown increasingly impatient with the fact that ASCII does not provide many of the characters that are essential in writing other languages. A more recently devised character code, the Unicode Worldwide Character Standard, supports many more characters. At the time we first added Unicode to this reading, the standard defined bit sequences for at least 49194 characters for the Arabic, Armenian, Bengali, Bopomofo, Canadian Aboriginal Syllabics, Cherokee, Cyrillic, Devanagari, Ethiopic, Georgian, Greek, Gujarati, Gurmukhi, Han, Hangul, Hebrew, Hiragana, Kannada, Katakana, Khmer, Latin, Lao, Malayalam, Mongolian, Myanmar, Ogham, Oriya, Runic, Sinhala, Tamil, Telugu, Thaana, Thai, Tibetan, and Yi writing systems, as well as a large number of miscellaneous numerical, mathematical, musical, astronomical, religious, technical, and printers' symbols, components of diagrams, and geometric shapes. You can view many of the options at http://www.unicode.org/charts/.

Unicode uses a sequence of sixteen bits for each character, allowing for 2¹⁶ (that is, 65536) codes altogether. Many bit sequences are still unassigned and may, in future versions of Unicode, be allocated for some of the numerous writing systems that are not yet supported. The current version of Unicode The designers have completed work on the Deseret, Etruscan, and Gothic writing systems, although it appears that only Deseret and Gothic have been added to the standard. Characters for the Shavian, Linear B, Cypriot, Tagalog, Hanunoo, Buhid, Tagbanwa, Cham, Tai, Glagolitic, Coptic, Buginese, Old Hungarian Runic, Phoenician, Avenstan, Tifinagh, Javanese, Rong, Egyptian Hieroglyphic, Meroitic, Old Persian Cuneiform, Ugaritic Cuneiform, Tengwar, Cirth, tlhIngan Hol (that is, "Klingon"; can you tell that CS folks are geeks, even CS folks who work on international standards?), Brahmi, Old Permic, Sinaitic, South Arabian, Pollard, Blissymbolics, and Soyombo writing systems are under consideration, in preparation, or already added to the standard.

Although some local Scheme implementations use and presuppose the ASCII character set, the Scheme language does not require this, and Scheme programmers should try to write their programs in such a way that they could easily be adapted for use with other character sets (particularly Unicode).

Summary of notation and procedures

• Constant notation: #\ch (character constants) "string" (string constants).
• Character constants: #\a (lowercase a) ... #\z (lowercase z); #\A (uppercase A) ... #\Z (uppercase Z); #\0 (zero) ... #\9 (nine); #\space (space); #\newline (newline); and #\? (question mark).
• Character conversion: char->integer, integer->char, char-downcase, and char-upcase
• Character predicates: char?, char-alphabetic?, char-numeric?, char-lower-case?, char-upper-case?, char-whitespace?, char<?, char<=?, char=?, char>=?, char>?, char-ci<?, char-ci<=?, char-ci=?, char-ci>=?, and char-ci>?.
• String predicates: string?
• String constructors: make-string, string, string-append
• String extractors: string-ref, substring
• String conversion: list->string, number->string, string->list, string-upcase, string-downcase
• String analysis: string-length
• String comparison: string<?, string<=?, string=?, string>=?, string>?, string-ci<?, string-ci<=?, string-ci=?, string-ci>=?, string-ci>?

Self Checks

Check 1: Establishing types

Identify the type of each of the following Scheme values.

"a"
a
#\a

Check 2: Collating sequences (‡)

As you may recall, Scheme uses a collating sequence for the letters, assigning a sequence number to each letter. Many implementations of Scheme, including MediaScript, use the Unicode collating sequence. (ASCII, the American Standard Code for Information Interchange, is a subset of Unicode.)

a. Using char->integer, determine the Unicode collating-sequence numbers for the capital letter A and for the lower-case letter a. Then determine the Unicode collating-sequence numbers for the capital letter B and the lower-case letter b. Finally, determine the Unicode collating-sequence numbers for the capital letter X and the lower-case letter x. Do you notice any patterns?

b. Using integer->char, find out what Unicode character is in position 38 in the collating sequence.

c. Do the digit characters precede or follow the capital letters in the collating sequence?

d. If you were designing a character set, where in the collating sequence would you place the space character? Why?

e. What position does the space character occupy in Unicode? (Hint: See the character constants in the summary above.)

f. What character occupies position 477 in Unicode?

Check 3: Character predicates

Review the list of character predicates listed in the summary above.

a. Determine whether our implementation of Scheme considers #\newline a whitespace character.

b. Determine whether our implementation of Scheme indicates that capital B precedes or follows lower-case a.

c. Verify that the case-insensitive comparison operation, char-ci<?, gives the expected result for the previous comparison.

d. Determine whether our implementation of Scheme indicates that #\a and #\A are the same letter. (It should not.)

e. Find an equality predicate that returns #t when given #\a and #\A as parameters.

Q&A

Could you explain the (char<=? #\a #\n #\z) example?

Sure. Just like (<= 1 2 3) checks if 2 is between 1 and 3, (char<=? #\a #\n #\z) checks if #\n is between #\a and #\z, at least according to the collating sequence. What we see in the sample code is that lowercase n is between lowercase a and lowercase z (inclusive), but uppercase N is not. Lower n with a tilde (ñ) is not between lowercase a and lowercase z.

The #t you see is shorthand for "true".

What's an equality predicate?

A predicate is something that returns true or false. An equality predicate is something that checks whether two things are the same.

What significance does the number related to the character have in the unicode char->integer? Why does the order matter?

The numbers matter primarily in that we use the numbers in comparing characters (e.g., with char<=?). We'll also find some convenient ways of using the numbers. For example, you might notice that each lowercase letter is 32 more than the corresponding uppercase letter.

Why does (char->integer #\ ) also produce the same result as (char->integer #\space)? I get that they are more or less the same thing, but why did the creators of Scheme want this to be so?

Both #\ and #\space represent the space character. Most of us find the latter easier to read than the former. I'm not sure why the designers of Scheme permitted #\ (with the space), since it's almost impossible to read.

Why is the value of (string-length "a\\b") 3 rather than 4?

"\\" is how we write the backslash character. (Yes, that's right, we use two characters to reprsent a single character.) So "a\\b" is the character a, the backslash character, and the character b.

Basic Types

We explore some of the basic types that many implementations of Scheme, including Scheme, support. These include a variety of numeric types, characters, and strings.

Useful functions and notation

In the reading, we introduced a score of new functions for processing the basic types of Scheme. Think of them as an essential vocabulary for expressing basic computation in Scheme, similar to the new vocabulary you might encounter when learning a foreign language. However, unlike a foreign language, there isn't an expectation that you get a deck of flash cards and memorize these function names. Instead, the expectation is that you will eventually memorize these functions by consistently building programs that use these functions, i.e., practice.

To this end, we'll try to provide concise references to the functions that we introduce in the reading to aid you in your task. Feel free to note the location of these sections and use them to quickly look up the appropriate functions when needed. (Also feel free to write them down on flash cards for easy reference.)

Numbers

Basic numeric operations: +, -, *, /, quotient, remainder, expt.

Numeric conversion: floor, ceiling, round, truncate.

Numeric type predicates: number?, integer?.

Characters

Constant notation: #\ch (character constants)

Character constants: #\a (lowercase a) ... #\z (lowercase z); #\A (uppercase A) ... #\Z (uppercase Z); #\0 (zero) ... #\9 (nine); #\space (space); #\newline (newline); and #\? (question mark).

Character conversion: char->integer, integer->char, char-downcase, char-upcase

Character predicates: char?, char-alphabetic?, char-numeric?, char-lower-case?, char-upper-case?, char-whitespace?

Character comparison: char<?, char<=?, char=?, char>=?, char>?, char-ci<?, char-ci<=?, char-ci=?, char-ci>=?, and char-ci>?.

Strings

Constant notation: "string" (string constants).

String predicates: string?

String constructors: make-string, string, string-append

String extractors: string-ref, substring

String conversion: number->string, string->number, string->number

String analysis: string-length

String comparison: string<?, string<=?, string=?, string>=?, string>?, string-ci<?, string-ci<=?, string-ci=?, string-ci>=?, string-ci>?

The lab

The first person at the computer is the A-side. The second person is the B-side. Download the appropriate code.

• basic-types.scm

After you've downloaded the code, follow the instructions in the file.

When you are done, upload your basic-types.scm file to Gradescope.

Notes

Notes on From reals to integers

Here are the ways we tend to think of the four functions:

(floor r) finds the largest integer less than or equal to r. Some would phrase this as "floor rounds down".

(ceiling r) finds the smallest integer greater than or equal to r. Some would phrase this as "ceiling rounds up".

(truncate r) removes the fractional portion of r, the portion after the decimal point.

(round r) rounds r to the nearest integer. It rounds up if the decimal portion is greater than 0.5 and it rounds down if the decimal portion is less than 0.5. If the decimal portion equals 0.5, it rounds toward the even number.

> (round 1.5)
2
> (round 2.5)
2
> (round 7.5)
8
> (round 8.5)
8
> (round -1.5)
-2
> (round -2.5)
-2

It's pretty clear that floor and ceiling differ: If r has a fractional component, then (floor r) is one less than (ceiling r).

It's also pretty clear that round differs from all of them, since it can round in two different directions.

We can also tell that truncate is different from ceiling, at least for positive numbers, because ceiling always rounds up, and removing the fractional portion of a positive number causes us to round down.

So, how do truncate and floor differ? As the previous paragraph implies, they differ for negative numbers. When you remove the fractional component of a negative number, you effectively round up. (After all, -2 is bigger than -2.2.) However, floor always rounds down.

Why does Scheme include so many ways to convert reals to integers? Because experience suggests that if you leave any of them out, some programmer will need that precise conversion.

Return to the problem

Acknowledgements

This laboratory is based on a similar laboratory from a prior version of CSC 151. At some point, it included problems on lists and files. It no longer does.

Boolean values and predicate procedures

Many of Scheme's control structures, such as conditionals (which you will learn about in a subsequent reading), need mechanisms for constructing tests that return the values true or false. These tests can also be useful for gathering information about a variety of kinds of values. In this reading, we consider the types, basic procedures, and mechanisms for combining results that support such tests.

Introduction

When writing complex programs, we often need to ask questions about the values with which we are computing. For example, should this entry come before this other entry when we sort the entries in a table or is this location within 100 miles of this second location? Frequently, these questions, which we often phrase as tests (not the same as unit tests), are used in control structures. For example, we might decide to do one thing if a value is a string and another if it is an integer.

To express these kinds of questions, we need a variety of tools. First, we need a type in which to express the valid answers to questions. Second, we need a collection of procedures that can answer simple questions. Third, we need ways to combine questions. Finally, we need control structures that use these questions. In the subsequent sections of this reading, we consider each of these issues. We will return to more complex control structures in another reading.

Boolean values

A Boolean value is a datum that reflects the outcome of a single yes-or-no test. For instance, if one were to ask whether Des Moines is within 100 miles of Boston, it would determine that the two cities are not that close and it would signal this result by displaying the Boolean value for "no" or "false", which is #f. There is only one other Boolean value, the one meaning "yes" or "true", which is #t. These are called "Boolean values" in honor of the logician George Boole who was the first to develop a satisfactory formal theory of them. (Some folks now talk about "fuzzy logic" that includes values other than "true" and "false", but that's beyond the scope of this course.)

Predicates

A predicate is a procedure that always returns a Boolean value. A procedure call in which the procedure is a predicate performs some yes-or-no test on its arguments. For instance, the predicate number? (the question mark is part of the name of the procedure) takes one argument and returns #t if that argument is a number, #f if it does not. Similarly, the predicate even? takes one argument, which must be an integer, and returns #t if the integer is even and #f if it is odd. The names of most Scheme predicates end with question marks, and Grinnell's computer scientists recommend this useful convention, even though it is not required by the rules of the programming language.

Scheme provides a wide variety of basic predicates and Scamper adds a few more. We will consider a few right now, but learn more as the course progresses.

Type predicates

The simplest predicates let you test the type of a value. Scheme provides a number of such predicates.

• number? tests whether its argument is a number.
• integer? tests whether its argument is an integer.
• string? tests whether its argument is a string.
• procedure? tests whether its argument is a procedure.
• boolean? tests whether its argument is a Boolean value.
• list? tests whether its argument is a list.

Equality predicates

Scamper provides a predicate, equal? for testing whether two values can be understood to be the same.

• equal? tests whether its two arguments are the same or, in the case of lists, whether they have the same contents.

equal? works on any pair of values, even though they have different types. Of course, we expect that if two values have different types, they should not be equal. We commonly compare numbers for equality enough, that it is worthwhile to have a version of equal? that only works on numbers.

• = tests whether its arguments, which must all be numbers, are numerically equal; 5 and 5.0 are numerically equal for this purpose.

Numeric predicates

Scheme also provides many numeric predicates, some of which you may have already explored.

• even? tests whether its argument, which must be an integer, is even.
• odd? tests whether its argument, which must be an integer, is odd.
• zero? tests whether its argument, which must be a number, is equal to zero.
• positive? tests whether its argument, which must be a real number, is positive.
• negative? tests whether its argument, which must be a real number, is negative.

Comparators

When we use a predicate to compare two values, most frequently to see if one should precede the other in some natural ordering, we often refer to that predicate as a "comparator".

Numeric comparators

Scheme provides a number of numeric comparators.

• < tests whether its arguments, which must all be numbers, are in strictly ascending numerical order. (The < operation is one of the few built-in predicates that does not have an accompanying question mark.)
• > tests whether its arguments, which must all be numbers, are in strictly descending numerical order.
• <= tests whether its arguments, which must all be numbers, are in ascending numerical order, allowing equality.
• >= tests whether its arguments, which must all be numbers, are in descending numerical order, allowing equality.

Some other comparators

As you've studied other types, you may have seen other comparators. Here are some of the more common ones.

• char<? tests whether its arguments, which must all be characters, are in strictly ascending alphabetical order.
• char<=? tests whether its arguments, which must all be characters, are in ascending alphabetical order.
• char>? tests whether its arguments, which must all be characters, are in strictly descending alphabetical order.
• char>=? tests whether its arguments, which must all be characters, are in descending alphabetical order.
• char-ci<? tests whether itss arguments, which must all be characters, are in strictly ascending alphabetical order, ignoring case.
• char-ci<=? tests whether its arguments, which must all be characters, are in ascending alphabetical order, ignoring case.
• char-ci>? tests whether its arguments, which must all be characters, are in strictly descending alphabetical order, ignoring case.
• char-ci>=? tests whether its arguments, which must all be characters, are in descending alphabetical order, ignoring case.

> (char<? #\a #\a)
#f
> (char<=? #\a #\a)
#t
> (char<? #\a #\b)
#t
> (char<? #\a #\b)
#t
> (char-ci<? #\a #\b)
#t
> (char<=? #\a #\a)
#t
> (char-ci<=? #\a #\a)
#t

• string<? tests whether its arguments, which must all be strings, are in strictly ascending alphabetical order.
• string<=? tests whether its arguments, which must all be strings, are in ascending alphabetical order.
• string>? tests whether its arguments, which must all be strings, are in strictly descending alphabetical order.
• string>=? tests whether its arguments, which must all be strings, are in descending alphabetical order.
• string-ci<? tests whether its arguments, which must all be strings, are in strictly ascending alphabetical order, but ignoring case.
• string-ci<=? tests whether its arguments, which must all be strings, are in ascending alphabetical order, but ignoring case.
• string-ci>? tests whether its arguments, which must all be strings, are in strictly descending alphabetical order, but ignoring case.
• string-ci>=? tests whether its arguments, which must all be strings, are in descending alphabetical order, but ignoring case.

Negating Boolean values with not

Not all the procedures we use to work with Boolean values are strictly predicates. Another useful Boolean procedure is not, which takes one argument and returns #t if the argument is #f and #f if the argument is anything else. For example, one can test whether picture is not an image with:

(import image)
(define picture (square 100 "solid" "black"))
(not (image? picture))

If Scheme says that the value of this expression is #t, then picture is not an image.

Combining Boolean values with and and or

The and and or keywords have simple logical meanings. In particular, the and of a collection of Boolean values is true if all are true and false if any value is false, the or of a collection of Boolean values is true if any of the values is true and false if all the values are false. For example,

(and #t #t #t)
(and (< 1 2) (< 2 3))
(and (odd? 1) (odd? 3) (odd? 5) (odd? 6))
(and)
(or (odd? 1) (odd? 3) (odd? 5) (odd? 6))
(or (even? 1) (even? 3) (even? 4) (even? 5))
(or)

Detour: Keywords vs. procedures

You may note that we were careful to describe and and or as "keywords" rather than as "procedures". The distinction is an important one. Although keywords look remarkably like procedures, Scheme distinguishes keywords from procedures by the order of evaluation of the parameters. For procedures, all the parameters are evaluated and then the procedure is applied. For keywords, not all parameters need be evaluated, and custom orders of evaluation are possible.

If and and or were procedures, we could not guarantee their control behavior. We'd also get some ugly errors. For example, consider the extended version of the even? predicate below:

(define new-even?
  (lambda (val)
    (and (integer? val) (even? val))))

Suppose new-even? is called with 2.3 as a parameter. In the keyword implementation of and, the first test, (integer? ...), fails, and new-even? returns false. If and were a procedure, we would still evaluate the (even? ...), and that test would generate an error, since even? can only be called on integers.

Writing our own predicates and comparators

We can, of course, write our own predicates. For example, here is a predicate that determines whether its input, a real number, is between 0 and 100, inclusive.

(define valid-grade?
  (lambda (val)
    (<= 0 val 100)))

We can also write our own comparators. For example, here's a somewhat pointless comparator that orders words based on their second letter.

;;; (second-letter<? str1 str2) -> boolean?
;;;   str1 : string?
;;;   str2 : string?
;;; Determine if the second letter of str1 alphabetically precedes 
;;; the second letter of str2.
(define second-letter<?
  (lambda (str1 str2)
    (char-ci<? (string-ref str1 1) 
               (string-ref str2 1))))

Mental models: Tracing and and or

As you may recall, it is useful to have a mental model for how things work in Scheme.
Our traditional model is that we evaluate the parameters to a procedure and then apply the procedure.
However, and and or behave a bit differently.

Here's the basic behavior of and. Note that we do not necessarily evaluate all of its parameters.

• Rule A1: If and has no parameters, replace (and) with #t
• Rule A2: If and has exactly one parameter, evaluate that parameter and replace the and expression by the value of the parameter.
• Rule A3: If and has more than one parameter, evaluate the first parameter.
  • Rule A3a: If the evaluated parameter is false, replace the whole and expression by false (#f).
  • Rule A3b: If the evaluated parameter is true, remove the first parameter to and and continue.

Let's look at a simple but silly example.

    (* 2 (and (< 3 4) 5 (+ 1 2)))
    ; Rule A3: More than one parameter
--> (* 2 (and #t 5 (+ 1 2)))
    ; Rule A3b: Parameter (#t) is truish, so drop it.
--> (* 2 (and 5 (+ 1 2)))
    ; Rule A3b: Parameter (5) is truish, so drop it
--> (* 2 (and (+ 1 2)))
    ; Rule A2: Only one parameter, use it in place of the `and`.
--> (* 2 (+ 1 2))
--> (* 2 3)
--> 6

We won't usually use and with non-Boolean values. However, there are times that it can be useful to do so. Let's look at one possibility.

(define divide
  (lambda (x y)
    (and (not (zero? y)) (/ x y))))

    (divide 4 2)
    ; Procedure call: Replace x by 4 and y by 2 in the body.
--> (and (not (zero? 2)) (/ 4 2))
    ; Rule A3: Evaluate the first parameter
--> (and (not #f) (/ 4 2))
--> (and #t (/ 4 2))
    ; Rule A3b: First parameter is truish, so drop it
--> (and (/ 4 2))
    ; Rule A2: Only one parameter.  Use it in place of the and.
--> (/ 4 2)
--> 2

    (divide 4 0)
    ; Procedure call: Replace x by 4 and y by 2 in the body.
--> (and (not (zero? 0)) (/ 4 0))
    ; Rule A3: Evaluate the first parameter
--> (and (not #t) (/ 4 0))
--> (and #f (/ 4 0))
    ; Rule A3a: If the first parameter is fale, replace the and by #f
--> #f

Note that in the second example, we never attempted the illegal division of 4 by zero. Contrast this with what happens if we used a standard procedure, such as list.

    (list (not (zero? 0)) (/ 4 0))
--> (list (not #t) (/ 4 0))
--> (list #f (/ 4 0))
--> BOOM!  Can't divide 4 by zero.

Let's see the difference in Scamper.

Why do we receive a BOOM! in Scamper? This is because, like the not-a-number value NaN discussed in the numbers reading, dividing by zero results in the Infinity value. Effectively, this might as well be an error because we can't do anything meaningful with Infinity!

Now, what about or? Here are the rules for or expressions.

• Rule O1: If or has no parameters, replace (or) with #f
• Rule O2: If or has exactly one parameter, evaluate that parameter and replace the and expression by the value of the parameter.
• Rule O3: If or has more than one parameter, evaluate the first parameter.
  • Rule O3a: If the evaluated parameter is false, remove the first parameter and continue.
  • Rule O3b: If the evaluated parameter is true, replace the or expression by the first parameter.

Self checks

Exercise 1: Combining boolean values

Experience suggests that students understand and and or much better after a little general practice figuring out how they combine values. Fill in the following tables for each of the operations and and or. The third column of the table should be the value of (and arg1 arg2), where arg1 is the first argument and arg2 is the second argument. The fourth column should be the value of (or arg1 arg2).

Exercise 2: Comparing strings for length (‡)

We know how to compare strings alphabetically. Write a comparator, (shorter? str1 str2) that returns true if the length of str1 is strictly less than the length of str2.

> (shorter? "a" "ab")
#t
> (shorter? "abc" "ab")
#f
> (shorter? "ab" "ba")
#f
> (shorter? "" "abc")
#t

Acknowledgements

This reading is closely based on a similar reading from CSC 151 2018S. We've removed a section on the comparator procedure, which we've dropped from the class library, and added short sections on regular expressions, filtering, and combining predicates. Much of the discussion of combining predicates comes from a reading on filtering from CSC 151 2018S. .

In Spring 2022, we added a section on tracing.

Conditional evaluation in Scheme

Many programs need to make choices. In this reading, we consider Scheme's conditional expressions, expressions that allow programs to behave differently in different situations.

Introduction

When Scheme encounters a procedure call, it looks at all of the subexpressions within the parentheses and evaluates each one. Sometimes, however, the programmer wants Scheme to exercise more discretion. Specifically, the programmer wants to select just one subexpression for evaluation from two or more alternatives. In such cases, one uses a conditional expression, an expression that checks whether some condition is met and selects the subexpression to evaluate on the basis of the outcome of that condition. (We will sometimes refer to these conditions as "tests". The tests (conditions) in conditionals are a question about the state of input or the system that let us make a decision.)

For instance, suppose we want to explicitly classify a city as "North" if its latitude is at least 39.72 and "South" if its latitude is less than 39.72. To write a procedure that like this, we benefit from a mechanism that allows us to explicitly tell Scheme how to choose which expression to evaluate. Such mechanisms are the primary subject of this reading.

If expressions

The simplest conditional expression in Scheme is an if expression. An if expression typically has three components:

1. A condition or guard.
2. A consequent or if-branch.
3. An alternative or else-branch.

It selects one or the other of these expressions, depending on the outcome of the guard. The general form is

(if <expr1> <expr2> <expr3>)

Where the guard, if-branch, and else-branch correspond to <expr1>, <expr2>, and <expr3>, respectively.

We will return to the particular details in a moment. For now, let us consider the conditional we might write for the procedure to determine whether a location is in the North or South of the US. (We would not normally include comments; the code should be self-explanatory.)

(if (>= latitude 39.72) ; If the latitude is at least 39.72
    "North"             ; Classify it as North
    "South")            ; Otherwise, classify it as "South"

To turn this expression into a procedure, we need to add the define keyword, a name (such as categorize-city), a lambda expression, and such. We also want to give appropriate documentation and a bit of cleanup to the results.

Here, then, is the complete definition of the categorize-city procedure:

;;; (categorize-city latitude) -> string?
;;;   latitude : real?
;;; Categorize a city as "North" or "South" based on its latitude.
(define categorize-city
  (lambda (latitude)
    (if (>= latitude 39.72) ; If the latitude is at least 39.72
        "North"             ; Classify it as North
        "South")))          ; Otherwise, classify it as S"South"

In an if-expression of the form (if <expr1> <expr2> <expr3>){:.signature}:

• <expr1> is an expression that evaluates to a boolean value, i.e., to either #t or #f. We call this the condition or guard expression (or shorter, "guard") of the conditional.
• <expr2> is an expression that is evaluated only when the guard evaluates to #t. We call this the consequent or if-branch of the conditional.
• <expr3> is an expression that is evaluated only when the guard evaluates to #f. We call this the alternative or else-branch of the conditional.

Note that a boolean value can only evaluate to exactly one of #t and #f. Therefore, we expect that exactly one of the consequent and alternative will be evaluated when evaluating a conditional.

How does this play out in our mental model of computation? Let's consider a call to categorize-city and see how it evaluates:

    (categorize-city 30.0)
--> (if (>= 30.0 39.72)
        "North"
        "South")
--> (if #f
        "North"
        "South")
--> "South"

Note in this example how we first evaluate the condition to #f and then substitute the alternative expression for the overall conditional expression. If we had, instead evaluated the condition to #t, then we would have substituted the consequent expression in the place of the overall expression.

The semantics of conditionals

How do conditional work with our mental model of computation? At a high-level, a conditional proceeds as follows:

1. We first evaluate the guard to a value and that value must be of boolean type.
2. If the guard evaluates to true, then we substitute the if-branch for the overall conditional and continue evaluation. Otherwise, the guard must have evaluated to false. We then substitute the else-branch for the overall conditional and continue evaluation.

These rules can be captured by the following evaluation skeletons where e1, e2, and e3 are arbitrary expressions:

1.  (if e1 e2 e3) --> (if e1' e2 e3)    [whenever e1 --> e1']

2.  (if #t e2 e3) --> e2

    (if #f e2 e3) --> e3

Note that we do not evaluate e2 and e3 until after e1 is fully evaluated to a boolean value. On top this we only evaluate exactly one of e2 and e3 depending on whether e1 evaluates to #t or #f.

In our example evaluation above:

    (categorize-city 30.0)
--> (if (>= 30.0 39.72)
        "North"
        "South")
--> (if #f
        "North"
        "South")
--> "South"

We first evaluated the expression (>= 30.0 39.72) to a value. That value was #f. As a result, the conditional evaluates to the else-branch which contains the expression "South". "South" itself is a string value, so we are done evaluating at this point!

Supporting multiple alternatives with cond

Suppose that we wanted to write a conditional expression that consisted of more than two possibilities. For example, how would I write a conditional that tested whether a number was negative, positive, or zero? Because an if-expression is an expression and the branches of an if-expression are themselves expressions, we can nest if-expressions to achieve this effect:

(if (n < 0)
    "lower"           ; n < 0
    (if (equal? n 0)
        "zero"        ; n = 0
        "higher"))    ; n > 0

We can see this works with our mental model of evaluation, e.g., if n = 0:

    (if (0 < 0)
        "lower"
        (if (equal? 0 0)
            "zero"
            "higher"))
    ; Evaluate the guard
--> (if #f
        "lower"
        (if (equal? 0 0)
            "zero"
            "higher"))
    ; The guard is false; use the alterante
--> (if (equal? 0 0)
        "zero"
        "higher")
    ; Evaluate the guard
--> (if #t
        "zero"
        "higher")
    ; The guard is true; use the consequent
--> "zero"

While nesting if-expressions in this matter works, it is far from convenient. As you have experienced, writing nested expressions in Scheme can be tedious and error-prone because of the need to correctly match and nest parentheses. Because of this, Scheme provides an alternative to the if-expression, the cond-expression, that captures this pattern more concisely.

(cond
  [guard-0
   consequent-0]
  ...
  [guard-n
   consequent-n]
  [else
   alternate])

(Note that like if, cond is also a keyword. Recall that keywords differ from procedures in that the order of evaluation of the parameters may differ.)

The first expression within a cond clause is a guard, similar to the condition in an if expression. When the value of such a guard is found to be #f, the subexpression that follows the guard is ignored and Scheme proceeds to the guard at the beginning of the next cond clause. But when a guard is evaluated and the value turns out to be true, the consequent for that guard is evaluated and its value is the value of the whole cond expression. Only one guard/consequent clause is used: subsequent cond clauses are completely ignored.

In other words, when Scheme encounters a cond expression, it works its way through the cond clauses, evaluating the guard at the beginning of each one, until it reaches a guard that succeeds (one that does not have #f as its value). It then makes a ninety-degree turn and evaluates any consequents in the selected cond clause, retaining the value of the last consequent. (If there are no consequents, it uses the value of the guard.)

If all of the guards in a cond expression are found to be false, the value of the cond expression is unspecified (that is, it might be anything!). To prevent the surprising results that can ensue when one computes with unspecified values, good programmers customarily end every cond expression with a cond clause in which the keyword else appears in place of a guard. Scheme treats such a cond clause as if it had a guard that always succeeded. If it is reached, the subexpressions following else are evaluated, and the value of the last one is the value of the whole cond expression.

For example, here is a cond expression that attempts to figure out what the type of datum is and gives back a string that represents that type.

(define type-of
  (lambda (datum)
    (cond
      [(number? datum) 
       "number"]
      [(string? datum)
       "string"]
      [else
       "some-other-type"])))

The expression has four cond clauses. In the first, the guard is (number? datum). If datum is a number, the expression produces the string "number". If not, we proceed on to the second cond clause. Its guard is (string? datum). If datum is a string, the expression produces the string "string" and nothing else. Finally, if none of those cases hold, the else clause produces the value "some-other-type".

In our mental model of computation, cond behaves identically to the nested if-expression we originally designed. We evaluate each of the conditions in top-down order until we arrive at a condition that evaluates to #t. The entire cond then evaluates to the consequent associated with that guard. For example, let's call type-of on a string and see what we get:

    (type-of "my-symbol")
--> (cond 
      [(number? "my-symbol")
       "number"]
      [(string? "my-symbol")
       "string"]
      [else
       "some-other-type"]
    ; Evaluate the first guard
--> (cond 
      [#f
       "number"]
      [(string? "my-symbol")
       "string"]
      [else
       "some-other-type"]
    ; The first guard is false; drop the first clause
--> (cond 
      [(string? "my-symbol")
       "string"]
      [else
       "some-other-type"]
    ; Evaluate the second guard
--> (cond 
      [#t
       "string"]
      [else
       "some-other-type"]
    ; The first guard is true; evaluate to its body
--> "string"

In our mental model, we can imagine "peeling" away the conditionals one at a time in a top-bottom fashion until we arrive at a true one. If all of them evaluate to #f then the else clause fires.

A caution: Watch your parens!

As you may have noted from our discussion of cond, cond expressions can use square brackets rather than parenthesis to indicate structure. That is, they do not surround an expression to evaluate (a procedure followed by its parameters). Instead, they serve only to group things. In this case, the parentheses group the guard and consequents for each cond clause. The square brackets are just a notational convenience; parenthesis will work just as well, and you'll see a lot of Scheme code that uses parentheses rather than square brackets. Scheme, like most modern Scheme implementations, allows both because the square brackets add a bit of clarity.

When writing cond clauses, you should take the time to verify that you've used the right number of parentheses and square brackets. Each clause has its own open and close square brackets (or open and close parenthesis). Typically, the guard has parentheses, unless it's the else clause. Make sure to include both sets.

Expressing conditional computation with and and or

As we saw in the reading on Boolean values, both and and or provide a type of conditional behavior. In particular, and evaluates each argument in turn until it hits a value that is #f and then returns #f (or returns the last value if none return #f). Similarly, or evaluates each argument in turn until it finds one that is not #f, in which case it returns that value, or until it runs out of values, in which case it returns #f.

That is, (or exp0 exp1 ... expn){:.signature} behaves much like the following cond expression, except that the or version evaluates each expression once, rather than twice.

(cond
  [exp0 
   exp0]
  [exp1 
   exp1]
  ...
  [expn 
   expn]
  [else 
   #f])

Similarly, (and exp0 exp1 ... expn){:.signature} behaves much like the following cond expression.

(cond
  [(not exp0) 
   #f]
  [(not exp1) 
   #f]
  ...  [(not expn) #f] [else expn]) 

Most beginning programmers find the cond versions much more understandable, but some advanced Scheme programmers use the and and or forms because they find them clearer. Certainly, the cond equivalents for both or and and are quite repetitious.

Reference

(if <expr1> <expr2> <expr3>){:.signature} Standard keyword. : Evaluate <expr1>. If its value is true, substitute and evaluate <expr2> and return its value. If the value of the condition is false (#f), substitute and evaluate <expr3>.

(cond [guard-1 consequents-1] [guard-2 consequents-2] ... [guard-n consequents-n] [else alternative]){:.signature} Standard keyword. : Evaluate each guard in turn until one is true. It then evaluates the corresponding sequence of consequent expressions and returns the value of the last consequent. If none of the guards is true, evaluates the alternative and returns its value.

(and <expr1> ... <exprk>){:.signature} Standard keyword. : Evaluate each expression in turn. If any of those values is false, return false. Otherwise, return the value of the last expression.

(or <expr1> ... <exprk>){:.signature} Standard keyword. : Evaluate each expression in turn. If any of those values is true, return the first true value. Otherwise, return false.

Self checks

Check 1: Basics (‡)

a. Assuming num is defined as an integer, write an if expression that produces double the value of num if it is odd, and half the value otherwise.

b. Write a cond expression that takes a real number, num, as input and produces the symbol positive if num is greater than zero, the symbol negative if num is less than zero, and the symbol neither otherwise.

Check 2: Choosing a kind of conditional

a. Why might you choose if rather then cond?

b. Why might you choose cond rather than if?

Booleans values, predicates, and conditionals

In this lab, you will have the opportunity to explore the use of predicates as well as Scheme's primary conditional control operations, if and cond.

We may have reached the point in which you need fewer instructions. So let's give it a try.

We will use the now-standard approach for this lab. The person who arrived at the computer first is side A. The other person is side B.

Start by making a copy of the code.

• conditionals.scm

Then follow the instructions in the file.

Don't forget to submit the file on Gradescope, to include your partner when submitting, and to email the code to your partner.

Take-home Assessment #3: Beat Machine

Electronic musical tools help democratize music, allowing those without the training or capability to play a musical instrument to express musical ideas. In this assessment, we'll use the music library to implement one of these basic tools, the drum machine, that form the basis for many modern electronic songs!

For this take-home assessment, please write your code in a file called beat-machine.scm and turn it into Gradescope when you are done. As you format your work, please make sure to:

• Include a complete header in your source file indicating assignment, authorship, etc., similar to our labs.
• Use the lab library to label the different parts of the output of your program as outlined in the instructions below.

The Beat Machine

A staple of electronic music is the drum machine. A drum machine allows the user to create patterns of drum beats from a set of sound samples imitating real-world percussive instruments such as a snare drum or a cymbal. They can be found all over modern popular music, e.g., dance pop and electronic music from the 80s and 90s:

• Phil Collin's In the Air Tonight uses a Roland CR-78.
• Michael Jackson's Man in The Mirror uses a Linn 9000
• Aphex Twin's Heliosphan uses a Roland TR-909.

The primary a user interacts with a drum machine is usually a row of button, e.g., on the Roland TR-808:

Each button corresponds to one pulse of a groove, so that a user can instruct the drum machine to play a sound on a given beat by simply pressing the appropriate button. For example, the 16 buttons on the 808 break up a groove into 16 equal parts, i.e., sixteenth notes. If were to press the following buttons on the 808 (x indicates that button has been pressed):

[x][ ][ ][x] [x][ ][ ][x] [x][ ][ ][x] [x][ ][x][ ]

The drum machine would produce the following beat, emulated here in Scamper's music library:

(import music)

; 16th notes on the bass drum
(define bass (note 35 sn))
; A 16th rest
(define r16 (rest sn))

(mod percussion
  (seq bass r16  r16  bass
       bass r16  r16  bass
       bass r16  r16  bass
       bass r16  bass r16))

Many drum machines feature a grid of these buttons where each row corresponds to one instrument, e.g., the bass drum or a snare and each column corresponds to a pulse. In this manner, a user of a drum machine can "program" in their beat live by toggling different voices and pulses with the grid of buttons!

Problem 1: Individual Pulses

Let's build up a definition of a beat-machine by decomposing this problem in a bottom-up fashion. The elementary element of a drum machine is a single button that toggles whether a note or a pulse is played. In our implementation, we'll use a number to represent a single button and whether it is toggle:

• 0 will correspond to the button being off.
• 1 will correspond to the button being on.

(Note: a boolean is a more appropriate datatype to represent the state of a button. But in the later parts of this problem, we will add more "states" to each button than "on" and "off" which will justify our current choice of a number!)

To begin, write a function (button->comp instr d state) that takes:

• An instr value corresponding to the MIDI percussion voice that should be played.
• A duration d that is the length of the pulse.
• The state of the button, a number.

And returns a composition that is either a rest or a note with appropriate voice and duration depending on whether state is 0 or 1, respectively. For example:

• (button->comp 35 sn 0) would produce a 16th note rest, i.e., (rest sn)
• (button->comp 35 sn 1) would produce a 16th note on the bass drum, i.e., (note 35 sn).

Problem 2: A Row of Pulses

Now let's scale up to a whole row of buttons. We haven't introduced a way to create genuine buttons in Scamper. However, we can use source code to emulate this setup!

Since one button is represented by a number, we'll use a list of numbers to represent a row. For example, the beat from the introduction to this problem:

[x][ ][ ][x] [x][ ][ ][x] [x][ ][ ][x] [x][ ][x][ ]

Would be represented by the following Scheme list:

(define bass-pattern
  (list 1 0 0 1
        1 0 0 1
        1 0 0 1
        1 0 1 0))

(Observe how I use spacing to make the division of pulses as clear as possible!)

Next, use button->comp to write a function (line->comp instr dur line) that takes:

• An instr value corresponding to the MIDI percussion voice that should be played.
• A duration d that is the length of the pulse.
• A line of button states, i.e., a list of numbers.

And returns a composition corresponding to the given parameters. For example, calling (line->comp 35 sn bass-pattern) with the bass-pattern defined above would produce the bass beat that we hard-coded in the introduction to this problem.

Problem 3: A Pattern of Pulses

To capture a complete drum groove, we now need to represent a grid of button. Here, we'll take advantage of our source code to represent this grid as a list of list of numbers. When formatted appropriately, our list of lists can look like a grid! For example, in our introductory lab on music, we introduced a simple rock beat with 8th note subdivisions:

Bass   (35): [x][ ] [ ][ ] [x][ ] [ ][ ]
Snare  (38): [ ][ ] [x][ ] [ ][ ] [x][ ]
Hi-hat (42): [x][x] [x][x] [x][x] [x][x]
Crash  (49): [x][ ] [ ][ ] [ ][ ] [ ][ ]

We can represent this pattern with a list of lists as follows:

(define pattern
  (list 
    (list 1 0  0 0  1 0  0 0)
    (list 0 0  1 0  0 0  1 0)
    (list 1 1  1 1  1 1  1 1)
    (list 1 0  0 0  0 0  0 0)))

Using line->comp, define our main function, (beat-machine d pat), that takes:

• A duration d that is the length of the pulse of our pattern.
• A pattern pat representing the full groove as a list of four lists of numbers.

Each list in this overall list corresponds to one of the voices of the drum kit. In the definition of pattern above:

• The first list corresponds to the bass drum (MIDI value 35).
• The second list corresponds to the snare drum (MIDI value 38).
• The third list corresponds to the hi-hat (MIDI value 42).
• The fourth list corresponds to the crash cymbal (MIDI value 49).

The order of the list is arbitrary, so you can choose to order your instruments' list in any way that you choose as long as you are consistent (and document your choices in beat-machine's comment!).

beat-machine should return a composition that is the complete groove specified by the pattern. So (beat-machine en pattern) using the pattern defined above would produce the rock drum groove from our lab. Make sure that beat-machine produces a composition that uses percussion voices!

Problem 4: More Options

Because our beat-machine uses numbers to represent buttons, we have the room to add more options for each pulse other than "on" and "off." To this end, implement three additional functions that allow our beat machine to make different kinds of sounds.

• (ghost instr d) creates a ghost note with the given voice instr and duration d. A ghost name is a (very) quiet note relative to the regular volume of the composition.
• (accent instr d) creates n accented note with the given voice instr and duration d. An accented note is a loud note relative to the regular volume of the composition.
• (roll instr d) creates a roll with the given voice instr and duration d. A roll is four evenly-spaced notes within the time duration d. These individual notes are played at a softer volume than the regular volume of the composition. For example, if d is a quarter note (qn), then (roll ... d) produces a composition of four 16th notes (\( \frac{1}{4} \times 4 = \frac{1}{16} \)) played softly in sequence.

To modify the volume of your produced compositions, the dynamics modification will be useful. Note that the default loudness of the composition is 64.

To implement roll, you will likely need to do some manual computation over durations. A duration is implemented as a simple fraction with the following functions:

• (dur x y) creates a duration \( \frac{x}{y} \). For example (dur 1 4) is equivalent to a quarter note.
• (numerator x) retrieves the numerator of a duration/fraction.
• (denominator y) retrieves the denominator of a duration/fraction.

Once you have implemented these functions, you will need to add them to your beat machine. To do so, you should assign different numbers to each new function and modify button->comp to use those functions when that number is encountered in a pattern.

The choice of assignment is up to you. However, you certainly need to document your choice in the documentation comment for beat-machine. These kinds of assumptions about the inputs to our function (here, the interpretation of the numbers in the provided lists) are excellent candidates for documentation!

Problem 5: Make Some Beats

With our basic beat-machine finished, let's try it out! define three different patterns and use your beat-machine to create three different grooves. In your code, you should use the (description ...) function from the lab library to output a description of your groove. Below the description, you should call beat-machine with the appropriate arguments to create a playable version of your groove!

Feel free to listen to your favorite music and try to approximate the beat to the best of your ability. Or take the basic rock beat and try shifting things around to find something new! If you need some inspiration, here are some ideas:

• A basic funk groove (e.g., "What is Hip" by Tower of Power is characterized by 16th note subdivision. The hi-hat plays constant 16th notes, the snare plays on the second and fourth beats, and the bass drum on the first and third beats. However, many funk grooves make liberal use of ghost notes on the snare to fill the space!

• Many latin grooves (e.g., "Mas Que Nada" by Sergio Mendes) create a syncopated effect with the snare and bass drum.

  snare: [ ][ ]  [x][ ]  [ ][x]  [ ][ ]
  bass:  [x][ ]  [ ][x]  [x][ ]  [ ][x]
  

Problem 6: Extended Beat Machine

The beat-machine is a complete program you can show off to your friends. However, the joy of building a program is that there is endless room for additions and customization!

To close this assessment, add two additional features to your beat machine implementation, extending the functionality in significant ways. For example, you may:

• Add an additional percussion voice to the machine, e.g., a tom-tom drum.
• Create a new type of note like ghost and accent or aggregate set of notes like roll.
• Devise a way to specify include melody into the beat machine, e.g., playing a collection of notes (an apreggio) instead of a percussion voice.

Importantly, you changes must preserve the original behavior of beat-machine, i.e., the earlier parts of this assessment need to stay intact. Beyond this requirement, you are free to tinker to your heart's content! Notably, you may introduce additional parameters to beat-machine as needed by your implementation.

For each of your features, you should:

• Include a one-sentence description of your feature in a (description ...) tag.
• Below the description, use the feature in a pattern and output the resulting groove with beat-machine.

Take-home assessment 3: transforming images

You will create only one file for this mini-project, image-transformations.scm. You should begin your project with this starter code. You will submit both that file and some images you create in part three.

Background

If you've played with an image-editing application like Photoshop, you've likely discovered that such applications provide a wide variety of mechanisms for transforming images. In this assignment, you will build your own versions of some image transformation. While we cannot reasonably explore how to build all such mechanisms, we will consider three kinds of mechanisms in this assignment.

We will start in part one with transformations based on the RGB values of each pixel in the image.

We will introduce a new color representation in part two, HSV (hue-saturation-value) colors, and explore some pixel-based transformations that use HSV colors.

In part three, you will design your own transformations.

Part one: Transforming images by transforming RGB colors

As you may recall, we can build a variety of image transformations by using the following model.

(define my-color-transformation
  (lambda (c)
    (rgb (some-computation c)
         (some-computation c)
         (some-computation c))))

(define my-image-transformation
  (lambda (img)
    (pixel-map my-color-transformation img)))

For example, to swap the red and blue components of an image, we might write the following.

;;; (rgb-swap-rb c) -> rgb?
;;;   c : rgb?
;;; Swap the red and blue components of `c`.
(define rgb-swap-rb
  (lambda (c)
    (rgb (rgb-blue c)
         (rgb-green c)
         (rgb-red c))))

;;; (swap-red-blue img) -> image?
;;;   img : image?
;;; Create a new image by swapping the red and blue components of
;;; each pixel in `img`.
(define swap-red-blue
  (lambda (img)
    (pixel-map rgb-swap-rb img)))

Here's the procedure in action. We'll start with our kitten.

Here's what happens when we call swap-red-blue on that image.

We can also build swap-red-blue by plugging the lambda part of rgb-swap-rb in place of rgb-swap-rb.

(define swap-red-blue
  (lambda (img)
    (pixel-map (lambda (c)
                 (rgb (rgb-blue c)
                      (rgb-green c)
                      (rgb-red c)))
               img)))

In a few cases, we can use composition to write the color transformations that are applied to each pixel. For example, the following procedure decreases the green component of each pixel in an image.

;;; (decrease-green img) -> image?
;;;   img : image?
;;; Create a new image by making each pixel of `img` less green (and
;;; a bit more blue and red).
(define decrease-green
  (lambda (img)
    (pixel-map (o rgb-pseudo-complement rgb-greener rgb-pseudo-complement)
               img)))

Here's the effect on the kitten.

We can also use the section operation along with some multi-parameter RGB operations to achieve some transformations. For example, here's one that sets the green component of an image to the maximum value.

;;; (maximize-green img) -> image?
;;;   img : image?
;;; Createa a new image by setting the green component of each pixel
;;; to the maximum value.
(define maximize-green
  (lambda (img)
    (pixel-map (section rgb-add (rgb 0 255 0) _) img)))

And here's the effect on our kitten.

Perhaps that wasn't the best transformation to use.

These few procedures give you a sample of the kinds of "basic" RGB transformations we might do. Of course, we will normally do somewhat more complex transformations than these. Nonetheless, they serve as a starting point for thinking about transformations.

1a. Extreme components

Write a procedure, (rgb-extreme color), that takes one parameter, an RGB color, and turns each component to 255 if it is at least 128 and to 0 if it is less than 128.

> (rgb->string (rgb-extreme (rgb 0 64 200)))
"0/0/255"
> (rgb->string (rgb-extreme (rgb 128 130 0)))
"255/255/0"

We've provided a procedure, (extreme img), that takes one parameter, an image, and applies rgb-extreme to each pixel in the image.

1b. Dominant components

Write a procedure, `(rgb-enhance-dominant color), that takes one parameter, an RGB color, and produces a new color in which each component is 255 if it is the largest component (or tied for largest) and 0 otherwise.

> (rgb->string (rgb-enhance-dominance (rgb 0 5 0)))
"0/255/0"
> (rgb->string (rgb-enhance-dominance (rgb 200 199 199)))
"255/0/0"
> (rgb->string (rgb-enhance-dominance (rgb 10 0 10)))
"255/0/255"

Hint: While you can write this procedure with conditionals, you might be able to achieve more concise code with a clever combination of max, addition, division, rounding, and multiplication.

We've provided a procedure, (enhance-dominance img), that applies rgb-enhance-dominance to each pixel in an image.

1c. Flattening

A common technique for manipulating images is known as “flattening” the image. In general, we flatten an image by restricting the values of each component to multiples of a certain value. For example, we might ensure that the components are each multiples of 16, 32, or 64. (We’ll use 255 instead of 256 for the highest multiple.)

How do we convert each component to the appropriate multiple? Consider the case of multiples of 32. If we divide the component by 32, round, and then multiply by 32, we’ll get the nearest multiple of 32. For example,

> (* 32 (round (/ 11 32)))
0
> (* 32 (round (/ 21 32)))
32
> (* 32 (round (/ 71 32)))
64
> (* 32 (round (/ 91 32)))
96
> (* 32 (round (/ 211 32)))
224
> (* 32 (round (/ 255 32)))
256

As the last example suggests, we may sometimes get a number outside of the range 0..255. Fortunately, the rgb function treats 256 (and any reasonable number greater than 256) the same as 255.

Write a procedure, (image-flatten-32 img), that flattens an image by converting each component to the nearest multiple of 32

You may then want to see the effect this procedure has on various images.

Hint: The sample code for computing nearest multiples of 32 should help.

1d. Eight-bit colors

Old-school video games did not provide nearly as many color options as we now have. To save memory, they used "eight bits" for a color, three for the red component, three for the green component, and two for the blue component. If you don't know about bits, that's okay. It means that there are only eight different values for the red component, eight different values for the green component, and four different values for the blue component.

Write a procedure, (8bit img), that converts an image to the equivalent of 8-bit color.

Note: While you can use some ideas from the prior problem, the process you used for image-flatten-32 should have given you nine different component levels: 0, 32, 64, 96, 128, 160, 192, 224, and 255 (the last computed as 256).

1e. Cycling through colors

As you have seen, when we apply the typical color transformation, such as rgb-darker or rgb-redder, we eventually reach a limit of 0 or 255. But we can get some interesting effects by "wrapping around" at the end. For example, here's the output from a function that adds 90 to a number, wrapping when we go beyond 255.

> (cyclic-add-90 75)
165 ; 75 + 90 = 165
> (cyclic-add-90 165)
255 ; 165 + 90 = 255
> (cyclic-add-90 166)
0 ; 166 + 90 = 256, wrap around to 0
> (cyclic-add-90 167)
1 ; 167 + 90 = 257, wrap around to 1
> (cyclic-add-90 255)
89 ; we wrap around because we hit 255
> (cyclic-add-90 89)
179 ; 89 + 90 = 179
> (cyclic-add-90 179)
13 ; 179 + 90 = 269, 269 - 256 = 13

As you might expect, cyclic-add-90 can be written in a variety of ways, combining addition and remainder. Here's one approach.

(define cyclic-add-90
  (lambda (val)
    (remainder (+ val 90) 256)))

Here's another.

(define cyclic-add-90 (o (section remainder _ 256) (section + _ 90)))

Write a procedure, (rgb-cyclic-add c1 c2), that takes two RGB colors as input and produces a new color formed by the cyclic addition of the corresponding components of the two colors.

> (rgb->string (rgb-cyclic-add (rgb 200 100 100) (rgb 100 250 80)))
"44/94/180"
> (rgb->string (rgb-cyclic-add (rgb 165 166 167) (rgb 90 90 90)))
"255/0/1"

> (pixel-map (section rgb-cyclic-add (rgb 192 192 192) _) kitten)

1f. Cycling through colors, revisited

Write a procedure, (rgb-cyclic-subtract c1 c2), that behaves much like rgb-subtract, except that if the component would end up negative, it cycles back to higher numbers.

> (rgb->string (rgb-cyclic-subtract (rgb 10 20 30) (rgb 25 25 25)))
"241/251/5"
> (rgb->string (rgb-cyclic-subtract (rgb 241 251 5) (rgb 25 25 25)))
"216/226/236"

> (pixel-map (section rgb-cyclic-subtract _ (rgb 32 32 32)) kitten)

> (pixel-map (section rgb-cyclic-subtract _ (rgb 128 128 128)) kitten)

> (pixel-map (section rgb-cyclic-add _ (rgb 128 128 128)) kitten)

1g. Gamma correction

Because humans do not perceive brightness linearly, some image formats modify the meaning of the stored values’ brightness scale (0-255) to better cover the range of sensitivities with a nonlinear transformation.

The typical transformation is commonly called a Gamma correction, for the name of the parameter used to determine the extent of rescaling. In particular, when a color component brightness value is on the real-valued scale of 0-1 (rather than our discrete 0-255 scale), the transformation is given by V_out = (expt V_in gamma). You can read more about this transformation on Wikipedia if you’re especially curious, or simply forge ahead with the assignment if you’re not.

In this problem, you will implement a series of steps to do this gamma correction on an image.

i. Write a procedure, (gamma-correct-component component gamma), that takes a color component value (i.e., a single number in the range 0-255), and applies the gamma correction described above. Note that you’ll need to rescale the component to the range 0-1 (by dividing) before you exponentiate and rescale it back to 0-255 (by multiplying) afterward.

> (gamma-correct-component 128 1/2)
181.0
> (gamma-correct-component 128 2)
64
> (gamma-correct-component 64 1/2)
128.0
> (gamma-correct-component 64 1/4)
180.0
> (gamma-correct-component 64 2)
16
> (gamma-correct-component 64 3)
4
> (gamma-correct-component 255 1/4)
255

ii. Write a procedure, (gamma-correct-color c gamma), that gamma corrects cby applyinggamma-correct-component` to each component.

> (rgb 128 0 0)

> (gamma-correct-color (rgb 128 0 0) 1/2)

> (rgb->string (gamma-correct-color (rgb 128 0 0) 1/2))
"181/0/0"

> (gamma-correct-color (rgb 128 0 0) 3)

> (rgb->string (gamma-correct-color (rgb 128 0 0) 3))
"32/0/0"

iii. Write a procedure, (gamma-correct-two img), that darkens the image by gamma-correcting each pixel with a gamma of two.

> (gamma-correct-two kitten)

iv. Write a procedure, (gamma-correct-half img), that lightens the image by gamma-correcting each pixel with a gamma of 1/2.

> (gamma-correct-half kitten)

Part two: HSV colors and HSV-based transformations

As we learned in the reading on design and color, RGB is not the only way to represent colors on the computer. For example, we might represent a color in terms of hue, saturation, and value. Hue represents the pure color (e.g., red, blue, yellow, or a combination of these). Saturation represents the "colorfulness" of the hue in the color. For instance, a completely saturated color would be a pure hue (like red), while a less saturated color might appear just as bright but somewhat faded (perhaps rose or pink). Finally, Value represents the brightness or darkness of the color.

As shown below, hue is represented as an angle, or a point on a circle. Thus, the values 0-360 sweep through colors red (0 degrees), yellow (60 degrees), green (120 degrees), cyan (180 degrees), blue (240 degrees), magenta (300 degrees), and back to red (at 360 or 0 degrees).

A reference page on HSV suggests that you can also think of value as how much black pigment you've mixed with the primary color pigment. When the value is 100, all of the pigment is the color and there's no black pigment. When the value is 0, there's no color pigment and much white pigment as possible. That page also suggests that you can also think of saturation as how much white pigment we've added. When the saturation is 100, we have all color pigment and no white pigment. When the saturation is 0, we have no color pigment and all white pigment.

There's a process by which we can convert an RGB color into an HSV color and an HSV color to an RGB color. Fortunately, you don't need to translate that process into Scheme; we've provided it as part of the image library. You can use both (rgb->hsv rgb-color) and (hsv->rgb hsv-color). There's also a (hsv hue saturation value) procedure.

Let's explore them a bit.

We'll start with the three primaries.

> (hsv 0 100 100)

> (hsv 120 100 100)

> (hsv 240 100 100)

> (rgb->string (hsv->rgb (hsv 0 100 100)))
"255/0/0"
> (rgb->string (hsv->rgb (hsv 120 100 100)))
"0/255/0"
> (rgb->string (hsv->rgb (hsv 240 100 100)))
"0/0/255"

Now let's try a few pure colors in-between them.

> (hsv 60 100 100)

> (hsv 300 100 100)

> (hsv 270 100 100)

> (hsv 330 100 100)

> (rgb->string (hsv->rgb (hsv 60 100 100)))
"255/255/0"
> (rgb->string (hsv->rgb (hsv 300 100 100)))
"255/0/255"
> (rgb->string (hsv->rgb (hsv 270 100 100)))
"128/0/255"
> (rgb->string (hsv->rgb (hsv 330 100 100)))
"255/0/128"

What happens if we change the saturation of pure red?

> (hsv 0 100 100)

> (hsv 0 75 100)

> (hsv 0 50 100)

> (hsv 0 25 100)

> (hsv 0 0 100)

> (rgb->string (hsv->rgb (hsv 0 100 100)))
"255/0/0"
> (rgb->string (hsv->rgb (hsv 0 75 100)))
"255/64/64"
> (rgb->string (hsv->rgb (hsv 0 50 100)))
"255/128/128"
> (rgb->string (hsv->rgb (hsv 0 25 100)))
"255/191/191"
> (rgb->string (hsv->rgb (hsv 0 0 100)))
"255/255/255"

How about changing the value?

> (hsv 0 100 100)

> (hsv 0 100 75)

> (hsv 0 100 50)

> (hsv 0 100 25)

> (hsv 0 100 0)

> (rgb->string (hsv->rgb (hsv 0 100 100)))
"255/0/0"
> (rgb->string (hsv->rgb (hsv 0 100 75)))
"191/0/0"
> (rgb->string (hsv->rgb (hsv 0 100 50)))
"128/0/0"
> (rgb->string (hsv->rgb (hsv 0 100 25)))
"64/0/0"
> (rgb->string (hsv->rgb (hsv 0 100 0)))
"0/0/0"

If we're going in the other direction, we can determine the hue, saturation, and value by using the hsv-hue, hsv-saturation, and hsv-value procedures. (There's also a hsv-alpha, but we won't be using it at the moment.)

> (hsv-hue (rgb->hsv (rgb 128 16 255)))
268
> (hsv-saturation (rgb->hsv (rgb 128 16 255)))
94
> (hsv-value (rgb->hsv (rgb 128 16 255)))
100
> (hsv-hue (rgb->hsv (rgb 16 12 30)))
253
> (hsv-saturation (rgb->hsv (rgb 16 12 30)))
60
> (hsv-value (rgb->hsv (rgb 16 12 30)))
12

2a. hsv->string

When we're exploring hsv colors, we won't learn much about colors by using just hsv->rgb or rgb->hsv. Why not? Because they'll just appear as colors.

> (rgb 128 16 255)

> (rgb->hsv (rgb 128 16 255))

> (hsv 100 50 75)

> (hsv->rgb (hsv 100 50 75))

In the examples above, we used the rgb->string procedure to quickly give ourselves the red, green, and blue components.

> (rgb->string (hsv->rgb (hsv 0 50 100)))
"255/128/128"

Write a procedure, hsv->string, that takes an HSV value as input and produces a string of the form "hue-saturation-value".

> (hsv->string (hsv 100 50 75))
"100-50-75"
> (hsv->string (hsv 240 100 1))
"240-100-1"
> (hsv->string (rgb->hsv (rgb 128 16 255)))
"268-94-100"

2b. string->hsv

We might also find it useful to do the reverse calculation.

Write a procedure string->hsv, that takes a string of the form produced by hsv->string and returns the corresponding HSV color.

Note: You can use string-split to break the string apart and list-ref to get each of the three parts.

> (string->hsv "0-100-100")

> (string->hsv "310-50-100")

2c. Saturating colors

We're now ready to start exploring HSV-based transformations.

Write a procedure, (saturate img), that creates a new version of img by setting the saturation of each pixel to 100.

> (saturate kitten)

2d. Rotating hues

Document and write a procedure (rotate-hue image angle) that takes an image as a parameter and, for each pixel, produces a new RGB color where the HSV equivalent has a hue rotated by angle degrees (a number between zero and 360).

> (rotate-hue kitten 100)

> (rotate-hue kitten 50)

> (rotate-hue kitten 300)

Note: If the rotated angle is greater than 360 or less than 0, be sure to wrap around properly (e.g., using remainder) to get the correct hue angle.

2e. Setting hues

Document and write a procedure, (set-hue img new-hue), that takes an image and a hue value (in the range 0-360) as parameters and creates a image in which each pixel is set to the given hue.

> (set-hue kitten 0)

> (set-hue kitten 180)

Part three: Freestyle

a. Document and write a procedure, (my-rgb-transformation img value), that transforms img using value and the RGB components of the image.

b. Using your procedure, create three images---kitten-rgb-transformed-01.jpg, kitten-rgb-transformed-02.jpg, and kitten-rgb-transformed-03.jpg---that demonstrate how your procedure affects our kitten image. In a comment, indicate how you created each image.

c. Document and write a procedure, (my-hsv-transformation img value), that transforms img using value and the HSV components of the image.

d. Using your procedure, create three images---kitten-hsv-transformed-01.jpg, kitten-hsv-transformed-02.jpg, and kitten-hsv-transformed-03.jpg---that demonstrate how your procedure affects our kitten image. In a comment, indicate how you created each image.

What to submit

Submit image-transformations.scm and your six jpg files on Gradescope.

Grading rubric

Redo or above

Submissions that lack any of these characteristics will get an I.

[ ] Passes all of the one-star autograder tests.
[ ] Includes the specified file, `image-transformations.scm`.
[ ] Includes an appropriate header on the file that indicates the
    course, author, etc.
[ ] Acknowledges appropriately.
[ ] Code runs in Scamper.
[ ] The question marks in the documentation have been filled in.

Meets expectations or above

Submissions that lack any of these characteristics but have all of the prior characteristics will get an R.

[ ] Passes all of the two-star autograder tests.
[ ] Code is well-formatted with appropriate names and indentation.
[ ] Code has been reformatted with Ctrl-I before submitting.
[ ] Code generally follows style guidelines, including limiting the
    length of lines to about 80 characters.
[ ] Documentation for all core procedures is correct / has the correct form.

Exemplary / Exceeds expectations

Submissions that lack any of these characteristics but have all of the prior characteristics will get an M.

[ ] Passes all of the three-star autograder tests.
[ ] Style is impeccable (or nearly so).
[ ] Avoids repeated work.
[ ] Uses `section` and composition when appropriate.

Q&A

For certain parts of the mini-project such as 1c-flattening, are we allowed to create a color procedure and then use that to apply to the entire image or are we supposed to only make an image transformation by itself?

You can write helper procedures wherever you find them useful.

But please document them.

Can you explain when it is appropriate to use section and composition?

You should use section primarily when you're defining a one-parameter procedure by filling in one or more parameters of another procedure.

You should use composition primarily when you're defining a one-parameter procedure that only applies a sequence of one parameter procedures.

You also use cut and composition when you have a procedure---like pixel-map or map---that applies a procedure (often of the prior form) to a large number of values.

In each of these cases, section and composition make your code more concise. You should not use section or composition when it makes your code longer.

One place your instructors used composition in solving this assignment was when they needed to convert an RGB color to an HSV color, manipulate the HSV values, and then convert back to an RGB color.

Why are we finding the remainder in cyclic-add-90?

Because we want to "wrap around to zero" when we hid 256, and remainder achieves that for us.

I can write hsv-rotate-hue, which rotates the hue of a single HSV color. However, for some reason, I am unable to extend that to an image using `pixel-map. Any ideas?

Don't forget that pixel-map expects a procedure that takes an RGB color as an input and returns an RGB color. If your procedure expects an HSV color, you'll need to do some conversions.

You may also end up needing to cut that procedure, since hsv-rotate-hue needs two parameters and pixel-map needs a one-parameter procedure.

I've tried using 36 and 37 as the even distribution values for the 3-bit components of the 8-bit color. Neither seems to work (as in they don't meet the tests).

You should probably use 255/7, which lets you precisely distribute the components. It may require a bit more care in rounding.

In this reading, we motivate the need to document our code to increase its readability and codify latent assumptions we make about our program design. We also introduce the particular format of code of documentation we will use for the remainder of the course.

Documenting Your Code

In computer programming, we design computational solutions to problems and then translate those solutions into our programming language of choice. Therefore, when we reason about the correctness of our programs, we need to do two things:

1. Is our solution (our algorithm) correct?
2. Is our translation of our solution to a program correct?

The second of these things is the reason why we care about making our code readable. Even if our code's *intent is correct, we will have difficulty determining that fact if we can't decide what the code does. This is why we emphasize the idea of making our code mirror our intent in this course. We heavily prefer realizing our solution to a problem directly as language constructs in our code to make it painfully evident that our translation from algorithm-to-program is correct.

While functional languages like Scheme make such translation easier, it is not always obvious from our code what our intent is, even with good structure and names. A great example of this is the humble substring function from the standard library:

(substring "hello world" 3 7)

substring takes three arguments: the string under consideration and two indices that describe the substring to extract from the first argument. However, how are the indices used by substring? Are the indices of the string 0-based or 1-based? Are the indices inclusive or exclusive? Execution of this example unveils the answers:

> (substring "hello world" 3 7)
"lo w"

The resulting substring starts from the fourth character of the input string and ends on the seventh. This implies that the indices are 0-based (since we specified the fourth character with index 3) and that the start index is inclusive and the end index is exclusive (since the index of the last character in the substring is 6).

Having to execute our function to figure out what it does is not ideal. What if the function we're considering takes a long time to execute? What if the function is deeply nested inside of our system and, thus, difficult to execute on its own? What if the function's behavior is so convoluted we don't even know what we could pass to the function to experiment?

Perhaps we could look at the source code of the function and gain some insights. In some cases, this will work. However, we do not always have the source code available to us. For example, there is not an easy way to jump from Scamper's API documentation to the source code it is documenting. Additionally, some functions, even when well-written, do not convey all these details. For example, here is the best implementation of substring I can come up with. (Note: We would have shown you the actual implementation of substring for Scamper, but it is in another programming language!)

(define substring
  (lambda (str start end)
    (list->string
     (map (lambda (i) (string-ref str i))
          (range start end)))))

We construct a substring by transforming the range of indices indicated by start and end into characters of the string. Note that while this is a direct, concise description of the function, the answers to our original questions---Are the indices 0- or 1-based? Are the arguments inclusive or exclusive?---are not evident from the source!

To make the answers to these questions obvious, we use function documentation comments or doc comment for short. Here is a doc comment for substring:

;;; (substring str start end) -> string?
;;;   str : string?
;;;   start : integer?, a 0-based index
;;;   end : integer?, a 0-based index
;;; Returns the substring of `str` denoted by the start index `start` 
;;; (inclusive) and end index `end` (exclusive).
(define substring
  (lambda (str start end)
    (list->string
     (map (lambda (i) (string-ref str i))
          (range start end)))))

Doc comments give us the full picture of what a function requires as input and what we can expect as output. Practically speaking, they form the bulk of the code documentation that we write in our programs.

The Anatomy of a Function Documentation Comment

Many programming languages provide special support for documenting functions, including a special syntax for specifying parameters and what the function returns. These languages then provide tools that extract these doc comments and create API documentation, e.g., the reference pages for Scamper's API found in "Docs" link found in the Scamper menu bar are mined directly from the Scamper source code! Even though these doc comments' practical effect is their extraction from code, it is useful to keep them in code so that we are reminded to update the documentation whenever we change the behavior of the function. Scamper does not yet have this functionality, so we instead present a simplified set of conventions for writing doc comments in the output of Scamper's documentation.

The doc comment for substring can be broken up into three parts. Note that throughout, we use triple semicolons (;;;) to encase our doc comments to make them stand out from other comments we might write.

Signature

;;; (substring str start end) -> string?

The signature of a function describes what it takes as input and produces as output. It should replicate a call to the function but with the parameter names in place of the actual values. As before, the names should be evocative of their intended use within the function. This gives the user an immediate sense of how to use the function. In addition to the call, the return type of the function is given following the arrow (->). The type of the value returned by the function is described by a predicate, typically one that tests the type of its argument.

Parameters

;;;   str : string?
;;;   start : integer?, a 0-based index
;;;   end : integer?, a 0-based index

This section describes the types of each parameter again by way of predicates that usually test type identity. In addition to the predicates, we might also specify other essential properties of the parameters that aren't necessarily captured in the predicate. For example, we note that both start and end are 0-based indices. In contrast, there is nothing special about str beyond the fact it is a string?, so we have nothing else include in its entry.

The set of conditions we place on a function's parameters are called the preconditions of the function. They represent the set of properties that the caller of the function must fulfill to ensure that function can operate successfully.

Note that the integer? predicate doesn't quite describe what values start and end ought to take on. In particular, negative integers do not make sense---they are not valid indices into the string. We could consider introducing a more specific predicate and use that instead:

;;; (natural? n) --> boolean?
;;;   n : integer?
;;;
;;; Returns true if and only if n is a natural number (n >= 0).
(define natural?
  (lambda (n) (>= n 0)))

However, this quickly leads to a rabbit hole of making up tons of new predicates all over the place! Rather than this, we'll favor using the type predicates defined in the standard library for our basic types:

• number? and integer?
• string?
• boolean?
• list?
• procedure?

And a few others we will introduce in the coming weeks. When our parameters have more requirements beyond what is captured by these functions, we'll use prose to describe them, e.g., "0-based index" for start and end. This prose can appear either in the parameters list alongside the relevant parameter if it is short. It can also appear in the description if the requirements on the parameters are more complicated to describe or involve multiple parameters. For example, by "index", we mean that start and end ought to be a valid index for the string. To make this explicit, we can describe this in the parameters list:

;;;   str : string?
;;;   start : integer?, a 0-based index (<= 0 start (length str))
;;;   end : integer?, a 0-based index (<= 0 end (length str))

Here, the constraint can be expressed as inequalities on start and end, namely that 0 ≤ start ≤ (length str) (and similarly for end). In the comment, we express this with a equivalent Scheme expression (<= 0 start (length str)). But writing this in traditional mathematical notation is also fine:

;;;   start : integer?, a 0-based index (0 <= start <= (length str))

It is also reasonable to push this information into the description, e.g.,

;;;
;;; Returns the substring of `str` denoted by the start index `start` 
;;; (inclusive) and the end index `end` (exclusive).  We expect that 
;;; 0 <= start <= (length str) and that 0 <= end <= (length str).

As a rule of thumb, if a constraint only involves one parameter and it is short to express (either with a Scheme expression, mathematical formula, or phrase), place it with the parameter list. If the constraint involves the interaction of multiple parameters or is complicated, place it in the description where there is more prose.

However, it is important that these preconditions are captured somewhere in our doc comment rather than worrying about where. In other words, follow this rule of thumb, but if it makes more logical sense or looks better to break the rule, feel free!

Description

;;;
;;; Returns the substring of `str` denoted by the start index `start` 
;;; (inclusive) and end index `end` (exclusive).

Finally, this section describes the behavior of the function. This includes:

1. A description of the computation that the function performs and the result value that it outputs.
2. Any important details about the function's behavior that a user of the function ought to know.

Practically speaking, we are writing simple enough functions in the course that the function description will be one sentence that describes the function's output. This description, coupled with the return type specified in the signature, serves as the postcondition to the function. A postcondition is what the function guarantees will occur provided that its precondition is satisfied.

When we think about other prose to write beyond the description of the function's output, we must keep in mind the audience of these doc comments. The audience for these doc comments is not us! Since we're writing the code, we usually have the implementation in our heads, so that these details are self-evident. Doc comments are meant for our collaborators and other potential users of this code to quickly learn about the program's available functionality without having to dive through the details of the code. This audience also includes our future selves who may have forgotten these details!

With this in mind, we want to include those details that are captured in our well-designed, "self-evident" code that users of our function ought to know. For substring, we want our users to know whether the indices are inclusive or exclusive on their ends. In general, this will include additional preconditions on the parameters of the functions that aren't readily captured in the parameters section of the doc comment.

Preconditions and Postconditions as Contracts

We think of our doc comments as describing a sort of contract between the caller and implementor of a function. This contract is made up of the preconditions---expected types and properties of the function parameters---and the postconditions---expected type and properties of the output---described by the doc comment. The contract acts as follows:

If the contract's preconditions are satisfied by the caller of the function, then the implementor of the function guarantees that the function will fulfill the postconditions of the contract.

In the context of substring, this means:

If the user provides a string and two valid, 0-based indices, then substring produces the substring starting at index start (inclusive) and end (exclusive).

If the function's caller does not fulfill these preconditions, then like in real life, the function is not bound to the contract; the function is free to do whatever it wants! It might throw an error, or it might return garbage entirely unrelated to the intended result. For example:

(substring 24710 0 3)

Luckily, in Scamper, the substring function checks its contract before proceeding execution. But somtimes, such contract checks are infeasible or impossible to implement! So we should be ready to encounter errors that aren't quite informative, or worse yet, silent errors where a non-sensible value is produced and is only caught in later code!

In summary, preconditions and postconditions give us a quick and easy way to understand a function's behavior. In the coming days, we'll see that they also give us a hook for reasoning about our code, especially if we encounter a bug in our implementations!

Documenting other parts of your code

As we've seen, doc comments are only one kind of comment we might use in our code. We might choose to document other places as well, e.g., inside the implementation of a function:

(cond 
  [(> x 0)  
   1]
  [(< x 0) 
   -1]
  ; x is neither positive nor negative, it must be zero.
  [else   
   0]) 

Here we remind ourselves in a comment that we arrive at the else branch because it must be the case that x is not greater than or less than 0. Is this comment necessarily? In some sense, it is because it isn't immediately obvious from the else what is true about x. However, if we took a few seconds to reason about how the cond operates, we could have arrived at that conclusion pretty quickly.

Even if this comment's utility is suspect, is there any harm in including such little notes? Different faculty have different perspectives. One set argues that it's worthwhile to include such comments as they ease the cognitive load on the reader. Some members of that group also tend to write the code in natural language before writing programming code. And that's a strategy we think you should use (writing in English first).

One argues that there is harm for including such comments on two levels:

1. It makes our code more verbose. While it is a small amount of additional visual clutter, it is still cluttered, nevertheless.
2. More importantly, the comment represents yet another thing that must be changed if we change the code! We do not want our documentation to get out of sync of the code it is documenting, so we are obligated to update these comments whenever we made relevant changes to the program.

This last point is the real nail in the coffin for including excessive amounts of documentation in code. The more documentation we include, the more maintenance cost we incur in keeping everything up to date.

In our small-scale programming context, the effect of code maintenance is minimal. But we want to ensure that you develop good programming habits in this course! We will discourage you from writing inter-function (i.e., within a function) in favor of writing code that is readable without additional comments (beyond doc comments). If you need a comment to remember how the innards of a function work, this is a strong sign you have made the function too complicated. Instead, use the decomposition tools we've introduced, such as helper functions and let-bindings, to make sense of the situation!

Self-Checks

Check: Oops

Here's the documentation for substring, gathered all together in one place.

;;; (substring str start end) -> string?
;;;   str : string?
;;;   start : integer?, a 0-based index (<= 0 start (length str))
;;;   end : integer?, a 0-based index (<= 0 end (length str))
;;; Returns the substring of `str` denoted by the start index `start` 
;;; (inclusive) and end index `end` (exclusive).

It turns out that the contract for substring is not complete; it is missing at least one precondition! Experiment with various possible inputs for substring until you find a precondition not covered by our current doc comment. Give an updated doc comment that covers this new precondition, adding it to either the parameter list or description of the comment.

Unit Testing

As you develop procedures and collections of procedures, you have a responsibility to make sure that they work correctly. One mechanism for checking your procedures is a comprehensive suite of tests. In this reading, we consider the design and use of tests. We also consider the testing facilities built into Scamper.

Introduction

Most computer programmers strive to write clear, efficient, and correct code. It is (usually) easy to determine whether code is clear. With some practice and knowledge of the correct tools, one can determine how efficient code is. However, believe it or not, it is often difficult to determine whether code is correct.

The gold standard of correctness is a formal proof that the procedure or program is correct. However, in order to prove a program or procedure correct, one must develop a rich mathematical toolkit and devote significant effort to writing the proof. Such effort is worth it for life-critical applications. However, for many programs, the effort and time required for a formal proof are often more than can be reasonably expected.

There is also a disadvantage of formal proof: Code often changes and the proof must therefore also change. Why does code change? At times, the requirements of the code change (e.g., a procedure that was to do three related things is now expected to do four related things). At other times, with experience, programmers realize that they can improve the code by making a few changes. If we require that all code be proven correct, and if changing code means rewriting the proof, then we discourage programmers from changing their code.

Hence, we need other ways to have some confidence that our code is correct. A typical mechanism is a test suite, a collection of tests that are unlikely to all succeed if the code being tested is erroneous. One nice aspect of a test suite is that when you make changes, you can simply re-run the test suite and see if all the tests succeed. To many, test suites encourage programmers to experiment with improving their code, since good suites will tell them immediately whether or not the changes they have made are successful.

But when and how do you develop tests? These questions are the subject of this reading.

What is a test?

As the introduction suggested, you should write tests when you write code. But what is a test? Put simply, a test is a bit of code that reveals something about the correctness of a procedure or a set of procedures. Most typically, we express tests in terms of expressions and their expected values.

For example, suppose we've written a procedure, remove-negatives, that removes negative numbers from a list and keeps the remainder of the values in the same order,

• (remove-negatives (list)) is the empty list.
• (remove-negatives (list 3)) is equal to (list 3)
• (remove-negatives (list 3 7 11)) is equal to (list 3 7 11)
• (remove-negatives (list -1 3 7 11)) is equal to (list 3 7 11)
• (remove-negatives (list -1 3 -2 7 -3 11)) is equal to (list 3 7 11)
• (remove-negatives (list -1 -2 -3)) is the empty list.

You might even expect to see the first as a postcondition of remove-negatives. You might also expect to see the others as postconditions (i.e. "if none of the elements in lst are negative, then result is lst"). You'll find that we often base our tests on the postconditions.

We could express those expectations in a variety of ways. The simplest strategy is to execute each expression, in turn, and see if the result is what we expected. You may have be using this form of testing regularly in your coding. (We often call this "experimenting with your code" to distinguish it from the kinds of testing we introduce in this reading.)

(remove-negatives is defined using a filter over the input list. We haven't discussed this yet, so don't worry about how we implemented remove-negatives. Focus on how it behaves instead!)

(define remove-negatives
  (lambda (l) (filter (lambda (n) (>= n 0)) l)))

(remove-negatives (list))
(remove-negatives (list 3))
(remove-negatives (list 3 7 11))
(remove-negatives (list -1 3 7 11))
(remove-negatives (list -1 3 -2 7 -3 11))
(remove-negatives (list -1 -2 -3))

One disadvantage of this kind of testing is that you have to manually look at the results to make sure that they are correct. You also have to know what the correct answers should be. But reading isn't always a good strategy. There's some evidence that you don't always catch errors when you have to do this comparison, particularly when you have a lot of tests. We know that we've certainly missed a number of errors this way. An appendix to this document presents an interesting historical anecdote about the dangers of writing a test suite in which you must manually read all of the results.

Since reading the results is tedious and perhaps even dangerous, it is often useful to have the computer do the comparison for you. For example, we might write a procedure, check, that checks to make sure that two expressions are equal. We can then use this procedure for the tests above, as follows:

(define remove-negatives
  (lambda (l) (filter (lambda (n) (>= n 0)) l)))

(define check
  (lambda (exp1 exp2)
     (if (equal? exp1 exp2)
         "OK"
         "FAILED")))

(check (remove-negatives (list)) 
       (list))
(check (remove-negatives (list 3))
       (list 3))
(check (remove-negatives (list 3 7 11))
       (list 3 7 11))
(check (remove-negatives (list -1 3 7 11))
       (list 3 7 11))
(check (remove-negatives (list -1 3 -2 7 -3 11))
       (list 3 7 11))
(check (remove-negatives (list -1 3 2 7 - 113))
       (list 3 7 11))
(check (remove-negatives (list -1 -2 -3))
       (list))

Note that in the penultimate test, the test itself, rather than remove-negatives, was incorrect.

Confirming that our code is correct is now simply a matter of scanning through the results and seeing if any say "FAILED". And, as importantly, we've specified the expected result along with each expression, so we don't need to look it up manually.

Of course, there are still some disadvantages with this strategy. For example, if we put the tests in a file to execute one by one, it may be difficult to tell which ones failed. Also, for a large set of tests, it seems a bit excessive to print OK every time. Finally, we get neither "OK" nor "FAILED" when there's an error in the original expression.

In fact, if an error occurs in the middle of a group of tests, the whole thing may come to a screeching halt.

(define remove-negatives
  (lambda (l) (filter (lambda (n) (>= n 0)) l)))

(define check
  (lambda (exp1 exp2)
     (if (equal? exp1 exp2)
         "OK"
         "FAILED")))

(check (remove-negatives 5) (list 1 2 3))

Testing frameworks

To handle these and other issues, many program development environments now include some form of testing framework. And even when they don't, languages often have accompanying testing frameworks. While testing frameworks differ, they tend to share some commonalities.

First, most testing frameworks provide a way for you to check expected results. That's a lot like our check procedure above. That is, we have a value we expect and an expression; we evaluate the expression; and we compare the result to the expected value. We will refer to procedures used to check expected results as "checks".

Second, most testing frameworks provide a way to group checks into test cases. Why would we need more than one check in a test case ? Sometimes, it's because we need to check multiple things about a result. For example, if we want to make sure that (median lst) has the right value, we might want to check that (a) the return value is a real number, (b) half the numbers in the list are less than the return value, and (c) half the numbers in the list are greater than the return value. But other times, the tester feels it's natural to put a lot of related checks into a single test case---if any of them fail, the whole test case fails. How do you divide checks into tests? In some sense, it's a matter of taste. Some testers like just a few checks per test case. Others like a lot.

Finally, most testing frameworks provide a way to group individual test cases into test suites. Why do we need groups of tests? Because we often have multiple procedures to test, both individually and in groups, and we want to run all of the tests to ensure that everything works together. For example, we might provide a library of a variety of related functions and want to test the whole library en masse.

So, when you first encounter a new testing framework, you should ask yourself three questions: How do you check for expected results? How do you group checks into test cases? And how do you group test cases into suites? (You should also ask a few related questions, such as how you run the tests.)

A testing framework for Scamper

We provide an additional statement forms that allows you to write unit tests for your code:

(test-case <description> <equality-test> <expected> <fn>)

Note that while this form look like a function call, because it is a statement, it can only appear at the top-level of your program.

Each of the four "arguments" to test-case are expressions as follows:

• <description> is an expression that evaluates to a string that describes the test case. Commonly, this should simply be a string literal describing the test.
• <equality-test> is an expression that evaluates to an equality function that takes two values and compares the values to see if they are equal. The test case will pass if the function returns #t and fail otherwise. This will often be the equal? function.
• <expected> an expression that evaluates to the expected value for this test case.
• <fn> is a zero-argument function that executes the code that we want to test. The result is function is tested for equality with the expected value.

Here is an example of simple use of test-case: one where the test passes and another when the test fails:

(import test)

(test-case "simple test case that passes"
  equal? 1
  (lambda () 1))

(test-case "simple test case that fails"
  equal? 1
  (lambda () 0))

Most of the time, we will simply pass equal? to test-case to compare expected and actual for equality in the way that we expect. However, depending on the situation, we might want to perform more complicated comparisons for equality.

For example, recall that our numbers are sometimes approximate due to round-off error. Comparing such approximate values for equality does not make sense because we expect them to differ from the expected value by some small amount, call it epsilon.

In these situations, rather than passing equal?, we can use the =-eps function from the standard prelude. (=-eps epsilon) will generate an equality-checking function that checks for equality within epsilon for two input values. In effect, the epsilon value allows us to tolerate a certain amount of error between the two values that we want to compare.

For example, here are some examples of using test-case and =-eps. Note how when the test succeeds, the output is a note that the test succeeded. When the test fails, you get feedback about why that was the case!

(import test)

(test-case "exact equality of 4"
  (=-eps 0) 4
  (lambda () 4))

(test-case "two times two is exactly four"
  (=-eps 0) 4
  (lambda () (* 2 2)))

(test-case "sqrt 2 squared, approximately"
  (=-eps 0.00001) 2
  (lambda () (* (sqrt 2) (sqrt 2))))

(test-case "sqrt 2 squared, exactly"
  (=-eps 0) 2
  (lambda () (* (sqrt 2) (sqrt 2))))

(import test)

(define remove-negatives
  (lambda (l) (filter (lambda (n) (>= n 0)) l)))

(test-case "empty list"
  equal? null
  (lambda () (remove-negatives null)))

(test-case "singleton list, no negatives"
  equal? (list 3)
  (lambda () (remove-negatives (list 3))))

(test-case "multiple elements, no negatives"
  equal? (list 3 7 11)
  (lambda () (remove-negatives (list 3 7 11))))

(test-case "negative at front of list"
  equal? (list 3 7 11)
  (lambda () (remove-negatives (list -1 3 7 11))))

(test-case "mixed list"
  equal? (list 3 7 11)
  (lambda () (remove-negatives (list -1 3 -2 7 -3 11))))

(test-case "all negative"
  equal? null
  (lambda () (remove-negatives (list -1 -2 -3))))

When to write tests

To many programmers, testing is much like documentation. That is, it's something you add after you've written the majority of the code. However, testing, like documentation, can make it much easier to write the code in the first place.

As we suggested in the reading on documentation, by writing documentation first, you develop a clearer sense of what you want your procedures to accomplish. Taking the time to write documentation can also help you think through the special cases. For some programmers, writing the formal postconditions can give them an idea of how to solve the problem.

If you design your tests first, you can accomplish similar goals. For example, if you think carefully about what tests might fail, you make sure the special cases are handled. Also, a good set of tests of the form "this expression should have this value" can serve as a form of documentation for the reader, explaining through example what the procedure is to do. There is even a popular style of software engineering, called test-driven development (TDD), in which you always write the tests first. Test-driven development is a key part of a variety of so-called "agile software development strategies".

Edge cases and corner cases

Although most of our tests will be for "normal" inputs, it can also be useful to ensure that your procedure works correctly for values at the "edge" of legality.

• If a procedure on lists should work correctly with the empty list, make sure that you have a test that uses the empty list.
• If a procedure is looking in a list for a particular kind of value, make sure to include a test which has that kind of value at the front of the list, a test that has that kind of value at the back of the list, and another that has it at both back and front.
• If a procedure is supposed to work with real numbers, make sure you check both exact and inexact numbers. Check zero. Check a really small number. Check a really large number.
• If a procedure is supposed to work with strings, make sure you try the empty strings.

Often, it's these "edge cases" that help us find the most subtle bugs in a procedure. So we always try to include some.

Self checks

Check 1: Testing experiments

In the Explorations pane, try test-case a few times to make sure that you understand its operation. You should also look for both matching and non-matching expected and actual. And you should see what happens when you include and do not include the message.

Is this check vague? Yes. That's intentional. We're at the point in the course when you should make it a matter of course (no pun intended) to try different inputs to see what happens.

Check 2: Checking =-eps

Explain, in your own words, what purpose of (=-eps) serves. (If you can't, you may want to conduct some more experiments.)

Check 3: Testing bound-grade

Sketch a set of tests for the bound-grade procedure, which takes a real number as input and outputs

• That number, if it is between 0 and 100, inclusive.
• Zero, if it is less than 0.
• 100, if it is greater than 100.

By "sketch", we mean "list the tests you'd write".

Appendix: An historical tale

Many of us are reminded of the need for unit testing by the following story by Doug McIlroy, posted to The Risks Digest: Forum on Risks to the Public in Computers and Related Systems:

Sometime around 1961, a customer of the Bell Labs computing center questioned a value returned by the sine routine. The cause was simple: a card had dropped out of the assembly language source. Bob Morris pinned down the exact date by checking the dutifully filed reversions tests for system builds. Each time test values of the sine routine (and the rest of the library) had been printed out. Essentially the acceptance criterion was that the printout was the right thickness; the important point was that the tests ran to conclusion, not that they gave right answers. The trouble persisted through several deployed generations of the system.

McIlroy, Doug (2006). Trig routine risk: An Oldie. Risks Digest 24(49), December 2006.

If Bell Labs had arranged for a count of successes and a list of failures---rather than a thick printout---they (and their customers) would have have been in much better shape.

We present a systematic approach to debugging your code and show you how you can use debugging tools to augment this approach.

Hypothesis-driven debugging

Hypothesis-driven debugging captures the idea that we can use the scientific process to make debugging systematic rather than ad-hoc. In this framework, we are observing and ultimately making predictions about the behavior of our program. There are five steps to hypothesis-driven debugging:

1. Gather data
2. State assumptions
3. Predict what is wrong
4. Use tools to verify/refute your prediction
5. Analyze your results

Gather data

In the first step, we gather data about the error that we have encountered. Primarily, this is the indicator that we have encountered an error in the first place. In many cases this is the error message generated by Scheme as the result of faulty syntax, a violated contract, etc. However, in the case of other errors, this may be more subtle, e.g., the output of a function not matching what you expected.

Scheme error messages help you narrow down the location and kind of error ultimately plaguing your code. Sometimes the error message is very clear about these things, e.g., this contract violation:

+: contract violation
  expected: number?
  given: "1"
  argument position: 2nd
  other arguments...:

Tells me that the second argument, "1", violates the contract of + because a number? was expected. In contrast:

read-syntax: expected a `)` to close `(

Hints at, but does not outright say, that the problem is that we're missing parentheses in our code. Furthermore, this error message does not say where the missing parentheses might be.

Because of the imprecision of errors, we rely on other data to get our bearings. This includes:

• The topology of the program, i.e., the order in which functions are called in our program. This is also captured by the call stack of an error which describes the sequence of function calls that generated the error in question.
• Our knowledge of what parts of the code were last edited since the appear began appearing. This is also called the delta of the code we added since our last successful execution of the program.

These are things you likely "just know" about your program, but it is important, especially early on, to explicitly acknowledge these facts in your mind when you encounter an error. In some cases, you might find it productive to write down this information to get it out of your head!

Kinds of errors

It is useful to understand the different kinds of errors possible when programming. Each kind of error begets its own set of strategies for ultimately resolving the problems at hand.

Regardless of programming language, we break up errors into two overarching classes:

• Static errors: these are errors that happen before the program executes.
• Dynamic errors: these are errors that happen during program execution.

Some languages and their tools have well-defined "pre-execution" phases where the program is compiled into an executable in one step and then ran in a second step. Scamper bleeds the pre-execution and execution phases together in its "Run" button. When run is pressed:

• Scamper first checks the syntax of our program to ensure that it is well-formed. It also checks to ensure that all of our usage of identifiers are well-scoped.
• Scamper then runs the program and outputs the result in a window.

Within each class of errors, there are different sub-categories of errors that are dependent on the language involved. In Scheme, there are two kinds of static errors you will encounter:

• Syntax errors where the program is malformed in some way, e.g., missing a parentheses.
• Undefined identifier errors where an identifier is used outside of its scope. Recall that Scheme is a lexically scoped language. That is, the syntax of the program alone determines where an identifier is live or usable.

In Scheme, virtually every other error you see is a dynamic error of some form or another. These include:

• Contract violations where a value is passed to a function and that value does not fulfill the function's contract (preconditions).
• Exceptions where function-defined errors are raised, e.g., divisor by error or out-of-bounds list indexing.
• Logic errors where a program is semantically correct, i.e., language constructs are used in a consistent manner, but the output of the program is still wrong. For example, your translation of an arithmetic formula may incorrectly contain a subtraction when an addition was needed.

State assumptions

When designing your program, you made assumptions about its behavior. For example, the preconditions and postconditions of a function codify assumption about its behavior. Because the program didn't work as expected, those assumptions were likely violated in some way. It is therefore important to explicitly consider what assumption you have made about your code as they can serve as starting points for further investigation.

For example, suppose we have a function that counts all of the occurrences of a given letter in the string:

;;; (extract-occurrences s c) -> exact-nonnegative-integer?
;;;   s : string?
;;;   c : char?
;;; Returns the number of occurrences of c in s.

And you receive the following contract violation (a dynamic error) when testing the function with the expression (extract-occurrences 12718 #\1):

string-ref: contract violation
  expected: string?
  given: 12718
  argument position: 1st
  other arguments...:

If we note that our function expects that s is a string?, its precondition, then we can more readily identify the likely problem, even without looking at the code: 12718 is a number? rather than a string?. Most likely, s is not a string? which violates our precondition.

Predict what is wrong

We first hypothesize what is wrong with the code before we actually dive in and use debugging tools. This is akin to the scientific method where we make our predictions before running our experiments. In the context of general science, this is important because if we run our experiments first, we will likely make predictions specifically to match the results from the experiments. This doesn't mean our predictions are wrong---indeed, we have to do some sort of observing before predicting to generate reasonable hypotheses in the first place. But such behavior does not scientifically validate our hypotheses; additional experimentation is necessary to do so.

When debugging, we don't run risk of violating ethical standards if we observe-and-then-predict. However, we do run the risk of wasting our time if we aren't entering the observation phase of debugging without a clear prediction to verify or refute. Programs can be wrong in a startling amount of ways. We can become quickly overwhelmed by the possibilities if we begin prodding the code with a debugger before we have an idea of what we are looking for. Therefore, making predictions first helps us tame the complexity of problem solving.

If you can immediately predict the root cause of the error, that's great! But frequently, that is not the case. Instead, you might make smaller predictions about the behavior of parts of your program you suspect are problematic. The most common of these predictions you might make are:

• "The value of this variable is x." You make a prediction about the value of a particular variable.
• "I made it to this part of the code." You make a prediction about the flow of execution in the program, e.g., the program execute the if-branch versus the else-branch of a conditional?

In both cases, you can use the data and assumptions you gathered previously along with your mental model of computation to help you make these predictions.

Use tools to verify/refute your prediction

It is only at step 4 where we actually use debugging tools! Now that we have something concrete to look for, we can use our debugging tools to quickly find that thing rather than dig aimlessly.

In most languages, there are a variety of tools that people use to verify and refute predictions about our code's behavior.

• Loggers that capture the relevant state of our program during its execution. Loggers include print debugging where you use the print-to-console facilities of most languages to quickly log values.
• Debuggers that allow us to systematically execute a program step-by-step and inspect the contents of variables, the call stack, etc.
• Unit testing frameworks that allow us to check smaller pieces of the program. (As you may have recently learned, it's often best to check small pieces of a program before checking bigger pieces.)
• Assertions that allow us to verify conditions at certain points in a program and stop the program if those conditions aren't met.

Each approach has some trade-offs:

• Loggers, in particular, print debugging, are easier and more intuitive to use. However, they are limited in scope---you can only see what you log---and invasive to code---you litter your code with prints that you need to remember to clean up or comment out when you are done. There are also "Heisenbugs", situations in which the bug disappears when you log and reappear when you stop logging.
• Debuggers are more comprehensive, powerful, and specifically do not leave "traces" in your code. However, that power comes at a price: debuggers can be more complicated to learn and more annoying to use on a consistent basis, especially for smaller problems.
• Unit testing frameworks often focus on small parts. Sometimes it's the combination of small parts that break things.
• Assertions, like loggers, may need to be turned off (and may require effort to do so. Assertions are also harder to use in a functional framework.

Our primary tool for debugging is the explorations pane which allows us to reply execution of our program.

Analyze your results

After using your debugging tool of choice, what are the ramifications of what you found? If your prediction was the root cause, then congratulations; you're done! Otherwise, your prediction has given you some new information. What further predictions can you make that will get you closer to the root cause of the problem? Repeat the hypothesis-driven debugging process until you unveil this cause!

Self-Check: Going Through the Motions (‡)

In a previous lab, you wrote a function for making change given an amount of cents. Here's an attempt at the function.

(Note this function uses functionality, namely let-bindings, we have not seen yet. But that is ok! We can use our tools, namely the stepper, and intuition to diagnose errors, even with new code!)

(define make-change
  (lambda (n)
    (let* ([quarters (quotient n 25)]
           [left-over (remainder n 25)]
           [dimes (quotient n 25)]
           [left-over (remainder left-over 25)]
           [nickels (quotient left-over 25)]
           [cents (remainder left-over 25)])
      (list quarters dimes nickels cents))))

However the function does not work as expected:

(import test)

(define make-change
  (lambda (n)
    (let* ([quarters (quotient n 25)]
           [left-over (remainder n 25)]
           [dimes (quotient n 25)]
           [left-over (remainder left-over 25)]
           [nickels (quotient left-over 25)]
           [cents (remainder left-over 25)])
      (list quarters dimes nickels cents))))

(test-case "change example"
  equal? (list 5 0 0 4) (lambda () (make-change 129)))

Go through each step of the hypothesis debugging process to discover, diagnose, and ultimately fix the problem. For each step of the process, write a sentence or two about what you did and why. For this problem, you do not have to submit your fixed code; we only want your description of what you did during the debugging process!

Documentation and Testing

In this lab, you will get practice reading and writing thorough documentation and reasoning about a function's pre- and post-conditions and writing tests for these functions.

Download the code for this lab here:

• documentation-and-testing.scm

Upload the completed lab to Gradescope when you are done!

The Music Library

So far, we've looked at a variety of primitive types---integral and floating-point numbers, characters and strings, and booleans. How can we combine these to form more interesting types? This will be the subject of the remainder of the course, but you have seen at least one example of such an aggregate datatype before: images. For example, consider a rectangle:

(import image)
(rectangle 100 100 "solid" "aqua")

We can think of a rectangle as a datatype made up of four primitive types: two numbers and two strings.

This week, we will look at another datatype aligned with the audio theme of this course: musical compositions. The music library provides a number of functions for creating and manipulating musical compositions. In this part, we'll introduce the basic functionality of the library.

(By the way, don't worry if you don't know anything about music. We'll explain everything along the way!)

The music Library

The most important function that the music library provides is the note function which creates a composition consisting of one note.

(import music)
(note 60 qn)

The note function takes two arguments:

• A number corresponding to the MIDI note value of the note to be played. MIDI, short for Musical Instrument Digital Interface, is a standard for allowing digital instruments to interface with computers. The value 60 here corresponds to middle C on the keyboard.

• A duration value that will be the duration of the note to be played. We express durations in terms of ratios of notes. qn is a variable of type duration? that is a quarter note, i.e., the ratio \( \frac{1}{4} \). (A quarter of what? We'll discuss that in the lab!)

Taken together, (note 60 qn) is a musical composition consisting of a single note that is a middle C played for the length of a quarter note. You can try out the note in the output window above!

With images, shapes like rectangle and circle can be combined to form larger images with functions like above, beside, and overlay. With compositions, we have two options for creating smaller compositions from larger ones:

• We can play compositions sequentially, i.e., one after the other, with the seq function.
• We can play compositions in parallel, with the par function.

For example, a B♭ major chord consists of three notes: B♭, D, and F. These correspond to MIDI notes 58, 62, and 65, respectively. With this information, we can play these three notes in sequence or parallel, with seq and par, respectively:

(import music)
(seq (note 58 qn)
     (note 62 qn)
     (note 65 qn))

(par (note 58 qn)
     (note 62 qn)
     (note 65 qn))

Surprisingly, there's not much left to the music library! With just three functions---note, par, and seq---we can write and explore music in our Scamper programs!

The Lab: Music in Scamper

Download the code from

• the-music-library.scm

and follow the instructions.

When you are done, make sure to save the file and then upload the completed lab to Gradescope.

Design and Color

Light and color

Most of us see colors. (Both vision and color vision are prerequisites to the ability to see color, so not everyone sees colors.) In addition to vision the other element needed for us to see color is light. There are two kinds of light that allow us to see color. The first is incandescence this light is produced by heated materials: the sun, fire, and tungsten light bulbs, for example. The second kind of light is luminescence; this light is the result of specific movements and emissions of electrons, producing light at a lower temperature than incandescence. Fireflies, fluorescent lights, televisions, computer monitors and lasers generate luminescent light. Both incandescence and luminescence produce white light, the light that makes up the visible spectrum of color.

Humans have long used pigments to create color. What we see as color in a painting on the wall of a cave or on a canvas is reflected light. Each pigment selectively absorbs, or subtracts, specific wavelengths of the visible spectrum and reflects the rest. The color red, for example, is red because when light hits its surface the pigment absorbs (subtracts) the entire visible spectrum except the red portion. This kind of is subtractive color.

The kind of color we are creating and manipulating in this course is produced by luminescent light. Each pixel in your computer monitor combines red (R), green (G), and blue (B) lights. They can be added together to create virtually any color perceivable to the eye. When all three colors are added together in equal amounts the result is white. This is additive color---or simply RGB color.

Some principles of color

The following are some terms and approaches used to teach artists and designers the fundamentals of color theory. As a general reference from an art and design perspective, we use the subtractive color system here, with a few exceptions, these principles also apply to additive color.

Hue: Hue simply refers to the name of the color. Red, green, orange, and purple, for example, are hues. However, there is a distinction between hue and color. One hue can be varied to produce many colors---there are relatively few hues, but there can be an unlimited number of colors. Pink, rose scarlet, maroon, and crimson are all colors, but the hue in each case is red.

Primary colors: The three primary subtractive colors are red, yellow, and blue. From these all other colors are mixed. (In contrast, the three additive colors are red, green, and blue.)

Secondary colors: The three secondary colors are mixtures of two primaries---orange, violet, and green. Because of the relative strength of the various hues, a visual middle secondary does not always contain equal amounts of the two colors.

Tertiary colors: The six tertiary colors are mixtures of a primary and an adjacent secondary---yellow-orange, red-orange, red-violet, blue-green, blue-violet, and yellow-green.

Value: Value refers to the lightness or darkness of the color; value is altered by adding black or white to a color. Adding black darkens the color and produces a shade or low-value color. Adding white lightens the color, producing a tint or high-value color. Value, like color itself, is variable and entirely dependent on surrounding hues for its visual sensation. Most people can distinguish at least forty shades and tints of any color.

Saturation: Saturation refers to the brightness of a color---because a color is fully saturated only when pure and unmixed. Mixing black or white with a color changes its value, but also affects its saturation. There are two ways to lower the saturation of a color, to make a color less bright, more neutral. The first is to mix gray with the color. The second is to mix a color with its complement---the color directly across from it on the color wheel. When not mixed, but placed side-by-side, complimentary colors intensify the visual brilliance of one another, so that the colors appear to vibrate.

Color schemes

We may analyze or generate images using a variety of color scheme combinations.

Complementary: A complementary color scheme joins contrasting colors that lie opposite each other on the color wheel.

Analogous: An analogous color scheme combines three colors that are adjacent to one another on the color wheel.

Monochromatic: A monochromatic color scheme involves the use of only one color. The color can vary in value and pure black or white may be added. The resulting effect is extremely harmonious, and generally quiet and subtle.

Cool and warm colors: Blue and green are thought of as cool colors with blue-green the coldest of hues. Red, yellow, and orange are thought of as warm colors with red-orange as the warmest color. Warm colors tend to advance while cool colors tend to recede. Warm/cool color relationships allow for establishing depth and volume in painting. (I'm not sure whether these assessments of coolness and warmth are universal or specific to certain cultures.)

Color discord: Color discord is the opposite of color harmony. Colors widely separated on the color wheel (but not compliments) are generally seen as discordant combinations. A couple of examples: combining a primary and a tertiary that is beyond an adjacent secondary like red and blue-purple; combining a secondary and a tertiary beyond an adjacent primary like orange and yellow-green. It is important to note that the impression of discord is much greater when the value of the two colors is similar.

Color context: a color can appear to be different depending on the colors that surround it; the perception of it changes according to its context.

These principles serve a reference point for an informed exploration of color. With practice you will develop your own ability to articulate visual information with color. The articulate arrangement of visual information leads one not only to clear communication but to expression as well.

Color Matters has useful illustrations of some of these principles and color schemes. The Palleton Color Scheme Designers makes it very easy to experiment with creating color palettes incorporating several color schemes.

Self Checks

Check 1: Color Schemes

Pick one or two images that you find compelling and consider the color schemes you think they employ. (Please spend no more than five minutes on this task.)

RGB colors

Introduction

In our initial exploration of images, you learned about how to make images using simple shapes. In our initial work, we limited ourselves to named colors. However, one of the great advantages of computational image making is that it is possible to describe colors that do not have a name. In fact, it is often better to use a more precise definition than is possible with a name. After all, we may not agree on what precisely something like "springgreen" or "burlywood" means. (One color scheme that we've found has both "Seattle salmon" and "Oregon salmon". Would you know how those two colors relate?)

In fact, it may not only be more accurate to represent colors non-textually, it may also be more efficient, since the computer will often need to look up color names in a table to convert them to an underlying representation.

Representing colors

The most popular scheme for representing colors for display on the computer screen is RGB. In this scheme, we build each color by combining varying amounts of the three primary colors, red, green, and blue. (What, you think that red, yellow, and blue are the primary colors? It turns out that primary works differently when you're transmitting light, as on the computer screen, than when you're reflecting light, as when you color with crayons on paper.)

So, for example, purple is created by combining a lot of red, a lot of blue, and essentially no green. You get different purple-like colors by using different amounts of red and blue or even different ratios of red and blue.

When we describe the amount of red, green, and blue, we traditionally use integers between 0 and 255 to describe each component color. Why do we start with 0? Because we might not want any contribution from that color. Why do we stop with 255? Because 255 is one less than 28 (256), and it turns out that numbers between 0 and 255 are therefore easy to represent on computers. (For those who learned binary in high school or elsewhere, if you have exactly eight binary digits, and you only care to represent positive numbers, you can represent exactly the integers from 0 to 255. This is akin to being able to count up to 999 with three decimal digits.)

If there are 256 possible values for each component, then there are 16,777,216 different colors that we can represent in standard RGB. Can the eye distinguish all of them? Not necessarily. Nonetheless, it is useful to know that this variety is available, and many eyes can make very fine distinctions between nearby colors.

Racket usually adds a fourth component to colors: an alpha value. We will ignore that for the time being. But you may see an extra 255 being added to the end of colors you create, at least when you view them in numeric form.

Relevant procedures

Let us now turn to the primary procedures we will use to work with RGB colors.

We build a new color with the (rgb red-component green-component blue-component)` procedure. We can also set the opacity of the color by adding a fourth component, typically referred to as the alpha channel or just alpha. With with the other components, the alpha channel is between 0 and 255.

Here are a few colors.

> (rgb 255 0 0)

> (rgb 0 255 0)

> (rgb 0 128 0)

> (rgb 255 0 255)

> (rgb 191 0 191)

> (rgb 127 0 127)

> (rgb 127 0 192)

> (rgb 192 0 127)

> (rgb 0 0 255)

> (rgb 0 0 255 255)

> (rgb 0 0 255 192)

> (rgb 0 0 255 128)

> (rgb 0 0 255 64)

> (rgb 0 0 255 0)

Can you explain why we chose each set of examples?

Color names

You may note that we often prefer to use color names. We can convert a color name to an RGB color using (color-name->rgb name).

> (color-name->rgb "purple")

> (color-name->rgb "salmon")

> (color-name->rgb "yellow")

If you give color-name->rgb something other than a color name, it will return the special value #f, which represents "false".

> (color-name->rgb "csc151")
#f

But what color names are available? The procedure (all-color-names), which takes no parameters, gives you all the valid color names.

> (all-color-names)
'("aliceblue"
  "antiquewhite"
  "aqua"
  "aquamarine"
  "azure"
  ...
  "whitesmoke"
  "yellow"
  "yellow green"
  "yellowgreen")

There are 181 names, including the with/without space equivalents, such as "yellow green" and "yellowgreen".

Since you may not want to peruse the full list, there's also a find-colors procedure.

> (find-colors "violet")
'("blue violet" "blueviolet" "darkviolet" "medium violet red" 
  "mediumvioletred" "palevioletred" "violet" "violet red" "violetred")

It returns an empty list when you give it something that's not a color name.

> (find-colors "ugly")
null

Extracting color components

Obviously, just seeing a color on the screen doesn't let you compute with it. Hence, there are procedures to extract the red, green, blue, and alpha components of any RGB color.

> (color-name->rgb "palevioletred")

> (rgb-red (color-name->rgb "palevioletred"))
219
> (rgb-green (color-name->rgb "palevioletred"))
112
> (rgb-blue (color-name->rgb "palevioletred"))
147
> (rgb-alpha (color-name->rgb "palevioletred"))
255

[Design detour] Computing with color: Complementary colors

In creating works, many artists and visual designers consider the applications of complementary colors. A pair of colors is complementary if the sum of the two colors is a kind of grey (including black or white). What does it mean to sum two colors? Well, it turns out that complementarity is really defined only for a different representation of colors (hue, saturation, and value, or HSV). Nonetheless, we can come close to simulating it in RGB, so we will call complementary colors defined using their RGB values pseudo-complementary colors.

In RGB, we can add the colors by adding the corresponding components (capping the sum at 255) or by averaging the corresponding components. We'll use the former technique, because it can be a bit easier to analyze capping.

For example, the pseudo-complement of green (0/255/0) is magenta (255/0/255) because when we add them together, we get 255/255/255, which is white.

> (rgb 0 255 0)

> (rgb 255 0 255)

Depending on what you accept as the definition of "grey", colors can have many pseudo-complements. For example, consider the color 128/0/0, which is similar to maroon. One logical pseudo-complement to that color is 127/255/255 (a color for which there is no name, but which seems to be similar to aquamarine), since when we add the two colors together, we get 255/255/255, which is still white. However, one might also consider 0/128/128 (a color similar to teal) as a pseudo-complement, since when we add the two together, we get 128/128/128, a nice medium grey.

> (rgb 128 0 0)

> (rgb 127 255 255)

> (rgb 128 0 0)

> (rgb 0 128 128)

> (rgb 128 128 128)

In general, when we say "pseudo-complementary color", we mean the one which, when we add the RGB components to those of the first color, we get white. When we ask for multiple pseudo-complements for the same color, we'll mean those that, when added, give us a color in which all three components are the same (that is, a version of grey).

Transforming colors

As the design detour suggests, we will often want to build new colors from prior colors. For example, given a color, we might want to complete the pseudo-complement of that color. Rather than doing it by hand, we can have the computer do the computation for us.

How? The algorithm should be fairly straightforward.

• The red component of the pseudo-complement of c is 255 minus the red component of `c.
• The green component of the pseudo-complement of c is 255 minus the green component of `c.
• The blue component of the pseudo-complement of c is 255 minus the blue component of `c.
• We can combine those three newly-computed complements with rgb.

;;; (color-pseudo-complement c) -> color?
;;;   c : color?
;;; Compute the pseudo-complement of a color
(define color-pseudo-complement
  (lambda (c)
    (rgb (- 255 (color-red c))
         (- 255 (color-green c))
         (- 255 (color-blue c)))))

Let's give it a try.

> (color-pseudo-complement (rgb 255 0 255))

> (rgb-red (color-pseudo-complement (rgb 255 0 255)))
0
> (rgb-green (color-pseudo-complement (rgb 255 0 255)))
255
> (rgb-blue (color-pseudo-complement (rgb 255 0 255)))
0

We can, of course, write color transformations that do a wide variety of things. For example, if we want to simulate the experience of people who cannot readily distinguish red and green, we can set both the red and green components to something closer to the average of the red and green components of the original. (This approach doesn't really give you the experience of red-green color-blind people, but it may give some sense.)

;;; (rgb-merge-red-green r) -> rgb
;;;   r : rgb?
;;; Make both the red and green components closer to the average of the
;;; two components.
(define rgb-merge-red-green
  (lambda (c)
    (rgb (quotient (+ (rgb-red c) (rgb-red c) (rgb-green c)) 3)
         (quotient (+ (rgb-red c) (rgb-green c) (rgb-green c)) 3)
         (rgb-blue c))))

Let's try it out.

> (rgb-merge-red-green (rgb 0 0 0))

> (rgb-merge-red-green (rgb 255 0 0))

> (rgb-merge-red-green (rgb 0 255 0))

> (rgb-name->rgb "violet")

> (rgb-merge-red-green (color-name->rgb "violet"))

It certainly did something. We probably need more context to see if it achieved our goals.

From color transformations to image transformations

One way to get more context is to use the color transformations on complete images. The procedure (pixel-map color-transformation image) does just that.

There are several ways to load an image with Scamper. One of them, with-image-file, allows to load an image file, e.g., a PNG or JPEG, from our local computer. (with-image-file fn) outputs a file chooser widget that we can use to select an image file. Once that file is selected, the argument fn is run with the image loaded from the file. fn is a one-argument function that takes an image (loaded from disk) as input and produces a potentially modified version of the input image as output.

For example, suppose we had an image of a kitten on disk:

We can invoke with-image-file and select that image to process it. If we want to simply output the original image to the screen, we can provide a lambda that simply returns the original image given to it as input:

(with-image-file
  (lambda (img) img))

This transformation function is relatively boring. Putting together what we learned in this reading, we can now compute the complement of every pixel in the image. (More about pixels in a subsequent reading.)

(with-image-file
  (lambda (img) (pixel-map color-pseudo-complement img)))

Sure, that looks a bit like a color negative, right? (Have you ever seen a color negative? Has the author of this piece dated themselves?)

How about our other procedure?

(with-image-file
  (lambda (img) (pixel-map color-merge-red-green img)))

Fewer differences there, but we do see something happening.

Self checks

Check 1: Components

What value do you expect for each of these expressions?

a. (rgb-red (rgb 200 100 50))

b. (rgb-green (rgb 200 100 50))

c. (rgb-blue (rgb 200 100 50))

d. Check your answers experimentally.

Check 2: Components, revisited (‡)

What value do you expect for each of these expressions? (Please guess about the components on a-f; it's fine if you are not quite right.)

a. (rgb-red (color-name->rgb "red"))

b. (rgb-green (color-name->rgb "red"))

c. (rgb-blue (color-name->rgb "red"))

d. (rgb-red (color-name->rgb "darksalmon"))

e. (rgb-green (color-name->rgb "darksalmon"))

f. (rgb-blue (color-name->rgb "darksalmon"))

g. Check your answers experimentally.

Check 3: Removing the blue component (‡)

Write a procedure, (remove-blue color), that takes a rgb color as a parameter and removes the blue component of the color, setting it to 0 in the new color.

> (remove-blue (color-name->rgb "white"))

> (remove-blue (color-name->rgb "blue"))

> (remove-blue (color-name->rgb "purple"))

> (remove-blue (rgb 255 0 255))

Acknowledgements

The kitten image was downloaded from http://public-photo.net/displayimage-2485.html. Unfortunately, the site behind that URL has disappeared. Nonetheless, the kitten image lives on.

RGB colors

In this lab, we explore techniques for building and transforming RGB colors.

Procedures to remember

Basic color procedures

• (rgb r g b) - create a new RGB color.
• (rgb-red c) - extract the red component of a rgb color.
• (rgb-green c) - extract the green component of a rgb color.
• (rgb-blue c) - extract the blue component of a rgb color.

Working with color names

• (all-color-names) - list all the color names.
• (color-name->rgb name) - convert a color name to an RGB color.
• (find-colors name) - find all the colors that include name.

Working with images

• (with-image-file func) - load an image from disk and call the given function it.
• (pixel-map color-transformation image)

The lab

• Use the file rgb-colors.scm
• You should also download a copy of the kitten image to your desktop. Other images work, too!

Acknowledgements

The kitten image was downloaded from http://public-photo.net/displayimage-2485.html. Unfortunately, the site behind that URL has disappeared. Nonetheless, the kitten image lives on.

Anonymous procedures

While lambda expressions are the most common way to write procedures, there are also a variety of others. We consider how to use composition and sectioning to build new procedures from old.

Introduction

You've learned the most common approach we will use to defining procedures. To define a procedure, you use a form like the following.

(define <identifier>
  (lambda (<arguments>
    <expression>)))

If we wanted to define a procedure, add, that adds two values, we might write something like the following.

(define add
  (lambda (x y)
    (+ x y)))

However, you've already seen another way to define a procedure. Instead of the lambda expression, you can use define to give another name to a procedure that already exists. For example,

(define add +)

How are these two definitions similar? Both use the define keyword to associate a name (add) with something that defines a procedure. In the first case, it's a lambda expression. In the second, it's an existing procedure. Perhaps that's not surprising. We can also define numeric values using expressions or constants.

(define x (+ 1 5))
(define x 6)

The Lisp family of languages (including Scheme) set themselves apart from many programming languages by permitting you to use a variety of kinds of expressions to define procedures. You've already seen two: lambda expressions and existing procedures. In this reading, we'll explore two more: composition and partial expressions. Just as an arithmetic operation, like +, creates a numeric value, the composition and partial-expression operations create a procedural value.

It may not be a surprise that these operations can create new procedures; after all, procedures like map and apply take procedures as parameters.

Building new procedures through composition

You may have already seen composition in your study of mathematics. The composition of two functions, \( f \) and \( g \), is written \( f \circ g \) and represents a function that first applies \( g \) and then \( f \). That is, \( (f \circ g)(x) = f(g(x)) \).

In scamper, we use the compose function to represent function composition. Let's start by composing a few procedures with themselves.

(square 3)

(define quad (compose square square))

(quad 3)

(define add1 (lambda (n) (+ n 1)))

(add1 3)

(define add2 (compose add1 add1))

(add2 3)

Scamper also provides a synonym function for compose, o (lower-case 'o'), that is slightly more evocative of the mathematical definition of composition. For example, we can rewrite the definition of quad above using o as follows:

(define quad (o square square))

As these examples suggest, both quad and add2 are procedures. We've created these procedures in a new way, without a lambda. The quad procedure squares its parameter and then squares it again (\( 3 \times 3 = 9 \), \( 9 \times 9 = 81 \)). The add2 procedure adds one to its parameter and then adds another one.

What happens if we compose two different procedures? Let's check.

(define add1
  (lambda (n) (+ n 1)))

(define f1 (o square add1))

(f1 4)

(define f2 (o add1 square))

(f2 4)

As these examples suggest, the composed procedure applies the other procedures from right to left. That is, f1 adds one to its parameter and then squares its result, and f2 squares is parameter and then adds 1. If we wanted to make it perfectly clear what we want each procedure to do, we could name them as follows.

(define add1
  (lambda (n) (+ n 1)))

(define add1-then-square (o square add1))

(add1-then-square 4)

(define square-then-add1 (o add1 square))

(square-then-add1 4)

You can also compose more than two procedures. For example, we might write the following silly procedure.

(define add1
  (lambda (n) (+ n 1)))

(define fun (o add1 square add1))

Composition can be quite useful. The other day, I realized that there was no string-reverse, even though I had assumed there was. But reversing a string is a straightforward operation: Convert to a list, reverse the list, convert back to a string. So I can just write,

(define string-reverse (o list->string reverse string->list))

(string-reverse "hello world!")

Pipelining

compose allows us to build chains of functions. This is useful when we want to define a new function or pass a function to a higher-order function such as map. However, if we wish to invoke the resulting function directly, we still need to call it.

((compose square square square) 2)

We might find this syntax somewhat unwieldy for two reasons:

• The right-to-left nature of composition is unintuitive.
• We are not used to seeing a function application in the "function" position of a call.

The pipe function |> (a pipe | followed by a greater-than symbol >) is useful when we need to chain function calls together, i.e., send the inputs of one function into the next, sequentially, and we only to do it once. For example, here is how we might express the triple square computation using pipe:

(|> 2 square square square)

Note that the argument to the function chain comes first and the functions of the chain come afterwards, each as an argument to |>. Implicit in this example is the fact that pipe processes its arguments in the left-to-right direction which is likely more intuitive to read. To unveil this, here is a use of pipe over two operations where the order matters:

(define add1
  (lambda (n) (+ n 1)))

(|> 11 add1 square)

(|> 11 square add1)

The former example computes \( (11+1)^2 \) whereas the second computes \( (11^2) + 1 \).

Sectioning

When writing computational pipelines and function compositions, we commonly find ourselves wanting to write functions that simply call other functions with some of the arguments filled in. For example, add1 above is an example of such a function where all add1 does it give one argument to the (+) function, 1, and leaves the other argument as a parameter. We say that we are partially applying the (+) function, providing only one of its arguments, leaving a one-argument function behind.

In standard Scheme syntax, to achieve this effect, we must write out a lambda expression that immediately invokes the desired function, filling in values for some of the arguments and passing through the parameters of the lambda for the remainder.

(define add1
  (lambda (n) (+ n 1)))

This occurs often enough that it is useful to have more concise syntax for writing these partial function applications. Scamper provides such a construct: the section expression. For example, we can define add1 with section as follows:

(define add1
  (section + _ 1))

Here, Scamper turns (section + _ 1) into (lambda (n) (+ n 1)) where n is a fresh variable name for the hole (_, the underscore character) in the section expression. Each hole in a section expression turns into a unique parameter in the resulting lambda that the section becomes.

As another example, we can use section to concisely write a pair of functions that prepends and appends an exclamation mark to a string:

(define prepend-bang
  (section string-append "!" _))

(define append-bang
  (section string-append _ "!"))

(prepend-bang "hello")

(append-bang "hello")

In general, a section expression (section e1 ... ek) turns into a lambda whose body is a function application (lambda (...) (e1 ... ek)). One parameter is added to the lambda for each underscore (_) found in the section's expressions.

Self checks

Check 1: Subtracting three (‡)

Give three ways to define a procedure, subtract3, that takes a number as input and subtracts 3 from that number.

• Using lambda.
• Using the composition operation, o, along with a function (sub1 n) that subtracts 1 from its argument n.
• Using |>.

Which of the three do you prefer? Why?

Check 2: Partial application (‡)

Recall the standard library function (make-list n v) creates a list containing n copies of v. Use make-list and section to concisely write a definition for a function (list-zeroes n) that creates a list of n zeroes.

Sound and Music

Vibrations in the Air

We'll start our discussion by considering the sound of a single clap. How is this sound produced, how is it transmitted to us, and how do we hear it?

• When we clap, we rapidly close our hands together.

• The resulting impact compresses some of the air trapped between the colliding skin, forcing it out and away.

• This creates an outward expanding wave of high pressure air (a sphere that increases in radius at the speed of sound).

• As that wave reaches our ears, it hits the eardrum and causes it to vibrate.

• Those vibrations move the series of bone and tissue of the inner ear.

• Which in turn vibrate the cochlea, a small spiral of bone covered with tiny hairs.

• The movement of those hairs activates neurons, and the resulting signals are interpreted by our brain as sound.

So we can think of sound very generally as a rapid change in air pressure, which will expand outward in spherical waves from its origin.

~Expanding Spherical Compression Wave

*Thierry Dugnolle, CC0, via Wikimedia Commons

But what about musical notes?

If the air pressure changes reaching our ear arrives at regular intervals over a sustained period of time, we hear a single, sustained tone. The specific tone we hear depends on the frequency of these pressure changes, which is typically measured as the number of high pressure peaks to reach our ear in a second.

For example, the note we call A4 (sometimes used as a reference tone for concert pitch) is created from vibrations at the frequency of 440 Hz (440 high pressure peaks per second). The following command produces this pitch in scamper:

(import music)
(note 69 qn)

Don't worry too much about what this command means yet, or where that 69 came from (it's a MIDI value). We still have a ways to go. We'll see the music library in lab.

To summarize so far: sound is the result of pressure changes, while musical tones come from sustained vibrations. These pressure changes/vibrations will travel through a medium as expanding waves.

It's interesting to stop and note that these pressure changes and vibrations don't have to travel through air alone (although those are the most common sounds we tend to hear). It is possible to hear even when submerged underwater. And stories of people putting their ears to the ground and hearing horses at great distances are actually plausible given the right type of terrain and/or enough horses. In both of these cases, the sounds are being transmitted as vibrations, but with water or rock as the medium.

This also explains why there's no sound in space: there's nothing to vibrate in a vacuum.

Acoustics

Musical notes are sustained vibrations in the air (typically). To produce music, we build instruments with parts that vibrate when we play them. Here are some examples of how musical vibrations are produced. For all of these examples, altering the sizes, shapes, and materials can result in dramatically different sounds and dramatically different instruments.

• Drums produce sound when the thin material stretched across their head vibrates as the result of being struck.

• When a (guitar, harp, kora, banjo, guqin, pipa, sitar, etc) string is plucked, it vibrates the entire body of the instrument to produce specific tones. Different length strings produce different notes.

• When a piano key is pressed, it causes a hammer to strike a group of strings in the interior. As the strings vibrate, they cause the whole instrument to vibrate (including other strings). Again, different length strings produce different notes.

• Drawing a bow across a string can cause the string to rapid vibrate, as with a violin, a cello, an erhu, and many other string instruments.

• Many woodwinds like clarinets produce music when the musician blows through the mouthpiece. The moving air vibrates a damp reed (thin piece of light wood), which causes the full body of the instrument to vibrate. Depressing valves on can open and close various holes, changing the airflow and shifting the frequency of the vibrations.

• Brass instruments like trumpets, trombones, and more generally solid-body horns, vibrate as the blown air passes through their body. Valves or sliders can again change the airflow and vibrations.

• Even the human voice produces song through vibrations! When you sing, your exhaled breath passes through your voice-box and causes it to vibrate. Meanwhile, whistling is the sound produced when quickly blown air vibrates your lips.

• Computers sound comes through their speakers, which often produce sound by vibrating a diaphragm, a circular stretched material commonly hidden behind a screen.

Pitch, Duration, Loudness, and Timbre

Now that we have an understanding of what musical sound is, let's start defining the various components of the perceived 'quality' of the sound. How can we distinguish different sounds from each other?

There are six qualities of sound often discussed, although we will mainly focus on the first four listed below.

• Pitch: the perceived note, how "high" or "low" it sounds. Controlled by the frequency of the vibrations, the number of pressure changes per second.

  

• Duration: how long the note is sustained, from when the first audible vibrations are produced to when it noticeably ceases or changes.

• Loudness: how loud or soft the note sounds. Depends on the magnitude of the pressure change: larger changes in pressure lead to louder volumes. The magnitude of the pressure is also called the amplitude of the sound wave, with large amplitudes waves being louder. Dynamics is often a term used to describe changing loudness in music. Note: loudness can also be described based on the listener's perception of loudness related to the number of nerves firing in the ear.

• Timbre: a measure of perceived quality of the sound that mostly depends on the "shape" of the sound wave, which is typically dependent on the objects producing the sound and the medium through which it is traveling. We will revisit timbre in the future, where we discuss synthesizing instrumentation ourselves!\

  

  *By Rburtonresearch - Own work, CC BY-SA 4.0,
  https://commons.wikimedia.org/w/index.php?curid=45074868

• Texture: the composition of multiple sounds into a single perceived moment of noise, whether harmonized into music or a dissonant cacophony of overlapping sounds.

• Location: the location of the source of the sound with respect to the listener's environment.

Each of these qualities are affected by different aspects of the sound wave like its frequency, amplitude, or shape. When we go to synthesize our own music, we will be able to control the actual waves our speakers generate. This will enable us to completely control all of these different qualities of the music we produce.

MIDI and Scamper

Further in the course, we will generate our own sounds. But for now, we are going to limit our interactions to the MIDI interface in the Scamper music library. The timbre of the MIDI music is mostly fixed (except for a few mods like the percussion mod), but the other sound qualities can be controlled through several functions or specified values.

The Pitch of a note is specified by the given MIDI value, which is an integer from 0 to 127. Each of these integers refers to a note in the classical western tradition. Some important note values are 60 (Middle-C, C4, 261.63 Hz) and 69 (A4, Concert Pitch, 440 Hz). The MIDI values from 21 to 108 are the keys on the classical piano.

The Duration of a note can be controlled with dur. We will explore this in much more detail in the future. For now, it is useful to know there are a number of specified values. Two important ones are qn denoting a quarter note (a standard 'beat'), and en denoting an eighth note (half of a standard 'beat').

The Loudness of a note can be controlled through the use of mod and dynamics functions. We'll see examples in lab.
The mod and percussion functions can be used to have notes represent specific percussive instruments.

Harmonics

In this reading, we are going to explore the concept of Pitch and further examine how changing the pitch of notes can alter the resulting music we produce.

Subdividing a String

First recall that we defined musical tones as vibrations in the air (typically), and that our reference note for concert pitch was A4, which vibrates with a frequency of 440 Hz (440 high pressure peaks per second). We are going to start with this pitch, and use a simple thought experiment to begin deriving other pitches!

Let's consider a specific example of producing this sound: plucking a string that vibrates at exactly 440 Hz:

(Credit: Juan M. Aguirregabiria author of Easy Java Simulation = Francisco Esquembre, CC BY-SA 3.0 https://creativecommons.org/licenses/by-sa/3.0, via Wikimedia Commons)

Now clearly this animation is not vibrating at 440 Hz (since that would be a bit too fast to easily see the motion), but it demonstrates the motion of the vibrating string.

We should note that this figure shows one possible way the string can vibrate when plucked. What is shown is the most natural mode of vibration, what we call the resonant frequency, where the full string sways back-and-forth together. But there are actually other modes of vibration. If we add a fixed point in the middle of the string, we can see that vibrations can form with a wave of half the wavelength (related to the distance between the fixed points) as the previous vibration. Halving the wavelength results in doubling the frequency of the produced pitch.

(Credit: Juan M. Aguirregabiria author of Easy Java Simulation = Francisco Esquembre, CC BY-SA 3.0 https://creativecommons.org/licenses/by-sa/3.0, via Wikimedia Commons)

But what is the affect of doubling the frequency on the pitch produced? What new tone have we developed?

If we start with A4 at 440 Hz, doubling the frequency gives us 880 Hz, which we label as A5. Here's the two played together:

(import music)

(seq (note 69 qn) (rest en)
     (note 81 qn) (rest en)
     (par (note 69 qn) (note 81 qn)))

Somehow, our brains recognize these as the same note, just one is higher up than the other! That's why we give them both the label A. We can keep doubling (or halving) to produce other As as well, they go from A0 at 27.5 Hz (the lowest note on the piano) to A7 at 3520 Hz (a little lower than the upper note on the piano, which is C8 at 4186.01 Hz).

Of course, you can continue going up or down in either direction, human hearing just has trouble keeping up. Each time we double or halve the frequency, we say we have moved up or down an octave: A5 is one octave above A4.

The Overtone Series

So we can halve the mode to go up an octave, but what if we try something like dividing our string into three vibrating sections (with 2 fixed points in the interior)? We get a brand new note as 3 times the frequency of the original note!

*Lookang many thanks to author of original simulation = Juan M. Aguirregabiria author of Easy Java Simulation = Francisco Esquembre, CC BY-SA 3.0 https://creativecommons.org/licenses/by-sa/3.0, via Wikimedia Commons

So what is this new note at 440*3=1320 Hz? It doesn't quite exist in modern western music. It turns out that some of the arithmetic gets weird when we keep going with our subdivisions of the string, and to deal with it, western music settled on a standard tuning that adjusts everything slightly to make the numbers mostly align.

Instead of exactly 3 times the original frequency for A4 (which should be 1320 Hz), we define E6 as 1318.51. It's pretty close at least! Let's listen to these notes together:

(import music)

(seq (note 69 qn) (rest en)
     (note 81 qn) (rest en)
     (note 88 qn) (rest en)
     (par (note 69 qn) (note 81 qn) (note 88 qn)))

They sound pretty good together, though that new note is definitely a distinct new pitch.

Here's an interesting question to ask: what if we take our new E6 and halve its frequency to get what we might call E5? This totally works, and gives us E5, a note with a adjusted frequency set at 659.26 Hz.

What is the relationship between this new E5 and the original A4? We tripled the frequency to get to E6, then halved it to get to E5, so we have a new frequency of 3/2 of the original frequency:

440 Hz * 3/2 = 660 Hz ~ 659.26 Hz (E5)

Let's hear these notes together:

(import music)

(seq (note 69 qn) (rest en)
     (note 76 qn) (rest en)
     (note 81 qn) (rest en)
     (note 88 qn) (rest en)
     (par (note 69 qn) (note 76 qn)) (rest en)
     (par (note 81 qn) (note 88 qn)))

But why stop at subdividing 3 times, what if we subdivide 4 times (~A6), or 5 times (~C#7), or more? This is called the overtone series!

*By Moodswingerscale.jpg: Y Landmanderivative work: W axell, Public domain, via Wikimedia Commons

The Western Chromatic Scale

If we continue this process of subdivision, and follow what the western musicians eventually settled on as a standard tuning, you end up with 12 roughly equally spaced notes in a single octave. Below is code that will play these notes for the octave between A4 and A5. This code plays the 12 notes and arrives back at the 13th (the repeated full octave). The names of the notes are provided as comments (some notes have two names, with # pronounced "sharp" and b pronounced "flat").

(import music)

(seq (note 69 qn) (rest en)  ; A4
     (note 70 qn) (rest en)  ; A#4 / Bb4
     (note 71 qn) (rest en)  ; B4
     (note 72 qn) (rest en)  ; C5
     (note 73 qn) (rest en)  ; C#5 / Db5
     (note 74 qn) (rest en)  ; D5
     (note 75 qn) (rest en)  ; D#5 / Eb5
     (note 76 qn) (rest en)  ; E5
     (note 77 qn) (rest en)  ; F5
     (note 78 qn) (rest en)  ; F#5 / Gb5
     (note 79 qn) (rest en)  ; G5
     (note 80 qn) (rest en)  ; G#5 / Ab5
     (note 81 qn) (rest en)) ; A5

This sequence is called "the chromatic scale."

Western music is commonly composed by first choosing certain specified subset of these possible chromatic notes and composing music while remaining mostly limited to those notes and the chords that they can produce. We call that type of subset of chromatic notes a 'scale.'

The most common scale in the western tradition is the Major Scale. Below is the subset of our chromatic notes in sequence which produce the A-Major Scale:

(import music)

(seq (note 69 qn) (rest en)  ; A4
     (note 71 qn) (rest en)  ; B4
     (note 73 qn) (rest en)  ; C#5 / Db5
     (note 74 qn) (rest en)  ; D5
     (note 76 qn) (rest en)  ; E5
     (note 78 qn) (rest en)  ; F#5 / Gb5
     (note 80 qn) (rest en)  ; G#5 / Ab5
     (note 81 qn) (rest en)) ; A5

We'll return to this discussion of scales in the future, and explore the western rules of selecting notes to form a scale. These rules are based on the relationship between the frequency of the notes selected. The notes picked for each scale are related to important overtones of the root note of the scale.

Of course, some non-western traditions will require a return to our previous discussion of frequencies and further subdividing of our vibrating string...

Lab: Scales and Chords

In today's lab, we'll look at the relationship between pitches by writing code that generates scales and chords. Additionally, we'll examine the section and compose/o operations in more detail.

• scales-and-chords.scm

and follow the instructions.

When you are done, make sure to save the file and then upload the completed lab to Gradescope.

Transforming RGB colors

We examine the building blocks of one of the common kinds of algorithms used for RGB colors: Generating new colors from existing colors.

Introduction

We have just started to learn about RGB colors, and so the operations we might do on images and colors are somewhat basic. How will we expand what we can do, and what we can write? In part, we will learn new Scheme techniques, applicable not just to image computation, but to any computation. In part, we will learn new functions in Scamper that support more complex image computations. In part, we will write our own more complex functions.

For now, we will focus on transforming color images. One common algorithmic approach to images is the construction of filters, algorithms that systematically convert one image to another image. Complex filters can do a wide variety of things to an image, from making it look like the work of an impressionist painter to making it look like the image has been painted onto a sphere. However, it is possible to write simple filters with not much more Scheme than you know already.

In readings and labs, we will consider filters that are constructed by transforming each color in an image using an algorithm that converts one RGB color to another. In this reading, as well as some followups, we will consider some basic approaches for transforming images, including some basic operations for transforming colors and ways to combine them into more complex transformations.

Some basic transformations

Rather than writing every transformation from scratch, we will start with a few basic transformations in the image library.

Making colors lighter and darker

The simplest transformations are rgb-darker and rgb-lighter. These operations make a color a little bit darker and a little bit lighter. If you apply them repeatedly, you can darker and darker (or lighter and lighter) colors, eventually reaching black (or white).

> (color-name->rgb "blueviolet")

> (rgb->string (color-name->rgb "blueviolet"))
"138/43/226"

> (rgb-darker (color-name->rgb "blueviolet"))

> (rgb->string (rgb-darker (color-name->rgb "blueviolet")))
"122/27/210"

> (rgb-darker (rgb-darker (color-name->rgb "blueviolet")))

> (rgb->string (rgb-darker (rgb-darker (color-name->rgb "blueviolet"))))
"106/11/194"

> (rgb-lighter (color-name->rgb "blueviolet"))

> (rgb->string (rgb-lighter (color-name->rgb "blueviolet")))
"154/59/242"

Note that these are pure procedures. When you compute a darker or lighter version of a color, the purpose is to create a new color. Hence, the original color is unchanged.

Transforming components

In addition to making the color uniformly darker or lighter, we can also increase individual components using rgb-redder, rgb-greener, and rgb-bluer.

> (color-name->rgb "blueviolet")

> (rgb->string (color-name->rgb "blueviolet"))
"138/43/226"

> (rgb-redder (color-name->rgb "blueviolet"))

> (rgb-greener (color-name->rgb "blueviolet"))

> (rgb-bluer (color-name->rgb "blueviolet"))

> (rgb->string (rgb-redder (color-name->rgb "blueviolet")))
"170/27/210"
> (rgb->string (rgb-greener (color-name->rgb "blueviolet")))
"122/75/210"
> (rgb->string (rgb-bluer (color-name->rgb "blueviolet")))
"122/27/255"

As the examples suggest, for some people, making a color slightly redder, greener, or bluer is hard to detect. Sometimes it's easier to see the changes if we make the transformations a few times. (Since the first call to rgb-bluer increases the blue component to its largest value, we may not see further increases.)

> (rgb-redder (rgb-redder (color-name->rgb "blueviolet")))

> (rgb-greener (rgb-greener (color-name->rgb "blueviolet")))

> (rgb-bluer (rgb-bluer (color-name->rgb "blueviolet")))

> (rgb->string (rgb-redder (rgb-redder (color-name->rgb "blueviolet"))))
"202/11/194"
> (rgb->string (rgb-greener (rgb-greener (color-name->rgb "blueviolet"))))
"106/107/194"
> (rgb->string (rgb-bluer (rgb-bluer (color-name->rgb "blueviolet"))))
"106/11/255"

Other simple transformations

The rgb-rotate procedure rotates the red, green, and blue components of a color, setting red to green, green to blue, and blue to red. It is intended mostly for fun, but it can also help us think about the use of these components.

> (color-name->rgb "blueviolet")

> (rgb->string (color-name->rgb "blueviolet"))
"138/43/226"

> (rgb-rotate-components (color-name->rgb "blueviolet"))

> (rgb->string (rgb-rotate-components (color-name->rgb "blueviolet")))
"43/226/138"

> (rgb-rotate-components (rgb-rotate-components (color-name->rgb "blueviolet")))

> (rgb->string (rgb-rotate-components (rgb-rotate-components (color-name->rgb "blueviolet"))))
"226/138/43"

The rgb-phaseshift procedure is another procedure with less clear uses. It adds 128 to each component with a value less than 128 and subtracts 128 from each component with a value of 128 or more. While this is somewhat like the computation of a pseudo-complement, it also differs in some ways. Hence, the image library also provides a rgb-pseudo-complement procedure that computes the pseudo-complement of an RGB color.

> (color-name->rgb "blueviolet")

> (rgb->string (color-name->rgb "blueviolet"))
"138/43/226"

> (rgb-phaseshift (color-name->rgb "blueviolet"))

> (rgb->string (rgb-phaseshift (color-name->rgb "blueviolet")))
"10/171/98"

> (rgb-pseudo-complement (color-name->rgb "blueviolet"))

> (rgb->string (rgb-pseudo-complement (color-name->rgb "blueviolet")))
"117/212/29"

Writing your own color transformations

At the beginning of this reading, you learned a few basic procedures for transforming colors. Are these the only ways that you can transform colors? Certainly not! You are free to write your own color transformations. For example, you might decide that rgb-greener should use a more complicated formula for making colors greener, scaling multiplicatively rather than additively.

(define greener
  (lambda (c)
    (rgb (* 9/10 (rgb-red c))
         (+ 8 (* 11/10 (rgb-green c)))
         (* 9/10 (rgb-blue c))
         (rgb-alpha c))))

Let's see how well that works.

> (color-name->rgb "blueviolet")

> (greener (color-name->rgb "blueviolet"))

> (greener (greener (color-name->rgb "blueviolet")))

> (greener (greener (greener (color-name->rgb "blueviolet"))))

> (greener (greener (greener (greener (color-name->rgb "blueviolet")))))

> (greener (greener (greener (greener (greener (color-name->rgb "blueviolet"))))))

> (rgb->string (color-name->rgb "blueviolet"))
"138/43/226"
> (rgb->string (greener (color-name->rgb "blueviolet")))
"124/55/203"
> (rgb->string (greener (greener (color-name->rgb "blueviolet"))))
"112/68/183"
> (rgb->string (greener (greener (greener (color-name->rgb "blueviolet")))))
"101/83/165"
> (rgb->string (greener (greener (greener (greener (color-name->rgb "blueviolet"))))))
"91/99/148"

Of course, this is not the only way to define a procedure like greener. We could also define it in terms of the existing procedures. For example, since rgb-greener seems to increment the green component by 32 and rgb-darker seems to decrement all three components by 16, we could try something like

(define greener2
  (lambda (c)
    (rgb-greener (rgb-greener (rgb-darker (rgb-darker c))))))

> (color-name->rgb "blueviolet")

> (rgb->string (color-name->rgb "blueviolet"))
"138/43/226"

> (greener2 (color-name->rgb "blueviolet"))

> (rgb->string (greener2 (color-name->rgb "blueviolet")))
"74/75/162"

There are also color transformations you cannot build (at least not easily) from the basic transformation. For example, suppose you want to eliminate extreme colors. You might choose to bound each component so that it is at least 64 and no more than 192.

;;; (bound val lower upper) -> number?
;;;   val : number?
;;;   lower : number?
;;;   upper : number?
;;; "Bounds" `val`, ensuring that the result is `lower` if `val` is
;;; less than `lower` and `upper` if `val` is greater than `upper`.
(define bound
  (lambda (val lower upper)
    (max lower (min upper val))))

;;; (bound-component component) -> integer?
;;;   component : integer?
;;; Bounds a component to a value between 64 and 192.
(define bound-component
  (lambda (component)
    (bound component 64 192)))

;;; (rgb-bound c) -> rgb?
;;;   c : rgb?
;;; Bound all of the components of `c`.
(define rgb-bound
  (lambda (c)
    (rgb (bound-component (rgb-red c))
         (bound-component (rgb-green c))
         (bound-component (rgb-blue c))
         (rgb-alpha c))))

Let's try it out.

> (color-name->rgb "blueviolet")

> (rgb->string (color-name->rgb "blueviolet"))
"138/43/226"

> (rgb-bound (color-name->rgb "blueviolet"))

> (rgb->string (rgb-bound (color-name->rgb "blueviolet")))
"138/64/192"

> (color-name->rgb "black")

> (rgb->string (color-name->rgb "black"))
"0/0/0"

> (rgb-bound (color-name->rgb "black"))

> (rgb->string (rgb-bound (color-name->rgb "black")))
"64/64/64"

> (color-name->rgb "whitesmoke")

> (rgb->string (color-name->rgb "whitesmoke"))
"245/245/245"

> (rgb-bound (color-name->rgb "whitesmoke"))

> (rgb->string (rgb-bound (color-name->rgb "whitesmoke")))
"192/192/192"

Self checks

Check 1: Repeated transformations

We've seen that applying rgb-darker multiple times makes a color much darker. What do you expect to happen if we apply each of the following two times?

• rgb-bound
• rgb-pseudo-complement
• rgb-phaseshift

Check 2: Inverse transformations (‡)

rgb-lighter and rgb-darker seem to be inverses of each other. That is, if we make a color darker and then lighter, we seem to end up with the same color.

> (rgb-darker (rgb-lighter (rgb 100 100 100)))

> (rgb->string (rgb-darker (rgb-lighter (rgb 100 100 100))))
"100/100/100"

Are there any colors for which (rgb-darker (rgb-lighter c)) gives a different color?

Check 3: Writing new transformations

Write a procedure, (rgb-grey c), that takes an RGB color as input and produces a greyscale color, one in which the red, green, and blue components are the same (and equal to the average of the components in c).

Transforming images

We explore how to expand the power of color transformations, first by applying them to images rather than to individual colors then by further combining them into new transformations.

From transforming colors to transforming images

You may have been asking why we have been focusing on transforming individual colors, other than that using the transformations helps us better understand the underlying representation. Here's one reason: Many image filters are written by applying a transformation to each color in the image.

So, how do we write image filters? That is, how do we generalize color transformations to image filters? The csc151 library includes a helpful procedure, (pixel-map colortrans image), that builds a new image by setting the color at each position in the new image to the result of applying the given color transformation to the color at the corresponding position in the original image.

Using pixel-map and the color transformations we learned in the previous reading, we can now transform images in a few basic ways: we can lighten images, darken images, complement images (and perhaps even compliment the resulting images), and so on and so forth.

Let's consider a few examples. We'll start with this public domain image of a kitten, which we will refer to as kitten.

This image can be loaded via the with-image-from-url function. (with-image-from-url url fn) takes two arguments:

• The uniform resource locator, i.e., URL, of an image. URLs are used to specify the location of a file on the internet.
• A callback function fn that takes the image Scamper loads from the URL as input. The output of fn is then rendered to the output pane.

The URL of the kitten image is:

• https://scamper.cs.grinnell.edu/images/kitten.jpg

(Note: For security reasons related to running within a web browser, Scamper currently cannot load images not found on scamper.cs.grinnell.edu!)

For example, here are two uses of the function. The first use simply outputs the image unmodified. The second applies a transformation via pixel-map.

(with-image-from-url "https://scamper.cs.grinnell.edu/images/kitten.jpg"
  (lambda (img)
    img))

(with-image-from-url "https://scamper.cs.grinnell.edu/images/kitten.jpg"
  (lambda (img)
    (pixel-map rgb-redder img)))

Composing transformations

But what if we want more interesting filters, ones that can't be described with just a single built-in transformation? One thing that we can do is to combine transformations. There are two ways to transform an image using more than one transformation: You can do each transformation in sequence, or you can use function composition, an old mathematical trick that you learned how to do in Scheme in the last reading. Consider, for example, the problem of lightening an image and then increasing the red component. We can certainly write the following sequence of definitions.

> (define intermediate-picture (pixel-map rgb-redder picture))
> (define modified-picture (pixel-map rgb-darker intermediate-picture))

However, it is not necessary to name the intermediate image. We can instead choose to nest the calls to pixel-map, using something like this definition.

> (define modified-picture (pixel-map rgb-darker (pixel-map rgb-redder picture)))

However, even this more concise instruction still creates the intermediate (redder but not lighter) version of the picture. Can we make each color in the image both redder and lighter?

In a recent reading, we learned that we can define a new transformation by combining other transformations with the composition function, compose (or its shorthand, o). Using that function, we can write the following instructions.

> (define rgb-fun (o rgb-lighter rgb-redder))
> (define modified-picture (pixel-map rgb-fun picture))

But even that is a bit verbose. Do we really want to name rgb-fun when we only use it once? No. Fortunately, Scheme lets us use the function created by compose without naming it, just as it lets us use most expressions without naming them.

> (define modified-picture (pixel-map (o rgb-darker rgb-redder) picture))

Let's try this on our kitten.

(with-image-from-url "https://scamper.cs.grinnell.edu/images/kitten.jpg"
  (lambda (img)
    (pixel-map (o rgb-darker rgb-redder) kitten)))

What's the difference between this instruction and the nested calls to pixel-map? In effect, we've changed the way you sequence operations. That is, rather than having to write multiple instructions, in sequence, to get something done, we can instead insert information about the sequencing into a single instruction. By using composition, along with nesting, we can then express our algorithms more concisely and often more clearly. It is also likely to be a bit more efficient, since we make one new image, rather than two.

Detour: Saving images

It's useful to be able to load images so that we can manipulate them. It's even more useful to be able to save images that we've created. Luckily, since Scamper operates in the browser, the images we see in the output are genuine images that we simply download! To download an image that you create, right-click on the image and select "Save image as..." (or the equivalent in your browser).

Mapping binary color procedures with section

So far, so good. We know how to load images with image-load. We know how to make new versions of existing images using pixel-map. We know how to save the result using image-save. Are we missing anything?

It turns out that we're missing a few things. Right now, the only way we can make a variant of an image is using one of the unary (single-parameter) procedures, either the built-in procedures, such as rgb-redder, or ones we create with the composition operator, compose. But we know other procedures transforming colors, such as rgb-subtract or rgb-average, that are not unary. (In case you haven't encountered these procedures, you can find them at the end of the reading.) How do we use such procedures?

It doesn't make sense to write (rgb-subtract pic (rgb 0 0 255)), since picture is not an RGB color. Hopefully, we'll get an error message if we try.

> (with-image-from-url "https://scamper.cs.grinnell.edu/images/kitten.jpg"
  (lambda (img)
    (rgb-subtract img (rgb 0 0 255))))
Runtime error [10:5-10:36]: (rgb-subtract) expected an RGB value, received object

It also doesn't make sense to use rgb-subtract as the first parameter to pixel-map, as in (pixel-map rgb-subtract pic), because we don't have a place to specify the color we are subtracting. Once again, Scamper should issue an error message.

> (with-image-from-url "https://scamper.cs.grinnell.edu/images/kitten.jpg"
  (lambda (img)
    (pixel-map rgb-subtract img))
Runtime error [8:5-8:32]: (pixel-map) wrong number of arguments to rgb-subtract provided. Expected 2, received 1.

Not the most helpful error message, but an error message nonetheless.

We might be tempted to write something like (pixel-map pic (rgb-subtract (rgb 0 0 255)). However, that will also cause problems, since it looks like we are calling rgb-subtract on a single value, and not the two values it is supposed to take.

> (with-image-from-url "https://scamper.cs.grinnell.edu/images/kitten.jpg"
  (lambda (img)
    (pixel-map (rgb-subtract (rgb 0 0 255)) img)))
Runtime error [8:16-8:43]: (rgb-subtract) wrong number of arguments to rgb-subtract provided. Expected 2, received 1.

It's probably good that we get an error message here, since it's not clear whether (rgb 0 0 255) is supposed to be the first or second parameter to rgb-subtract---are we subtracting (rgb 0 0 255) from each color, or are we subtracting each color from (rgb 0 0 255)?

To handle situations like this, scamper includes a special form, section, that lets you fill in some parameters to a function. It takes the form (section procedure arg1 arg2 ...)). In other words the syntax is like a function call (procedure arg1 arg2 ...) except with section at the front!

When we want to fill in a particular parameter, we write the value we want. When we want to leave a parameter blank, we write the special symbol _. For example, here's a function that subtracts the blue component from every color.

(define rgb-subtract-blue (section rgb-subtract _ (rgb 0 0 255)))

(with-image-from-url "https://scamper.cs.grinnell.edu/images/kitten.jpg"
  (lambda (img)
    (pixel-map rgb-subtract-blue img)))

If, instead, we want to subtract the current color from white (which is how we computed the pseudo-complement), we can swap the place that we put the special symbol.

(define rgb-subtract-from-white (section rgb-subtract (rgb 255 255 255) _))

(with-image-from-url "https://scamper.cs.grinnell.edu/images/kitten.jpg"
  (lambda (img)
    (pixel-map rgb-subtract-from-white img)))

As in the case of unary functions created with compose, we don't have to name the function we create. Here's an instruction that will make a somewhat bluer version of the kitten.

(with-image-from-url "https://scamper.cs.grinnell.edu/images/kitten.jpg"
  (lambda (img)
    (pixel-map (section rgb-average (rgb 0 0 255) _)
               img)))

Self checks

Check 1: Fade to grey

a. Without using a lambda, write a procedure, (average-with-grey c), that everages c with (rgb 127 127 127).

b. What do you expect to happen if you transform the image with average-with-grey?

c. Check your answer experimentally.

d. What do you expect to happen if you twice transform the image with average-with-grey?

e. Check your answer experimentally.

Binary RGB procedures

Here are the binary RGB procedures mentioned above in the discussion of cutting.

;;; (rgb-subtract c1 c2) -> rgb?
;;;   c1 : rgb?
;;;   c2 : rgb?
;;; Create a new RGB color by subtracting each component of `c2` from
;;; the corresponding component of `c1`.
(define rgb-subtract
  (lambda (c1 c2)
    (rgb (- (rgb-red c1) (rgb-red c2))
         (- (rgb-green c1) (rgb-green c2))
         (- (rgb-blue c1) (rgb-blue c2))
         (rgb-alpha c1))))

;;; (rgb-average c1 c2) -> rgb?
;;;   c1 : rgb?
;;;   c2 : rgb?
;;; Create a new RGB color by averaging the corresponding components of
;;; c1 and c2.
(define rgb-average
  (lambda (c1 c2)
    (rgb (* 1/2 (+ (rgb-red c1) (rgb-red c2)))
         (* 1/2 (+ (rgb-green c1) (rgb-green c2)))
         (* 1/2 (+ (rgb-blue c1) (rgb-blue c2)))
         (* 1/2 (+ (rgb-alpha c1) (rgb-alpha c2))))))

Transforming images

We explore techniques for transforming images, focusing on the use of anonymous procedures.

Procedures to remember

Basic color procedures

• (rgb r g b) - create a new RGB color.
• (rgb r g b a) - create a new RGB color, also specifying the alpha channel.
• (rgb-red c) - extract the red component of an rgb color.
• (rgb-green c) - extract the green component of an rgb color.
• (rgb-blue c) - extract the blue component of an rgb color.

Transforming colors

• (rgb-darker c) - create a darker version of c (if possible).
• (rgb-ligheter c) - create a lighter version of c (if possible).
• (rgb-redder c) - create a redder version of c (if possible).
• (rgb-greener c) - create a greener version of c (if possible).
• (rgb-bluer c) - create a bluer version of c (if possible).
• (rgb-pseudo-complement c) - get the pseudo-complement of c.
• (rgb-complement c) - get the HSV complement of c.
• (rgb-greyscale c) - convert c to greysacle.
• (rgb-phaseshift c) - phase shift each component of c by 128, adding 128 to values less than 128 and subtracting 128 from values greater than or equal to 128.
• (rgb-rotate-components c) - rotate the RGB components of c.

Combining colors

• (rgb-add c1 c2) - Add the components of two RGB colors.
• (rgb-subtract c1 c2) - Subtract corresponding components of c2 from c1.
• (rgb-average c1 c2) - Average the components in c1 and c2.

Working with color names

• (all-color-names) - list all the color names.
• (color-name->rgb name) - convert a color name to an RGB color.
• (find-colors name) - find all the colors that include name.

Working with images

• (with-image-file fn) - loads an image, calling fn with the image as input.
• (with-image-from-url url fn) - loads an image from url, calling fn on the image as input.
• (pixel-map color-transformation image) - apply a color transformation to each pixel in an image.
• `(image-save img filename) - save an image to a file.

Working with procedures

• (section (expression-with-underscores)) - Build a new procedure that takes one parameter for each underscore in expression-with-underscores.
• (o fun1 fun2 fun3 ... funk) - Build a new procedure that applies funk then ... then fun3 then fun2 then fun1 to its parameter.

The lab

• Use the file transforming-images.scm.
• Find an image you like, such as your campus directory picture (or President Harris' directory picture, or your instructor's directory picture) and save it to your desktop.

Acknowledgements

The kitten image was downloaded from http://public-photo.net/displayimage-2485.html. Unfortunately, the site behind that URL has disappeared. Nonetheless, the kitten image lives on.

This lab was originally written in 2024Sp, based on a lab from 2017Sp.

Naming values with local bindings

Algorithm designers regularly find it useful to name the values their algorithms process. We consider why and how to name new values that are only available within a procedure.

Introduction

When writing programs and algorithms, it is useful to name values we compute along the way. For example, in an algorithm that, given a list of numbers, sorts that list of numbers, it may be useful to name the sorted list along the way. When we associate a name with a value, we say that we bind that name to the value.

So far we've seen three ways in which names are bound to values in Scheme.

• The names of built-in procedures, such as + and quotient, are predefined. There are also some predefined values, such as pi. When the Scheme interpreter starts up, these names are already bound to the procedures they denote.
• The programmer can introduce a new binding by means of a definition. A definition may introduce a new equivalent for an old name, or it may give a name to a newly computed value.
• When a programmer-defined procedure is called, the parameters of the procedure are bound to the values of the corresponding arguments in the procedure call. Unlike the other two kinds of bindings, parameter bindings are local -- they apply only within the body of the procedure. Scheme discards these bindings when it leaves the procedure and returns to the point at which the procedure was called.

As you develop more and longer procedures, you will find that there are many times you want to create local names for values that are not parameters. We will consider such names in this reading.

Redundant work

You will find that there are many times when you are designing algorithms that you end up telling the computer to do the same thing again and again and again. For example, here's a bit of code that determines the ratio of vowels to consonants and let's see how well it works.

;;; (tally f l) -> number?
;;;   f : function?, a predicate over elements of l
;;;   l : list?
;;; Returns the number of occurrences that f returns
;;; #t for each element of the list.
(define tally
  (lambda (f l)
    (if (null? l)
        0
        (+ (if (f (car l))
               1
               0)
           (tally f (cdr l))))))

;;; (vowel? ch) -> boolean?
;;;   ch : char?
;;; Determine whether ch is a vowel.
(define vowel?
  (lambda (ch)
    (or (char=? (char-downcase ch) #\a)
        (char=? (char-downcase ch) #\e)
        (char=? (char-downcase ch) #\i)
        (char=? (char-downcase ch) #\o)
        (char=? (char-downcase ch) #\u))))

;;; (consonant? ch) -> boolean?
;;;   ch : char
;;; Determine if ch is a consonant
(define consonant?
  (lambda (ch)
    (and (char-alphabetic? ch) (not (vowel? ch)))))

;;; (v2c-ratio str) -> rational?
;;;   str : string
;;; Determine the ratio of vowels to consonants in str
(define v2c-ratio
  (lambda (str)
    (/ (tally vowel? (string->list str))
       (tally consonant? (string->list str)))))

(v2c-ratio "Hello")
(v2c-ratio "Aaargh!")
(v2c-ratio "aeiouxy")
; Whoops!
(v2c-ratio "a")  

'Eh. It's good enough for now.

But there's a problem with the design. We're repeating some work.

Please identify some points at which we repeat work.

We mean it.

That is, stop here and ask yourself, "Where does the code duplicate work?"

Are you done?

Are you sick of these pauses? If more students paused when we asked questions, we wouldn't have to insert these kinds of notes.

Anyway, work is being repeated in at least three ways.

• First, we call (char-downcase ch) as many as five times. It feels like we should be able to do it once.
• Second, we call (string->list str) twice. It feels like we should be able to do it once. This may even have a bigger effect than the five calls to char-downcase because building lists can be "expensive".
• Third, we ask if many letters are a vowel twice, once when counting the vowels and once when counting the consonants.

That last problem is going to be hard to deal with, particularly as we try to keep our code readable. So let's focus on the first two. Can we avoid calling (char-downcase ch) so many times?

Yes, you can fill in the annoying delay now.

Here's one approach: We can decompose the task into two tasks. We'll write one procedure that determines if a character is a lowercase vowel.

;;; (lower-case-vowel? ch) -> boolean?
;;;   ch : char?
;;; Determine whether ch is a lowercase vowel.
(define lower-case-vowel?
  (lambda (ch)
    (or (char=? ch #\a)
        (char=? ch #\e)
        (char=? ch #\i)
        (char=? ch #\o)
        (char=? ch #\u))))

That seems straightforward enough, doesn't it? Our vowel? procedure can then call that other procedure using a letter converted to lowercase.

;;; (vowel? ch) -> boolean?
;;;   ch : char?
;;; Determine whether ch is a vowel.
(define vowel?
  (lambda (ch)
    (lower-case-vowel? (char-downcase ch))))

About as easy to read as before. A little more typing on our part. And we've saved some computation. In fact, this kind of decomposition is a strategy programmers use fairly frequently: Rewrite procedures that do a sequence of steps by using one procedure for each step.

In fact, now that we've phrased it as a sequence of steps, we can take advantage of composition.

;;; (vowel? ch) -> boolean?
;;;   ch : char?
;;; Determine whether ch is a vowel.
(define vowel? (o lower-case-vowel? char-downcase))

Detour: Why are we repeating the documentation each time we show you a new imlementation of the vowel? predicate? Mostly to remind you that there's a value to writing documentation, even when our procedures are short and simple.

Will anyone ever use lower-case-vowel? by itself? Possibly. But if not, we should try something else. Is there something else?

Racket's let Expressions

There is. Racket provides let expressions as a way to bind values to names. A let-expression contains a binding list and a body. The body can be any expression, or any sequence of expressions, to be evaluated with the help of the local name bindings. The binding list takes the form of a parentheses enclosing zero or more binding expressions of the form (name value).

That precise definition may have been a bit confusing, so here's the general form of a let expression

(let ([name1 exp1]
      [name2 exp2]
      ...
      [namen expn])
     body

As shorthand, we call each of the name-expression pairs of a let-expression a binder.

When the Racket evaluator encounters a let-expression, it begins by evaluating all of the expressions inside its binding specifications. Then the names in the binding specifications are bound to those values. Next, the expressions making up the body of the let-expression are evaluated, in order. The value of the last expression in the body becomes the value of the entire let-expression. Finally, the local bindings of the names are cancelled. (Names that were unbound before the let-expression become unbound again; names that had different bindings before the let-expression resume those earlier bindings.)

What do we mean by "bound"? As you may recall, the Racket evaluator maintains a table of names and corresponding values. We call that association a "binding". When the evaluator encounters a name, it looks up the binding in the table.

Here's one way to write vowel? with let and without helpers.

;;; (vowel? ch) -> boolean?
;;;   ch : char?
;;; Determine whether ch is a vowel.
(define vowel?
  (lambda (ch)
    (let ([lc (char-downcase ch)])
      (or (char=? lc #\a)
          (char=? lc #\e)
          (char=? lc #\i)
          (char=? lc #\o)
          (char=? lc #\u)))))

Important! Note that even though binding lists and binding specifications start with parentheses, they are not procedure calls; their role in a let-expression simply to give names to certain values while the body of the expression is being evaluated. The outer parentheses in a binding list are structural -- they are there to group the pieces of the binding list together.

As we've seen, using a let-expression often simplifies an expression that contains two or more occurrences of the same subexpression. The programmer can compute the value of the subexpression just once, bind a name to it, and then use that name whenever the value is needed again. Sometimes this speeds things up by avoiding such redundancies as the recomputation of values. In other cases, there is little difference in speed, but the code may be a little clearer.

Comparing let and define

You may have missed it, but there are a few subtle and important issues with the use of let rather than define to name values and procedures. One difference has to do with the availability (or scope) of the name. Values named by define are available essentially everywhere in your program. In contrast, values named by let are available only within the let expression. (In case you were wondering, the term scope has nothing to do with the mouthwash.)

In addition, local variables (given by let) and global variables (given by our standard use of define) affect previous uses of the name differently (or at least appear to). When we do a new top-level define, we permanently replace the old value associated with the name. That value is no longer accessible. In contrast, when we use let to override the value associated with a name, as soon as the let binding is finished, the previous association is restored.

Finally, there's a benefit to using let instead of define according to the principle of information hiding. Evidence suggests that programs work better if the various pieces do not access values relevant primarily to the internal workings of other pieces. If you use define for your names, they are accessible (and therefore modifiable) everywhere. Hence, you enforce this separation by policy or obscurity. In contrast, if you use let to define your local names, these names are completely inaccessible to other pieces of code. We return to this issue in our discussion of the ordering of let and lambda below.

Our mental model of computation and let

Now that we've discussed how let works at a high-level, let's consider how let behaves precisely within the context of our mental model of computation. For example, consider the following expression:

(let ([x (+ 1 1)]
      [y (* 2 3)]
      [z (- 8 5)])
  (+ x y z))

We think about evaluating a let-expression in multiple stages.

1. First, we evaluate the expression of each binding of the let to values.
2. We then (a) substitute the resulting value for the binder's corresponding variable everywhere that variable occurs in the body of the let and (b) substitute the body of the let for the overall let-expression.
3. Finally, we continue evaluating the substituted let-body as normal.

Let's see how this works in our example above.

First, we must evaluate each of the binding expressions in turn:

    (let ([x (+ 1 1)]
          [y (* 2 3)]
          [z (- 8 5)])
         (+ x y z))
--> (let ([x 2]
          [y (* 2 3)]
          [z (- 8 5)])
         (+ x y z))
--> (let ([x 2]
          [y 6]
          [z (- 8 5)])
         (+ x y z))
--> (let ([x 2]
          [y 6]
          [z 3])
         (+ x y z))

Now, we must substitute values-of-bound-variables in the body of the let and then substitute the let-body itself. From the above expression, we will substitute 2 for x, 6 for y, and 3 for z everywhere in the expression (+ x y z). The resulting expression is what the entire let evaluates to. From there, we evaluate the expression normally to arrive at a final result.

--> (let ([x 2]
          [y 6]
          [z 3])
         (+ x y z))
--> (+ 2 6 3)
--> 11

Note that we only substitute for the variable as it appears in the body of the let. We do not substitute for the variable if it occurs outside of the body! For example, if we nest a let-binding in larger computation:

(+ (let ([x 1])
        (* x 5))
   (- x 1))

There are two occurrences of x here:

1. (* x 5): this is the body of the let so we will eventually substitute 1 for it.
2. (- x 1): this is the second argument to + and is outside the body of the let, so we do not substitute for it. Presumably, this x is bound by a different construct, e.g., a define.

Sequencing bindings with let*

Sometimes we may want to name a number of interrelated things. For example, suppose we wanted to square the average of a list of numbers. (It may not sound all that interesting, but it's something that people do sometimes). Since computing the average involves summing values, we may want to name three different things: the total (the sum of the values), the count (the number of values), the mean (the average of the values). We can nest one let-expression inside another to name both things.

(let ([total (reduce + values)]
      [count (length values)])
     (let ([mean (/ total count)])
          (* mean mean)))

One might be tempted to try to combine the binding lists for the nested let-expressions, thus:

; Combining the binding lists doesn't work!
(let ([total (reduce + values)]
      [count (length values)]
      [mean (/ total count)])
    (* mean mean))

This approach won't work. (Try it and see!). It's important to understand why not. The problem is as follows. Within one binding list, all of the expressions are evaluated before any of the names are bound. Specifically, Scheme will try to evaluate both (reduce + values) and (/ total count) before binding either of the names total and mean; since (/ total count) can't be computed until total and count have value, an error occurs.

The takeaway message is thus: You have to think of the local bindings coming into existence simultaneously rather than one at a time.

Because one often needs sequential rather than simultaneous binding, Scheme provides a variant of the let-expression that rearranges the order of events: If one writes let* rather than let, each binding specification in the binding list is completely processed before the next one is taken up:

; Using let* instead of let works!
(let* ([total (reduce + values)]
       [count (length values)]
       [mean (/ total count)])
      (* mean mean))

The star in the keyword let* has nothing to do with multiplication. Just think of it as an oddly shaped letter. It means do things in sequence, rather than all at once. While someone probably knows the reason to use * for that meaning, the authors of this text do not.

let* and our mental model

Our intuition is that let processes each of its bindings independently and in parallel. In contrast, let* processes each of its bindings sequentially so that later bindings can refer to earlier bindings. This is precisely how our corresponding mental model of let* works. In contrast to let:

1. First, we process the bindings in-order by:

   1. Evaluating the expression of the binding let* to a value.
   2. Substituting that value everywhere that binder occurs in each successive binding and the body of the let*.
   3. Peel off the processed binding, reducing the number of binders by one.

2. Once we are done processing all the binders, note that we should have substituted for all of variables bound by the let* (similarly to let). We then substitute the body of the let for the overall let*-expression.

3. Finally, we continue evaluating the substituted let-body as normal.

Here is a simple let* expression and how it evaluates step-by-step in this model:

    (let* ([x 5]
           [y (* x 2)]
           [z (+ x y)])
      (+ x y z))
--> (let* ([y (* 5 2)]
           [z (+ 5 y)])
      (+ 5 y z))
--> (let* ([y 10]
           [z (+ 5 y)])
      (+ 5 y z))
--> (let* ([z (+ 5 10)])
      (+ 5 10 z))
--> (let* ([z (+ 15)])
      (+ 5 10 z))
--> (+ 5 10 15))
--> 30

Positioning let relative to lambda

In the examples above, we've tended to do the naming within the body of the procedure. That is, we write:

(define proc
  (lambda (params)
    (let (...)
      exp)))

However, Scheme also lets us choose an alternate ordering. We can instead put the let before (i.e., outside of) the lambda.

(define proc
  (let (...)
    (lambda (params)
      exp)))

Why would we ever choose to do so? Let us consider an example. Suppose that we regularly need to convert years to seconds. (About a decade ago, Prof. Rebelsky said, "When you have sons between the ages of 5 and 12, you'll understand.") You might begin with

(define years-to-seconds
  (lambda (years)
    (* years 365.24 24 60 60)))

This produce does correctly compute the desired result. However, it is a bit hard to read. For clarity, you might want to name some of the values.

(define years-to-seconds
  (lambda (years)
    (let* ([days-per-year 365.24]
           [hours-per-day 24]
           [minutes-per-hour 60]
           [seconds-per-minute 60]
           [seconds-per-year (* days-per-year hours-per-day
                                minutes-per-hour seconds-per-minute)])
      (* years seconds-per-year))))

(display (years-to-seconds 10))

We have clarified the code, although we have also lengthened it a bit. However, as we noted before, a second goal of naming is to avoid re-computation of values. Unfortunately, even though the number of seconds per year never changes, we compute it every time that someone calls years-to-seconds. How can we avoid this re-computation? One strategy is to move the bindings to define statements.

(define days-per-year 365.24)
(define hours-per-day 24)
(define minutes-per-hour 60)
(define seconds-per-minute 60)
(define seconds-per-year 
  (* days-per-year hours-per-day minutes-per-hour seconds-per-minute))

(define years-to-seconds
  (lambda (years)
    (* years seconds-per-year)))

However, such a strategy is a bit dangerous. After all, there is nothing to prevent someone else from changing the values here.

(define days-per-year 360) ; Some strange calendar, perhaps in Indiana.
...
> (years-to-seconds 10)
311040000

What we'd like to do is to declare the values once, but keep them local to years-to-seconds. The strategy is to move the let outside the lambda.

(define years-to-seconds
  (let* ([days-per-year 365.24]
         [hours-per-day 24]
         [minutes-per-hour 60]
         [seconds-per-minute 60]
         [seconds-per-year (* days-per-year hours-per-day
                              minutes-per-hour seconds-per-minute)])
        (lambda (years)
          (* years seconds-per-year))))

(years-to-seconds 10)

As you will see in the lab, it is possible to empirically verify that the bindings occur only once in this case, and each time the procedure is called in the prior case.

One moral of this story is *whenever possible, move your bindings outside the lambda!. Let's return to the vowel? procedure we wrote above.

;;; (vowel? ch) -> boolean?
;;;   ch : char?
;;; Determine whether ch is a vowel.
(define vowel?
  (lambda (ch)
    (let ([lc (char-downcase ch)])
      (or (char=? lc #\a)
          (char=? lc #\e)
          (char=? lc #\i)
          (char=? lc #\o)
          (char=? lc #\u)))))

That code is still somewhat repetitious. After all, we're doing the same thing for each of the cases: comparing. For starters, we can use lists and their associated functions to reduce the clutter of the 5-way or call.

;;; (vowel? ch) -> boolean?
;;;   ch : char?
;;; Determine whether ch is a vowel.
(define vowel?
  (lambda (ch)
    (let ([lc (char-downcase ch)]
          [vowels (string->list "aeiou")])
      (apply (lambda (b1 b2) (or b1 b2))
             (map (section char=? lc _) vowels)))))

(vowel? #\t)
(vowel? #\e)
(vowel? #\0)

But that definition requires Scheme to build the list every time we call the vowel? procedure. It may not matter if we do that once, or twice, or even a hundred times. But when we're tallying a list of 42,000 elements, e.g., comparing vowels to consonants in The Wizard of Oz, that's a lot of extra work. Hence, we might more sensibly write the following.

;;; (vowel? ch) -> boolean?
;;;   ch : char?
;;; Determine whether ch is a vowel.
(define vowel?
  (let ([vowels (string->list "aeious")])
       (lambda (ch)
         (let ([lc (char-downcase ch)])
              (apply (lambda (b1 b2) (or b1 b2))
                (map (section char=? lc _) vowels))))))


(vowel? #\t)
(vowel? #\e)
(vowel? #\0)

Unfortunately, it is not always possible to move the bindings outside of the lambda. In particular, if your let-bindings use parameters, then you need to keep them within the body of the lambda.

;;; (vowel? ch) -> boolean?
;;;   ch : char?
;;; Determine whether ch is a vowel.
(define vowel?
  (let ([vowels (string->list "aeious")]
        [lc (char-downcase ch)])
       (lambda (ch)
         (apply (lambda (b1 b2) (or b1 b2))
                (map (section char=? lc _) vowels)))))

(vowel? #\t)
(vowel? #\e)
(vowel? #\0)

If you try to run this, it will complain that it doesn't know what ch is. (Or, worse yet, it will use some other ch that bears no relation to the input to the procedure).

Local procedures

As you may have noted, let behaves somewhat like define in that programmers can use it to name values. But we've used define to name more than values; we've also used it to name procedures. Can we also use let for procedures?

Yes, one can use a let- or let*-expression to create a local name for a procedure. And we name procedures locally for the same reason that we name values, because it speeds and clarifies the code.

(define hypotenuse-of-right-triangle
  (let ([square (lambda (n) (* n n))])
    (lambda (first-leg second-leg)
      (sqrt (+ (square first-leg) (square second-leg))))))

Regardless of whether square is also defined outside this definition (e.g., as a procedure that draws squares), the local binding gives it the appropriate meaning within the lambda-expression that describes what hypotenuse-of-right-triangle does.

Note, once again, that there are two places one might define square locally. We can define it before the lambda (as above) or after the lambda (as below). In the first case, the definition is done only once. In the second case, it is done every time the procedure is executed.

(define hypotenuse-of-right-triangle
  (lambda (first-leg second-leg)
    (let ([square (lambda (n) (* n n))])
      (sqrt (+ (square first-leg) (square second-leg))))))

So, which we should you do it? If the helper procedure you're defining uses any of the parameters of the main procedure, it needs to come after the lambda. Otherwise, it is generally a better idea to do it before the lambda. As you practice more with let, you'll find times that each choice is appropriate. It may be difficult at first, but it will become clearer as time goes on.

Self checks

Check 1: Exploring let (‡)

What are the values of the following let-expressions? You may use Scamper to help you answer these questions, but be sure you can explain how it arrived at its answers.

a.

(let ([tone "fa"]
      [call-me "al"])
  (string-append call-me tone "l" tone))

b.

(let ([total (+ 8 3 4 2 7)])
  (let ([mean (/ total 5)])
    (* mean mean)))

c.

(let* ([total (+ 8 3 4 2 7)]
       [mean (/ total 5)])
   (* mean mean))

d.

(let ([total (+ 8 3 4 2 7)]
      [mean (/ total 5)])
   (* mean mean))

e.

(let ([inches-per-foot 12.0]
      [feet-per-mile 5280])
  (let ([inches-per-mile (* inches-per-foot feet-per-mile)])
    (* inches-per-mile inches-per-mile)))

Check 2: Comparing let and let*

1. You may have discovered that Check 1b and Check 1c are equivalent. Which do you prefer? Why?

2. Rewrite Check 1e to use let*.

Check 3: Ratios, revisited (‡)

1. Rewrite v2c-ratio using a helper procedure to avoid the redundant call to string->list.

2. Rewrite v2c-ratio using let to avoid the redundant call to string->list.

Naming values with local bindings

In this laboratory, you will ground your understanding of the basic techniques for locally naming values and procedures in Scheme, let and let*.

For now (and perhaps for the foreseeable future), the person closest to the board is Side A. The other person is Side B.

Download the code from

• local-bindings.scm

And follow the instructions.

When you are done, make sure to save the file as text and then upload the completed lab to Gradescope.

Acknowledgements

The first question of this lab is adapted from a similar lab from spring 2018.

Pair Programming

Today, we'll take a break from technical topic to focus on collaborative work. Why do we emphasize pair programming in this course? How can we be effective partners in problem-solving?

Our class on Wednesday will feature a group discussion about pair programming where we will share our experiences with the practice in the course and how we might be better partners for the remainder of the semester. In preparation for our group discussion, please read these two articles on pair programming and collaborative work:

• "How Pair Programming Really Works," Stuart Wray
• "Diverse Teams Feels Less Comfortable — and That's Why They Perform Better," Rock, Grant, and Grey

Self-check

Reading Reflection (‡)

Please complete the reading reflection questions and pair programming survey found on Gradescope!

Take-home Assessment #4: Arpeggiator

(Note: this assignment is due on Thursday October 10th instead of our usual Monday deadline.)

In the previous take-home assessment, you built a beat machine, a way to use computers to assist in the process of building rhythmic patterns. Can we use computer technology to similarly build up melodic patterns? In this assessment, we'll build a software-based arpeggiator that does exactly that, practicing our list transformation techniques along the way!

For this take-home assessment, please write your code in the provided starter file:

• arpeggiator.scm

And turn in your code when you are done!

About arpeggiators

An arpeggio is when the notes of a chord are played sequentially rather than simultaneously. You've likely heard arpeggios whenever you listed to guitar-based music:

• "Arpeggio" by Ichika Nito

Sweeping arpeggios of the sort highlighted in the video take immense amount of skill to develop and execute in a live context. However, most modern keyboards now feature the ability to generate these arpeggios by simply holding down the relevant notes on the keyboard. Additionally, with these devices you can customize the arpeggio to play the notes of the chord in different orders, rhythms, and speeds!

To learn more about arpeggiators, check out this introductory video from Sweetwater:

• What Is an Arpeggiator? – Daniel Fisher

In Scamper, we can achieve this effect relatively easily using seq to create a sequential pattern and then repeat to repeat that pattern as desired:

(import music)

(define arp-example
  (seq (note 58 sn)
       (note 61 sn)
       (note 65 sn)
       (note 68 sn)))

(display arp-example)

(repeat 10 arp-example)

In this assessment, we'll build up a library of functions that allow us to put together patterns of arpeggiated chords in a composable manner, ala functional programming!

Reminder about code style and testing

Now that we introduced the style guidelines for the course, we expect you to follow them for all your programs moving forward! Please utilize appropriate style as outlined by our style guidelines when developing your programs to get the most benefit out of the readability that good style provides.

Additionally, make sure to include appropriate test cases (via test-case) and examples of your functions as required by these instructions. Please do not include any extraneous output beyond that which we prescribe, so that we can quickly assess your program's correct. You may include the code that you use, e.g., to debug your program. However, please make sure it is commented out when you submit your assignment!

Part 1: Chords to notes

In a previous lab, we built up functions to play musical intervals. Similarly, before we dive into the arpeggiator proper, we'll build up functions that help us specify various chords.

Recall that in our system, we specify the pitch of a note with a number. This pitch value corresponds to one of the note values used in western music theory:

• MIDI Note/Key Number Chart (computermusicresource.com)

For example, the note value 60 corresponds to a "middle C" or a C note at octave 3. The unit of this "note value" is the semitone the smallest interval between pitches recognized in this system.

• Note value 61 (C#) is one semitone away from C,
• Note value 62 (D) is 2 two semitones away from C,

And so forth. A chord, therefore is a collection of notes separated by pattern of these semitones. For example, a major chord is a collection of notes consisting of:

• A root note value, e.g., note value 60 (middle C)
• A note 4 semitones away, e.g., note value 64 (E)
• A note 7 semitones away, e.g., note value 67 (G)

(import music)
(define root 60)
(seq (note root en)
     (note (+ root 4) en)
     (note (+ root 7) en))

Other chords feature different patterns of semitones. Common chord types can be found on Wikipedia, linked below:

• Chord (music): Examples (Wikipedia)

Problem 1a: chord-notes

To begin, write a function (chord-notes root symbol) that takes:

• A root note specified as a numeric MIDI value and
• A valid chord symbol given as a string.

And returns a list of midi note values corresponding to the notes of the specified chord. Value chord symbols are the "long symbol" names found in the linked Wikipedia article. These symbols also appear as a list in the starter file:

;;; A list of the chord symbols supported by chord-notes.
;;; Taken from: https://en.wikipedia.org/wiki/Chord_(music)#Examples
(define chord-symbols
  (list "maj" "maj6" "dom7" "maj7" "aug" "aug7"
        "min" "min6" "min7" "minmaj7" "dim" "dim7"))

Note that we use "maj" to represent a major triad chord which has no long name in the Wikipedia table.

Also note that since it is a precondition of the function to receive a valid chord symbol, you do not need to include an explicit check for when the symbol is not one of the strings in the list above.

The starter file has a fairly comprehensive test suite for this function. However, still write two additional tests for this function demonstrating its correctness.

Problem 1b. chord-symbol->chord

Next, write a function (chord-symbol root symbol dur seq-or-par) that takes

• A root note specified as a numeric MIDI value,
• A valid chord symbol given as a string,
• A note duration dur that will be given to each note, and
• Either the seq or par functions from the music library.

And returns a complete chord (as a playable composition) specified by the arguments. Whether seq or par is passed to the seq-or-par argument will determine whether the chord is played as sequential notes, i.e., an arpeggio, or as parallel notes, i.e., a true chord.

In addition to the provided starter test case, write two additional tests for this function demonstrating its correctness.

Problem 1c. all-chords

Finally, with a function capable of creating a single chord, write a function (all-chords root dur seq-or-par) that creates a list of pairs which each pair contains:

• The chord symbol name.
• A composition that plays the chord according to the given parameters.

To do this, utilize the chord-symbols list given to you in the starter code. Additionally, the pair function from the standard library allows you to create a pair:

(import music)

(pair -1 1)

(pair "maj" (par (note 60 qn)
                 (note 64 qn)
                 (note 67 qn)))

You do not need to write tests for this function, but you should use the two example invocations of all-chords given in the starter file to check your work. Note that since you tested the previous functions thoroughly (and presumably, used them in all-chords in a compositional manner), all-chords is likely already correct! Nevertheless, you should use these examples to try out your work and hear the different chord sounds!

Part 2: ARP

Next, let's write our arpeggiator functions! These functions will all take two things as input:

• A list of MIDI note values (e.g., generated from chord-notes) and
• A duration value that determines the length of each note,

And will generate an arpeggio, i.e., a composition consisting of the chord notes played sequentially, according to different patterns.

We describe each of the patterns below and give an example of the output. This output is also reflected in each test-case given in the starter file. You should also give two additional test cases for each function demonstrating their correctness.

Problem 2a. plain-arp

(plain-arp notes dur) creates an arpeggio from the given notes played "as-is," i.e., in sequential order as given in the list.

(import music)
(define notes (list 40 50 60 70 80 90))

; (plain-arp notes qn) --> ...
(seq (note 40 qn) (note 50 qn) (note 60 qn)
     (note 70 qn) (note 80 qn) (note 90 qn))

Problem 2b. reverse-arp

(reverse-arp notes dur) creates an arpeggio from the given notes played in reverse order relative to the given list.

(import music)
(define notes (list 40 50 60 70 80 90))

; (reverse-arp notes qn) --> ...
(seq (note 90 qn) (note 80 qn) (note 70 qn)
     (note 60 qn) (note 50 qn) (note 40 qn))

Problem 2c. sorted-arp

(sorted-arp notes dur) creates an arpeggio from the given notes played in sorted order according to ascending note value.

(import music)
(define notes (list 60 80 90 40 50 70))

; (sorted-arp notes qn) --> ...
(seq (note 40 qn) (note 50 qn) (note 60 qn)
     (note 70 qn) (note 80 qn) (note 90 qn))

Problem 2d. splice-arp

(splice-arp notes dur) creates an arpeggio from the given notes where the second half of the notes are played first and the first half of the notes are played second.

(Hint: list-take and list-drop would be useful here.)

(import music)
(define notes (list 40 50 60 70 80 90))

; (splice-arp notes qn) --> ...
(seq (note 70 qn) (note 80 qn) (note 90 qn)
     (note 40 qn) (note 50 qn) (note 60 qn))

Problem 2e. random-arp

(random-arp notes dur) create an arpeggio where the notes are randomly drawn from notes. The number of notes in the arpeggio is the same as the length of notes. A note from notes may appear zero or multiple times in the resulting arpeggio.

To implement this function, you will need a new library function that behaves rather simply, but we'll have much more to say about it later in the course:

;;; (random n) -> list?
;;;   n: integer?, n >= 0
;;; Returns a random number in the range 0 to n (exclusive).

(random 10)

(random 10)

(random 10)

If you refresh this page, you'll see that each call to random above will take on a different value in the range 0 through 10 (exclusive)! Use random in conjunction with list-ref to achieve the effect that random-arp is looking for!

Note that because random-arp generates random output, it is more difficult to test! One corner test case is provided for you in the starter code to give you a sense of how you might test the function. Rather than writing additional test-cases, call you function in the file and simply re-run and check the output of your function multiple times to get a sense of whether it is wormking!

Problem 2f. Factoring out the redundancy

At this point, you may have noticed that problem 2f was at the start of the part 2 section in the starter code! Why?

Now that you have written five versions of arp, you should have noticed some significant redundancy in the code you have written! For this final problem of this part, go back and factor our the redundancy in your arp functions, defining helper functions before the various implementations of your *-arp functions. Make sure to write doc comments and at least two tests for each function that you write.

(Hint: there is a specific point of redundancy between the various arp functions we want you to factor out in your implementation! Recall that the way we reduce these redundancies is by creating a generalizing function that captures the shared behavior and allows for variation when it occurs in function parameters. You will need to do the same here, but the necessary variation isn't value-oriented, it is behavior-oriented! What type of value could I pass to my general arp function to capture this variation?)

Part 3: Progressions

Our arpeggiator works over individual chords. However, let's now lift this behavior to progressions, i.e., collections of chords. If we think of individual chords as words, then progressions are sentences, conveying complete (musical) thoughts!

With the machinery we've developed in this assessment, we can represent a progression as a list of pairs of root notes and symbol names. For example, the following example chord progression can be found in the starter code.

(import music)

;;; An example chord progression: a (sort-of) ii-V-i in Bb.
(define example-progression
  (list (pair 60 "min7")
        (pair 65 "dom7")
        (pair 60 "dim7")
        (pair 58 "min7")))

;;; Each chord of the progression played as true chords
(seq (par (note 60 qn) (note 63 qn) (note 67 qn) (note 70 qn))
     (par (note 65 qn) (note 69 qn) (note 72 qn) (note 75 qn))
     (par (note 60 qn) (note 63 qn) (note 66 qn) (note 69 qn))
     (par (note 58 qn) (note 61 qn) (note 65 qn) (note 68 qn)))

;;; The notes of the progression played sequentially as a collection
;;; of arpeggios
(seq (note 60 sn) (note 63 sn) (note 67 sn) (note 70 sn)
     (note 65 sn) (note 69 sn) (note 72 sn) (note 75 sn)
     (note 60 sn) (note 63 sn) (note 66 sn) (note 69 sn)
     (note 58 sn) (note 61 sn) (note 65 sn) (note 68 sn))

Write a function (progression->notes progression) that takes a progression, a list of pairs of root note values and chord symbols, and returns a list of note values drawn from each chord in the progression in sequential order. In addition to the test case given in the starter code for example-progression come up with 2 additional test cases for this function. Additionally, observe in the starter code how we can combine our various arp functions with progression->notes to create some cool musical effects!

Part 4: Freestylin'

Now we have a complete arpeggiator toolkit where we can specify a musical progression and output an arpeggiation of that progression! To close this assessment, put your tools together to create a musical composition of your design. The only requirement is that you should combine one or more calls to progression->notes with one or more calls to your arp functions to generate some non-trivial music! Additionally, you may choose to include percussion, e.g., a simply quarter note bass drum or even your beat machine from the previous assessment, to provide a rhythmic groove! Include any such new code under the final part in the source file.

You should use display to make your composition playable and include a description of the composition before displaying it via the description function.

Rubric

R or above

• Displays a good faith attempt to complete every required part of the assignment.

M or above

• Includes the specified file, arpeggiator.scm.
• Includes an appropriate header on all submitted files that includes the course, author, etc.
• Code runs in Scamper without errors.
• Documents and names all core procedures correctly.
• Code generally follows style guidelines.
• Code includes required tests.
• Basic functionality of all core functions is present and correct:
• Freestyle composition is present and operational.

E

• Function documentation is complete and appropriately evocative of each function's behavior.
• Code follows style guidelines completely, with at most three minor errors present.
• Code is well-designed, avoiding repeated work through decomposition and appropriate language constructs.
• Each set of tests includes at least one edge case (e.g., an empty list, if appropriate).
• Implementation of all core functions is completely correct.

Take-home Assessment: Shape Lists

As the subtitle suggests, in this assignment we will consider techniques for building complex images based on lists of shapes. Along the way, we will explore uses of "the big three" list procedures.

Logistics

Please start with the template code, and please save all of your work as shape-lists.scm!

The write-up

The write-up for this assignment can be found on the CSC 151-03 section's website:

• Take-home assessment 4: Exploring lists of shapes

List Basics

We consider some basic issues of Scheme's list data type, which is used to collect multiple values. We explore the ways to create lists and a few operations used to manipulate lists.

Introduction

In your initial explorations with Scheme you have investigated a variety of basic types of data, including numbers, strings, and images. You can work on many kinds of problems with just these types. However, when you want to address more complex problems, particularly problems from data science, you will need to work with collections of data - not just the rating of a movie from one newspaper, but the rating of that movie from many newspapers (or even the ratings of many movies from many newspapers); not just one word, but a sequence of words.

In Scheme, the simplest mechanism for dealing with collections of data is the list data type. Lists are collections of values that you can process one-by-one or en masse. In this reading, we will consider Scheme's list data type as well as a few procedures to build and manipulate lists. We will return to lists in a near future.

You may recall that there are five basic issues we should consider when we encounter a new type: its name, its purpose, how one expresses values in the type, how the computer displays values in the type, and what operations are available to you. (It may seem that we are repeating this list of issues; that's because we want you to accustom yourself to asking about those five issues each time you encounter or design a new type.)

We've already covered the first two: The name of the type is "list" and its primary purpose is to group or collect values. Let's explore the rest.

Displaying lists

What does a list value look like? We have already seen several examples of lists as the result of functions from the standard library. For example, string->list produces a list of characters from a string:

(string->list "hello world!")
> (list #\h #\e #\l #\l #\o #\space #\w #\o #\r #\l #\d #\!)

Observe the result of this function call. In Scamper, we display a list as a finished call to the list function. Each of the arguments are the values stored in that list. We can observe this distinction in the following example:

(list (+ 1 1) (string-length "hello world!") 32)

Note how the resulting list contains the values 2 (the result of (+ 1 1)), 12 (the result of string-length) and 32.

As a historical note (and perhaps a forewarning if we forget to modify the readings!), in Scheme, a list is displayed in a different way: a parenthesized list of values starting with an apostrophe, also called a tick. For example, the result of (string->list "hello world!") in Racket would be:

> (string->list "hello world!")
'(#\h #\e #\l #\l #\o #\space #\w #\o #\r #\l #\d #\!)

To avoid throwing more syntax at you, we elect in Scamper to use the function form of list to represent list values.

Creating lists

Because lists play a central role in Scheme, there are a wide variety of ways to create lists. One common way to create lists is with the (list exp0 exp1 ...) procedure, which evaluates all of its parameters and creates a list from those parameters.

(list 2 3 5 7)
(list "two" "three" "five" "seven")
(list 1 (+ 2 3) 4)
(list 1 (list + 2 3) 4)
(list 1 (list (+ 2 3)) 4)
(list)

If you need a list of identical values for some reason, you can use the (make-list n val) procedure, which takes two parameters: the number of copies of a value to make in the list and the particular value to copy.

(make-list 5 "hello")
(make-list 2 4)
(make-list 4 2)

Because we often find that we need a sequence of numbers, Scheme includes a procedure called (range n) that takes an integer n as input produces a list numbers from 0 up to n, exclusive.

(range 7)
(range 4)

Additionally, range can take two, or even three arguments so that you can further specify the pattern of numbers the function produces.

With two arguments, (range n m) produces a list in the range n to m, exclusive.

(range 3 10)
(range -11 2)

With three arguments, (range n m k) will create a list of number from n to m, exclusive, but step by k. This allows us to specify ranges that go backwards rather than forwards!

(range 1 10 2)
(range 13 -5 -3)

Note that the three argument form of range is the most general form, and we can view the two-argument and one-argument forms as special cases of the general form. For example, the following range calls are equivalent:

(range 10)
(range 0 10 1)

Some list operations

Perhaps the simplest list operation is (length lst), which gives you the number of elements in the list.

(length (list))
(length (list 3 4 5))
(length (string-split "he took his vorpal sword in hand" " "))

You can also extract an element of a list using the (list-ref list index) operation. In Scheme, the position of an element is the number of values that appear before that element; hence, the initial element of a list is element 0, not element 1.

(define observation (list "Computers" "are" "sentient" "and" "Malicious"))
observation
(list-ref observation 0)
(list-ref observation 2)
(length observation)
(list-ref observation 4)
(list-ref observation 5)

The (index-of lst val) procedure serves as something like the opposite of list-ref: Given a list and an element, it returns the position (index) of the first instance of that element.

(define lead-in (list "a" "one" "and" "a" "two" "and" "a" "..."))
(index-of lead-in "one")
(index-of lead-in "and")
(list-ref lead-in (index-of lead-in "and"))

The (reverse lst) procedure creates a new list that consists of the same elements as lst, but in the opposite order.

(reverse (range 10))
(reverse (list "a" "b" "c" "d" "e"))

The (append lst1 lst2) procedure creates a new list that consists of all the elements of the first list followed by the elements of the second list.

(append (range 5) (range 5))
(append (make-list 3 "hello") (make-list 4 "echo"))

The (list-take lst n) procedure builds a new list that consists of the first n elements of lst and the (list-drop lst n) procedure builds a list by removing the first n elements of lst.

(define some-ia-counties
  (list "Adair" "Adams" "Alamakee" "Appanoose" "Audobon"))
(list-take some-ia-counties 3)
(list-drop some-ia-counties 3)
(list-take (reverse some-ia-counties) 2)

Self Checks

Check 1: Checking list procedures (‡)

Predict the results of evaluating each of the following expressions.

(list 2 1)
(make-list 1 2)
(make-list -1 2)
(append (list 2 1) (list 2 1))
(index-of (list "a" "b") "a")
(index-of (list "a" "b") "c")
(range 3)
(range 0)

Check 2: Ranges, revisited

How could we make the list (list 6 5 4 3) with range in conjunction with other standard library list functions?

Transforming Lists

In this reading, we investigate a particular form of decomposition relevant in computing in which transformations over a collection of values are really transformations of the individual elements of the collection.

An Example: Mapping Salaries

Imagine representing the collection of yearly salaries found at a startup using a simple list, for example:

(define salaries (list 100000 100000 50000 75000 500000))

And now imagine computing everyone's updated salary after a standard cost-of-living adjustment (COLA). We might decompose this problem into the problem of computing one person's updated salary. Let's take the first person whom makes 100000 (units deliberately unspecified) as an example. The Social Security COLA for 2020 was %1.6, so we can calculate the updated salary using arithmetic:

(+ 100000 (* 100000 0.016))

And we can abstract this into a function that computes the updated salary when given a salary:

;;; (compute-cola-salary salary) -> number?
;;;   salary : number?, non-negative
;;; Returns the given salary, updated for cost-of-living.
(define compute-cola-salary
  (lambda (salary) 
    (+ salary (* salary 0.016))))

Good! We can now calculate the updated salary for any person. However, how do we do this for a collection of salaries, a collection represented as a list?

Note that the calculation of each salary is independent of the other salaries. That is, someone's adjusted salary only depends on their salary and not other salaries. In this situation, we simply want to apply our solution for a single person, compute-cola-salary, to every element of the list. We say that we want to lift the function compute-cola-salary from operating on a single salary to a list of salaries.

In Scheme, we realize the behavior of lifting a function to a list of values with the map function:

(define salaries (list 100000 100000 50000 75000 500000))

(define compute-cola-salary
  (lambda (salary)
    (+ salary (* salary 0.016))))

(map compute-cola-salary salaries)

salaries

Note that the map procedure does not affect the original list.

The map procedure

map is a powerful procedure! It allows to concisely describe how to transform the values of a list in terms of an operation over a single element of the list. Let's break down how you use map.

map itself is a function of two arguments as seen in our above example.

• The first argument is a function that transforms a single element of the list. By "transform", we mean the function:

  • Takes as an input an element of the list.
  • Produces as an output the result of transforming that element.

  In our above example, compute-cola-salary is a function that transforms an old salary into a new, adjusted salary.

• The second argument is a list that contains the elements that we wish to transform.

Any transformation function over salaries can be passed in to our call to map, for example, the startup might have gone public so everyone gets their salary doubled:

(define salaries (list 100000 100000 50000 75000 500000))

(define double-salary
  (lambda (salary)
    (* salary 2)))

(map double-salary salaries)

The startup might have hit a downturn and needs to reduce their salaries:

(define salaries (list 100000 100000 50000 75000 500000))

(define downsize
  (lambda (salary)
    (/ salary 2)))

(map downsize salaries)

Or worse yet, the downturn might be so bad that the startup needs to do the right thing and let go of its higher-earning employees to stay under budget:

(define salaries (list 100000 100000 50000 75000 500000))

(define should-keep
  (lambda (salary)
    (< salary 75000)))

(map should-keep salaries)

Observe that we have transformed our list of salaries into a list of booleans indicating whether we should keep the employee with that salary.

Transforming collections of data with map.

This last example alludes to the idea that map isn't constrained to keep the type of the elements of the resulting list the same as the old list. Indeed, the power of the map is we can transform the list in arbitrary ways as long as those transformations are independent between list elements. As long as we can recognize the "collection" being transformed in our problem, we can write solutions in surprisingly elegant ways.

As an example, consider the following code that draws a collection of green circles beside each other:

(import image)

(define green-circle
  (lambda (radius)
    (circle radius "solid" "green")))

(beside (green-circle 20)
        (green-circle 40)
        (green-circle 60)
        (green-circle 40)
        (green-circle 20))

Using decomposition, we have organized this image as a bunch of green circles of different sizes. But look at that redundancy! Calling green-circle many times is undesirable: it takes time and effort to read and write the code. Furthermore, the "repetitive" nature of the image isn't truly captured in the code. This keeps us from generalizing the function further, e.g., varying the numbers of green-circles in the figure.

However, if we instead decompose the problem as a transformation over lists, we'll arrive at a better solution. But where is the list in this code? While there isn't a list anywhere in the code for us to immediately map over, we do note that the image can be thought of as a collection of circles.

With this in mind, we can decompose the problem of generating a collection of circles into creating a single circle. The way we do this is with the green-circle function, passing in the desired size for one of the circles. The size is therefore the element we are transforming! We're transforming a size into a circle by way of the green-circle function. We can then transform a collection of sizes into a collection of circles by lifting green-circle using map:

(import image)

(define green-circle
  (lambda (radius)
    (circle radius "solid" "green")))

(define circles (map green-circle (list 20 40 60 40 20)))

circles

Working with lists of values

We aren't done yet! This isn't a single image composed of a bunch of green circles. This is a list of green circles of different sizes (note the (list ... ) surrounding the circles).

As with the original version of the code, we need to use beside to combine the circles. However, if we simply pass this expression to beside, we get an error:

(import image)

(define green-circle
  (lambda (radius)
    (circle radius "solid" "green")))

(define circles (map green-circle (list 20 40 60 40 20)))

(beside circles)

Why does this error occur? Let's think carefully about the types of the values involved:

• beside is a function that takes a collection of images, one per argument, e.g., (beside image1 image2 image3 image4 image5). Each argument is a single image.
• circles is defined to be (map green-circle (list 20 40 60 40 20)) which is a list of images.

Finally, consider the complete expression (besides circles). Each argument to besides should be a single image but circles is a list of images instead. That's where our error arises!

Ultimately, we have to, somehow, pass in each image in the list circles to each argument position of besides. How do we do this? It turns out we have to employ an additional standard library function of Scheme to do this, apply.

(import image)

(define green-circle
  (lambda (radius)
    (circle radius "solid" "green")))

(define circles (map green-circle (list 20 40 60 40 20)))

(apply beside circles)

More generally, apply is a helpful standard library function when working with lists of arguments. apply takes two arguments:

• A function to run or apply on a collection of arguments.
• The collection of arguments to apply to the function, stored in a list.

As a simpler example of apply, consider the simple (+) function which can take any number of arguments:

(+ 1 2 3 4 5)

While (+) takes any number of arguments, it cannot take a single list as an argument:

(+ (list 1 2 3 4 5))

To pass this list of numbers to (+), we can use the apply function:

(apply + (list 1 2 3 4 5))

Pause for reflection

So let's summarize the image code we've written:

(import image)

(define green-circle
  (lambda (radius) 
    (circle radius "solid" "green")))

(define circles
  (map green-circle (list 20 40 60 40 20)))

(define circles-besides
  (apply beside circles))

circles-besides

We've decomposed the problem of drawing the circles not as a series of repeated calls to green-circles but as a collection that is the result of transforming the sizes of the circles into green circles. While this interpretation may have come less naturally to you, I would argue that once you understand transformations with map that this is a more readable and concise solution to the problem.

As a final note, I'll mention that it is more flexible, too. For example, there's nothing special about the fact that we wanted the circles besides each other. The following modified code leverages our abstractions to get a different effect with minimal effort:

(import image)

(define green-circle
  (lambda (radius) 
    (circle radius "solid" "green")))

(define circles
  (map green-circle (list 20 40 60 40 20)))

(apply above circles)

This is the power of decomposition in action! In particular, if we use appropriate abstractions, we can create highly reusable code that both captures our intent but can be used in other contexts with minimal modification.

Thinking with types

As you've likely discovered already, it is important that we use the correct types when we run our procedures. With both map and apply, we have to think a bit more deeply about types.

What are the types of the inputs to map?

That's a real question. Take a minute and think about it.

We mean it.

Hopefully, you said something like

map takes two inputs. The first is a procedure. The second is a list of values.

But there's more to it than that. There's a relationship between the procedure and the list of values. In particular, the procedure much be applicable to each value in the list. Let's consider two simple examples.

You may remember that square computes the square of a number and string-upcase converts a string to upper case.

(square 5)
(string-upcase "quiet")

If we're using map, we should use square with lists of numbers and string-upcase with lists of strings.

(range 6)
(map square (range 6))
(string-split "please be quiet not loud" " ")
(map string-upcase (string-split "please be quiet not loud" " "))

But what happens if we don't match types? Let's see.

(map square (string-split "please be quite not loud" " "))
(map string-upcase (range 6))

You'll note that we get errors. Are they the errors you expected? It might be nicer if Scamper more explicitly told us that the elements of the list were not the correct types for the procedure. But it's done that in its own way.

What if we do something even stranger, such as writing something other than a procedure in the procedure position, or something other than a list in the list position? Let's try.

(map 5 (list 1 2 3))
(map square 5)

It's good to see that these error messages are clear. Let's do our best to remember those so that when we see them, we know what's gone wrong.

Next, let's move on to apply. Like map, apply takes a procedure and a list as parameters. While map applies the procedure element by element, apply applies the procedure to the elements en masse, as it were.

(apply * (list 2 3 4))
(apply string-append (list "this" "and" "that"))

Once again, we should see what happens if we give incorrect types.

(apply * (list 2 3 4))
(apply string-append (list "this" "and" "that"))
(apply * (list "this" "and" "that"))
(apply * (list 2 3 "four"))
(apply string-append (list 2 3 4))
(apply 2 (list 2 3 4))
(apply 2 3)
(apply + 2 3 4)

We will need to practice reading error messages like those. But each is saying, in essence, "you got the types wrong".

Mental models: Tracing map and apply

As we've seen, it's useful to be able to trace our Scheme code by hand to consider what Scheme is doing (or at least what we think it's doing) and, therefore, why we get the results or errors that we do. And you already know many aspects of the mental model for doing so, particularly the rule that you evaluate arguments before applying a procedure and that you use substitution for user-defined procedures.

• Evaluating (map f (list v1 v2 ... vk)) is equivalent to evaluating (list (f v1) (f v2) ... (f vk)).
• Evaluating (apply f (list v1 v2 ... vk)) is equivalent to evaluating (f v1 v2 ... vk)

So let's try an example.

(define dub
  (lambda (x)
    (* 2 x)))

;     (apply + (map dub (range 3 8 2)))
; --> (apply + (map dub (list 3 5 7)))
; --> (apply + (list (dub 3) (dub 5) (dub 7)))
; --> (apply + (list 6 (dub 5) (dub 7)))
; --> (apply + (list 6 10 (dub 7)))
; --> (apply + (list 6 10 14))
; --> (+ 6 10 14)
; --> 30

Note that when we're working with lists, it's helpful to explicitly write (list ...), which reminds us that we're dealing with a list and not an expression to further evaluate.

While we'll rarely write out all of these steps, it helps to keep them in mind as we think about what map and apply are doing. And we will, on occasion, pull out a piece of paper (or an electronic document) to think through part of the steps of an evaluation.

Self-checks

Self-check 1 (Differences) (‡)

Write a function decrement that takes an integer as input and returns an integer one less than the input.

Now use decrement and map to write an expression that decrements the contents of the following list three times:

(define example-list (list 10 20 30 40 50))

title: List basics

We further explore Scheme's list structures. Lists permit us to group data and process those data as a group. We also explore the procedures that we can use with lists, such as range, map, and apply

Useful procedures and notation

Standard list notation

(list v1 v2 ... vk) is a list containing the elements v1, v2, ..., vk.

Creating lists

(list e1 e2 ... ek) returns a list of the elements e1, e2, ..., ek.

(make-list n v) returns a list of n copies of v.

(range n) returns a list of all the natural numbers strictly less than n (starting with 0).

(range s n) returns a list of all the natural numbers between s (inclusive) and n (exclusive).

(range s n i) returns a list of all the natural numbers between s (inclusive) and n (exclusive), incrementing by i each time.

Manipulating lists

(map f l) returns a new list that is the result of applying the function f to each element of the list l. In other words, (map f (list v1 v2 ... vk)) is equivalent to (list (f v1) (f v2) ... (f vk)).

(apply f l) calls variable-argument function f with the elements of l. In other words, (apply f (list v1 v2 ... vk)) is equivalent to (f v1 v2 ... vk).

(map f l1 l2) returns a new list that is the result of applying the binary function f to each of the elements in l1 and l2 element-wise. In other words, (map f (list u1 u2 ... uk) (list v1 v2 ... vk)) is equivalent to (list (f u1 v1) (f u2 v2) ... (f uk vk)).

Other list operations

(length lst) returns the length of list lst.

(reverse lst) returns the list lst but with its elements in reverse order.

(append l1 l2) appends lists l1 and l2 together.

(take lst n) returns a new list consisting of the first n elements of lst.

(drop lst n) returns new list consisting of all but the first n elements of lst.

(list-ref lst n) returns the nth element of list lst, zero index-based.

(index-of val lst) returns the index of the first occurrence of val in list lst.

Preparation

1. Review the list of procedures above.

2. If you have not done so already, you may want to open a separate tab or window in your browser for the reading on list basics and the reading on transforming lists.

3. Load the lab. Remember that the person closer to the board is Side A and the person further fro the board is Side B.

   • list-basics.scm

4. Get started!

The "Big Three" list operations

We've started to see some significant power in using two "higher order" list operations, map and apply. These are called "higher order" procedures because they take procedures as inputs.

map is particularly useful for a variety of reasons. First, it lets us do a form of repetition: We use map to repeatedly apply a procedure to different values (the elements of the list or lists we map over). But it's more than that. Experience suggests that using map leads to a different way of thinking about repetition than other mechanics found in other languages such as "for loops". (Don't worry if you've never heard of for loops. You'll learn about them in another CS class.)

More importantly, map permits some cool implementations. Since map does not specify the order in which the elements are processed, one can implement map so that all (or at least many) of the applications can be done at the same time. (Computer scientists say "in parallel".) As we start to reach the limits on the speed of one processing unit, the way we make large computations faster is to parallelize them, to make them run on multiple processing units. While there are explicit ways to break up a program, by relying on procedures like map, we can trust the underlying system to parallelize sensibly, without worrying about particular details. In fact, map is so important that it's a core part of the parallelization technologies that both Google and Amazon use.

As you might expect, map alone does not suffice. As you've already seen, it helps to be able to combine the elements of a list into a single value. We've used apply for that, but, as we shall soon see, it does not suffice for all cases. In addition, we may find that not all the values in a list are worth considering. So let's consider some other useful procedures.

Combining the elements in a list

When we began our exploration of numbers, we used a variety of unary (one parameter) procedures, such as those above. But we also used some binary (two parameter) operations, such as addition or multiplication. Can we also use those with lists? It seems like we'd want to. For example, if we wanted to compute the mean value in a collection of numbers, we want to add up all the elements in the collection and then divide by the length of the collection.

We've seen one way to do so. We can use apply. For example, we can sum the elements in a list with (apply + lst). But what happens if we don't have an "n-ary" procedure (one that takes arbitrarily many inputs). Consider, for example, the problem of reversing each word in a string consisting of a sequence of words separated by spaces.

The first two steps seem relatively straightforward. We use string-split to break the string into words. We use string-reverse (or our anonymous version of string-reverse) to reverse each word.

(map (o list->string reverse string->list)
     (string-split "this is a sample set of words" " "))

How do we get them back together? We could try string-append.

(apply string-append
       (map (o list->string reverse string->list)
            (string-split "this is a sample set of words" " ")))

Whoops! We've lost the spaces. What to do? What to do?

Fortunately, there's a standard approach that involves a different kind of decomposition. Rather than thinking about putting everything together all at once, we write a procedure that combines neighboring elements and then repeatedly apply it to neighboring pairs until we're down to a single element. There are two common terms for that work, "folding" and "reducing". We'll use the latter.

First, let's build our helper procedure. While it will eventually be an anonymous procedure (more on those later), we'll start by naming it for convenience.

(define combine-with-space
  (section string-append _ " " _))

(combine-with-space "a" "b")
(combine-with-space "Hello" "Goodbye")

Now, we can use the reduce procedure with combine-with-space. (reduce f l), converts l to a single value by repeatedly applying f to neighboring pairs of values, replacing the pair with the result of the function.

(define combine-with-space
  (section string-append _ " " _))

(reduce combine-with-space (list "a" "b" "c" "d"))

How does that work? Well, we said that reduce repeatedly applies the function to neighboring pairs of values. Let's consider what happens.

• We start with four values to combine: "a", "b", "c", and "d".
• We combine "a" and "b" with a space, yielding "a b". We now have three values to combine: "a b", "c", and "d".
• We combine the "a b" and the "c" with a space in between, yielding "a b c". We now have two values to combine. "a b c" and "d".
• We combine the "a b c" and the "d" with a space in between, yielding "a b c d". We are now down to one value.

Of course, we could also combine the values in other ways.

• We start with four values to combine: "a", "b", "c", and "d".
• We combine "c" and "d" with a space, yielding "c d". We now have three values to combine: "a", "b", and "c d".
• We combine "a" and "b" with a space, yielding "a b". We now have two values to combine: "a b" and "c d".
• We combine the "a b" and the "c d" with a space, yielding "a b c d". We are now down to one value.

Fortunately, we end up with the same value either way. That's because our procedure is associative. (More on that later.)

So we can now go back to our original problem: Creating a new string with reversed versions of all the original words.

(reduce (section string-append _ " " _)
        (map (o list->string reverse string->list)
             (string-split "this is a sample set of words" " ")))

Like map, reduce provides some advantages to the computer scientist, programmer, or software engineer. First, it encourages you to think in terms of decomposition. Rather than dealing with the whole list at once, you simply think of what to do with neighboring pairs and then rely on reduce to do the heavy lifting. And, once again, we can gain some efficiencies. If it doesn't matter which order we do the operations, we can do some of them simultaneously and otherwise find orderings that are a bit more efficient. (Yes, it turns out that there are orderings that are more efficient.) And string-append (or, in our case, combine-with-space) is not the only operation in which the order of operations doesn't matter. The same holds (more or less) for addition and multiplication. For those of you with a mathematical mindset, reduce works well with any associative binary operation.

We can, of course, use reduce in many other ways. To find the largest value in the list, we reduce with max.

(reduce max (list 3 1 5 10 3 2))

To find the smallest, we reduce with min.

(reduce min (list 3 1 5 10 3 2))

Order of operations