Package cs1302.oracle

Class OracleStringList

java.lang.Object

cs1302.oracle.OracleStringList

All Implemented Interfaces:

StringList

public class OracleStringList
extends Object
implements StringList

Oracle implementation of a StringList. For the purposes of your project, an object of this OracleStringList class is called an oracle. Some examples that illustrate how you might use an oracle can be found here.

Constructor Summary

Constructors

Constructor	Description
OracleStringList()	Construct an empty oracle string list.

Method Summary

Modifier and Type	Method	Description
boolean	add(int index, StringList itemList)	Inserts multiple items into this string list at the specified index position.
boolean	add(int index, String item)	Inserts an item into this string list at the specified index position.
void	clear()	Removes all of the items from this string list.
boolean	contains(int start, String target)	Returns true if start >= 0 and there exists an item at or after the start index that equals the target string.
String	get(int index)	Returns the item at the specified index position in this string list.
boolean	isEmpty()	Returns true if this string list has no items.
String	makeString(String start, String sep, String end)	Returns a string representation of this string list that begins with start and ends with end, with every string in the string list separated by sep.
String	remove(int index)	Removes the item at the specified index position in this string list.
StringList	reverse()	Returns a new string list that contains the items from this string list in reverse order.
int	size()	Returns the number of items in this string list.
StringList	slice(int start, int stop)	Returns a new string list that contains the items from this list between the specified start index (inclusive) and stop index (exclusive).
String	toString()	Returns makeString("[", ", ", "]").

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Details

OracleStringList

public OracleStringList()

Construct an empty oracle string list.

Method Details

size

public int size()

Returns the number of items in this string list.

Specified by:

size in interface StringList

Returns:

the number of items in this string list

isEmpty

public boolean isEmpty()

Returns true if this string list has no items. More formally, a string list is empty if, and only if, its size is zero.

Specified by:

isEmpty in interface StringList

Returns:

true if this string list is empty; false otherwise

add

public boolean add(int index,
 String item)

Inserts an item into this string list at the specified index position. If an item was already at that position, then that item and subsequent items are shifted to the right (i.e., one is added to their indices).

This method either returns true or throws one of its documented exceptions, but never both.

Specified by:

add in interface StringList

Parameters:

index - index at which the specified string is to be inserted

item - item to be inserted

Returns:

true if this list changed as a result of the call

add

public boolean add(int index,
 StringList itemList)

Inserts multiple items into this string list at the specified index position. The relative order of inserted items is preserved. If items were already at that or subsequent positions, then those items are shifted to the right (i.e., itemList.size() is added to their indices).

Instead of inserting items into a string list one at a time, this method enables users to insert multiple items into a string list all at once. Here are some examples:

 // first list
 StringList list1 = new OracleStringList();
 list1.add(0, "a");
 list1.add(1, "b");

 // second list
 StringList list2 = new OracleStringList();
 list2.add(0, "0");
 list2.add(1, "1");

 // insert second list into first list
 list1.add(1, list2);
 System.out.println(list1); // [a, 0, 1, b]

 // insert modified first list into itself
 list1.add(1, list1);
 System.out.println(list1); // [a, a, 0, 1, b, 0, 1, b]
 

The last code snippet shown above is an example of self-reference; that is, it is a scenario where the source and destination objects are the very same object. This is allowed! Implementers should take special care to avoid accidental infinite loops in situations involving self reference since the size of the source string list may change as items are inserted into the destination string list.

This method should return !itemList.isEmpty() or throw one of its documented exceptions, but never both. It should also support self-reference as described above; that is, a call to this method should still work when itemList refers to the calling string list object itself.

Specified by:

add in interface StringList

Parameters:

index - index at which the specified items are to be inserted

itemList - string list of items to be inserted

Returns:

true if this list changed as a result of the call

get

public String get(int index)

Returns the item at the specified index position in this string list.

Specified by:

get in interface StringList

Parameters:

index - index of the item to return

Returns:

the item at the specified position in this string list

remove

public String remove(int index)

Removes the item at the specified index position in this string list. Any items in the string list that were after the removed string are shifted to the left (i.e., one is subtracted from their indices).

Specified by:

remove in interface StringList

Parameters:

index - index of the item to remove

Returns:

the string that was removed

makeString

public String makeString(String start,
 String sep,
 String end)

Returns a string representation of this string list that begins with start and ends with end, with every string in the string list separated by sep. Here is an example, assuming list refers to an empty StringList:

 String result1 = list.makeString("~", "!", "#");
 String result2 = list.makeString(null, null, null);
 list.add(0, "a");
 list.add(1, "b");
 list.add(2, "c");
 String result3 = list.makeString("~", "!", "#");
 String result4 = list.makeString(null, null, null);

 System.out.println(result1);
 System.out.println(result2);
 System.out.println(result3);
 System.out.println(result4);
 

The output would be:

 ~#
 nullnull
 ~a!b!c#
 nullanullbnullcnull
 

Each argument to this method may be null. If null is used for an argument, then "null" should be used. This is consistent with the regular rules for string concatenation and does not usually require any extra code to handle (i.e., you don't usually need an extra case to handle this).

Specified by:

makeString in interface StringList

Parameters:

start - specified starting string

sep - the specified separator string

end - the specified ending string

Returns:

a string representation of this string list that begins with start and ends with end, with every string in the string list separated by sep

toString

public String toString()

Returns makeString("[", ", ", "]").

Specified by:

toString in interface StringList

Overrides:

toString in class Object

Returns:

makeString("[", ", ", "]")

clear

public void clear()

Removes all of the items from this string list. The string list will be empty after this method returns.

Specified by:

clear in interface StringList

slice

public StringList slice(int start,
 int stop)

Returns a new string list that contains the items from this list between the specified start index (inclusive) and stop index (exclusive). This method does not modify the calling object. If start and stop are in bounds and equal, then the returned string list is empty. The returned string list must be an object of the same class as the calling object. Here is an example, assuming list refers to a non-empty string list with items referring to "a", "b", "c", and "d":

 System.out.println(list);    // [a, b, c, d]

 StringList slice0 = list.slice(0, 4);
 System.out.println(slice0);  // [a, b, c, d]
 System.out.println(list);    // [a, b, c, d]

 StringList slice1 = list.slice(1, 3);
 System.out.println(slice1);  // [b, c]
 System.out.println(list);    // [a, b, c, d]

 StringList slice2 = list.slice(2, 4);
 System.out.println(slice2);  // [c, d]
 System.out.println(list);    // [a, b, c, d]

 StringList slice3 = list.slice(1, 1);
 System.out.println(slice3);  // []
 System.out.println(list);    // [a, b, c, d]

The "calling object" in the method description refers to the object that you call slice on. For example, if you call list.slice(0, 1) and list refers to an ArrayStringList object, then list.slice(0, 1) should return a reference to a new ArrayStringList object containing the desired items. Since ArrayStringList is compatible with StringList, the object's reference can be returned without casting and without modifying the method's return type.

Specified by:

slice in interface StringList

Parameters:

start - left endpoint (inclusive) of the slice

stop - right endpoint (exclusive) of the slice

Returns:

a new string list with the items from this list from start (inclusive) to stop (exclusive)

reverse

public StringList reverse()

Returns a new string list that contains the items from this string list in reverse order. The returned string list must be an object of the same class as the calling object.

Specified by:

reverse in interface StringList

Returns:

a new string list with items from this list in reverse order

contains

public boolean contains(int start,
 String target)

Returns true if start >= 0 and there exists an item at or after the start index that equals the target string. If no such item exists, then false is returned. Unlike the add methods that throws exceptions when called with bad arguments, this contains method simply returns false instead.

Specified by:

contains in interface StringList

Parameters:

start - the index from which to start the search

target - the item to search for

Returns:

true if there exists an item at or after start such that item.equals(target), or false if there is no such occurrence