shapelib 0.7.2 → 0.8.0

data/Rakefile

@@ -1,48 +1,157 @@
+# frozen_string_literal: true
+
 require 'rubygems'
 require 'rake'
-require 'jeweler'
-$LOAD_PATH << File.expand_path('lib')
-
-begin
-  require 'shapelib/version'
-  Jeweler::Tasks.new do |gem|
-    gem.name = "shapelib"
-    gem.summary = %Q{Simple wrapper around the shapelib library}
-    gem.description = gem.summary
-    gem.email = %q{nick@nickstoys.com}
-    gem.homepage = "http://github.com/mperham/shapelib"
-    gem.authors =  ["prasinos@users.sourceforge.net", "Mike Mangino", "Mike Perham", "Nick Estes"]
-    gem.add_development_dependency 'rake-compiler', '>= 0.7.0'
-    gem.has_rdoc = false
-    gem.version = Shapelib::VERSION
-    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+require 'open3'
+require 'tmpdir'
+require 'rbconfig'
+require 'shellwords'
+require 'rake/clean'
+require 'rake/testtask'
+require 'rubygems/package_task'
+
+desc 'Build with Clang in C23 mode and run the tests in isolation'
+task 'c23-test' do
+  root = __dir__
+  compiler = ENV.fetch('CC', 'clang')
+  flags = "#{ENV.fetch('CFLAGS', RbConfig::CONFIG['CFLAGS'])} -std=gnu2x"
+  make = Shellwords.split(ENV['MAKE'] || RbConfig::CONFIG['MAKE'] || 'make')
+  tests = Dir.glob(File.join(root, 'test/**/test_*.rb')).sort
+  abort 'c23-test: no test files found.' if tests.empty?
+
+  build_dir = Dir.mktmpdir('shapelib-c23-')
+  puts "C23 compiler: #{compiler}"
+  puts "C23 build directory: #{build_dir}"
+  configure = <<~'RUBY'
+    require 'rbconfig'
+    RbConfig::MAKEFILE_CONFIG['CC'] = RbConfig::CONFIG['CC'] = ARGV.shift
+    $0 = ARGV.shift
+    load $0
+  RUBY
+  Dir.chdir(build_dir) do
+    sh Gem.ruby, '-e', configure, compiler,
+       File.join(root, 'ext/shapelib_ext/extconf.rb'), "--with-cflags=#{flags}"
+    sh(*make)
   end
-  Jeweler::GemcutterTasks.new
-rescue LoadError => le
-  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler: #{le.message}"
+  binary = File.join(build_dir, "shapelib_ext.#{RbConfig::CONFIG['DLEXT']}")
+  abort 'c23-test: the isolated extension was not built.' unless File.file?(binary)
+  sh Gem.ruby, "-I#{build_dir}", "-I#{File.join(root, 'lib')}", "-I#{File.join(root, 'test')}",
+     '-e', 'ARGV.each { |file| require File.expand_path(file) }', *tests
+end
+
+desc 'Build and test every installed RVM Ruby, with a results table and logs'
+task 'rvm-test' do
+  root = __dir__
+  env = ENV.keys.grep(/\ABUNDLE_/).to_h { |key| [key, nil] }
+  env['RUBYOPT'] = nil
+  env['RUBYLIB'] = nil
+
+  begin
+    output, error, status = Open3.capture3(env, 'rvm', 'list', 'strings')
+  rescue Errno::ENOENT
+    abort 'rvm-test: RVM is not installed or its executable is not on PATH.'
+  end
+  abort "rvm-test: unable to list installed Rubies: #{error.strip}" unless status.success?
+  versions = output.lines.map(&:strip).reject(&:empty?).uniq.sort
+  abort 'rvm-test: no installed RVM Rubies found.' if versions.empty?
+  tests = Dir.glob(File.join(root, 'test/**/test_*.rb')).sort
+  abort 'rvm-test: no test files found.' if tests.empty?
+
+  logs = Dir.mktmpdir('shapelib-rvm-test-')
+  results = []
+  versions.each_with_index do |version, index|
+    puts "Testing #{version} (#{index + 1}/#{versions.length})..."
+    build_dir = File.join(logs, "build-#{index + 1}")
+    Dir.mkdir(build_dir)
+    run = lambda do |log, directory, *command|
+      system(env, 'rvm', version, 'do', *command, chdir: directory, out: log, err: %i[child out])
+    rescue SystemCallError => e
+      log.puts e.message
+      false
+    end
+
+    built = File.open(File.join(logs, "#{version}-build.log"), 'w') do |log|
+      run.call(log, build_dir, 'ruby', File.join(root, 'ext/shapelib_ext/extconf.rb')) && run.call(log, build_dir, 'make')
+    end
+    passed = if built
+               File.open(File.join(logs, "#{version}-test.log"), 'w') do |log|
+                 run.call(log, root, 'ruby', "-I#{build_dir}", "-I#{File.join(root, 'lib')}", "-I#{File.join(root, 'test')}", '-e', 'ARGV.each { |file| require File.expand_path(file) }', *tests)
+               end
+             end
+    results << [version, built ? 'PASS' : 'FAIL', if built
+                                                    passed ? 'PASS' : 'FAIL'
+                                                  else
+                                                    'SKIPPED'
+                                                  end]
+  end
+
+  width = [4, *versions.map(&:length)].max
+  puts
+  puts format("%-#{width}s  %-5s  %s", 'Ruby', 'Build', 'Tests')
+  results.each { |row| puts format("%-#{width}s  %-5s  %s", *row) }
+  puts "Logs and isolated builds: #{logs}"
+  abort 'rvm-test: one or more versions failed; see the logs above.' if results.any? do |row|
+    row[1..2] != %w[PASS PASS]
+  end
+end
+
+spec = Gem::Specification.load(File.expand_path('shapelib.gemspec', __dir__))
+abort 'Unable to load shapelib.gemspec' unless spec
+Gem::PackageTask.new(spec) {}
+
+desc 'Run tests, package the gem, and push it to RubyGems.org'
+task release: %i[test gem] do
+  sh Gem.ruby, '-S', 'gem', 'push', File.join('pkg', spec.file_name)
 end
 
-require 'rake/testtask'
 Rake::TestTask.new(:test) do |test|
-  test.libs = %w(lib test)
+  test.libs = %w[lib test]
   test.pattern = 'test/**/test_*.rb'
   test.verbose = true
 end
 
-task :test => :check_dependencies
-task :default => :test
+task test: :compile
+task default: :test
+
+build_dir = File.join('tmp', RUBY_PLATFORM, 'shapelib_ext', RUBY_VERSION)
+extconf = File.expand_path('ext/shapelib_ext/extconf.rb', __dir__)
+makefile = File.join(build_dir, 'Makefile')
+binary = "shapelib_ext.#{RbConfig::CONFIG['DLEXT']}"
 
-#require 'rake/rdoctask'
-require 'rdoc/task'
-Rake::RDocTask.new do |rdoc|
-  rdoc.rdoc_dir = 'rdoc'
-  rdoc.title = "shapelib"
-  rdoc.rdoc_files.include('README*')
-  rdoc.rdoc_files.include('lib/**/*.rb')
+file makefile => [extconf] do
+  mkdir_p build_dir
+  Dir.chdir(build_dir) { sh Gem.ruby, extconf, *ARGV.grep(/\A--?/) }
 end
 
+desc 'Compile the extension for the current Ruby'
+task compile: makefile do
+  make = Shellwords.split(ENV['MAKE'] || RbConfig::CONFIG['MAKE'] || 'make')
+  Dir.chdir(build_dir) { sh(*make) }
+  cp File.join(build_dir, binary), File.join('lib', binary)
+end
+task 'compile:shapelib_ext' => :compile
+
+CLEAN.include(build_dir)
+CLOBBER.include('tmp', File.join('lib', binary))
+
+rdoc_files = FileList['README*', 'lib/**/*.rb']
+desc 'Build the HTML documentation'
+task rdoc: 'rdoc/created.rid'
+file 'rdoc/created.rid' => rdoc_files.to_a + ['Rakefile'] do
+  begin
+    require 'rdoc'
+  rescue LoadError => error
+    raise unless error.path == 'rdoc'
 
-gem 'rake-compiler', '>= 0.7.0'
-require "rake/extensiontask"
+    abort 'Documentation requires RDoc. Install it with: gem install rdoc'
+  end
+  RDoc::RDoc.new.document(['--op', 'rdoc', '--title', 'shapelib', *rdoc_files])
+end
 
-Rake::ExtensionTask.new('shapelib_ext')
+desc 'Rebuild the HTML documentation from scratch'
+task rerdoc: %i[clobber_rdoc rdoc]
+desc 'Remove generated HTML documentation'
+task :clobber_rdoc do
+  rm_rf 'rdoc'
+end
+task clobber: :clobber_rdoc

data/doc/Interface.html

@@ -8,9 +8,9 @@
 <link href="style.css" type="text/css" rel="stylesheet" />
 </head>
 <body>
-<h1><a name="label-0" id="label-0">module ShapeLib</a></h1><!-- RDLabel: "module ShapeLib" -->
+<h1><a name="label-0" id="label-0">module Shapelib</a></h1><!-- RDLabel: "module Shapelib" -->
 <p>This module is a wrapper of C Shapefile Library
-(also called <a href="http://shapelib.maptools.org/">ShapeLib</a>).
+(also called <a href="http://shapelib.maptools.org/">Shapelib</a>).
 It consists of basically two classes:
 <a href="#label-5">ShapeFile</a> and <a href="#label-29">Shape</a>.
 If you are unfamiliar with object-oriented programming,
@@ -20,17 +20,17 @@ please see <a href="#label-83">Appendix A: C to Ruby equivalence table</a>.</p>
 <h2><a name="label-1" id="label-1">module functions</a></h2><!-- RDLabel: "module functions" -->
 <p>Following three functions construct a point object.
 It can be used like top level function after <code>include</code>:</p>
-<pre>include ShapeLib
+<pre>include Shapelib
 pt = new_point(1, 2)</pre>
 <p>Arguments <var>x</var>, <var>y</var>, <var>z</var>, and <var>m</var> <a href="#label-85">should be Float</a>.</p>
 <dl>
-<dt><a name="label-2" id="label-2"><code>ShapeLib.new_point <var>x</var>, <var>y</var></code></a></dt><!-- RDLabel: "ShapeLib.new_point x, y" -->
+<dt><a name="label-2" id="label-2"><code>Shapelib.new_point <var>x</var>, <var>y</var></code></a></dt><!-- RDLabel: "Shapelib.new_point x, y" -->
 <dd>
 creates a <a href="#label-51">class Point</a> object.</dd>
-<dt><a name="label-3" id="label-3"><code>ShapeLib.new_point <var>x</var>, <var>y</var>, <var>m</var></code></a></dt><!-- RDLabel: "ShapeLib.new_point x, y, m" -->
+<dt><a name="label-3" id="label-3"><code>Shapelib.new_point <var>x</var>, <var>y</var>, <var>m</var></code></a></dt><!-- RDLabel: "Shapelib.new_point x, y, m" -->
 <dd>
 creates a <a href="#label-57">class PointM</a> object.</dd>
-<dt><a name="label-4" id="label-4"><code>ShapeLib.new_point <var>x</var>, <var>y</var>, <var>m</var>, <var>z</var></code></a></dt><!-- RDLabel: "ShapeLib.new_point x, y, m, z" -->
+<dt><a name="label-4" id="label-4"><code>Shapelib.new_point <var>x</var>, <var>y</var>, <var>m</var>, <var>z</var></code></a></dt><!-- RDLabel: "Shapelib.new_point x, y, m, z" -->
 <dd>
 creates a <a href="#label-59">class PointZ</a> object.</dd>
 </dl>
@@ -52,14 +52,14 @@ or just basename (like "<code>basename</code>").
 Suffix <code>.shp</code> must be lowercase if specified.
 Both <code>.shp</code> and <code>.shx</code> files must exist at the specified path.</p>
 <p>Argument <var>access</var> are passed to <code>fopen(3)</code> through
-<a href="#label-92">ShapeLib</a> <code>SHPOpen()</code> function.
+<a href="#label-92">Shapelib</a> <code>SHPOpen()</code> function.
 Either '<code>rb</code>' or '<code>rb+</code>' should be used.</p>
 <p>If a block is given to these constructors,
 the opened shapefile object is yielded like File::open.
 The shapefile is closed at the end of block,
 and the constructor returns <code>nil</code>.</p>
 <pre># example
-ShapeLib::ShapeFile.open(filename) { |fp|
+Shapelib::ShapeFile.open(filename) { |fp|
    print "#{filename} has #{fp.size} records.\n"
 }</pre></dd>
 <dt><a name="label-9" id="label-9"><code>ShapeFile::new <var>filename</var>, <var>shapetype</var>, <var>attrs</var></code></a></dt><!-- RDLabel: "ShapeFile::new filename, shapetype, attrs" -->
@@ -90,7 +90,14 @@ Argument <var>field_name</var> is a String for field name;
 <var>field_type</var> specifies <a href="#label-87">field type</a>;
 <var>width</var> is nonnegative Integer for field width in characters; and
 <var>decimal</var> is nonnegative Integer for decimal points.
-Only Float field requires <var>decimal</var>; otherwise it can be missing.</p>
+Field names must be at most 10 bytes and unique ignoring case.
+Overlong or duplicate names raise ArgumentError before the field is added.
+Only Float field requires <var>decimal</var>; otherwise it can be missing.
+Integer and Float fields require <var>decimal</var> between 0 and 255 inclusive.
+Date fields require width 8 and zero decimal places. They are available
+when the native shapelib headers provide FTDate (shapelib 1.5.0 or newer).
+Date values are eight-digit YYYYMMDD Strings, or nil for nulls.
+Writes check the eight-digit format without calendar validation.</p>
 <pre># example
 fp.add_field 'name', :String, 32
 fp.add_field 'height', "Float", 9, 1</pre></dd>
@@ -119,8 +126,9 @@ returns the name of the attribute field with <var>index</var>, or nil on failure
 <dd>
 returns the type of the <a href="#label-89">attribute field</a>.
 The result is Symbol
-(one of :String, :Integer, :Float, :Logical, or :Invalid)
-or nil on failure.</dd>
+(one of :String, :Integer, :Float, :Logical, :Date, or :Invalid)
+or nil on failure.
+Older native libraries classify Date fields as :String.</dd>
 <dt><a name="label-19" id="label-19"><code>shapefile.field_width <var>field</var></code></a></dt><!-- RDLabel: "shapefile.field_width field" -->
 <dd>
 returns the width of the <a href="#label-89">attribute field</a>.</dd>
@@ -142,7 +150,9 @@ the next record to previously read one
 (or the first record #0 for the first time) is used.
 An instance of <a href="#label-29">class Shape</a> is returned,
 including all attributes written on the DBF.
-On error <code>nil</code> is returned.</dd>
+At end of file or on a geometry-read failure, <code>nil</code> is returned.
+If a DBF with attribute fields is present but its record cannot be read,
+IOError is raised. Files without a DBF or with no fields remain readable.</dd>
 <dt><a name="label-24" id="label-24"><code>shapefile.rewind</code></a></dt><!-- RDLabel: "shapefile.rewind" -->
 <dd>
 After that, <a href="#label-23">shapefile.read</a>
@@ -159,7 +169,8 @@ returns the number of records (or shapes) in the shapefile.
 writes <var>shape</var> into shapefile at record number <var>rec</var>.
 The <var>shape</var> must be a instance of <a href="#label-29">class Shape</a> or subclass.
 Attributes attached to <var>shape</var> are stored into DBF file.
-If <var>rec</var> is missing, the record is appended at the end of shapefile.</dd>
+If <var>rec</var> is missing, nil, or -1, the record is appended at the end of shapefile.
+An existing nonnegative record index replaces that record.</dd>
 <dt><a name="label-28" id="label-28"><code>shapefile.close</code></a></dt><!-- RDLabel: "shapefile.close" -->
 <dd>
 <p>The <code>close</code> method flushes all information
@@ -270,7 +281,7 @@ returns the <a href="#label-86">type of shape</a> by Symbol.</dd>
 <p>returns a hash that contains all attributes and geometry information.
 Each attribute have a key of String,
 while geometry information has keys of Symbol.</p>
-<pre>pt = ShapeLib::Point::new(1, 2, 'name' =&gt; 'Madison')
+<pre>pt = Shapelib::Point::new(1, 2, 'name' =&gt; 'Madison')
 pt.to_h =&gt; {"name"=&gt;"Madison", :zvals=&gt;[0.0], :n_parts=&gt;0,
     :n_vertices=&gt;1, :maxbound=&gt;[1.0, 2.0, 0.0, 0.0],
     :part_start=&gt;nil, :part_type=&gt;nil, :xvals=&gt;[1.0],
@@ -285,29 +296,29 @@ Note that this lose information.</dd>
 <p>returns WKT (well known text) representation of geometry
 as defined in <a href="#label-94">ISO 19125-1</a>.
 <em>Caution: current implementation does not always handle Polygon[MZ] and MultiPatch correctly.</em></p>
-<pre>ShapeLib::Arc.new([1, 2], [3, 4], [5, 6]).wkt
+<pre>Shapelib::Arc.new([1, 2], [3, 4], [5, 6]).wkt
 =&gt; "LINESTRING(1 2, 3 4, 5 6)"
-ShapeLib::Arc.new([[1, 2], [3, 4]], [[5, 6], [7, 8]]).wkt
+Shapelib::Arc.new([[1, 2], [3, 4]], [[5, 6], [7, 8]]).wkt
 =&gt; "MULTILINESTRING((1 2, 3 4), (5 6, 7 8))"</pre></dd>
 <dt><a name="label-47" id="label-47"><code>shape.xvals</code></a></dt><!-- RDLabel: "shape.xvals" -->
 <dd>
 <p>returns an array of x values.</p>
-<pre>ShapeLib::Arc.new([1, 2], [3, 4], [5, 6]).xvals
+<pre>Shapelib::Arc.new([1, 2], [3, 4], [5, 6]).xvals
 =&gt; [1.0, 3.0, 5.0]</pre>
 <p>Multipart shape results flattened array (all parts joined).</p>
-<pre>ShapeLib::Arc.new([[1, 2], [3, 4]], [[5, 6], [7, 8]]).xvals
+<pre>Shapelib::Arc.new([[1, 2], [3, 4]], [[5, 6], [7, 8]]).xvals
 =&gt; [1.0, 3.0, 5.0, 7.0]</pre></dd>
 <dt><a name="label-48" id="label-48"><code>shape.yvals</code></a></dt><!-- RDLabel: "shape.yvals" -->
 <dd>
 <p>returns an array of y values.</p>
-<pre>ShapeLib::Arc.new([1, 2], [3, 4], [5, 6]).xvals
+<pre>Shapelib::Arc.new([1, 2], [3, 4], [5, 6]).xvals
 =&gt; [2.0, 4.0, 6.0]</pre></dd>
 <dt><a name="label-49" id="label-49"><code>shape.mvals</code></a></dt><!-- RDLabel: "shape.mvals" -->
 <dd>
 <p>returns an array of m values. Nil is returned for missing value.</p>
-<pre>ShapeLib::Arc.new([1, 2], [3, 4], [5, 6]).mvals
+<pre>Shapelib::Arc.new([1, 2], [3, 4], [5, 6]).mvals
 =&gt; [nil, nil, nil]
-ShapeLib::ArcM.new([1, 2, 3], [4, 5, 6], [7, 8, 9]).mvals
+Shapelib::ArcM.new([1, 2, 3], [4, 5, 6], [7, 8, 9]).mvals
 =&gt; [3, 6, 9]</pre></dd>
 <dt><a name="label-50" id="label-50"><code>shape.zvals</code></a></dt><!-- RDLabel: "shape.zvals" -->
 <dd>
@@ -382,7 +393,11 @@ Constructs a object with multiple polygons.</dd>
 <dt><a name="label-72" id="label-72"><code>MultiPoint::new <var>point</var>, <var>point</var>, ...</code></a></dt><!-- RDLabel: "MultiPoint::new point, point, ..." -->
 <dt><a name="label-73" id="label-73"><code>MultiPoint::new [<var>point</var>, <var>point</var>, ...]</code></a></dt><!-- RDLabel: "MultiPoint::new [point, point, ...]" -->
 <dd>
-Above two are the same.</dd>
+Above two are the same for a nonempty list of points. Each point may
+be a coordinate array [x, y, m, z] or an object with x and y methods.
+A single coordinate array is also accepted. No arguments create an
+empty MultiPoint; for compatibility, a single empty array creates
+one point at the origin.</dd>
 </dl>
 <h2><a name="label-74" id="label-74">class MultiPointM</a></h2><!-- RDLabel: "class MultiPointM" -->
 <p>MultiPointM is similar to MultiPoint, but points also have m (measure) coordinates.</p>
@@ -398,9 +413,11 @@ Note that the first element of each array must be <a href="#label-88">part type<
 <h2><a name="label-78" id="label-78">constants</a></h2><!-- RDLabel: "constants" -->
 <h3><a name="label-79" id="label-79">Field Type Constants</a></h3><!-- RDLabel: "Field Type Constants" -->
 <dl>
-<dt><a name="label-80" id="label-80"><code>ShapeLib::String</code></a></dt><!-- RDLabel: "ShapeLib::String" -->
-<dt><a name="label-81" id="label-81"><code>ShapeLib::Integer</code></a></dt><!-- RDLabel: "ShapeLib::Integer" -->
-<dt><a name="label-82" id="label-82"><code>ShapeLib::Float</code></a></dt><!-- RDLabel: "ShapeLib::Float" -->
+<dt><a name="label-80" id="label-80"><code>Shapelib::String</code></a></dt><!-- RDLabel: "Shapelib::String" -->
+<dt><a name="label-81" id="label-81"><code>Shapelib::Integer</code></a></dt><!-- RDLabel: "Shapelib::Integer" -->
+<dt><a name="label-82" id="label-82"><code>Shapelib::Float</code></a></dt><!-- RDLabel: "Shapelib::Float" -->
+<dt><code>Shapelib::Date</code></dt>
+<dd>Available when the native shapelib headers provide FTDate.</dd>
 </dl>
 <h2><a name="label-83" id="label-83">Appendix A: C to Ruby equivalence table</a></h2><!-- RDLabel: "Appendix A: C to Ruby equivalence table" -->
 <ul>
@@ -478,8 +495,12 @@ This appendix discusses the detail of acceptable value.</p>
 <dd>
 Any object that respond to <code>to_f</code> is converted to Float.
 String is not acceptable.
-<code>nil</code> is treated as -2e-38 (NODATA) for <var>m</var> (measure) coordinate,
+<code>nil</code> is treated as -2e38 (NODATA) for <var>m</var> (measure) coordinate,
 or as 0.0 otherwise.
+Measures below -1e38 are read as nil; exactly -1e38 is valid.
+The exact legacy null marker -2e-38 is also read as nil for compatibility
+with files written by older versions of this gem. Other negative measures
+are preserved.
 </dd>
 <dt><a name="label-86" id="label-86">type of shapes</a></dt><!-- RDLabel: "type of shapes" -->
 <dd>
@@ -487,9 +508,9 @@ For <a href="#label-9">ShapeFile::new</a>
 and <a href="#label-32">Shape::new</a>,
 acceptable values for <var>shapetype</var> are:
 <ul>
-<li>Class object like ShapeLib::Point (listed in <a href="#label-30">structure of subclasses</a>)</li>
+<li>Class object like Shapelib::Point (listed in <a href="#label-30">structure of subclasses</a>)</li>
 <li>String such as <code>"Point"</code> or <code>"PolygonZ"</code>
-    (the same list, but do not include "ShapeLib::")</li>
+    (the same list, but do not include "Shapelib::")</li>
 <li>Symbol such as <code>:Point</code> or <code>:PolygonZ</code>
     (result of <a href="#label-25">shapefile.shape_type</a> and <a href="#label-43">shape.shape_type</a>),
     or</li>
@@ -502,8 +523,8 @@ acceptable values for <var>shapetype</var> are:
 For <a href="#label-12">shapefile.add_field</a>,
 acceptable values for <var>field_type</var> are:
 <ul>
-<li>String "String", "Integer", or "Float", or</li>
-<li>Symbol :String, :Integer, or :Float
+<li>String "String", "Integer", "Float", "Logical", or "Date", or</li>
+<li>Symbol :String, :Integer, :Float, :Logical, or :Date
     (result of <a href="#label-18">shapefile.field_type</a>).</li>
 <li>Integer constants listed <a href="#label-79">above</a>.</li>
 </ul>
@@ -533,7 +554,7 @@ For <a href="#label-32">Shape::new hash</a>, the argument <var>hash</var>
 </dl>
 <h2><a name="label-91" id="label-91">References</a></h2><!-- RDLabel: "References" -->
 <dl>
-<dt><a name="label-92" id="label-92">ShapeLib</a></dt><!-- RDLabel: "ShapeLib" -->
+<dt><a name="label-92" id="label-92">Shapelib</a></dt><!-- RDLabel: "Shapelib" -->
 <dd>
 <a href="http://shapelib.maptools.org/shp_api.html">&lt;URL:http://shapelib.maptools.org/shp_api.html&gt;</a>
 <a href="http://shapelib.maptools.org/dbf_api.html">&lt;URL:http://shapelib.maptools.org/dbf_api.html&gt;</a>
@@ -552,7 +573,7 @@ or <a href="http://shapelib.maptools.org/dl/shapefile.pdf">&lt;URL:http://shapel
 <p class="foottext">
 <a name="foottext-1" id="foottext-1" href="#footmark-1"><sup><small>*1</small></sup></a><small>If DBF file has different number of records,
 warning message is shown in $VERBOSE mode.</small><br />
-<a name="foottext-2" id="foottext-2" href="#footmark-2"><sup><small>*2</small></sup></a><small>taken from <a href="#label-92">ShapeLib</a> document.</small><br />
+<a name="foottext-2" id="foottext-2" href="#footmark-2"><sup><small>*2</small></sup></a><small>taken from <a href="#label-92">Shapelib</a> document.</small><br />
 </p>
 </body>
 </html>

data/doc/Interface.rd

@@ -1,8 +1,8 @@
 =begin
-= module ShapeLib
+= module Shapelib
 
 This module is a wrapper of C Shapefile Library
-(also called ((<ShapeLib|URL:http://shapelib.maptools.org/>))).
+(also called ((<Shapelib|URL:http://shapelib.maptools.org/>))).
 It consists of basically two classes:
 ((<ShapeFile|class ShapeFile>)) and ((<Shape|class Shape>)).
 If you are unfamiliar with object-oriented programming,
@@ -16,16 +16,16 @@ A extension library (({shapelib})) must be required before using this module:
 Following three functions construct a point object.
 It can be used like top level function after (({include})):
 
-  include ShapeLib
+  include Shapelib
   pt = new_point(1, 2)
 
 Arguments ((|x|)), ((|y|)), ((|z|)), and ((|m|)) ((<should be Float>)).
 
---- ShapeLib.new_point x, y
+--- Shapelib.new_point x, y
     creates a ((<class Point>)) object.
---- ShapeLib.new_point x, y, m
+--- Shapelib.new_point x, y, m
     creates a ((<class PointM>)) object.
---- ShapeLib.new_point x, y, m, z
+--- Shapelib.new_point x, y, m, z
     creates a ((<class PointZ>)) object.
 
 == class ShapeFile
@@ -47,7 +47,7 @@ when each shapefile is no longer used.
     Both (({.shp})) and (({.shx})) files must exist at the specified path.
 
     Argument ((|access|)) are passed to (({fopen(3)})) through
-    ((<ShapeLib>)) (({SHPOpen()})) function.
+    ((<Shapelib>)) (({SHPOpen()})) function.
     Either '(({rb}))' or '(({rb+}))' should be used.
 
     If a block is given to these constructors,
@@ -56,7 +56,7 @@ when each shapefile is no longer used.
     and the constructor returns (({nil})).
 
 	# example
-	ShapeLib::ShapeFile.open(filename) { |fp|
+	Shapelib::ShapeFile.open(filename) { |fp|
 	   print "#{filename} has #{fp.size} records.\n"
 	}
 
@@ -87,7 +87,14 @@ when each shapefile is no longer used.
     ((|field_type|)) specifies ((<field type>));
     ((|width|)) is nonnegative Integer for field width in characters; and
     ((|decimal|)) is nonnegative Integer for decimal points.
+    Field names must be at most 10 bytes and unique ignoring case.
+    Overlong or duplicate names raise ArgumentError before the field is added.
     Only Float field requires ((|decimal|)); otherwise it can be missing.
+    Integer and Float fields require ((|decimal|)) between 0 and 255 inclusive.
+    Date fields require width 8 and zero decimal places. They are available
+    when the native shapelib headers provide FTDate (shapelib 1.5.0 or newer).
+    Date values are eight-digit YYYYMMDD Strings, or nil for nulls.
+    Writes check the eight-digit format without calendar validation.
 
       # example
       fp.add_field 'name', :String, 32
@@ -118,8 +125,9 @@ when each shapefile is no longer used.
 --- shapefile.field_type field
     returns the type of the ((<attribute field>)).
     The result is Symbol
-    (one of :String, :Integer, :Float, :Logical, or :Invalid)
+    (one of :String, :Integer, :Float, :Logical, :Date, or :Invalid)
     or nil on failure.
+    Older native libraries classify Date fields as :String.
 
 --- shapefile.field_width field
     returns the width of the ((<attribute field>)).
@@ -141,7 +149,9 @@ when each shapefile is no longer used.
     (or the first record #0 for the first time) is used.
     An instance of ((<class Shape>)) is returned,
     including all attributes written on the DBF.
-    On error (({nil})) is returned.
+    At end of file or on a geometry-read failure, (({nil})) is returned.
+    If a DBF with attribute fields is present but its record cannot be read,
+    IOError is raised. Files without a DBF or with no fields remain readable.
 
 --- shapefile.rewind
     After that, ((<shapefile.read|shapefile.read rec = -1>))
@@ -159,7 +169,8 @@ when each shapefile is no longer used.
     writes ((|shape|)) into shapefile at record number ((|rec|)).
     The ((|shape|)) must be a instance of ((<class Shape>)) or subclass.
     Attributes attached to ((|shape|)) are stored into DBF file.
-    If ((|rec|)) is missing, the record is appended at the end of shapefile.
+    If ((|rec|)) is missing, nil, or -1, the record is appended at the end of shapefile.
+    An existing nonnegative record index replaces that record.
 
 --- shapefile.close
     The (({close})) method flushes all information
@@ -231,7 +242,7 @@ depending on the type of shape.
     It returns (({true})) if a change is made and
     (({false})) if no change is made.
     Only polygon objects will be affected though any object may be passed."
-    ((-taken from ((<ShapeLib>)) document.-))
+    ((-taken from ((<Shapelib>)) document.-))
 --- shape.shape_id
     returns the number of record by which the shape is read from a shapefile.
     Nil is returned if the shape is not read from file.
@@ -243,7 +254,7 @@ depending on the type of shape.
     returns a hash that contains all attributes and geometry information.
     Each attribute have a key of String,
     while geometry information has keys of Symbol.
-	pt = ShapeLib::Point::new(1, 2, 'name' => 'Madison')
+	pt = Shapelib::Point::new(1, 2, 'name' => 'Madison')
 	pt.to_h => {"name"=>"Madison", :zvals=>[0.0], :n_parts=>0,
 	    :n_vertices=>1, :maxbound=>[1.0, 2.0, 0.0, 0.0],
 	    :part_start=>nil, :part_type=>nil, :xvals=>[1.0],
@@ -259,34 +270,34 @@ depending on the type of shape.
     as defined in ((<ISO 19125-1>)).
     ((*Caution: current implementation does not always handle Polygon[MZ] and MultiPatch correctly.*))
 
-      ShapeLib::Arc.new([1, 2], [3, 4], [5, 6]).wkt
+      Shapelib::Arc.new([1, 2], [3, 4], [5, 6]).wkt
       => "LINESTRING(1 2, 3 4, 5 6)"
-      ShapeLib::Arc.new([[1, 2], [3, 4]], [[5, 6], [7, 8]]).wkt
+      Shapelib::Arc.new([[1, 2], [3, 4]], [[5, 6], [7, 8]]).wkt
       => "MULTILINESTRING((1 2, 3 4), (5 6, 7 8))"
 
 --- shape.xvals
     returns an array of x values.
 
-      ShapeLib::Arc.new([1, 2], [3, 4], [5, 6]).xvals
+      Shapelib::Arc.new([1, 2], [3, 4], [5, 6]).xvals
       => [1.0, 3.0, 5.0]
 
     Multipart shape results flattened array (all parts joined).
 
-      ShapeLib::Arc.new([[1, 2], [3, 4]], [[5, 6], [7, 8]]).xvals
+      Shapelib::Arc.new([[1, 2], [3, 4]], [[5, 6], [7, 8]]).xvals
       => [1.0, 3.0, 5.0, 7.0]
 
 --- shape.yvals
     returns an array of y values.
 
-      ShapeLib::Arc.new([1, 2], [3, 4], [5, 6]).xvals
+      Shapelib::Arc.new([1, 2], [3, 4], [5, 6]).xvals
       => [2.0, 4.0, 6.0]
 
 --- shape.mvals
     returns an array of m values. Nil is returned for missing value.
 
-      ShapeLib::Arc.new([1, 2], [3, 4], [5, 6]).mvals
+      Shapelib::Arc.new([1, 2], [3, 4], [5, 6]).mvals
       => [nil, nil, nil]
-      ShapeLib::ArcM.new([1, 2, 3], [4, 5, 6], [7, 8, 9]).mvals
+      Shapelib::ArcM.new([1, 2, 3], [4, 5, 6], [7, 8, 9]).mvals
       => [3, 6, 9]
 
 --- shape.zvals
@@ -353,7 +364,11 @@ PolygonZ is similar to PolygonM, but points also have z coordinates.
 MultiPoint is a set of points.
 --- MultiPoint::new point, point, ...
 --- MultiPoint::new [point, point, ...]
-    Above two are the same.
+    Above two are the same for a nonempty list of points. Each point may
+    be a coordinate array [x, y, m, z] or an object with x and y methods.
+    A single coordinate array is also accepted. No arguments create an
+    empty MultiPoint; for compatibility, a single empty array creates
+    one point at the origin.
 
 == class MultiPointM
 MultiPointM is similar to MultiPoint, but points also have m (measure) coordinates.
@@ -368,9 +383,11 @@ MultiPointZ is similar to MultiPointM, but points also have z coordinates.
 
 == constants
 === Field Type Constants
---- ShapeLib::String
---- ShapeLib::Integer
---- ShapeLib::Float
+--- Shapelib::String
+--- Shapelib::Integer
+--- Shapelib::Float
+--- Shapelib::Date
+    Available when the native shapelib headers provide FTDate.
 
 == Appendix A: C to Ruby equivalence table
 * DBFHandle:
@@ -446,16 +463,20 @@ This appendix discusses the detail of acceptable value.
 : should be Float
   Any object that respond to (({to_f})) is converted to Float.
   String is not acceptable.
-  (({nil})) is treated as -2e-38 (NODATA) for ((|m|)) (measure) coordinate,
+  (({nil})) is treated as -2e38 (NODATA) for ((|m|)) (measure) coordinate,
   or as 0.0 otherwise.
+  Measures below -1e38 are read as nil; exactly -1e38 is valid.
+  The exact legacy null marker -2e-38 is also read as nil for compatibility
+  with files written by older versions of this gem. Other negative measures
+  are preserved.
 
 : type of shapes
   For ((<ShapeFile::new|ShapeFile::new filename, shapetype, attrs>))
   and ((<Shape::new|Shape::new hash>)),
   acceptable values for ((|shapetype|)) are:
-  * Class object like ShapeLib::Point (listed in ((<structure of subclasses>)))
+  * Class object like Shapelib::Point (listed in ((<structure of subclasses>)))
   * String such as (({"Point"})) or (({"PolygonZ"}))
-    (the same list, but do not include "ShapeLib::")
+    (the same list, but do not include "Shapelib::")
   * Symbol such as (({:Point})) or (({:PolygonZ}))
     (result of ((<shapefile.shape_type>)) and ((<shape.shape_type>))),
     or
@@ -465,8 +486,8 @@ This appendix discusses the detail of acceptable value.
 : field type
   For ((<shapefile.add_field|shapefile.add_field field_name, field_type, width, decimal = 0>)),
   acceptable values for ((|field_type|)) are:
-  * String "String", "Integer", or "Float", or
-  * Symbol :String, :Integer, or :Float
+  * String "String", "Integer", "Float", "Logical", or "Date", or
+  * Symbol :String, :Integer, :Float, :Logical, or :Date
     (result of ((<shapefile.field_type|shapefile.field_type field>))).
   * Integer constants listed ((<above|Field Type Constants>)).
 
@@ -487,7 +508,7 @@ This appendix discusses the detail of acceptable value.
 
 
 == References
-: ShapeLib
+: Shapelib
   ((<URL:http://shapelib.maptools.org/shp_api.html>))
   ((<URL:http://shapelib.maptools.org/dbf_api.html>))
 : ESRI Whitepaper