Class TeamCsvService

java.lang.Object
edu.ucsb.cs156.frontiers.services.TeamCsvService

@Service public class TeamCsvService extends Object
Builds the compact team tables that instructors traditionally produce by hand: every student's name abbreviated as far as it can be while staying unique, laid out in several side-by-side column pairs (e.g. "Name,Team,,Name,Team"). The name abbreviation, the column balancing and the CSV writing are separate steps so that different tables (name to team, team to names) can share them.
  • Field Details

  • Constructor Details

    • TeamCsvService

      public TeamCsvService()
  • Method Details

    • titleCase

      public String titleCase(String name)
      Converts a name to Title Case: the first letter of each word is upper case and the rest lower case. A new word starts after any non-letter character, so hyphenated names and names with apostrophes are handled (e.g. "MARY-JANE O'BRIEN" becomes "Mary-Jane O'Brien"). Leading and trailing whitespace is removed; null becomes "".
      Parameters:
      name - the raw name (may be null)
      Returns:
      the name in Title Case
    • firstWord

      public String firstWord(String name)
      Returns the first word of the given name: everything before the first whitespace, once leading and trailing whitespace has been removed. The roster's first name field often holds a first and a middle name ("Chris Edward"); we assume the first space marks the end of the first name. Null becomes "".
      Parameters:
      name - the raw name (may be null)
      Returns:
      the first word of the name
    • nameAndTeams

      public List<NameAndTeam> nameAndTeams(List<RosterStudent> students)
      Computes the abbreviated name and team for each student, preserving the order of the input list. The first name is the first word of the roster's first name field (see firstWord(String)), so a middle name in that field is ignored. Each name is abbreviated as far as possible while remaining unique among all students:
      • first name only, where no other student shares that first name;
      • first name plus last initial, where that is enough to be unambiguous;
      • first name plus full last name, otherwise;
      • first name plus full last name followed by an asterisk, when another student has exactly the same first and last name (the instructor can then disambiguate by hand).
      The team is the first of the student's teams, or "" if the student has no team.
      Parameters:
      students - the roster students, already in the desired order
      Returns:
      one NameAndTeam per student, in the same order
    • layoutColumns

      public <T> List<List<T>> layoutColumns(List<T> items, int columns)
      Splits the items into the given number of columns, filling column by column, with the column lengths as balanced as possible: every column gets items.size() / columns items, and the first items.size() % columns columns get one extra.
      Type Parameters:
      T - the type of item being laid out (e.g. a student, or a whole team)
      Parameters:
      items - the items, in order
      columns - the number of columns, at least 1
      Returns:
      a list of exactly columns lists, the first of which is never shorter than any other
      Throws:
      IllegalArgumentException - if columns is less than 1
    • chunkColumns

      public <T> List<List<T>> chunkColumns(List<T> items, int perColumn)
      Splits the items into columns of at most perColumn items, filling column by column: every column except the last one is full. Unlike layoutColumns(List, int), the number of columns is not fixed; there are as many as needed, and always at least one (which is empty when there are no items).
      Type Parameters:
      T - the type of item being laid out (e.g. a student, or a whole team)
      Parameters:
      items - the items, in order
      perColumn - the most items in one column, at least 1
      Returns:
      the columns, in order
      Throws:
      IllegalArgumentException - if perColumn is less than 1
    • writeColumnsCsv

      public void writeColumnsCsv(Writer writer, List<String> headerCells, List<List<List<String>>> columns) throws IOException
      Writes a CSV made of several side-by-side columns separated by a blank cell. The header line repeats headerCells once per column; then there is one line per row of the longest column. Each column is a list of rows, and each row a list of cells with the same length as headerCells. Rows missing from shorter columns are written as blank cells.
      Parameters:
      writer - where to write the CSV
      headerCells - the cells of one column's header, e.g. ["Name", "Team"]
      columns - the columns, each a list of rows of cells
      Throws:
      IOException - if writing fails
    • writeName2TeamCsv

      public void writeName2TeamCsv(Writer writer, List<NameAndTeam> entries, int columns) throws IOException
      Writes the "Name,Team" table: the entries balanced across the given number of column pairs, filling column by column.
      Parameters:
      writer - where to write the CSV
      entries - the entries, in order
      columns - the number of "Name,Team" column pairs, at least 1
      Throws:
      IOException - if writing fails
      IllegalArgumentException - if columns is less than 1
    • groupByTeam

      public List<List<NameAndTeam>> groupByTeam(List<NameAndTeam> entries)
      Groups the entries by team, one list per team, with the teams in case-insensitive alphabetical order by name and the entries within each team in their original order. Entries with no team (a blank team name) are collected into one extra group placed last, so that unassigned students are still visible.
      Parameters:
      entries - the entries, in order
      Returns:
      one list per team, teams sorted by name, unassigned students last
    • writeTeamTableCsv

      public void writeTeamTableCsv(Writer writer, List<NameAndTeam> entries, int columns) throws IOException
      Writes the "Team,Name" table: the teams (see groupByTeam(List)) balanced across the given number of column pairs, filling column by column, with one row per student. Columns are balanced by number of teams, not number of students, so that a team is never split across two columns.
      Parameters:
      writer - where to write the CSV
      entries - the entries, in order
      columns - the number of "Team,Name" column pairs, at least 1
      Throws:
      IOException - if writing fails
      IllegalArgumentException - if columns is less than 1
    • writeFormattedTeamsCsv

      public void writeFormattedTeamsCsv(Writer writer, List<NameAndTeam> entries) throws IOException
      Writes the formatted teams CSV with NAMES_PER_COLUMN names and TEAMS_PER_COLUMN teams per column; see writeFormattedTeamsCsv(Writer, List, int, int).
      Parameters:
      writer - where to write the CSV
      entries - the entries, in order
      Throws:
      IOException - if writing fails
    • writeFormattedTeamsCsv

      public void writeFormattedTeamsCsv(Writer writer, List<NameAndTeam> entries, int namesPerColumn, int teamsPerColumn) throws IOException
      Writes the formatted teams CSV: two tables, one after the other, each preceded by a title line. The "by name" table lists every entry in "Name,Team" column pairs of namesPerColumn rows each; the "by team" table lists the teams (see groupByTeam(List)) and their members in "Team,Name" column pairs of teamsPerColumn teams each, so a team is never split. Both fill column by column and use as many columns as needed. Imported into a spreadsheet, the file only needs formatting and splitting into two tabs to become a team sheet.
      Parameters:
      writer - where to write the CSV
      entries - the entries, in order
      namesPerColumn - the most names in one column of the "by name" table, at least 1
      teamsPerColumn - the most teams in one column of the "by team" table, at least 1
      Throws:
      IOException - if writing fails
      IllegalArgumentException - if namesPerColumn or teamsPerColumn is less than 1