Interfaces Objective To discuss the considerations that must be addressed when designing an interface To illustrate these design issues with a simple yet useful example The essence of design is to balance competing goals and constraints Although there are many tradeoffs when one is writing a small self contained system the ramifications of particular choices remain within the system and affect only the individual programmer But when code is to be used by others decisions have wider repercussions The examples in these slides come from Brian W Kernighan and Rob Pike The Practice of Programming Addison Wesley 1999 CSV Themes Interfaces what services and access are provided The interface is in effect a contract between the supplier and the customer The desire is to provide services that are uniform and convenient with enough functionality to be easy to use but not so much as to become unwieldy Themes Information Hiding What information is visible and what is private An interface must provide straightfoward access to the components while hiding the details of the implementation so they can be changed without affecting users Themes Resource Management who is responsible for managing memory and other resources Here the main problems are allocating and freeing storage and managing shared copies of information Themes Error handling who detects errors who reports them and how When an error is detected what recovery is attempted Topics CSV CSV CSV CSV Comma separated values Prototype library A library for others A C implementation Topics Interface Principles 1 2 3 4 Hide implementation details Choose a small orthogonal set of primitives Don t reach behind the user s back Do the same thing the same way everywhere Resource Management 1 Free a resource in the same layer that allocated it Abort Retry Fail 1 2 Detect errors at a low level handle them at a high level Use exceptions only for exceptional situations Comma Separated Values CSV A natural and widely used format for tabular data Each row is a line of text The fields on each line are separated by commas Text format used by many spreadsheets Example Good Student CS265 Advanced Programming Tools and Techniques A Bad Student CS265 Advanced Programming Tools and Techniques D Prototype Library plan to throw one away you will anyhow Frederick Brooks It is not usually until you ve built and used a version of the program that you understand the issues well enough to get the design right First version ignore many of the difficulties complete enough to be useful and to gain some familiarity with the problem Prototype char buf 200 char field 20 input line buffer fields csvgetline read and parse line return field count sample input LU 86 25 11 4 1998 2 19PM 4 0625 int csvgetline FILE fin int nfield char p q if fgets buf sizeof buf fin NULL return 1 nfield 0 for q buf p strtok q n r NULL q NULL field nfield unquote p return nfield Prototype unquote remove leading and trailing quote char unquote char p if p 0 if p strlen p 1 p strlen p 1 0 p return p csvtest main test csvgetline function int main void int i nf while nf csvgetline stdin 1 for i 0 i nf i printf field d s n i field i return 0 Decisions Made in Prototype Doesn t handle long input lines or lots of fields Lines terminated by newlines Fields are separated by commas and surrounding quotes removed no embedded quotes Input line not preserved overwritten when creating fields No data saved from one input line to the next Access to fields through global variable does not prevent access beyond last field Decisions Made in Prototype Global variables make code unsuitable to multi threaded environment or interleaved calls Caller must open and close files Input and splitting are inextricably linked The return value is the number of fields each line must be split to compute this value Each decision is interwoven into the code There is no way to change any of these properties without changing the code Specification Fields are separated by commas A field may be enclosed in double quotes A quoted field may contain commas but not newlines A quoted field may contain double quotes represented by Fields may be empty and empty string both represent an empty field Leading and trailing white space is preserved Specification csvgetline char csvgetline FILE f reads one line from open input file f assumes that input lines are terminated by r n r n or EOF returns pointer to line with terminator removed or NULL if EOF occurred line may be of arbitrary length returns NULL if memory limit exceeded line must be treated as read only storage caller must make a copy to preserve or change contents Specification csvfield char csvfield int n fields are numbered from 0 returns n th field from last line read by csvgetline returns NULL if n 0 or beyond last field fields are separated by commas fields may be surrounded by such quotes are removed within is replaced by and comma is not a separator Specification csvfield cont in unquoted fields quotes are regular characters there can be an arbitrary number of fields of any length returns NULL if memory limit exceeded fields must be treated as read only storage caller must make a copy to preserve or change contents behavior undefined if called before csvgetline is called Specification csvnfield int csvnfield void returns number of fields on last line read by csvgetline behavior undefined if called before csvgetline is called Header File extern char csvgetline FILE f read next input line extern char csvfield int n return field n extern int csvnfield void return number of fields Internal Variables enum NOMEM 2 static static static static static static out of memory signal char line NULL input chars char sline NULL line copy used by split int maxline 0 size of line and sline char field NULL field pointers int maxfield 0 size of field int nfield 0 number of fields in field static char fieldsep field separator chars Internal Functions endofline check for and consume r n r n or EOF static int endofline FILE fin int c reset set variables back to starting values static void reset void split split line into fields static int split void advquoted quoted field return pointer to next separator static char advquoted char p Example ab cd e f g h line ab cd e f g h field 0 ab field 1 cd field 2 e f field 3 field 4 g h a b c d e f g h a b 0 c d 0 0 e f 0 0 0 g h 0 1 2 3 4 5 Main Program include include include include stdio h string h stdlib h assert h include csv h csvtest main test CSV library