Launch the IDE and create a project squarer.proj that contains squarer.c as its only source file. Change the project settings the following way:

• set the project type to "Shared Library"

• set the file name to "squarer" (under "PPC project")

• remove __start as the "Main" entry point (under "Linker")

• set "use #pragma" (under "PEF")

You can then make the shared library.

squarer.c: (the shared library)

extern "C" int squarer(int);

#pragma export on
int  squarer(int x)
{
  return x*x;
}
#pragma export off

The #pragma primitive tells the linker which symbols to export from the shared library. Without it, the function squarer() would be invisible from the executable. Also, squarer() is declared as extern C to avoid C++ name mangling.

Now create another project for the application that's going to call squarer(). This one takes the default project settings. Add main.c and the shared library squarer to the project, and make your application.

main.c: (the executable that links against the shared library)

#include <stdio.h>

extern "C" int squarer(int);

int main(int argc, char **argv)
{
  int    n;

  n = squarer(5);
  printf("> squarer(5) = %d\n", n);
}

In the <app_dir> (i.e., the directory that the application lives in), create a directory named lib and copy "squarer" into it. The kernel loader automatically looks in <app_dir>/lib for shared libraries (in addition to looking in the system-defined library directories).

Launch the application from the shell, and you'll see the expected result

$ squarer
> squarer(5) = 25

"Very good," you think, "but je suis francais—I want to use her as an add-on!"

Shared libraries and add-ons are built exactly the same way (remember, they're structurally identical). So we don't have to do anything different to build "squarer". "squarer" does not change, but the way the function squarer() is invoked does.

Here's the new version of main.c:

#include <stdio.h>
#include <image.h>

int main(int argc, char **argv)
{
  int n;
  int (*squarer)(int);
  image_id aoid;

  aoid = load_add_on("squarer");
  if (aoid < 0) {
    printf("problems loading the add-on\n");
    return 1;
  }
  if (get_image_symbol(aoid, "squarer",
        B_SYMBOL_TYPE_TEXT, &squarer)) {
    printf("problems finding symbol 'squarer'\n");
    return 1;
  }

  n = (*squarer)(5);
  printf("squarer(5) = %d\n", n);

  unload_add_on(aoid);
}

The code is pretty much self-explanatory. get_image_symbol() takes B_SYMBOL_TYPE_TEXT as a parameter to indicate the symbol is a function.

Copy squarer into a directory add-ons that you create in the app's directory—that's where load_add_on() will look for the add-on. Run the application, and you'll get the same result. But the important difference is that you can now load any add-on, and, as long as it respects our convention (i.e., if it defines a function int squarer(int)), you can use its services.

Where should you put your shared libraries and add-ons? When asked to load a shared library or an add-on, the system uses an environment variables in its search: LIBRARY_PATH (for libraries) and ADDON_PATH (for add-ons). Each is a list of paths using a colon (":") as a separator.

LIBRARY_PATH is set by default to:

%A/lib:/boot/home/config/lib:/boot/beos/system/lib

Where %A is means the app directory. You see now why we have put the shared library "squarer" in a directory named lib/.

As for which branch of the search path to put your library in, the convention is the following:

• If the library is application specific, put it in %A/lib.

• If it can be of some use to applications from other third parties, put it in /boot/home/config/lib.

• DON'T put it in /boot/beos/system/lib. This directory is reserved for system libraries.

Note an interesting use of the %A/lib directory. If you ship some application on a CD that relies on a certain version of the system libraries (libroot.so and libbe.so for example), you can very well include those on the CD in that %A/lib directory. They will automatically override the libraries in /boot/beos/system/lib for your application, but not for other applications. This way, you can be sure that your application will run, no matter what version of the system software is currently installed on the user's machine, and it won't mess up the rest of the system. No more installation nightmares.

In a similar manner, ADDON_PATH is set by default to:

%A/add-ons:/boot/home/config/add-ons:/boot/beos/system/add-ons

The "branch" rules are the same as with libraries:

• An application-specific add-on should be put in %A/add-ons.

• An add-on that's intended to be shared by different applications would end up in /boot/home/config/add-ons.

• /boot/beos/system/add-ons is reserved for system add-ons.

Also note that you can use symbolic links in combination with the %A/lib or %A/add-ons directories. %A refers to the directory of the real (resolved) application, not of the link. For example:

/boot/home/fred is a symbolic link to /boot/apps/myapps/fred; when /boot/home/fred is launched, %A refers to /boot/apps/myapps. This makes it possible to hide the lib/ and add-ons/ directories from the user.

Only your imagination limits what you can do with libraries and add-ons. We at Be have been using them quite a bit in interesting manners. But we count on you to get the best out of them and invent other powerful uses.

This is probably the first question that crosses a developer's mind, even if you're developing in FORTRAN: how does strlen() work with UTF-8 text? Well, it's simple, strlen() counts the number of bytes in a string until it encounters a null-terminator (a byte with a value of 0). Since UTF-8 is backwards compatible with plain old ASCII, a null-character is still a null-character is still a null-character. So, that's that: strlen() will still work as expected with UTF-8. That is, it will return the number of bytes, not the number of characters (or glyphs) in your string.

In a multibyte encoding method such as UTF-8, a byte-count is different from a count of characters (which, incidentally, is why the function BTextView::SetMaxChars() was renamed to BTextView::SetMaxBytes()). This might seem strange (or even bad) at first, but it's actually a good thing. After all, malloc() could care less how many instances of Japanese characters there are in a string when you're trying to allocate some memory into which to copy it.

What if you want to know how many bytes a character is, so that the number of characters in a string can be calculated? First of all, you should consider carefully whether it is indeed necessary for you to know this information. Again, functions such as strchr(), strcpy(), strlen(), and strstr() work as-is with UTF-8. (This is true not only for the BeOS, but for UTF-8 text processing in general.)

Byte-lengths of characters are an issue only if there is potential for something to clobber portions of a multibyte character. For example, a text engine needs to be aware of a character's length so that it knows how many bytes to traverse when the user moves the insertion point.

OK, you're convinced that you need to know how to measure a character's length. One approach is to simply iterate through the bytes, counting from one initial byte to another. Another more exciting approach, however, is to use Pierre's Uber-inline:

inline uint32
utf8_char_len(uchar byte)
{
  return (((0xE5000000 >> ((byte >> 3) & 0x1E)) & 3) + 1);
}

When given an initial UTF-8 byte, the above inline will tell you the number of bytes (from 1 to 4) in the character that the initial byte represents. It's a hairy inline, and, to be honest (here's the confession part), I'm not so sure I could explain how it works...it just does. Keep in mind that the inline looks only at the initial byte of the character, and therefore does not verify that the following bytes actually make any sense when construed as a UTF-8 character.

So, with the help of Pierre's inline, you could count the number of characters in a string as follows:

uint32 numChars = 0;
for (uint32 i = 0; string[i] != '\0'; numChars++)
  i += utf8_char_len(string[i]);

A similar but more subtle issue arises with functions such as tolower(). Many (if not all) of the toXXX()/isXXX() functions in ctype.h are not UTF-8 aware. They will fail or even munge your UTF-8 data, so beware. The proper implementations of those functions require the use of carefully crafted mapping tables. A less accurate, but often sufficient, implementation is to use those functions only on 7-bit ASCII data. Something like:

inline uchar
utf8_safe_tolower(uchar byte)
{
  return ((byte < 0x80) ? tolower(byte) : byte);
}

Take a look at the Support Kit when you receive your copy of the Preview Release. There are two UTF-8 conversion routines in a new header file called (surprise!) UTF8.h. convert_to_utf8() and convert_from_utf8() are already documented in The Be Book, look there for more details. Also, if you simply want to convert some non-UTF-8 files, try out a little tool called xtou in /bin. Its usage is pretty straight-forward; do the following in a shell if you want to convert your ISO 8859-1 document to UTF-8:

$ xtou -f iso1 my_iso1_file

You can optionally specify the -n option to convert carriage-returns to newlines (useful for Mac files).

There is an inherent slowness to synchronous server calls because of the associated messaging (client to server, then back to client) overhead. Since BFont::StringWidth() (and the BView equivalent) relies on the App_Server for font metrics information, repeated calls to StringWidth() can be costly. The solution is to cache this information wherever sensible. For example, if you have an object that draws a line under some text, it might make sense for you to cache the string's width so as to avoid the gratuitous calling of StringWidth(). Ming tells me that the price of a float at Fry's is ridiculously cheap these days, so don't be too shy about equipping your classes with another member variable or two.

If you're writing, say, a text engine or a web browser (read: something string-width intensive), simply caching a single string's width might not be what you want. You probably want to be able to find out any string's width without incurring the messaging overhead each time. Sounds like you want your own StringWidth() function.

I happened to have such a "width buffer" object, and did some profiling with it. BStopWatch revealed the potential performance boost of a local string-width mechanism to be significant. On average, it took a version of NetPositive that did no caching roughly 530 microseconds to calculate the various strings (one at a time) in its default page. With caching enabled, the number went down to 54 microseconds.

I'll save the implementation details of my width buffer class for another article, but here are some things to remember if you decide to write your own.

• Escapements rule. As long as you don't rely on B_STRING_SPACING mode, you can store the escapements of the individual characters on a per font style (and potentially size) basis, and then use those values to calculate the pixel width of any string. As usual, The Be Book has much information on this topic, as does Pierre's recent two-part article, "The New Font Engine, PART 1 and 2" (issues 76 and 77 of the Be Newsletter).

• Don't assume 256. Remember, we use UTF-8. Creating a statically sized table of 256 items is not sufficient. Neither is pre-allocating a table for the entire Unicode code space. I implemented my class using a simple linear probing hash table.

• Keep App_Server calls to a minimum. The whole point of caching things locally is to avoid the number of actual App_Server calls. For example, BFont::GetEscapements() allows for multiple characters to be measured per call. Every call counts.

That's it! Hope you get to know and love UTF-8 as much as Ron and I do.