String class Translation

NOTE:

These are a little sketchy...I'll fill in details 'soon'.

Translation of String Contents to Integers

we want to be able to convert the contents of a String object to the typical built-in types. this translation can be thought of as changing a stream of characters into a single value. this leads us to the idea of inputing values from a stream (like cin). if you think about it, istreams are just translating the stream of characters from either the keyboard or a file into built-in types for storage. maybe we could use the >> operator for translation from String (just as the iostream library uses it for 'translation' from a stream).
we've already looked at this in an earlier lab or two. so we'll probably want to have our String class reuse our Cstring translation functions (so we incur less work).
so now we just need to write the bodies and make sure we know where we are translating from within our data string. here's a first shot at translating to long integer:
```
const String & String::operator>>(long & data) const
{
    str_to_long(string, data, translate_position);
    return *this;
}
```
notice that we call the earlier defined str_to_long function. it's arguments are a const Cstring, a reference to a long for the data value, and a reference to the position within the Cstring to translate from (which becomes where the translation stopped). then we return the String object so the programmer can cascade their calls like with the istream objects.

however, we've forgotten several things. first we must watch for the state of the translation. just like an istream object, we need to watch for end-of-strING and failed translation. (of course, we can skip physical disk failure checking, as we mentioned before.):

const String & String::operator>>(long & data) const
{
    long remember_position = translate_position;
    str_to_long(string, data, translate_position);
    clear((translate_position==remember_position)
              ?(failbit)
              :((translate_position > length)
                  ?(eosbit)
                  :(goodbit)));
    return *this;
}

here we hold on to the current translation position in a local variable. then we call our translation function to do its work. finally, we look at the translation position that results (recall it is a reference argument). if the translation position hasn't moved from our remembered version, we must have failed to translate anything. otherwise, if the translation position is now beyond the length of the string, we can set the end-of-string flag. if neither of those is the case, we can set the good flag.

not bad. however, there are certain circumstances to be looked into. what if the String were already in a failed state when this operation is called? what would an istream do? it would ignore the call. so, then, should we:

const String & String::operator>>(long & data) const
{
    long remember_position = translate_position;
    if (good())
    {
        str_to_long(string, data, translate_position);
        clear((translate_position==remember_position)
                  ?(failbit)
                  :((translate_position > length)
                      ?(eosbit)
                      :(goodbit)));
    }
    return *this;
}

only if we are in a good state will we proceed. otherwise we return ourselves unchanged (even in a translation-sort-of-way).

and what about the case where there are leading spaces. well, we know that we are supposed to be able to ignore leading spaces. and the str_to_long function will. but what if it finds some invalid character after a bunch of spaces. well, it won't (probably) deal with moving the translation position back to before the spaces. oops...we should watch for that:

const String & String::operator>>(long & data) const
{
    long remember_position;
    skipws();
    remember_position = translate_position;
    if (good())
    {
        str_to_long(string, data, translate_position);
        clear((translate_position==remember_position)
                  ?(failbit)
                  :((translate_position > length)
                      ?(eosbit)
                      :(goodbit)));
    }
    return *this;
}

of course it is a complete matter of opinion as to whether our object should move back to before the spaces when a translation fails. that'll be up to you.

having finished off long integers, how about short integers? they are very similar, just having a shortened range. what is that range? well, the limits header has constants which define the sizes for all discrete types. the constants for short integer are SHRT_MAX and SHRT_MIN (oddly enough). so:

const String & String::operator>>(short & data) const
{
    long remember_position = translate_position, test_data;
    *this >> test_data;
    if (good())
    {
        if (test_data > SHRT_MAX || test_data < SHRT_MIN)
        {
            seekg(remember_position);
            clear(failbit);
        }
        else
        {
            data = test_data;
            clear((translate_position==remember_position)
                      ?(failbit)
                      :((translate_position > length)
                          ?(eosbit)
                          :(goodbit)));
        }
    }
    return *this;
}

of course, thinking through this, we see a bit of redundancy and remove it:

const String & String::operator>>(short & data) const
{
    long remember_position = translate_position, test_data;
    *this >> test_data;
    if (good())
    {
        if (test_data > SHRT_MAX || test_data < SHRT_MIN)
        {
            seekg(remember_position);
            clear(failbit);
        }
        else
        {
            data = test_data;
        }
    }
    return *this;
}

after all, our call to our sibling operator for long integers has already set the eosbit and failbit if things didn't go okay. all we have to take care of is the range checking!
then, further thought leads us back to the question of whether our operator should remember the position before spaces when a translation failure occurs. looking at our range error, we see that it does, indeed, reset to the pre-space position. there are two ways to fix this: change the short translator or change the long translator. again, it is up to you as to which you prefer. I'll show the change to the short translator here:
```
const String & String::operator>>(short & data) const
{
    long remember_position, test_data;
    skipws();
    remember_position = translate_position;
    *this >> test_data;
    if (good())
    {
        if (test_data > SHRT_MAX || test_data < SHRT_MIN)
        {
            seekg(remember_position);
            clear(failbit);
        }
        else
        {
            data = test_data;
        }
    }
    return *this;
}
```
I've done this here not because I feel it is the better solution (I'd rather the String back up to before the spaces) but because it is the simpler and easier to understand.

Other Built-In Data Types

the rest of the translations are quite similar: str_to_double is called for both double and float (FLT_MAX and FLT_MIN are found in the float header file), str_to_char is called for character, and str_to_bool can be done in several ways to your taste.

But Isn't String Supposed to Behave Like a Built-In Type?

lastly, we treat our own class as a built-in type, so why not allow translation of String to String (extraction of a String object from another String object):

const String & String::operator>>(String & data) const
{
    long remember_position;
    if (good())
    {
        skipws();
        remember_position = translate_position;
        while (!isspace(string[translate_position]) &&
               (string[translate_position] != EOS))
        {
            translate_position++;
        }
        data.destroy();
        data.alloc_val(translate_position-remember_position);
        data.copy_val(string+remember_position);
        clear((translate_position > length) ? (eosbit) : (goodbit));
    }
    return *this;
}

note how we re-use our constructor utility functions here with a bit of pointer math to make our jobs much simpler.
also note how we've only checked for an end-of-string condition. translation to a String object cannot fail -- it can only run out of data.

we could also use a String::getline sort of feature for translating a String from another String until an arbitrary stop character. (remember that istream::getline actually has a default argument which is '\n' for the character to stop at.) of course, being a String object, we could offer them more power -- stop at any of a group of characters. here's a start:

long String::getline(String & data,
                     const String & stop_at_any = String('\n')) const
{
    long remember_position = translate_position;
    if (good())
    {                          // note this use of our find operator
        while (((string[translate_position] ^ stop_at_any) == -1) &&
               (string[translate_position] != EOS))
        {
            translate_position++;
        }
        data.alloc_val(translate_position-remember_position);
        data.copy_val(string+remember_position);
        clear((translate_position > length) ? (eosbit) : (goodbit));
    }
    return data.length;
}

the only thing is, what if the data didn't get changed (we are in a bad state)? let's make a slight change to the return statement:
```
    return (remember_position == translate_position) ? (0) : (data.length);
```
much better...!