CS 312 - Week 1.1
CS 312 Audio Programming Winter 2020

Choose Go to Server from the Go menu in Finder.

Login with your Carleton email name and password.

Mount your cs312 courses folder.

smb://courses.ads.carleton.edu/COURSES/cs312-00-w20

A courses folder icon will appear on the Desktop.

Type this command and press Return.

setup312 <your_email_name>

Type this command to display your current directory
The # is comment. You don't have to type comments.

# This is a comment. Read and learn but don't type
# Print Working Directory
pwd
# should display something like
/Volumes/COURSES/cs312-00-w20/StuWork/<your_email_name>

Execute this command.

echo $HOME312
# should display same thing
/Volumes/COURSES/cs312-00-w20/StuWork/<your_email_name>

If everything worked continue. If not ask me for help.

The terminal runs a command line application called a shell. There are many shells available. Mac OS uses bash.

Copy/paste/execute these commands.

# folder and directory mean the same thing
# the directory and file separator is /
cd $HOME312
mkdir bin
mkdir common
mkdir cs312
cd cs312/
mkdir hw11
cd hw11
mkdir class11
cd class11
touch c111_hello.cpp
touch c112_putto.cpp
touch c113_numberbase.cpp
touch c114_print_overload.cpp
touch c115_arithmetic_types.cpp
touch c116_struct_test.cpp
code .

Important:
Often the last line is not executed and is still showing at the Terminal prompt. You'll have to type Return/Enter to execute it. If a closing return is missing in the last line will still be sitting there. Once all commands have been executed you'll return to a blank prompt. This frequently happens. Always check.

Notes:

#

comments begin with #

cd

Change Directory

mkdir

Make Directory

touch

Create a file

code

Open the class11 directory in Visual Studio Code

When I develop a series of commands like this I often don't get it right the first time. It that case execute one line at a time and observe the results.

Hereafter called vsCode.
The vsCode window should be open and displaying the contents of the class11 directory on the left.

#include <iostream>

#include is C++ directive that tells the compiler which files are required to compile a program.
<iostream> is a C++ library that provides functions to read from standard input and write to standard output. Standard input and output is provided through the Terminal.

#include <file> vs. #include "file"

File names in angle brackets <…> are system library header files that were installed by the operating system and compiler language.

File names in double quotes "…" are user or third party header files that are supplied by the programmer and are required to compile the program.

#include <string>

<string> is a C++ library that provides functions to manipulate a sequence of text characters.

"hello, world"

Text enclosed in double quotes is a C++ string.

int main()

main( ) is a function that takes no parameters and returns an int.

{ }

Curly braces enclose code blocks and are scope delimiters. Any local variables declared with the curlies are allocated on the stack and are only visible to the program within that scope.

}

The closing brace is the closest thing C++ has to garbage collection. When execution reaches the closing }, all local variables declared within that code block are destroyed.

std::cout

cout is the C++ library function that outputs text to the Terminal. If you've done any C programming it's a modern replacement of the printf() function.

std is a C++ namespace. All C++ library functions are declared in the namespace std. The double colons are the namespace scope operator. Tying function names to namespaces helps avoid name collisions that might otherwise occur between C++ libraries, third party libraries, and user defined names.

<< (put to)

The double less than is called the "put to" operator and sends whatever is on the right to the device on the left. In this case the device is the Terminal. It can also be used to write data to a memory locations, strings, and files.

>> (get from)

The double greater than than is called the "get from" operator that reads input from the Terminal and uses it to set the value of the variable on the right.

std::endl

std::endl is the name of a function that outputs a return character, or endline. It is defined in the namespac std.
You can include an endline character in a string using the \n escape character.

; (semicolon)

Normal C++ statements end with a semicolon. There are other uses that you'll learn about as the course continues.

header files

End with .h (In older code you may see .hh and .hpp used)
Header files are declarations that make constants, variables, and functions visible to other files that #include them.

implementation (source) files

End with .cpp and should be paired with a header file of the same name.
Source files contain code for the functions declared in their header file and often contain many other supporting functions that are not visible to the outside world.

You'll notice that all numbers look like base 10 numbers, excluding the bad one. C++ uses standard prefixes for different number bases: 0x for base 16 and 0 for base 8. Try the running c113_numberbase.cpp again after making the two changes underlined in red.

Build and Run

Output

DECIMAL(dec) HEXADECIMAL(hex) OCTAL(oct)

DECIMAL
dec 1234 base(10)       1234
hex 0xBAD base(10)      2989
oct 04567 base(10)      2423

HEXADECIMAL
dec 1234 base(16)       0x4d2
hex 0xBAD base(16)      0xbad
oct 04567 base(16)      0x977

OCTAL
dec 1234 base(8)        02322
hex 0xBAD base(8)       05655
oct 04567 base(8)       04567

AS DECLARED
dec 1234 base(10)       1234
hex 0xBAD base(16)      0xbad
oct 04567 base(8)       04567

back to hex using int 1234
0x4d2
0x4d2
WATCH OUT - conversions remain until changed
meant to be decimal but forgot << std::dec
0xbad

A C++ struct is an object that can contain data as well as the functions that process that data. The data can be of mixed types. All data and functions in a struct is public and is visible to any other class that uses it.

Here's a simple example that contains two string types and two functions that print the strings.

struct Hello {
  // delcare struct variables
  std::string str1;
  std::string str2;
  // delcare struct function
  void print();
  void print( const std::string a, const std::string b);
}; // structs end with semicolon

Open c116_struct_test.cpp
Copy/paste

#include <iostream>
#include <string>

struct Hello {
  // delcare struct variables
  std::string str1;
  std::string str2;
  // delcare struct function
  void print();
  void print( const std::string a, const std::string b);
}; // structs end with semicolon

// implement struct function
void Hello::print() {
  std::cout << str1 << str2 << std::endl;
}

void Hello::print( const std::string a, const std::string b) {
  std::cout << a << b << std::endl;
}

int main() {
  // create an Hello struct
  Hello hs;

  // initialize struct variables
  hs.str1 = "Hello,";
  hs.str2 = " World!";

  hs.print();
  hs.print("Hi", " CS 312 :>)");

  hs.str1 = "What's, ";
  hs.str2 = "up?";
  hs.print();

  return 0;
}

Build and Run

Output

Hello, World!
Hi CS 312 :>)
What's, up?

During the course we'll be using functions from these C++ std libraries. The libraries we'll use the most are shown in bold.
<iostream>
<string>
<vector>
<sstream>
<fstream>
<chrono>
<cmath> <random>
<algorithm>
<numeric>
<ios> <iomanip> <regex> <map>

You'll see the main() function called in different ways.

The original main function dates back to C, predating C++. In those days many programs were executed from the command line. The two function parameters allowed data to be passed in to the program. The argc parameter held the number of parameters. The argv was a variable length array that contained the data passed in. Data of different types could be passed in but the program had to have knowledge of the order and type of the parameters expected. If they didn't match, the program failed.

int main(int argc, char const *argv[])
{
  std::cout << "hello, world" << std::endl;
  return 0;
}

These invocations also work if you're not passing data to the executable.

Does not return a value.

void main()
{
  std::cout << "hello, world" << std::endl;
}

Returns a value of zero. The zero return value of a C++ function indicates "success", no errors occurred.

int main()
{
  std::cout << "hello, world" << std::endl;
  return 0;
}

Declares a return value but ignores it. The program exits at the closing brace whether it succeeded or failed.

int main()
{
  std::cout << "hello, world" << std::endl;
}

⁄ ⁄

The double slash is used as a single line comment. The double slash and any remaining text on that line is ignored by the compiler.

⁄* … *⁄

Multiple lines comments are enclosed by /* and */.

/*
  Line 2 comment
  Line 2 comment
  Line 3 comment
*/

It's easy to comment out blocks of code with the #if ... #endif directives.

#if 0 // or #if false
  code statement;
  code statement;
  code statement;
#endif

Arithmetic

Comparison

Assignment

Logical

Bitwise

A lot of CS 312 style formatting happens auto-magically when you save your files in vsCode, but it can't do everything. These are additional guidelines you should follow for CS 312.

Terminal runs a program called a shell. On the Mac the default shell is bash. All CS 312 assignments and examples assume you're using the bash shell. When Terminal starts up it executes commands found in the .bash_profile file in your home directory. You've may never have seen it because its filename begins with a dot. Dot files on the Mac are hidden. You can make them visible in a Finder window by typing Command-Shift-Period. You can see dot files in the Terminal using the ls -a command.

We'll use these two files to customize the bash Terminal for CS312:

.bash_profile

executed once at login and executes .bashrc

.bashrc

executed every time a new Terminal window or tab is opened

Implement write_body() to produce the following output.

Important : Use you and your partners names: Last First email.

/***************************************************************
hw111_boilerplate.cpp
Copyright (c) Carleton College CS312 free open source
Assignment: hw111
Duck Donald dduck@carleton.edu
Mouse Minny mmouse@carleton.edu
DATE: 2019-12-15
TIME: 14:46:25
****************************************************************/

Hint: Date and Time

Run this command in Terminal

date '+DATE: %Y-%m-%d' && date '+TIME: %H:%M:%S'

Google std::system for one way of capturing shell commands in C++.

Here's code I modified from one of the sites google returned: https://en.cppreference.com/w/cpp/utility/program/system

Copy/paste this code into a new file named /date.cpp.

#include <iostream>
#include <cstdlib>

int main()
{
}
    std::system("date"); // execute the UNIX command date

Compile and run

cl date && ./a.out

Output

Sun Dec 15 22:16:01 CST 2019

Modify it for use in boilerplate.cpp.

Implement these three functions to produce the output shown below.

// write lines beginning with #
void write_comment(const std::string& s);

// write lines where the status byte does not use a data2 byte
void write_midi_message_nodata2(int32_t timeStamp,
                                int16_t status,
                                int16_t data1);

 void write_midi_message_hasdata2(unsigned int timeStamp,
                                  unsigned char status,
                                  unsigned char data1,
                                  unsigned char data2);

Output

Your final output must match this exactly. Study the comments (lines beginning with #)

# A MIDI message contains three or four numbers separated by a single tab character
# number 1 is a time stamp in milliseconds in decimal format
# number 2 is a MIDI status message in hexadecimal format without the 0x prefix (range 0x80 - 0xFF)
# number 3 is a MIDI data1 message in decimal format (range 0 - 127)
# number 4 is a MIDI data2 message in decimal format (range 0 - 127)

# status 0xC0 begins a a patch change message
# indicating which instrument sound to use
# patch change messages do not use data2
# data1 is the instrument number.
0	c0	0

# status 0x90 begins a Note On (NON) message
# NON messages use both data1 and data2
# data1 is the MIDI note number that corresponds to
# keys on a piano where Middle C is note number 60
# data2 is the velocity or how loud or soft the note sounds
0	90	60	110

# status code 0x80 begins a Note Off (NOF) message
# NOF messages use both data1 and data2
# data1 is the MIDI note number that corresponds to
# keys on a piano where Middle C is note number 60
# data2 should be set to zero
900	80	60	0

# Every NON must be followed by a NOF with a later time stamp
1000	90	55	80
1400	80	55	0

# You can also send a NOF using a NON with a velocity of 0
1500	90	55	60
1900	90	55	0

# More NON-NOF pairs
2000	90	56	100
2900	80	56	0
3000	90	55	80
4200	80	55	0

# Another patch change
4999	c0	56

# More NON-NOF pairs
5000	90	59	110
5900	80	59	0
6000	90	60	127
8000	80	60	0

Notes

• The # symbol is a comment. Include it as the first character of the line followed by a space.
• Non comment lines are MIDI messages that contain 3 or 4 numbers.
• All numbers are separated by a single tab character.
• A tab character can be coded like this.

const char kTAB = '\t';
std::cout << 0 << kTAB << 90 << kTAB << 60 << kTAB << 100 << std::endl

We'll play it in the next class and you can hear what it sounds like.