Haghish, E. F. (2014). Practical Stata Programming: ASCII Characters in SMCL.
Updated on January 16th 2015

Ascii

| Quick Tips |     | Introduction |      | Algorithm |     | Ascii |     | Syntax |     | Line size |     | Loop |     | Download ado |    

Quick Tips

Ascii is a simple user-written Stata program, written by Adrian Mander. The program returns ascii characters and their number in SMCL markup language. It is a good education program because it is consisted of a single loop and also, teaches you how to type ascii characters in smcl. In this article I will go through the program and explain how it works.

Introduction

ascii is a user-written package, developed by Adrian Mande that merely returns numbers of ASCII characters in SMCL markup language. ASCII (pronunced /askee/), abbreviated from "American Standard Code for Information Interchange" which is a is a character-encoding scheme. The complete list of ascii table is printed below.

The image above is exactly what the ascii package is about, printing the ascii number and showing its characters in Stata. here is an example.

ascii

Each of the printed ASCII characters has a corresponding number which are ranging from 33 to 253. You may look at the upper table to figure out why the user-written package prints the ASCII characters from number 33 which prints the exclamation mark. I will discuss the algorithm and the procedure of the program below.

Algorithm

The algorithm of the program can be simplified as described below:

  • Define the syntax of the program to return all ascii characters "from the specified number" to 255
  • Define the default ascii characters (in case the user does not specify the minimum number) to number 33
  • Creating a loop that:
    • prints the ascii number and its corresponding ascii character
    • checkes the linesize to stay within the linesize of the Stata output
    • prints the ascii numbers and characters in a row as long as they are less than the Stata line size
    • And if the results line exceeds the Stata's line size, begins a new row
  • End the program

So the program is pretty simple but still it can teach you how to define value in the syntax, how to run a loop and print the results, and more interestingly, how to neatly organize the results in rows without exceeding the line size of Stata.


ascii

So let's have a look at the whole program before explaining it part by part. Look at the code carefully and try to make sense of it as much as you can. Try to pull it out of your own brain!

pr ascii
version 9.2
syntax [,Start(int 33)]

local yourls = c(linesize)
local col 1
forv i = `start' / 255 {
local ncol = `col' + 4
di in smcl _continue_ _col(`col') "`i'" _col(`ncol') `"{c `i'}"'
if `col' < `yourls' - 10 local col = `col' + 6
else {
di
local col 1
}
}

end

Syntax

pr ascii
version 9.2
syntax [,Start(int 33)]

The program begins with defining the program name and Stata version as expected. The syntax defines an option for the program, named Start. Since the option begins with a capital letter, this letter can be used for abbreviating the option. The syntax also defines a default value of 33 for the option and put it in square brackets which makes specifying it optional. The program will uses the value of Start option by refering to `start' local macro which we will see soon.


Line size

local yourls = c(linesize)
local col 1

What happens in this part of the program is that the value of Stata's line size - which is returned in creturn list - is called by assigning its value to a new macro named yourls which presumably stands for "Your Line Size." This was not - in my opinion - necessary because you could always call the line size using `c(linesize)'. In practice it does not matter if you say:

*** Example ***
display `c(linesize)'

Or saying

local yourls = c(linesize)
display `yourls'

Let me clarify that I am not saying what the author if this package has done is a "programming error." My point is that this command could be avoided and the program could have been made shorted. I am also trying to encourage you (and primarily myself) to think critically about other's programs.

This part of the code ends with defining a macro called col and setting its value to equal 1. Later in the program you will see that this macro will be used for arranging the results of the loop.

Forvalues loop

forv i = `start' / 255 {
local ncol = `col' + 4
di in smcl _continue_ _col(`col') "`i'" _col(`ncol') `"{c `i'}"'
if `col' < `yourls' - 10 local col = `col' + 6
else {
di
local col 1
}
}

This is the main part of the program. It consists of a loop that takes a range of values. That is why the loop begins with forvalues command. As mentioned earlier, the `start' macro is obtained from the syntax and it's default value is 33. Therefore, by default we have a loop that ranges from values of from 33 to 255.

local ncol = `col' + 4

Next, the author defines a new macro, called ncol which I guess means "Next Column." The author will use this macro along with the col macro to define the place of the each ascii number and its corresponding character. When I started writing about Stata programming, I began with writing about SMCL Markup Language because using SMCL in the program can be super confusing if you are not familiar with how Stata uses this markup language to print results and create tables. So go a head and read that article if you haven't read it already. Once you read that article, you notice that the two macros, col and ncol define the positions of "`i'" and `"{c `i'}"'. And you will also know that `"{c `i'}"' will take the value of `i' and returns its corresponding ascii character.

Note that the program is written for Stata version 9.2. and eversince, smcl markup has been changing. the _continue_ option is not supported in Stata 13, however the program is working correctly, because it reminds Stata to work with Stata 9.2 framework. This is one of the reasons that shows the importance of specifying the expected Stata version in the program. Since the program prints the results in a continuous row, instead of adding new line for each iteration, the program has to monitor the user's linesize. How does it do that?

Note that within each iterations of the loop, the values of col and ncol are changing. if `col' < `yourls' - 10, then the value of `col' increases with 6. Consequently, the value of ncol will increase by 10. Can you explain why? Because within each iteration the value of ncol equals `col' + 4 and since col increases for 6, ncol will increase by 10. Once the value of `col' becomes larger or equal to `yourls' - 10, the program adds a new line and reset the value of col to equal 1. This allows keeping the output table in a particular length without exceeding your line size.

Download

The example ado file below is the commented version of ascii.ado that you can download.
ascii.ado





Aboutفارسی