From 89efb7d9810643eb1b25c04e63203b591915448f Mon Sep 17 00:00:00 2001 From: Brian Anderson Date: Tue, 6 Dec 2011 13:58:45 -0800 Subject: [PATCH] libstd: Update docs --- doc/Languages.txt | 1 + src/libstd/c_vec.rs | 52 ++++++++++++++++++++ src/libstd/ctypes.rs | 108 ++++++++++++++++++++++++++++++++++++++++- src/libstd/float.rs | 13 ++--- src/libstd/io.rs | 6 +++ src/libstd/math.rs | 3 ++ src/libstd/math_f32.rs | 1 + src/libstd/math_f64.rs | 1 + src/libstd/str.rs | 3 +- src/libstd/tempfile.rs | 3 ++ 10 files changed, 178 insertions(+), 13 deletions(-) diff --git a/doc/Languages.txt b/doc/Languages.txt index c83e0d86ca9..565e4c27109 100644 --- a/doc/Languages.txt +++ b/doc/Languages.txt @@ -120,6 +120,7 @@ Language: Rust Block Comment: /* */ Package Separator: :: Function Prototype Enders: ; { + Predicate Prototype Enders: ; { Type Prototype Enders: ; } Class Prototype Enders: { Variant Prototype Enders: ; diff --git a/src/libstd/c_vec.rs b/src/libstd/c_vec.rs index ff5f636d103..7c2f1be7084 100644 --- a/src/libstd/c_vec.rs +++ b/src/libstd/c_vec.rs @@ -57,6 +57,16 @@ resource dtor_res(dtor: option::t) { Section: Introduction forms */ +/* +Function: create + +Create a c_vec::t from a native buffer with a given size. + +Parameters: + +base - A native pointer to a buffer +size - The number of elements in the buffer +*/ unsafe fn create(base: *mutable T, size: uint) -> t { ret t({base: base, size: size, @@ -64,6 +74,19 @@ unsafe fn create(base: *mutable T, size: uint) -> t { }); } +/* +Function: create_with_dtor + +Create a c_vec::t from a native buffer, with a given size, +and a function to run upon destruction. + +Parameters: + +base - A native pointer to a buffer +size - The number of elements in the buffer +dtor - A function to run when the value is destructed, useful + for freeing the buffer, etc. +*/ unsafe fn create_with_dtor(base: *mutable T, size: uint, dtor: fn@()) -> t { ret t({base: base, @@ -76,11 +99,29 @@ unsafe fn create_with_dtor(base: *mutable T, size: uint, dtor: fn@()) Section: Operations */ +/* +Function: get + +Retrieves an element at a given index + +Failure: + +If `ofs` is greater or equal to the length of the vector +*/ fn get(t: t, ofs: uint) -> T { assert ofs < (*t).size; ret unsafe { *ptr::mut_offset((*t).base, ofs) }; } +/* +Function: set + +Sets the value of an element at a given index + +Failure: + +If `ofs` is greater or equal to the length of the vector +*/ fn set(t: t, ofs: uint, v: T) { assert ofs < (*t).size; unsafe { *ptr::mut_offset((*t).base, ofs) = v }; @@ -90,10 +131,21 @@ fn set(t: t, ofs: uint, v: T) { Section: Elimination forms */ +// FIXME: Rename to len +/* +Function: size + +Returns the length of the vector +*/ fn size(t: t) -> uint { ret (*t).size; } +/* +Function: ptr + +Returns a pointer to the first element of the vector +*/ unsafe fn ptr(t: t) -> *mutable T { ret (*t).base; } diff --git a/src/libstd/ctypes.rs b/src/libstd/ctypes.rs index 82e414a864c..509eb3ef057 100644 --- a/src/libstd/ctypes.rs +++ b/src/libstd/ctypes.rs @@ -4,39 +4,143 @@ Module: ctypes Definitions useful for C interop */ +/* +FIXME: Add a test that uses some native code to verify these sizes, +which are not obviously correct for all potential platforms. +*/ + +/* +Type: c_int + +A signed integer with the same size as a C `int` +*/ type c_int = i32; + +/* +Type: c_uint + +An unsigned integer with the same size as a C `unsigned int` +*/ type c_uint = u32; -type void = int; // Not really the same as C +/* +Type: long + +A signed integer with the same size as a C `long` +*/ type long = int; + +/* +Type: unsigned + +An unsigned integer with the same size as a C `unsigned int` +*/ type unsigned = u32; + +/* +Type: ulong + +An unsigned integer with the same size as a C `unsigned long` +*/ type ulong = uint; -type intptr_t = uint; +/* +Type: intptr_t + +A signed integer with the same size as a pointer. This is +guaranteed to always be the same type as a Rust `int` +*/ +type intptr_t = uint; // FIXME: int + +/* +Type: uintptr_t + +An unsigned integer with the same size as a pointer. This is +guaranteed to always be the same type as a Rust `uint`. +*/ type uintptr_t = uint; type uint32_t = u32; +/* +Type: void + +A type, a pointer to which can be used as C `void *` + +Note that this does not directly correspond to the C `void` type, +which is an incomplete type. Using pointers to this type +when interoperating with C void pointers can help in documentation. +*/ +type void = int; + // machine type equivalents of rust int, uint, float +/* +Type: m_int + +FIXME: What C type does this represent? +*/ #[cfg(target_arch="x86")] type m_int = i32; #[cfg(target_arch="x86_64")] type m_int = i64; +/* +Type: m_uint + +FIXME: What C type does this represent? +*/ #[cfg(target_arch="x86")] type m_uint = u32; #[cfg(target_arch="x86_64")] type m_uint = u64; // This *must* match with "import m_float = fXX" in std::math per arch +/* +Type: m_float + +FIXME: What C type does this represent? +*/ type m_float = f64; +/* +Type: size_t + +An unsigned integer corresponding to the C `size_t` +*/ type size_t = uint; + +/* +Type: ssize_t + +A signed integer correpsonding to the C `ssize_t` +*/ type ssize_t = int; + +/* +Type: off_t + +An unsigned integer corresponding to the C `off_t` +*/ type off_t = uint; +/* +Type: fd_t + +A type that can be used for C file descriptors +*/ type fd_t = i32; // not actually a C type, but should be. + +/* +Type: pid_t + +A type for representing process ID's, corresponding to C `pid_t` +*/ type pid_t = i32; // enum is implementation-defined, but is 32-bits in practice +/* +Type: enum + +An unsigned integer with the same size as a C enum +*/ type enum = u32; diff --git a/src/libstd/float.rs b/src/libstd/float.rs index f916e97bbf8..015dceb1dc1 100644 --- a/src/libstd/float.rs +++ b/src/libstd/float.rs @@ -253,25 +253,18 @@ fn pow_uint_to_uint_as_float(x: uint, pow: uint) -> float { } -/** - * Section: Constants - */ - -//TODO: Once this is possible, replace the body of these functions -//by an actual constant. - /* Const: NaN */ const NaN: float = 0./0.; -/* Predicate: isNaN */ -pure fn isNaN(f: float) -> bool { f != f } - /* Const: infinity */ const infinity: float = 1./0.; /* Const: neg_infinity */ const neg_infinity: float = -1./0.; +/* Predicate: isNaN */ +pure fn isNaN(f: float) -> bool { f != f } + /* Function: add */ pure fn add(x: float, y: float) -> float { ret x + y; } diff --git a/src/libstd/io.rs b/src/libstd/io.rs index 910ec8bb9ea..06e1be2fc4b 100644 --- a/src/libstd/io.rs +++ b/src/libstd/io.rs @@ -1,3 +1,9 @@ +/* +Module: io + +Basic input/output +*/ + import ctypes::fd_t; import ctypes::c_int; diff --git a/src/libstd/math.rs b/src/libstd/math.rs index 72056548ca5..31bfe2ba3a6 100644 --- a/src/libstd/math.rs +++ b/src/libstd/math.rs @@ -23,6 +23,9 @@ import ctypes::c_int; import m_float = math_f64; // FIXME replace with redirect to m_float::consts::FOO as soon as it works +/* +Module: consts +*/ mod consts { /* Const: pi diff --git a/src/libstd/math_f32.rs b/src/libstd/math_f32.rs index 2172c9f8a99..6c36db51a67 100644 --- a/src/libstd/math_f32.rs +++ b/src/libstd/math_f32.rs @@ -17,6 +17,7 @@ export export consts; +/* Module: consts */ mod consts { /* diff --git a/src/libstd/math_f64.rs b/src/libstd/math_f64.rs index 639dc4a29b2..cc8fad9f665 100644 --- a/src/libstd/math_f64.rs +++ b/src/libstd/math_f64.rs @@ -17,6 +17,7 @@ export export consts; +/* Module: consts */ mod consts { /* diff --git a/src/libstd/str.rs b/src/libstd/str.rs index fb24c59f62f..2bae8d699a5 100644 --- a/src/libstd/str.rs +++ b/src/libstd/str.rs @@ -174,7 +174,8 @@ fn byte_len_range(s: str, byte_offset: uint, char_len: uint) -> uint { /* Function: bytes -Converts a string to a vector of bytes +Converts a string to a vector of bytes. The result vector is not +null-terminated. */ fn bytes(s: str) -> [u8] unsafe { let v = unsafe::reinterpret_cast(s); diff --git a/src/libstd/tempfile.rs b/src/libstd/tempfile.rs index 5f504ba2349..ee7d5e3b2d9 100644 --- a/src/libstd/tempfile.rs +++ b/src/libstd/tempfile.rs @@ -9,6 +9,9 @@ import option; import option::{none, some}; import rand; +/* +Function: mkdtemp +*/ fn mkdtemp(prefix: str, suffix: str) -> option::t { let r = rand::mk_rng(); let i = 0u;