If you’ve used Android’s Notepad tutorial (Version 3) , or modeled your own Activity on Notepadv3, then you’ve probably seen log messages that look something like this:

android.database.sqlite.DatabaseObjectNotClosedException:
    Application did not close the cursor or database object that was opened here
at android.database.sqlite.SQLiteCompiledSql.<init>(SQLiteCompiledSql.java:62)
at android.database.sqlite.SQLiteProgram.<init>(SQLiteProgram.java:80)
at android.database.sqlite.SQLiteStatement.<init>(SQLiteStatement.java:36)
at android.database.sqlite.SQLiteDatabase.compileStatement(SQLiteDatabase.java:1145)
at android.database.sqlite.SQLiteDatabase.updateWithOnConflict(SQLiteDatabase.java:1671)
at android.database.sqlite.SQLiteDatabase.update(SQLiteDatabase.java:1622)
at com.android.demo.notepad3.NotesDbAdapter.updateNote(NotesDbAdapter.java:186)
at com.android.demo.notepad3.NoteEdit.saveState(NoteEdit.java:106)
at com.android.demo.notepad3.NoteEdit.onPause(NoteEdit.java:87)
at android.app.Activity.performPause(Activity.java:3842)
at android.app.Instrumentation.callActivityOnPause(Instrumentation.java:1190)
at android.app.ActivityThread.performPauseActivity(ActivityThread.java:3335)
at android.app.ActivityThread.performPauseActivity(ActivityThread.java:3305)
at android.app.ActivityThread.handlePauseActivity(ActivityThread.java:3288)
at android.app.ActivityThread.access$2500(ActivityThread.java:125)
at android.app.ActivityThread$H.handleMessage(ActivityThread.java:2044)
at android.os.Handler.dispatchMessage(Handler.java:99)
at android.os.Looper.loop(Looper.java:123)
at android.app.ActivityThread.main(ActivityThread.java:4627)
at java.lang.reflect.Method.invokeNative(Native Method)
at java.lang.reflect.Method.invoke(Method.java:521)
at com.android.internal.os.ZygoteInit$MethodAndArgsCaller.run(ZygoteInit.java:868)
at com.android.internal.os.ZygoteInit.main(ZygoteInit.java:626)
at dalvik.system.NativeStart.main(Native Method)

This is resolved easily enough by overriding the onDestroy method in each of the Activities in your application — or at least, each Activity that uses the database. In the Notepadv3 app, this means overriding onDestroy in both the Notepadv3 and NoteEdit classes. The same definition is suitable for both classes:

    public void onDestroy() {
        super.onDestroy();

        // Replace mDbHelper as needed with your database connection, or
        // whatever wraps your database connection. (See below.)
        mDbHelper.close();
    }

In the Notepadv3 tutorial, the mDbHelper field is an instance of the class NotesDbAdapter, which wraps the database connection. NotesDbAdapter comes from google with the close method already defined, but there’s no code that calls it. With this change, we’re supplying the code that calls close at the right time. (I think.)

In general: If your activity opens a database by calling either SQLiteOpenHelper.getReadableDatabase or SQLiteOpenHelper.getWritableDatabase, then you should rely on SQLiteOpenHelper.close to close that database. Your activity’s onDestroy method must result in a call to the close method for any instances of SQLiteOpenHelper, or classes derived from it, that you’ve created. (In the code above, mDbHelper.close will have that effect.) SQLiteOpenHelper.close will then close any database handle that it created for you.

It’s often the case that bulk insertions are performed in the onCreate method of an SQLiteOpenHelper, so I’ll use that context for this example. (This has implications on transaction management, which in turn affects performance, as described below.)

Suppose the onCreate method currently looks something like this:

private class DatabaseHelper extends SQLiteOpenHelper {
    @Override
    public void onCreate(SQLiteDatabase db) {
        ContentValues values = new ContentValues();
        while (moreRowsToInsert) {
            // ... create the data for this row (not shown) ...

            // Add the data for each column
            values.put("Greek", greekData);
            values.put("Ionic", ionicData);
            // ...
            values.put("Roman", romanData);

            // Insert the row into the database.
            db.insert("columnTable", null, values);
        }
    }
    //...
}

Using DatabaseUtils.InsertHelper, this would be re-written as:

import android.database.DatabaseUtils.InsertHelper;
//...
private class DatabaseHelper extends SQLiteOpenHelper {
    @Override
    public void onCreate(SQLiteDatabase db) {
        // Create a single InsertHelper to handle this set of insertions.
        InsertHelper ih = new InsertHelper(db, "columnTable");

        // Get the numeric indexes for each of the columns that we're updating
        final int greekColumn = ih.getColumnIndex("Greek");
        final int ionicColumn = ih.getColumnIndex("Ionic");
        //...
        final int romanColumn = ih.getColumnIndex("Roman");

        while (moreRowsToInsert) {
            // ... Create the data for this row (not shown) ...

            // Get the InsertHelper ready to insert a single row
            ih.prepareForInsert();

            // Add the data for each column
            ih.bind(greekColumn, greekData);
            ih.bind(ionicColumn, ionicData);
            //...
            ih.bind(romanColumn, romanData);

            // Insert the row into the database.
            ih.execute();
        }
    }
    //...
}

As this shows, using InsertHelper is barely more complicated than using SQLiteDatabase.insert. The major differences are that you need to call ih.prepareForInsert() before adding (“binding”) the column data; and you need to obtain each column’s numeric index, which we get by calling ih.getColumnIndex() prior to the loop.

After replacing SQLiteDatabase.insert with DatabaseUtils.InsertHelper, the database insertion speed went from the equivalent of about 95 rows per second to about 525 rows per second. (“Equivalent of”, because the app also spends cycles creating the data to insert. Here, the performance timings are measured using constant data, eliminating that overhead.)

Other ways to speed up insertions

In addition to that gain, two more changes then brought the insertion speed to well over 900 rows per second. Whether these tricks techniques work for you will depend on your application.

Don’t bind empty columns

In my app, the data for at least 50% of the columns is empty. By skipping the call to ih.bind() when the column data is a null or empty string, I saw a roughly 30% performance boost.

Temporarily disable database thread locking

I’m loading the database during the onCreate method of my app’s SQLiteOpenHelper. During this time, it seems safe to assume that only one thread is accessing the database, so I use SQLiteDatabase.setLockingEnabled() to temporarily (let me emphasize that: temporarily) disable thread locks within the database API. This yielded about a 35% performance gain:

    public void onCreate(SQLiteDatabase db) {
    //...
    try {
        // *Temporarily* (have I emphasized that enough?) disable
        // thread locking in the database. Be sure to re-enable locking
        // within a finally block.
        db.setLockingEnabled(false);
        // ... load the database ...
    }
    finally {
        db.setLockingEnabled(true);
    }

Transactions and performance

A number of people have cited performance gains through use of explicit transactions in SQLite. However, SQLiteOpenHelper creates a transaction before invoking its callback methods (onCreate, onUpgrade, and onOpen), so explicit transaction control is unnecessary within those methods. (SQLiteOpenHelper will assume that the transaction was successful unless your method throws an exception.)

You would need to manage your own transactions if your insertion code is running outside of one of SQLiteOpenHelper‘s callback methods. The main APIs for this are SQLiteDatabase.beginTransaction, SQLiteDatabase.setTransactionSuccessful, and SQLiteDatabase.endTransaction.

It is possible to nest transactions, but, not surprisingly, this doesn’t seem to help performance. In fact, I saw a very slight performance degradation when using nested transactions (approximately 1%, probably below the accuracy of the measurements.) I also tried periodically closing the current transaction — the first of these being the transaction that was opened by SQLiteOpenHelper — then opening a new one. This didn’t yield much improvement, if any.

A bit of searching turned up this issue about using a Spinner in combination with a SimpleAdapter to display a CheckedTextView; it seems that a ViewBinder must be set on the SimpleAdapter for that combination to work. Although it’s not the same problem, it still made me wonder if the SimpleAdapter / Spinner combination might need a ViewBinder for displaying TextView, too.

I wasn’t able to reproduce the IllegalStateException when I ran a sample program on AndroidOS 2.2, but I thought I’d try it on 1.5 in the emulator. Sure enough, I hit the same problem that Chromium reported. Apparently, whatever issue this is has been fixed by 2.2, and perhaps in earlier releases. (I haven’t tried other releases besides 2.2 and 1.5.)

And I also found that ViewBinder once again comes to the rescue, preventing the IllegalStateException from being thrown.

Like some other interfaces in Android (I’m looking at you, CursorToStringConverter. You too, FilterQueryProvider), ViewBinder’s bark is worse than its bite. In other words, the name may be a bit intimidating, but the implementation is a breeze.

Here’s a sample program, adapted from Chromium’s example, that adds a ViewBinder to a SimpleAdapter. This works on AndroidOS 1.5 and 2.2 (and, presumably, intermediate versions as well.)

package org.oowb.HelloSpinner;

import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

import android.app.Activity;
import android.os.Bundle;
import android.view.View;
import android.widget.AdapterView;
import android.widget.SimpleAdapter;
import android.widget.Spinner;
import android.widget.TextView;
import android.widget.Toast;
import android.widget.AdapterView.OnItemSelectedListener;

/**
 *  Displays a list of colors in a Spinner.
 */
public class HelloSpinner extends Activity {
    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.main);

        // The key to use for reading the color from the Map
        final String[] from = new String[] { "color" };

        // The type of View to use for displaying the color name.
        // android.R.id.text1 is a standard resource for displaying text.
        final int[] to = new int[] { android.R.id.text1  };

        // Create the List of strings for the spinner to display. Each string
        // is embedded within a Map, using "color" as the key.
        final List<Map<String, String>> data =
            new ArrayList<Map<String, String>>();
        final String[] colors = getResources().getStringArray(R.array.colors);

        for (int i = 0; i < colors.length; i++) {
            data.add(addData(colors[i]));
        }

        final SimpleAdapter simpleAdapter =
            new SimpleAdapter(this, data,
                    android.R.layout.simple_spinner_item, from, to);
        simpleAdapter.setDropDownViewResource(
                android.R.layout.simple_spinner_dropdown_item);

        // Add a ViewBinder to display a color name in a TextView within the
        // Spinner. (This isn't needed in AndroidOS 2.2. In earlier releases,
        // when we're displaying text data within a Spinner, and no ViewBinder
        // is set in the SimpleAdapter, an IllegalStateException is thrown.)
        SimpleAdapter.ViewBinder viewBinder = new SimpleAdapter.ViewBinder() {

            public boolean setViewValue(View view, Object data,
                    String textRepresentation) {
                // We configured the SimpleAdapter to create TextViews (see
                // the 'to' array, above), so this cast should be safe:
                TextView textView = (TextView) view;
                textView.setText(textRepresentation);
                return true;
            }
        };
        simpleAdapter.setViewBinder(viewBinder);

        final Spinner spinner = (Spinner) findViewById(R.id.spinner);
        spinner.setAdapter(simpleAdapter);

        // Add an OnItemSelectedListener to display the selected Color
        spinner.setOnItemSelectedListener(new OnItemSelectedListener() {
            @Override
            public void onItemSelected(AdapterView<?> parent, View view,
                    int position, long id) {
                // Get the color name out of the Map
                final Map<String, String> data =
                    (Map<String, String>) parent.getItemAtPosition(position);
                final String text = "Selected Color:-  " + data.get("color");

                Toast.makeText(parent.getContext(), text,
                        Toast.LENGTH_LONG).show();
            }

            @Override
            public void onNothingSelected(AdapterView<?> arg0) {
                // Do nothing
            }
        });
    }

    /**
     * Convert the String that's passed in into a Map, with
     * "color" as the key, and the String as the value.
     * @param    colorName  The color to be inserted into a new Map
     * @return   the new Map
     */
    private Map<String, String> addData(String colorName) {
        Map<String, String> map = new HashMap<String, String>();
        map.put("color", colorName);
        return map;
    }
}

To complete the example, here are the layout (main.xml) and values files (arrays.xml and strings.xml):

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:orientation="vertical"
    android:padding="10dip"
    android:layout_width="fill_parent"
    android:layout_height="wrap_content">

    <Spinner
        android:id="@+id/spinner"
        android:layout_width="fill_parent"
        android:layout_height="wrap_content"
        android:drawSelectorOnTop="true"
        android:prompt="@string/prompt"
    />
</LinearLayout>

<?xml version="1.0" encoding="UTF-8"?>
<resources>
    <string-array name="colors">
        <item>Red</item>
        <item>Orange</item>
        <item>Yellow</item>
        <item>Green</item>
        <item>Blue</item>
        <item>Purple</item>
        <item>Violet</item>
        <item>Octarine</item>
    </string-array>
</resources>

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <string name="app_name">Color Chooser</string>
    <string name="prompt">Choose a color:</string>
</resources>

Earlier today, I published a lengthy examination of the work needed to supply an AutoCompleteTextView with data using a CursorAdapter. My intentions were pure, but my code was not. Where I’d seen a need for subclassing, it was because I hadn’t caught on to some of the handler methods provided by the SimpleCursorAdapter class.

Specifically, if we’re using a SimpleCursorAdapter, then:

• We don’t need to override the convertToString method, if instead we call adapter.setCursorToStringConverter.
• And there’s no need to override runQueryOnBackgroundThread, if instead we call adapter.setFilterQueryProvider.

This allows a significant refactoring of the SelectState class. Instead of the subclassed Adapter class, I’m now using anonymous inner classes to provide the cursor-to-name conversion and the filter query. The inner classes use essentially the same code as the methods that they’ve replaced.

The re-written SelectState follows. The full example can be downloaded as a ZIP file.

(See the earlier post for a description of the sample application’s functionality.)

package org.oowb.AutoCompleteExample;

import android.app.Activity;
import android.database.Cursor;
import android.os.Bundle;
import android.view.View;
import android.widget.AdapterView;
import android.widget.AutoCompleteTextView;
import android.widget.Button;
import android.widget.FilterQueryProvider;
import android.widget.SimpleCursorAdapter;
import android.widget.TextView;
import android.widget.AdapterView.OnItemClickListener;
import android.widget.SimpleCursorAdapter.CursorToStringConverter;

/**
 * A simple Android Activity to demonstrate:
 *
 * 1) How to use an AutoCompleteTextView with a SimpleCursorAdapter
 *
 * 2) How to access the cursor row for the user's choice, to obtain additional
 * data from that row when an item is selected.
 *
 * @author Dan Breslau
 *
 */
public class SelectState extends Activity {

    final static int[] to = new int[] { android.R.id.text1 };
    final static String[] from = new String[] { "state" };

    private TextView mStateCapitalView;
    private AutoCompleteTextView mStateNameView;
    private AutoCompleteDbAdapter mDbHelper;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        mDbHelper = new AutoCompleteDbAdapter(this);
        setContentView(R.layout.selectstate);
        Button confirmButton = (Button) findViewById(R.id.confirm);
        confirmButton.setOnClickListener(new View.OnClickListener() {
            public void onClick(View view) {
                setResult(RESULT_OK);
                finish();
            }
        });

        mStateCapitalView = (TextView) findViewById(R.id.state_capital);
        mStateNameView = (AutoCompleteTextView) findViewById(R.id.state_name);

        // Create a SimpleCursorAdapter for the State Name field.
        SimpleCursorAdapter adapter =
            new SimpleCursorAdapter(this,
                    android.R.layout.simple_dropdown_item_1line, null,
                    from, to);
        mStateNameView.setAdapter(adapter);

        // Set an OnItemClickListener, to update dependent fields when
        // a choice is made in the AutoCompleteTextView.
        mStateNameView.setOnItemClickListener(new OnItemClickListener() {
            public void onItemClick(AdapterView<?> listView, View view,
                        int position, long id) {
                // Get the cursor, positioned to the corresponding row in the
                // result set
                Cursor cursor = (Cursor) listView.getItemAtPosition(position);

                // Get the state's capital from this row in the database.
                String capital =
                    cursor.getString(cursor.getColumnIndexOrThrow("capital"));

                // Update the parent class's TextView
                mStateCapitalView.setText(capital);
            }
        });

        // Set the CursorToStringConverter, to provide the labels for the
        // choices to be displayed in the AutoCompleteTextView.
        adapter.setCursorToStringConverter(new CursorToStringConverter() {
            public String convertToString(android.database.Cursor cursor) {
                // Get the label for this row out of the "state" column
                final int columnIndex = cursor.getColumnIndexOrThrow("state");
                final String str = cursor.getString(columnIndex);
                return str;
            }
        });

        // Set the FilterQueryProvider, to run queries for choices
        // that match the specified input.
        adapter.setFilterQueryProvider(new FilterQueryProvider() {
            public Cursor runQuery(CharSequence constraint) {
                // Search for states whose names begin with the specified letters.
                Cursor cursor = mDbHelper.getMatchingStates(
                        (constraint != null ? constraint.toString() : null));
                return cursor;
            }
        });
    }
}

I recently integrated an AutoCompleteTextView into a prototype Android application that I’m developing. There isn’t exactly a wealth of documentation on the Web describing AutoCompleteTextView, and what I’ve found didn’t match the scenario I had in mind. Specifically:

• The choices came from a database, so I needed to use a CursorAdapter; and
• The AutoCompleteTextView had some dependent fields; changes to the value in the AutoCompleteTextView needed to be reflected in those dependent fields.

For example, let’s use a AutoCompleteTextView for choosing states. When the user chooses a state, I want to update a TextView to show the capital of the chosen state.

First the form appears with no value in the State Capital field (left); then a state is chosen from the list (right.)

After a state has been chosen, its capital is also displayed.

Adapting SQLite to AutoCompleteTextView

The documentation for AutoCompleteTextView says that it obtains suggestions from a data adapter. This should be familiar territory for anyone who’s used ListView, which also obtains its list items from a data adapter. Not surprisingly, AutoCompleteTextView uses a ListView internally.

However, ListView and AutoCompleteTextView require different interactions with their adapters. A standard ListView will typically need to fetch the list of items once, and only once. On the other hand, AutoCompleteTextView issues a query for matching choices whenever the user enters new text into the field. (In fact, the AutoCompleteTextView won’t issue a query until the user has typed some text. Hence the CursorAdapter‘s constructor can take null for the Cursor parameter.)

SimpleCursorAdapter wasn’t designed for this kind of usage pattern; in particular, it doesn’t know how you want to query for matching choices. So, you must derive from SimpleCursorAdapter, or from its base class, CursorAdapter. Your subclass must supply two methods that are essentially stubbed out in CursorAdapter:

• convertToString, which supplies the String value that is entered into the AutoCompleteTextView when a choice is made; and
• runQueryOnBackgroundThread. In this method, you invoke a query for choices that match the text entered by the user, and return a Cursor that provides the results.

Let’s take a closer look at implementing the derived CursorAdapter class.

public CharSequence convertToString(Cursor cursor)

This method receives the Cursor positioned to a specific row, and returns a String label or representation for that row.

public Cursor runQueryOnBackgroundThread(CharSequence constraint)

Just to clarify, “On Background Thread” means that this method is called in a background thread — it does not mean that you have to spawn that thread within this method.

This method runs a query to get choices that match the input. It’s up to the application to determine what constitutes a match. (In this example, I’m searching for states whose names begin with the given letters.)

The constraint parameter is the input that the user has typed in. It may be null if the user has typed, and then erased, input text. In this case, all results should be returned.

But wait, there’s more!

It might seem… well, simpler, to derive the new Adapter class from SimpleCursorAdapter. However, deriving from CursorAdapter requires only two additional methods to be implemented, newView and bindView, both of which are straightforward. Hence for this example, I’m using CursorAdapter as the base class. Later, I’ll describe the changes needed to use SimpleCursorAdapter as the base.

public View newView(Context context, Cursor cursor, ViewGroup parent)

newView returns a newly constructed View suitable for displaying a single item in the choice list. The usual method for doing this is to use the Inflater, which is given the resource ID of a layout that describes the new View. It’s not necessary to create your own layout file; Android provides a standard layout that’s appropriate for this purpose, identified by android.R.layout.simple_dropdown_item_1line.

public void bindView(View view, Context context, Cursor cursor)

This is called to display the label for the current row. If newView uses android.R.layout.simple_dropdown_item_1line for layout, then bindView will be called with a TextView as the View argument.

Updating dependent fields

To update dependent fields, start by creating a class that implements OnItemClickListener. (Here, it’s the Adapter class; it could also be your Activity, or some other class.) This interface defines a callback that’s invoked when the user makes a choice. The setOnItemClickListener method in AutoCompleteTextView associates the listener with the field.

The callback method, onItemClick, receives a position parameter that identifies the row number within the result set, starting from 0. For example, if the third state, “Arizona”, is chosen, the value of position will be 2. There’s also an AdapterView<?> parameter, whose purpose is a bit obscure. This is the ListView belonging to the AutoCompleteTextView. (This may be the only situation in which that ListView is directly exposed to the caller.)

We can then get the cursor from the AdapterView<?> parameter, and position it to the correct row, by calling getItemAtPosition. Note that getItemAtPosition returns an Object, so a cast is necessary. (It doesn’t seem to be documented anywhere that listView.getItemAtPosition will return a Cursor in this case.)

In the full example, this logic is seen in the line:

Cursor cursor = (Cursor) listView.getItemAtPosition(position)

The result would probably be the same if we replaced the above line with:

            Cursor cursor = getCursor();
            cursor.moveToPosition(position);

I went with the first approach because: 1) It’s (arguably) more in keeping with the Adapter’s contract. (There doesn’t seem to be any guarantee that changeCursor will be called by the main thread; without that call, getCursor() certainly won’t work.) And 2) it’s simpler, if by “simpler” we mean one less line of code.

The code

Now let’s have a look at the code. Here’s the Activity class, SelectState, with its nested Adapter class, ItemAutoTextAdapter. (The other class needed for this example, AutoCompleteDbAdapter, is available below.)

package org.oowb.AutoCompleteExample;

import android.app.Activity;
import android.content.Context;
import android.database.Cursor;
import android.os.Bundle;
import android.view.LayoutInflater;
import android.view.View;
import android.view.ViewGroup;
import android.widget.AdapterView;
import android.widget.AutoCompleteTextView;
import android.widget.Button;
import android.widget.CursorAdapter;
import android.widget.TextView;

/**
 * A simple Android Activity to demonstrate:
 *
 * 1) How to use an AutoCompleteTextView with a CursorAdapter
 *
 * 2) How to access the cursor row for the user's choice, to obtain
 *    additional data from that row when an item is selected.
 *
 * @author Dan Breslau
 *
 */
public class SelectState extends Activity {
    /**
     * Specializes CursorAdapter to supply choices to a AutoCompleteTextView.
     * Also implements OnItemClickListener to be notified when a choice is made,
     * and uses the choice to update other fields on the Activity form.
     */
    class ItemAutoTextAdapter extends CursorAdapter
            implements android.widget.AdapterView.OnItemClickListener {

        private AutoCompleteDbAdapter mDbHelper;

        /**
         * Constructor. Note that no cursor is needed when we create the
         * adapter. Instead, cursors are created on demand when completions are
         * needed for the field. (see
         * {@link ItemAutoTextAdapter#runQueryOnBackgroundThread(CharSequence)}.)
         *
         * @param dbHelper
         *            The AutoCompleteDbAdapter in use by the outer class
         *            object.
         */
        public ItemAutoTextAdapter(AutoCompleteDbAdapter dbHelper) {
            // Call the CursorAdapter constructor with a null Cursor.
            super(SelectState.this, null);
            mDbHelper = dbHelper;
        }

        /**
         * Invoked by the AutoCompleteTextView field to get completions for the
         * current input.
         *
         * NOTE: If this method either throws an exception or returns null, the
         * Filter class that invokes it will log an error with the traceback,
         * but otherwise ignore the problem. No choice list will be displayed.
         * Watch those error logs!
         *
         * @param constraint
         *            The input entered thus far. The resulting query will
         *            search for states whose name begins with this string.
         * @return A Cursor that is positioned to the first row (if one exists)
         *         and managed by the activity.
         */
        @Override
        public Cursor runQueryOnBackgroundThread(CharSequence constraint) {
            if (getFilterQueryProvider() != null) {
                return getFilterQueryProvider().runQuery(constraint);
            }

            Cursor cursor = mDbHelper.getMatchingStates(
                    (constraint != null ? constraint.toString() : null));

            return cursor;
        }

        /**
         * Called by the AutoCompleteTextView field to get the text that will be
         * entered in the field after a choice has been made.
         *
         * @param Cursor
         *            The cursor, positioned to a particular row in the list.
         * @return A String representing the row's text value. (Note that this
         *         specializes the base class return value for this method,
         *         which is {@link CharSequence}.)
         */
        @Override
        public String convertToString(Cursor cursor) {
            final int columnIndex = cursor.getColumnIndexOrThrow("state");
            final String str = cursor.getString(columnIndex);
            return str;
        }

        /**
         * Called by the ListView for the AutoCompleteTextView field to display
         * the text for a particular choice in the list.
         *
         * @param view
         *            The TextView used by the ListView to display a particular
         *            choice.
         * @param context
         *            The context (Activity) to which this form belongs;
         *            equivalent to {@code SelectState.this}.
         * @param cursor
         *            The cursor for the list of choices, positioned to a
         *            particular row.
         */
        @Override
        public void bindView(View view, Context context, Cursor cursor) {
            final String text = convertToString(cursor);
            ((TextView) view).setText(text);
        }

        /**
         * Called by the AutoCompleteTextView field to display the text for a
         * particular choice in the list.
         *
         * @param context
         *            The context (Activity) to which this form belongs;
         *            equivalent to {@code SelectState.this}.
         * @param cursor
         *            The cursor for the list of choices, positioned to a
         *            particular row.
         * @param parent
         *            The ListView that contains the list of choices.
         *
         * @return A new View (really, a TextView) to hold a particular choice.
         */
        @Override
        public View newView(Context context, Cursor cursor, ViewGroup parent) {
            final LayoutInflater inflater = LayoutInflater.from(context);
            final View view =
                    inflater.inflate(android.R.layout.simple_dropdown_item_1line,
                            parent, false);

           return view;
        }

        /**
         * Called by the AutoCompleteTextView field when a choice has been made
         * by the user.
         *
         * @param listView
         *            The ListView containing the choices that were displayed to
         *            the user.
         * @param view
         *            The field representing the selected choice
         * @param position
         *            The position of the choice within the list (0-based)
         * @param id
         *            The id of the row that was chosen (as provided by the _id
         *            column in the cursor.)
         */
        @Override
        public void onItemClick(AdapterView<?> listView, View view, int position, long id) {
            // Get the cursor, positioned to the corresponding row in the result set
            Cursor cursor = (Cursor) listView.getItemAtPosition(position);

            // Get the state's capital from this row in the database.
            String capital = cursor.getString(cursor.getColumnIndexOrThrow("capital"));

            // Update the parent class's TextView
            mStateCapitalView.setText(capital);
        }
    }

    private TextView mStateCapitalView;
    private AutoCompleteTextView mStateNameView;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        AutoCompleteDbAdapter dbHelper = new AutoCompleteDbAdapter(this);
        setContentView(R.layout.selectstate);
        Button confirmButton = (Button) findViewById(R.id.confirm);
        confirmButton.setOnClickListener(new View.OnClickListener() {
            public void onClick(View view) {
                setResult(RESULT_OK);
                finish();
            }
        });

        mStateCapitalView = (TextView) findViewById(R.id.state_capital);
        mStateNameView = (AutoCompleteTextView) findViewById(R.id.state_name);

        // Create an ItemAutoTextAdapter for the State Name field,
        // and set it as the OnItemClickListener for that field.
        ItemAutoTextAdapter adapter = this.new ItemAutoTextAdapter(dbHelper);
        mStateNameView.setAdapter(adapter);
        mStateNameView.setOnItemClickListener(adapter);
    }
}

Here’s the AutoCompleteDbAdapter class. It’s less interesting for this example, so the code is hidden by default. Click on the “show source” link to view it.

package org.oowb.AutoCompleteExample;

import android.app.Activity;
import android.content.ContentValues;
import android.content.Context;
import android.database.Cursor;
import android.database.SQLException;
import android.database.sqlite.SQLiteDatabase;
import android.database.sqlite.SQLiteOpenHelper;
import android.util.Log;

/**
 * Simple database access helper class.
 *
 * @author Dan Breslau
 */
public class AutoCompleteDbAdapter {
    /**
     * List of states and capitals.
     */
    private static final String[][] States = {
            { "Alabama", "Montgomery" },
            { "Alaska", "Juneau" },
            { "Arizona", "Phoenix" },
            { "Arkansas", "Little Rock" },
            { "California", "Sacramento" },
            { "Colorado", "Denver" },
            { "Confusion", "\"C\"" },
            { "Connecticut", "Hartford" },
            { "Delaware", "Dover" },
            { "Florida", "Tallahassee" },
            { "Georgia", "Atlanta" },
            { "Hawaii", "Honolulu" },
            { "Idaho", "Boise" },
            { "Illinois", "Springfield" },
            { "Indiana", "Indianapolis" },
            { "Iowa", "Des Moines" },
            { "Kansas", "Topeka" },
            { "Kentucky", "Frankfort" },
            { "Louisiana", "Baton Rouge" },
            { "Maine", "Augusta" },
            { "Maryland", "Annapolis" },
            { "Massachusetts", "Boston" },
            { "Michigan", "Lansing" },
            { "Minnesota", "St. Paul" },
            { "Mississippi", "Jackson" },
            { "Missouri", "Jefferson City" },
            { "Montana", "Helena" },
            { "Nebraska", "Lincoln" },
            { "Nevada", "Carson City" },
            { "New Hampshire", "Concord" },
            { "New Jersey", "Trenton" },
            { "New Mexico", "Santa Fe" },
            { "New York", "Albany" },
            { "North Carolina", "Raleigh" },
            { "North Dakota", "Bismarck" },
            { "Ohio", "Columbus" },
            { "Oklahoma", "Oklahoma City" },
            { "Oregon", "Salem" },
            { "Pennsylvania", "Harrisburg" },
            { "Rhode Island", "Providence" },
            { "South Carolina", "Columbia" },
            { "South Dakota", "Pierre" },
            { "Tennessee", "Nashville" },
            { "Texas", "Austin" },
            { "Utah", "Salt Lake City" },
            { "Vermont", "Montpelier" },
            { "Virginia", "Richmond" },
            { "Washington", "Olympia" },
            { "West Virginia", "Charleston" },
            { "Wisconsin", "Madison" },
            { "Wyoming", "Cheyenne" }
    };

    private static final String DATABASE_NAME = "capitals";
    private static final String TABLE_NAME = "state";
    private static final int DATABASE_VERSION = 1;

    private class DatabaseHelper extends SQLiteOpenHelper {

        DatabaseHelper(Context context) {
            super(context, DATABASE_NAME, null, DATABASE_VERSION);
        }

        @Override
        public void onCreate(SQLiteDatabase db) {
            final String DATABASE_CREATE_STATES =
                    "create table " + TABLE_NAME
                            + "(_id integer primary key autoincrement"
                            + ", state text not null"
                            + ", capital text not null)";

            db.execSQL(DATABASE_CREATE_STATES);
            populateWithData(db);
        }

        @Override
        public void onUpgrade(SQLiteDatabase db, int old, int new) {
            db.execSQL("DROP TABLE IF EXISTS " + TABLE_NAME);
            onCreate(db);
        }
    }

    private DatabaseHelper mDbHelper;
    private SQLiteDatabase mDb;
    private final Activity mActivity;

    /**
     * Constructor - takes the context to allow the database to be
     * opened/created
     *
     * @param activity
     *            the Activity that is using the database
     */
    public AutoCompleteDbAdapter(Activity activity) {
        this.mActivity = activity;
        mDbHelper = this.new DatabaseHelper(activity);
        mDb = mDbHelper.getWritableDatabase();
    }

    /**
     * Closes the database.
     */
    public void close() {
        mDbHelper.close();
    }

    /**
     * Return a Cursor that returns all states (and their state capitals) where
     * the state name begins with the given constraint string.
     *
     * @param constraint
     *            Specifies the first letters of the states to be listed. If
     *            null, all rows are returned.
     * @return Cursor managed and positioned to the first state, if found
     * @throws SQLException
     *             if query fails
     */
    public Cursor getMatchingStates(String constraint) throws SQLException {

        String queryString =
                "SELECT _id, state, capital FROM " + TABLE_NAME;

        if (constraint != null) {
            // Query for any rows where the state name begins with the
            // string specified in constraint.
            //
            // NOTE:
            // If wildcards are to be used in a rawQuery, they must appear
            // in the query parameters, and not in the query string proper.
            // See http://code.google.com/p/android/issues/detail?id=3153
            constraint = constraint.trim() + "%";
            queryString += " WHERE state LIKE ?";
        }
        String params[] = { constraint };

        if (constraint == null) {
            // If no parameters are used in the query,
            // the params arg must be null.
            params = null;
        }
        try {
            Cursor cursor = mDb.rawQuery(queryString, params);
            if (cursor != null) {
                this.mActivity.startManagingCursor(cursor);
                cursor.moveToFirst();
                return cursor;
            }
        }
        catch (SQLException e) {
            Log.e("AutoCompleteDbAdapter", e.toString());
            throw e;
        }

        return null;
    }

    /**
     * Populates the database with data on states and state capitals.
     *
     * @param db
     *            The database to be populated; must have the appropriate table
     *            ("state") and columns ("state" and "values") already set up.
     */
    private void populateWithData(SQLiteDatabase db) {
        try {
            db.beginTransaction();
            ContentValues values = new ContentValues();
            // Populate the database with the state/capital city
            // pairs found in the States array.
            for (String[] s : States) {
                values.put("state", s[0]);
                values.put("capital", s[1]);

                db.insert(TABLE_NAME, "state", values);
            }
            db.setTransactionSuccessful();
        }
        finally {
            db.endTransaction();
        }
    }
}

Using SimpleCursorAdapter

As mentioned above, changing the Adapter’s base class to SimpleCursorAdapter is fairly simple. Here’s a summary of the changes needed:

• The SimpleCursorAdapter constructor requires a resource ID for the layout used for items in the list. As before, we are using android.R.layout.simple_dropdown_item_1line for this layout.
• The constructor for SimpleCursorAdapter also requires parameters named from and to. These are arrays indicating which column(s) in the database hold the relevant data, and which field(s) in the View will display that data.
When the SimpleCursorAdapter is used to support an AutoCompleteTextView, only one column/field pair is used. The column, of course, is the column that supplies the names (here, “state”.) But how do we identify the field in the to array? Help comes to us through android.R.id.text1, a resource that is used to identify the first (and only) TextField within the standard item layout (android.R.layout.simple_dropdown_item_1line.)
This results in the following definitions for the from and to parameters. (I defined these in the outer SelectState class, because an inner class isn’t allowed to have static data.)

    final static int[] to = new int[] { android.R.id.text1 };
    final static String[] from = new String[] { "state" };

• The constructor is changed to call its superclass as follows:

super(SelectState.this,
        android.R.layout.simple_dropdown_item_1line,
        null, from, to);

• The newView and bindView methods can be removed.

<html>
<head>
	<!-- Stylesheets for SyntaxHighlighter -->
<link type="text/css" rel="stylesheet" href="styles/shCore.css"/>
<link type="text/css" rel="stylesheet" href="styles/shThemeDefault.css"/>
...
</head>
<body>

<em>...Some kind of interesting page content usually goes here,
but we're not interested in that right now...</em>

	<!-- Load the SyntaxHighlighter Core and Brush scripts. A
               separate Brush script is required for each language. -->
<script type="text/javascript" src="scripts/shCore.js"></script>
<script type="text/javascript" src="scripts/shBrushJava.js"></script>
<script type="text/javascript" src="scripts/shBrushJScript.js"></script>
	<!-- Don't forget the XML brush if you're using html-script -->
<script type="text/javascript" src="scripts/shBrushXml.js"></script>

	<!-- Now that all the script files are loaded, begin highlighting. -->
<script type="text/javascript">
SyntaxHighlighter.config.stripBrs = true;
// ... additional configuration, as needed ...

SyntaxHighlighter.all();
</script>

</body>

Some users have wanted a simpler way to integrate SyntaxHighlighter into their sites. Last year, David Chambers wrote a script that uses the Prototype library to load the required CSS and brush files. He ran into a troubling quirk in SyntaxHighlighter: It needs any required brush files to be loaded before it starts highlighting. I responded by updating the OOWB fork of SyntaxHighlighter, so that brushes could be loaded asynchronously. But that’s as far as I’d gone towards automated loading, until now.

I recently looked into adding automated loading to SyntaxHighlighter itself, coming up with not one, but two automated solutions. I should really say one and a half, as one is still in the alpha stage and will likely stay there.

The “alpha-stage” approach comprises a new JavaScript file that loads SyntaxHighlighter and the necessary brush files through AJAX, by way of a pair of simple Java servlets. I’d hoped that this would lead to faster load times, by reducing the total number of downloads. And so it does—sometimes. For testing, I used Google App Engine as the servlet host (using the free quotas.) Performance was inconsistent, to say the least; this is probably due to the Google App Engine’s method of starting up and shutting down servlets. It seemed that only by making repeated hits on the servlets in rapid succession could I be sure of getting to a container that already had my servlets running, thus getting good load times.¹ The servlets are still up there; if you’d like the Java source (to host them elsewhere), and/or the JavaScript for using them, just let me know.

I also implemented a pure JavaScript approach, which I hadn’t expected to yield better load times. Yet I’ve seen a number of cases where this is faster than the original, static way of loading SyntaxHighlighter. I’m releasing a new download so that you can try it out. I highly recommend that you test it thoroughly before putting it into real use.

To use this new method, the web page invokes SyntaxHighlighter.boot instead of SyntaxHighlighter.all. When boot is used as the entry point, SyntaxHighlighter determines which brushes are required by the web page, and issues HTTP requests for each brush file (as well as the appropriate CSS.) These requests use the age-old method of adding a tag for each brush, and a tag for each CSS file.

Using SyntaxHighlighter.boot, a web page only needs to add a couple of scripts, usually at the end of the . No CSS link elements are required.

<!--  We just need to load shCore.js near the end of the <body> element,
	then call SyntaxHighlighter.boot() with our configuration options. -->

<script type="text/javascript"
src="http://path/to/sh/directory/syntaxhighlighter/scripts/shCore.js"></script>

<script type="text/javascript">
	SyntaxHighlighter.boot(
		"http://path/to/syntaxhighlighter/root/syntaxhighlighter/",
		{theme : "Default"}, // Configuration settings
		{stripBrs : true}      // Default settings
	);
</script>

</body>

That’s it. Every page on your site can use the same set-up, regardless of which brush files it needs. (For another example, look at the HTML source for this page.)

When an HTML page includes external scripts—that is, elements with src attributes, the browser loads the script files synchronously, as it encounters them in the HTML. When the scripts are loaded dynamically, the browser can load them asynchronously; several scripts may then be loading simultaneously. This can be particularly helpful for pages that use multiple brushes. Here’s a Firebug sequence diagram of a web page with five brushes, loading in SyntaxHighlighter’s traditional way:

(Click on image for larger view)

Here’s the same page, modified to use the boot method. Notice that, unlike in the first picture, the shBrush...js files are loaded in parallel:

(Click on image for larger view)

Of course, this isn’t an entirely new discovery, but it came as a pleasant surprise nonetheless.

Availability

In addition to SyntaxHighlighter itself, I also modified Viper007Bond’s SyntaxHighlighter Evolved plugin for WordPress to use the new boot method. This simplified the code quite a bit, though it may have introduced bugs.

SyntaxHighlighter and SyntaxHighlighter Evolved are each available on the downloads page. Test before using. Note: If you’ve been using SyntaxHighlighter Evolved, you will probably need to re-set your settings if you install this plugin.

Implementation notes

In the traditional SyntaxHighlighter, all brushes must be loaded before SyntaxHighlighter.all is invoked. In this fork, “>brushes can load at any time after shCore.js has been loaded. This flexibility was key to the design of the boot method: If a brush is loaded after SyntaxHighlighter.all or SyntaxHighlighter.boot is invoked, SyntaxHighlighter looks through the page to see if there’s any input requesting the newly loaded brush.

The boot method needs to map each brush name to the script file that implements that brush. I implemented this by modifying the Perl script that builds and stages SyntaxHighlighter. The script now parses the *Brush.js files in the source tree, pulling out the names and aliases supported by each file, and writes them into an array in shCore.js. The downside of this is that testing via the boot method requires re-running the script, which builds and stages the files into a new directory, from where I can run tests. Even though the script only takes about a second, it’s crossed the boundary between having no build step in the development cycle, and having any build step in the development cycle.

When You Come To A Fork In The Road, Take It.

I had two motives for working on SyntaxHighlighter: One, to improve its display of code on my own blog and elsewhere. Two, as a training ground for learning JavaScript.

I was between jobs when I took on this project. As of this Monday, that will no longer be the case. That’s great news for me, but much as I’d like to keep the SyntaxHighlighter work moving forward, I don’t really know if or when I’ll have the time for it. On the other hand, I no longer feel like I need a private JavaScript training ground. So, I’ve pushed my repository to bitbucket.org as a fork of Alex’s repository. If he so chooses (and so far he hasn’t, which is fine), Alex is welcome to merge the fork into his branch. Perhaps more importantly, anyone else can now fork the code, and/or make contributions to this fork.

I do have some more goals in mind for SyntaxHighlighter. I’ll be writing about them in the not-too-distant future.

¹Perhaps a faster host would lead to the faster load times I’d hoped for; but that would probably require payment, which makes this approach considerably less attractive.

• In 2.1.364, the ruler functionality was removed. It’s still included here.
• 2.1.364 changed the way that wrapped lines are presented. I’ve kept the old presentation, but modified the icon that’s used to signify wrapping.
• Internally, 2.1.364 uses a separate HTML table to represent each line of source. I’ve maintained the older pattern of simply using a separate <div> to represent each line.

Other new bits in this release:

• I’ve added a “Hide” button to the toolbar. Code blocks can now be expanded/collapsed at the user’s whim. (As before, an author can still choose to present a block in the hidden/collapsed state.)
• When both a horizontal scrollbar and a gutter (the line number column) are displayed, the scrollbar no longer extends under the gutter. (I think this is an improvement; as always, feedback is welcome.) Update: I’ve backed out this change; it was causing problems with IE7.

The ZIP file is available through the Download Page.

New version of SyntaxHighlighter coming

Some folks have asked me offline if I’m going to be merging Alex Gorbatchev’s 2.1.364 version of SyntaxHighlighter with the OOWB fork that I’ve been supporting here. The answer to that is yes; if all goes well, I should be posting it in the next few days. As for creating a public repository, perhaps on bitbucket: Maybe. If you’d like to see this happen, please let me know. Actually, I’d like to hear from anyone who’s rolled out the OOWB fork: What site(s) are you using it on, and how is it working out? Please leave a comment, or send email.

Did I say “fork”? Uh, yeah. While 2.1.364 is solid, it doesn’t cover most of the improvements that I’ve made (check the Download Page to see a summary.) Ultimately, I’d like to see these changes rolled back into Alex’s version, but that doesn’t appear to be happening anytime soon. There could be good reasons for that; certainly my version looks larger, just for starters. (I think that the total footprint may be smaller, but that’s a tough call.) All I can really say is that we’ll see how it goes. I plan to keep making improvements in the software, at least for my own sake; but I regard Alex as the primary author and will continue to do so.

Let’s start with this:

As the graph shows, JavaScript array performance ranges from OK (nearly equivalent to scalars) to awful. The reasons for poor performance vary, but most can be boiled down to this: The JavaScript interpreter is essentially left guessing about how an array will be used. And guess it does. When an array is constructed and initialized, the interpreter can observe where data is stored into a new array. Certain kinds of patterns may nudge it to optimize for better speed, or lower memory consumption. So, performance suffers when the interpreter makes the wrong interpretation.

I looked into performance of JavaScript arrays with three popular Windows browsers: Internet Explorer 8, Google Chrome 3.0, and Firefox 3.5. Broadly speaking, these all seem to look for two or three types of arrays:

• Dense arrays: These provide faster access to individual elements of the array.
• Sparse arrays: These are typically optimized for lower memory use.
• Sized arrays: A variant of sparse arrays that are optimized for speed for certain cases.

The interpreters optimize for dense arrays if the array’s elements are initialized in a continuous range, starting at index 0. This initialization can be done before there’s any data for the array, by using placeholders such as 0, null, or even undefined. (There are other ways to get this optimization; this is simply the most reliable approach.)

Passing the array’s size in the constructor may also bring better performance. In my testing, I saw this only with sparse arrays in IE8 and (perhaps) in Chrome. I’ll refer to these as sized arrays; see below for some additional notes.

If an array is created as neither a dense nor a sized array, it’s treated as a sparse array.

As a general rule, the array’s behavior is established shortly after construction. If you sparsely populate an array, then assign other values to the remaining elements, you’re left with a densely-populated sparse array.¹

Now that we can finally get to some data, let’s discuss scalability. This graph represents the time taken to read about 30,000,000 values from arrays of various sizes, using three Windows browsers. Seven data sets are presented: Cleared and default arrays for each of IE8, Google Chrome 3.0, and Firefox 3.5, plus sized arrays for IE8.

Array Size Vs. Access Time. (Click for larger graph with legend)

Note that in three of the seven cases, time grows linearly as size increases². This growth effectively multiplies the program’s complexity by O(N). That is, an algorithm that might normally have O(N) performance instead shows O(N²) performance, and so on. This can have a sizable impact on scalability.

The graph makes it clear that the fastest arrays are cleared. However, making a very sparse cleared array would gobble up a large swath of memory for a small number of values. For such cases, you may want to stick with sparse or sized arrays. Here’s a closer look at their performance.

The following tests all used arrays of 180,000 elements. Each data point represents performance with a different “hit ratio”; that is, the ratio of defined values read from the array. While array density also varied, its effect appears in only one case, which I’ll show separately³. For reference, these graphs also show the performance with cleared arrays.

This graph shows the performance of sized, default, and cleared arrays in IE8. Notice that the “sized” trendline (in blue) begins significantly above the “default” trendline, and ends slightly above the “cleared” trendline. Clearly, IE optimizes sized arrays to work better when reading defined values.

Array Hits Vs. Access Time in IE8. (Click for larger graph with legend)

Firefox 3.5 also looks slower when accessing undefined elements, but there’s no real gain from passing a size parameter to the array constructor:

Array Hits Vs. Access Time in Firefox 3.5. (Click for larger graph with legend)

In Chrome, array access times are clustered into high and low ranges of values, based on array density. Chrome performs markedly better with arrays having a density of 10% or higher, vs. arrays of lower density. The data sets below have been split accordingly. Since there’s much more variation between these two ranges than here is among them, it’s a good bet that the 10% threshold is hard-coded somewhere in Chrome’s V8 JavaScript interpreter.

Array Hits Vs. Access Time in Chrome, by array density. (Click for larger graph with legend)

Notes on sized arrays

It makes sense that if a size is passed to the array constructor, and the size value is accurate, then the interpreter can optimize the array for that size. The problem is that the size value won’t always be accurate; nor does it suggest how dense the array might become. Hence the interpreter may not be able to rely on the size value even when it’s present.

Sized array behavior in IE8 isn’t what I’d expected. I’d found a note written prior to IE8′s release by one of its developers, which I had taken to mean that these arrays should perform like cleared arrays, but that’s clearly not the case. Sized arrays in IE8 actually incur a small penalty when accessing undefined array elements, to the point where if you access only undefined elements, a sized array may be slower than a default array. On a closer reading, the note refers to “any indexed entry” within the array’s range [emphasis mine.] Of course, undefined entries wouldn’t be indexed. The note was accurate, but arguably didn’t go far enough.

In Chrome, using an explicit size for a sparse array does seem to make a small but measurable difference in some cases. But on the whole, there’s little reason to use this for improved performance, especially since Chrome is currently the browser least in need of a performance boost in these tests.

The performance of Firefox 3.5 suggests that it ignores the constructor’s size parameter. However, a quick trip through the browser’s source code indicates that the size should make a difference. Perhaps other kinds of tests would be able to draw this out, or perhaps there’s an opportunity for improvement in the code.

Memory Consumption

Measuring the physical size of JavaScript data is a sketchy undertaking. About the best one can do is to compare the virtual memory size of the browser process before and after creating a large array. This isn’t going to be very accurate. All the same, where there’s a large difference between values, it’s probably significant.

In my last post, I wrote that a sparse 12K array of integers, implemented as a hash table, would likely consume over 36K of memory. If these measurements are reasonable, that was a gross understatement; a sparse 12K array could actually consume more than 70 bytes per element, or upwards of 860K.

At the extremes, for two arrays with the same length, one that’s very dense may use less memory than one of lower density—even though the lower density array, by definition, contains fewer values. Chrome and Firefox seem to account for this internally as they organize the array structure, but I’m not sure whether IE8 does.

Recommendations

• Use cleared arrays if speed is critical, or if the array reaches around 50% density. But don’t use them habitually, especially not for sparse arrays.
• Because of IE8′s quirks, you should think twice before creating sized arrays. They’re helpful only if you have sparse data and you won’t often access an undefined array element.

Looking ahead

JavaScript’s arrays are pleasant enough in normal use; but like all abstractions, they have their leaks. As JavaScript is used for increasingly sophisticated applications, it might be worthwhile for its designers to take a fresh look at scalability. There are ways to get the desired results, but negotiation via secret handshake doesn’t scale terribly well.

Without marring JavaScript’s simplicity, it should be possible to extend the language so that, when necessary, the developer can make plain to the interpreter what it should expect for a particular array. For example, this could mean adding APIs or syntax that let the developer declare the array’s expected size, density, and so forth. Or the problem could be addressed from the other direction: Simply allow the developer to request a structure that favors higher speed, or more compactness, for a particular array.

And although read-only objects may be a special case, I started down this path by looking at an array used as a lookup table which is effectively read-only after initialization. It would be nice if I could let the interpreter know this. A version of Ruby’s freeze method would fit the bill. This would give the interpreter a hint to optimize the array for read-only access, though it wouldn’t be required to do so.

Dreaming further, I’m also holding out hope that closures can be better optimized. After initialization, the lookup table in my version of String.trim() was only accessible to a single, read-only method. If the interpreter can verify that nothing’s going to change the array, it could move it to faster storage. Yes, this brings us back around to secret handshakes. But since closures have their own merits, I see this more as the icing on the cake.

The blog confirms that IE’s JavaScript interpreter manages arrays using a nonlinear structure, essentially a hash table. I’d guessed at this after seeing lower performance in trimOOWB when its lookup table was implemented as a large, and sparse, array. But contrary to my guess, this isn’t about avoiding re-allocation bottlenecks. It’s for dealing with sparse arrays without consuming unreasonable amounts of memory¹. (I’m feeling a little sheepish about this: Even though I’d noted the sparseness of the lookup table, I hadn’t made the connection. In fact, I’d been somewhat dismissive of that possibility. Live and learn.)

The blog also says that as of IE8, the JScript engine has heuristics for determining if an array is “dense”. It implements a dense array with a linear, array-like index in addition to its standard hash-like data structure; this index can make random access into the array much faster. The blog indicates that IE8 considers an array to be dense if either of the following conditions is true:

• You construct the array with an explicit size, and you don’t grow the array past that initial size.
• After creating the array, you initialize a continuous range of indices, starting from 0, up to and including the highest index that you expect to use. You must do this before writing into random indices within the array.²

As the writer says, using either of these two techniques should ensure that the array heuristics in IE 8 will treat your array as a dense array. The interpreter is free to decide to treat other arrays as dense, too. However, the testing I’ve done suggests that it’s not quite as simple as this. Contrary to the blog’s guidelines, I found that:

• Creating the array with an explicit size (whether or not followed by initializing the elements) had no measurable impact on the speed of the trim method.
• Initializing the lookup table’s full range of 12,289 elements (the vast majority of which are not whitespace) did improve performance.

This finding is specific to the trim method, and so these results should not be used as general performance guidelines. The usage pattern for a particular array can greatly affect its performance profile. I’ve found unrelated cases where specifying the array’s size could help or hurt performance. (I’ll write more about this in my next post.)

Following up on these hints led to a new version of trim that’s simpler and faster than my previous effort. This version is actually more closely related to the trim17 method from Yesudeep Mangalapilly than it is to trimOOWB. Hence I’ve named this newer one trim18 to reaffirm its heritage. (In Steve Levithan’s original post on JavaScript trim methods, he assigned numbers to each of the trim implementations that he examined. Yesudeep took up that naming scheme, and now I’m doing so as well.)

Performance

Since the last post, I’ve revised the benchmark for better precision. The structure is the same—both benchmarks call the three trim methods repeatedly with a fixed set of input data—but in the newer benchmark, the input strings are much longer, and the number of iterations is lower. This should yield more precise measurements of execution time. All the same, these results should be used with care; as is often said in the U.S.A, your mileage will vary.

The benchmark results are shown below. Please remember that these tables are not directly comparable to the numbers in my previous post.

ASCII data (only spaces and tabs used for whitespace)

Unicode data (using all ASCII and Unicode whitespace characters)

trim18 implementation

I left the explicit size in the array constructor call, even though I’d found no benefit from using it. It seems unlikely to cause any harm, and there may be environments where this method’s performance might benefit from it.

var trim18 = (function() {

    var tableSize = 0x3000 + 1;
    var whiteSpace = new Array(tableSize);

    // Initialize the array elements before populating the data.
    // (This may help performance, by hinting to the interpreter that
    //  the array should not be managed as a sparse array.)

    for (var i = 0; i < tableSize; i++) {
        whiteSpace[i] = false;
    }

    whiteSpace[0x0009] = true;  whiteSpace[0x000a] = true;
    whiteSpace[0x000b] = true;  whiteSpace[0x000c] = true;
    whiteSpace[0x000d] = true;  whiteSpace[0x0020] = true;
    whiteSpace[0x0085] = true;  whiteSpace[0x00a0] = true;
    whiteSpace[0x1680] = true;  whiteSpace[0x180e] = true;
    whiteSpace[0x2000] = true;  whiteSpace[0x2001] = true;
    whiteSpace[0x2002] = true;  whiteSpace[0x2003] = true;
    whiteSpace[0x2004] = true;  whiteSpace[0x2005] = true;
    whiteSpace[0x2006] = true;  whiteSpace[0x2007] = true;
    whiteSpace[0x2008] = true;  whiteSpace[0x2009] = true;
    whiteSpace[0x200a] = true;  whiteSpace[0x200b] = true;
    whiteSpace[0x2028] = true;  whiteSpace[0x2029] = true;
    whiteSpace[0x202f] = true;  whiteSpace[0x205f] = true;
    whiteSpace[0x3000] = true;

    function trim18(str) {
        var len = str.length, ws = whiteSpace, i = 0;
        while (ws[str.charCodeAt(--len)]);
        if (++len){
            while (ws[str.charCodeAt(i)]){ ++i; }
        }
        return str.substring(i, len);
    }

    return trim18;
})();