Add APIs to convert between phone and bopomofo

[czchen]

Phone is exported via chewing_get_phoneSeq(). However, the phone is meaningless if libchewing does not provide an API to convert it to bopomofo. We shall provide an API to convert phone to bopomofo.

[StanleyDing]

@czchen Hi, I believe the function PhoneFromUint() is what you are seeking. It takes a 16-bit integer and converts it back to phones.

[czchen]

PhoneFromUint() is a private API, and we need a public API.

[StanleyDing]

I shall implement it.

[StanleyDing]

Currently, whenever you want to get bopomofo from a single Uint or a sequence of Uint, you have to provide a buffer that is large enough to hold bopomofos. Functions like PhoneFromUint(), BopomofoFromUintArray() and chewing_userphrase_get() all work in this way.

It's rather difficult to determine the correct size of the buffer especially when a developer don't know the implementation of these functions and the format used. If the provided buffer is too small, the result will only contains parts of the bopomofo, and if the provided buffer is too large, it's not practical.

I think the better way is to return a allocated string that contains the bopomofos and urge the programmer to free it later. In such way, programmer can focus on dealing with the string and don't have to worry about the buffer size.

Since this will be a huge change, I would like to hear about your opinions.

[czchen]

Just like snprintf, the API can return buffer length for bopomofo so that caller can prepare enough buffer for it.

In previous experience, the allocated API is not recommended because caller cannot use the memory allocated by libchewing. It still needs to copy it to its internal structure. If the buffer is prepared by caller, we can save malloc, free, and copy parts.

[StanleyDing]

Comment delete. I see the problem!

[school510587]

Some member got confused about the meaning of "phone" in chewing_get_phoneSeq and key2pho.c [0]
Phone in chewing_get_phoneSeq represents Uint in key2pho.c, but phone in key2pho.c stands for the UTF8-encoded Bopomofo string.
Should we solve this inconsistency?
EG. Rename some functions in key2pho.c. The name Uint seems not obviously related to Bopomofo.

[0] https://groups.google.com/forum/#!topic/chewing-devel/Qj4bdZtN2ZA