Skip to content

Commit 9233a16

Browse files
jakobnissenvtjnash
jakobnissen
and
vtjnash
authored
Document Base.StatStruct's fields as public (#50177)
These fields are documented in the docstring of `stat`, and also mentioned as being public in the style guide, but their types are not documented, nor is `StatStruct` directly documented. --------- Co-authored-by: Jameson Nash <vtjnash@gmail.com>
1 parent 9dcedaa commit 9233a16

File tree

2 files changed

+61
-16
lines changed

2 files changed

+61
-16
lines changed

‎base/stat.jl

Lines changed: 39 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,30 @@ export
2525
stat,
2626
uperm
2727

28+
"""
29+
StatStruct
30+
31+
A struct which stores the information from `stat`.
32+
The following fields of this struct is considered public API:
33+
34+
| Name | Type | Description |
35+
|:--------|:--------------------------------|:-------------------------------------------------------------------|
36+
| desc | `Union{String, Base.OS_HANDLE}` | The path or OS file descriptor |
37+
| size | `Int64` | The size (in bytes) of the file |
38+
| device | `UInt` | ID of the device that contains the file |
39+
| inode | `UInt` | The inode number of the file |
40+
| mode | `UInt` | The protection mode of the file |
41+
| nlink | `Int` | The number of hard links to the file |
42+
| uid | `UInt` | The user id of the owner of the file |
43+
| gid | `UInt` | The group id of the file owner |
44+
| rdev | `UInt` | If this file refers to a device, the ID of the device it refers to |
45+
| blksize | `Int64` | The file-system preferred block size for the file |
46+
| blocks | `Int64` | The number of 512-byte blocks allocated |
47+
| mtime | `Float64` | Unix timestamp of when the file was last modified |
48+
| ctime | `Float64` | Unix timestamp of when the file's metadata was changed |
49+
50+
See also: [`stat`](@ref)
51+
"""
2852
struct StatStruct
2953
desc :: Union{String, OS_HANDLE} # for show method, not included in equality or hash
3054
device :: UInt
@@ -173,22 +197,21 @@ stat(fd::Integer) = stat(RawFD(fd))
173197
Return a structure whose fields contain information about the file.
174198
The fields of the structure are:
175199
176-
| Name | Description |
177-
|:--------|:-------------------------------------------------------------------|
178-
| desc | The path or OS file descriptor |
179-
| size | The size (in bytes) of the file |
180-
| device | ID of the device that contains the file |
181-
| inode | The inode number of the file |
182-
| mode | The protection mode of the file |
183-
| nlink | The number of hard links to the file |
184-
| uid | The user id of the owner of the file |
185-
| gid | The group id of the file owner |
186-
| rdev | If this file refers to a device, the ID of the device it refers to |
187-
| blksize | The file-system preferred block size for the file |
188-
| blocks | The number of 512-byte blocks allocated |
189-
| mtime | Unix timestamp of when the file was last modified |
190-
| ctime | Unix timestamp of when the file's metadata was changed |
191-
200+
| Name | Type | Description |
201+
|:--------|:--------------------------------|:-------------------------------------------------------------------|
202+
| desc | `Union{String, Base.OS_HANDLE}` | The path or OS file descriptor |
203+
| size | `Int64` | The size (in bytes) of the file |
204+
| device | `UInt` | ID of the device that contains the file |
205+
| inode | `UInt` | The inode number of the file |
206+
| mode | `UInt` | The protection mode of the file |
207+
| nlink | `Int` | The number of hard links to the file |
208+
| uid | `UInt` | The user id of the owner of the file |
209+
| gid | `UInt` | The group id of the file owner |
210+
| rdev | `UInt` | If this file refers to a device, the ID of the device it refers to |
211+
| blksize | `Int64` | The file-system preferred block size for the file |
212+
| blocks | `Int64` | The number of 512-byte blocks allocated |
213+
| mtime | `Float64` | Unix timestamp of when the file was last modified |
214+
| ctime | `Float64` | Unix timestamp of when the file's metadata was changed |
192215
"""
193216
stat(path...) = stat(joinpath(path...))
194217

‎test/file.jl

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1695,6 +1695,28 @@ if Sys.iswindows()
16951695
end
16961696
end
16971697

1698+
# Unusually for structs, we test this explicitly because the fields of StatStruct
1699+
# is part of its documentation, and therefore cannot change.
1700+
@testset "StatStruct has promised fields" begin
1701+
f, io = mktemp()
1702+
s = stat(f)
1703+
@test s isa Base.StatStruct
1704+
1705+
@test s.desc isa Union{String, Base.OS_HANDLE}
1706+
@test s.size isa Int64
1707+
@test s.device isa UInt
1708+
@test s.inode isa UInt
1709+
@test s.mode isa UInt
1710+
@test s.nlink isa Int
1711+
@test s.uid isa UInt
1712+
@test s.gid isa UInt
1713+
@test s.rdev isa UInt
1714+
@test s.blksize isa Int64
1715+
@test s.blocks isa Int64
1716+
@test s.mtime isa Float64
1717+
@test s.ctime isa Float64
1718+
end
1719+
16981720
@testset "StatStruct show's extended details" begin
16991721
f, io = mktemp()
17001722
s = stat(f)

0 commit comments

Comments
 (0)