add an api usage example

CHANGELOG.md

@@ -1,6 +1,7 @@
 # 1.9.2-dev
 
 * Require Dart 2.18
+* Add an API usage example in `example/`.
 
 # 1.9.1
 
@@ -201,7 +202,7 @@
 # 1.0.0
 
 This package was extracted from the
-[`source_maps`](http://pub.dartlang.org/packages/source_maps) package, but the
+[`source_maps`](https://pub.dev/packages/source_maps) package, but the
 API has many differences. Among them:
 
 * `Span` has been renamed to `SourceSpan` and `Location` has been renamed to

README.md

@@ -2,6 +2,8 @@
 [![pub package](https://img.shields.io/pub/v/source_span.svg)](https://pub.dev/packages/source_span)
 [![package publisher](https://img.shields.io/pub/publisher/source_span.svg)](https://pub.dev/packages/source_span/publisher)
 
+## About this package
+
 `source_span` is a library for tracking locations in source code. It's designed
 to provide a standard representation for source code locations and spans so that
 disparate packages can easily pass them among one another, and to make it easy

example/main.dart

@@ -0,0 +1,51 @@
+// Copyright (c) 2023, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+import 'dart:io';
+
+import 'package:source_span/source_span.dart';
+
+void main(List<String> args) {
+  final file = File('README.md');
+  final contents = file.readAsStringSync();
+
+  final sourceFile = SourceFile.fromString(contents, url: file.uri);
+  final spans = _parseFile(contents, sourceFile);
+
+  for (var span in spans.take(30)) {
+    print('[${span.start.line + 1}:${span.start.column + 1}] ${span.text}');
+  }
+}
+
+Iterable<SourceSpan> _parseFile(String contents, SourceFile sourceFile) sync* {
+  var wordStart = 0;
+  var inWhiteSpace = true;
+
+  for (var i = 0; i < contents.length; i++) {
+    final codeUnit = contents.codeUnitAt(i);
+
+    if (codeUnit == _eol || codeUnit == _space) {
+      if (!inWhiteSpace) {
+        inWhiteSpace = true;
+
+        // emit a word
+        yield sourceFile.span(wordStart, i);
+      }
+    } else {
+      if (inWhiteSpace) {
+        inWhiteSpace = false;
+
+        wordStart = i;
+      }
+    }
+  }
+
+  if (!inWhiteSpace) {
+    // emit a word
+    yield sourceFile.span(wordStart, contents.length);
+  }
+}
+
+const int _eol = 10;
+const int _space = 32;

pubspec.yaml

@@ -1,6 +1,7 @@
 name: source_span
 version: 1.9.2-dev
-description: A library for identifying source spans and locations.
+description: >-
+  Provides a standard representation for source code locations and spans.
 repository: https://github.com/dart-lang/source_span
 
 environment: