Treats:
#path
::stat
::lstat
#lstat
::directory?
Also adds section "Example Files" that explains assumptions about example files. I'm using t.txt already, and I'm pretty sure I'll need t.dat (binary data). I don't know whether I'll need t.rus (Russian text).
Allocating a string of length MAXPATHLEN and then shrinking the string
is inefficient when the resulting path is short. Preallocating a large
string is also a problem for Variable Width Allocation since we can't
easily downsize the capacity.
I ran the following benchmark:
```ruby
Benchmark.ips do |x|
{
"empty" => "",
"short" => "a/" * 10,
"medium" => "a/" * 100,
"long" => "a/" * 500
}.each do |name, path|
x.report(name) do |times|
i = 0
while i < times
File.expand_path(path)
i += 1
end
end
end
end
```
On this commit:
```
empty 97.486k (± 0.7%) i/s - 492.915k in 5.056507s
short 96.026k (± 2.4%) i/s - 486.489k in 5.068966s
medium 86.304k (± 1.3%) i/s - 435.336k in 5.045112s
long 59.395k (± 1.7%) i/s - 302.175k in 5.089026s
```
On master:
```
empty 94.138k (± 1.4%) i/s - 472.158k in 5.016590s
short 92.043k (± 1.4%) i/s - 468.180k in 5.087496s
medium 84.910k (± 2.3%) i/s - 425.750k in 5.017007s
long 61.503k (± 2.7%) i/s - 309.723k in 5.039429s
```
I used this regex:
([A-Za-z]+)\.html#(?:class|module)-[A-Za-z]+-label-([A-Za-z0-9\-\+]+)
And performed a global find & replace for this:
rdoc-ref:$1@$2
After the change to use realpath on loaded features, Solaris CI
started failing in test_no_curdir (which tests behavior for running
ruby without a working directory).
I was able to trace the problem to the following call chain:
rb_call_inits->Init_Thread->Init_thread_sync->rb_provide->
get_loaded_features_index->rb_check_realpath->rb_dir_getwd_ospath->
ruby_getcwd
This will throw an exception, but because Ruby hasn't been fully
initialized at the point the exception is thrown, it just exits
with a status of 1.
The bug here is that rb_check_realpath should not raise an
exception, it should return nil. This bug is hit on Solaris
because Solaris uses the realpath emulation instead of native
realpath, and the realpath emualation raised instead of
returning nil if the mode was RB_REALPATH_CHECK. Use rb_rescue
in the realpath emulation if the mode is RB_REALPATH_CHECK, and
swallow any exceptions raised and return nil.
Fill with the pointer to the root position, instead of zero and
comparing later. Also suppress a false warning by Visual C++.
```
file.c(4759): warning C4090: 'function': different 'const' qualifiers
```
Not every compilers understand that rb_raise does not return. When a
function does not end with a return statement, such compilers can issue
warnings. We would better tell them about reachabilities.
