From 2ec2d99bbd1a15a8f278b3cb82ddfa9ebafa96b3 Mon Sep 17 00:00:00 2001 From: Leah Hanson Date: Fri, 12 Apr 2013 09:41:07 -0400 Subject: [PATCH 1/6] add rustdoc comments with examples for the string versions of to_base64 and from_base64 --- src/libstd/base64.rs | 45 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) diff --git a/src/libstd/base64.rs b/src/libstd/base64.rs index 0266f2d8631cf..0815e0ff0b502 100644 --- a/src/libstd/base64.rs +++ b/src/libstd/base64.rs @@ -75,6 +75,23 @@ impl<'self> ToBase64 for &'self [u8] { } } +/** + * Convert any string (literal, `@`, `&`, `~`) to base64 encoding. + * + * + * *Example*: + * + * ~~~~ + * extern mod std; + * use std::base64::ToBase64; + * + * fn main () { + * let str = "Hello, World".to_base64(); + * println(fmt!("%s",str)); + * } + * ~~~~ + * + */ impl<'self> ToBase64 for &'self str { fn to_base64(&self) -> ~str { str::to_bytes(*self).to_base64() @@ -147,6 +164,34 @@ impl FromBase64 for ~[u8] { } } +/** + * Convert any string (literal, `@`, `&`, `~`) + * that contains a base64 encoded value, to the byte values it encodes. + * + * You can use the `from_bytes` function in `core::str` + * to turn a `[u8]` into a string with characters corresponding to those values. + * + * *Example*: + * + * This is an example of going from a string literal to the base64 encoding + * and back to the same string. + * + * ~~~~ + * extern mod std; + * use std::base64::ToBase64; + * use std::base64::FromBase64; + * use core::str; + * + * fn main () { + * let hello_str = "Hello, World".to_base64(); + * println(fmt!("%s",hello_str)); + * let bytes = hello_str.from_base64(); + * println(fmt!("%?",bytes)); + * let result_str = str::from_bytes(bytes); + * println(fmt!("%s",result_str)); + * } + * ~~~~ + */ impl FromBase64 for ~str { fn from_base64(&self) -> ~[u8] { str::to_bytes(*self).from_base64() From 27a0269501637d7fa27356caa9c13ab66fe5c8b0 Mon Sep 17 00:00:00 2001 From: Leah Hanson Date: Fri, 12 Apr 2013 22:15:56 -0400 Subject: [PATCH 2/6] Add comments for the implementations of from_base64 and to_base64 for . --- src/libstd/base64.rs | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/src/libstd/base64.rs b/src/libstd/base64.rs index 0815e0ff0b502..618f5ecccf73c 100644 --- a/src/libstd/base64.rs +++ b/src/libstd/base64.rs @@ -26,6 +26,21 @@ static CHARS: [char, ..64] = [ '0', '1', '2', '3', '4', '5', '6', '7', '8', '9', '+', '/' ]; +/** + * Turn a vector of `u8` bytes into a string representing them in base64. + * + * *Example*: + * + * ~~~~ + * extern mod std; + * use std::base64::ToBase64; + * + * fn main () { + * let str = [52,32].to_base64(); + * println(fmt!("%s", str)); + * } + * ~~~~ + */ impl<'self> ToBase64 for &'self [u8] { fn to_base64(&self) -> ~str { let mut s = ~""; @@ -102,6 +117,25 @@ pub trait FromBase64 { fn from_base64(&self) -> ~[u8]; } +/** + * Turn a vector of `u8`s representing characters + * encoding byte values in base64 into the vector of `u8` byte values. + * + * *Example*: + * + * ~~~~ + * extern mod std; + * use std::base64::ToBase64; + * use std::base64::FromBase64; + * + * fn main () { + * let str = [52,32].to_base64(); + * println(fmt!("%s", str)); + * let bytes = str.from_base64(); + * println(fmt!("%?",bytes)); + * } + * ~~~~ + */ impl FromBase64 for ~[u8] { fn from_base64(&self) -> ~[u8] { if self.len() % 4u != 0u { fail!(~"invalid base64 length"); } From 8e64b61df9a9b22dc742fcd25f0533f5b4580477 Mon Sep 17 00:00:00 2001 From: Leah Hanson Date: Sat, 13 Apr 2013 08:11:39 -0400 Subject: [PATCH 3/6] move rustdoc comments so that they attach to the functions rather than the impl blocks. --- src/libstd/base64.rs | 158 +++++++++++++++++++++---------------------- 1 file changed, 79 insertions(+), 79 deletions(-) diff --git a/src/libstd/base64.rs b/src/libstd/base64.rs index 618f5ecccf73c..5b1e82ce1f00e 100644 --- a/src/libstd/base64.rs +++ b/src/libstd/base64.rs @@ -26,22 +26,22 @@ static CHARS: [char, ..64] = [ '0', '1', '2', '3', '4', '5', '6', '7', '8', '9', '+', '/' ]; -/** - * Turn a vector of `u8` bytes into a string representing them in base64. - * - * *Example*: - * - * ~~~~ - * extern mod std; - * use std::base64::ToBase64; - * - * fn main () { - * let str = [52,32].to_base64(); - * println(fmt!("%s", str)); - * } - * ~~~~ - */ impl<'self> ToBase64 for &'self [u8] { + /** + * Turn a vector of `u8` bytes into a string representing them in base64. + * + * *Example*: + * + * ~~~~ + * extern mod std; + * use std::base64::ToBase64; + * + * fn main () { + * let str = [52,32].to_base64(); + * println(fmt!("%s", str)); + * } + * ~~~~ + */ fn to_base64(&self) -> ~str { let mut s = ~""; unsafe { @@ -90,24 +90,24 @@ impl<'self> ToBase64 for &'self [u8] { } } -/** - * Convert any string (literal, `@`, `&`, `~`) to base64 encoding. - * - * - * *Example*: - * - * ~~~~ - * extern mod std; - * use std::base64::ToBase64; - * - * fn main () { - * let str = "Hello, World".to_base64(); - * println(fmt!("%s",str)); - * } - * ~~~~ - * - */ impl<'self> ToBase64 for &'self str { + /** + * Convert any string (literal, `@`, `&`, `~`) to base64 encoding. + * + * + * *Example*: + * + * ~~~~ + * extern mod std; + * use std::base64::ToBase64; + * + * fn main () { + * let str = "Hello, World".to_base64(); + * println(fmt!("%s",str)); + * } + * ~~~~ + * + */ fn to_base64(&self) -> ~str { str::to_bytes(*self).to_base64() } @@ -117,26 +117,26 @@ pub trait FromBase64 { fn from_base64(&self) -> ~[u8]; } -/** - * Turn a vector of `u8`s representing characters - * encoding byte values in base64 into the vector of `u8` byte values. - * - * *Example*: - * - * ~~~~ - * extern mod std; - * use std::base64::ToBase64; - * use std::base64::FromBase64; - * - * fn main () { - * let str = [52,32].to_base64(); - * println(fmt!("%s", str)); - * let bytes = str.from_base64(); - * println(fmt!("%?",bytes)); - * } - * ~~~~ - */ impl FromBase64 for ~[u8] { + /** + * Turn a vector of `u8`s representing characters + * encoding byte values in base64 into the vector of `u8` byte values. + * + * *Example*: + * + * ~~~~ + * extern mod std; + * use std::base64::ToBase64; + * use std::base64::FromBase64; + * + * fn main () { + * let str = [52,32].to_base64(); + * println(fmt!("%s", str)); + * let bytes = str.from_base64(); + * println(fmt!("%?",bytes)); + * } + * ~~~~ + */ fn from_base64(&self) -> ~[u8] { if self.len() % 4u != 0u { fail!(~"invalid base64 length"); } @@ -198,35 +198,35 @@ impl FromBase64 for ~[u8] { } } -/** - * Convert any string (literal, `@`, `&`, `~`) - * that contains a base64 encoded value, to the byte values it encodes. - * - * You can use the `from_bytes` function in `core::str` - * to turn a `[u8]` into a string with characters corresponding to those values. - * - * *Example*: - * - * This is an example of going from a string literal to the base64 encoding - * and back to the same string. - * - * ~~~~ - * extern mod std; - * use std::base64::ToBase64; - * use std::base64::FromBase64; - * use core::str; - * - * fn main () { - * let hello_str = "Hello, World".to_base64(); - * println(fmt!("%s",hello_str)); - * let bytes = hello_str.from_base64(); - * println(fmt!("%?",bytes)); - * let result_str = str::from_bytes(bytes); - * println(fmt!("%s",result_str)); - * } - * ~~~~ - */ impl FromBase64 for ~str { + /** + * Convert any string (literal, `@`, `&`, `~`) + * that contains a base64 encoded value, to the byte values it encodes. + * + * You can use the `from_bytes` function in `core::str` + * to turn a `[u8]` into a string with characters corresponding to those values. + * + * *Example*: + * + * This is an example of going from a string literal to the base64 encoding + * and back to the same string. + * + * ~~~~ + * extern mod std; + * use std::base64::ToBase64; + * use std::base64::FromBase64; + * use core::str; + * + * fn main () { + * let hello_str = "Hello, World".to_base64(); + * println(fmt!("%s",hello_str)); + * let bytes = hello_str.from_base64(); + * println(fmt!("%?",bytes)); + * let result_str = str::from_bytes(bytes); + * println(fmt!("%s",result_str)); + * } + * ~~~~ + */ fn from_base64(&self) -> ~[u8] { str::to_bytes(*self).from_base64() } From 78bc10d94bcaecbc45687b82e82dd46a79cd29b3 Mon Sep 17 00:00:00 2001 From: Dan Luu Date: Sat, 13 Apr 2013 16:17:30 -0400 Subject: [PATCH 4/6] Doc review, as requested :-). Mostly just phrasing things differently, which is a matter of taste. Feel free to use or not use any of the changes I'm suggesting. I would say this one thing should be changed, though, not necessarily the way I changed it here. * Convert any string (literal, `@`, `&`, `~`) * that contains a base64 encoded value, to the byte values it encodes. If this structure is going to be used, either the entire clause, 'that contains a base64 encoded value', should be bracketed by commas, or the comma at the end of the clause should be removed. --- src/libstd/base64.rs | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/src/libstd/base64.rs b/src/libstd/base64.rs index 5b1e82ce1f00e..054f3a2b10839 100644 --- a/src/libstd/base64.rs +++ b/src/libstd/base64.rs @@ -28,7 +28,7 @@ static CHARS: [char, ..64] = [ impl<'self> ToBase64 for &'self [u8] { /** - * Turn a vector of `u8` bytes into a string representing them in base64. + * Turn a vector of `u8` bytes into a base64 string. * * *Example*: * @@ -92,7 +92,7 @@ impl<'self> ToBase64 for &'self [u8] { impl<'self> ToBase64 for &'self str { /** - * Convert any string (literal, `@`, `&`, `~`) to base64 encoding. + * Convert any string (literal, `@`, `&`, or `~`) to base64 encoding. * * * *Example*: @@ -119,8 +119,8 @@ pub trait FromBase64 { impl FromBase64 for ~[u8] { /** - * Turn a vector of `u8`s representing characters - * encoding byte values in base64 into the vector of `u8` byte values. + * Convert base64 `u8` vector into u8 byte values. + * Every 4 encoded characters is converted into 3 octets, modulo padding. * * *Example*: * @@ -200,16 +200,15 @@ impl FromBase64 for ~[u8] { impl FromBase64 for ~str { /** - * Convert any string (literal, `@`, `&`, `~`) - * that contains a base64 encoded value, to the byte values it encodes. + * Convert any base64 encoded string (literal, `@`, `&`, or `~`) + * to the byte values it encodes. * * You can use the `from_bytes` function in `core::str` * to turn a `[u8]` into a string with characters corresponding to those values. * * *Example*: * - * This is an example of going from a string literal to the base64 encoding - * and back to the same string. + * This converts a string literal to base64 and back. * * ~~~~ * extern mod std; From ced12a74cd5195852d9f074c5334a678f4aa001c Mon Sep 17 00:00:00 2001 From: Leah Hanson Date: Sun, 14 Apr 2013 08:01:54 -0400 Subject: [PATCH 5/6] update copyright notice on base64.rs --- src/libstd/base64.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/libstd/base64.rs b/src/libstd/base64.rs index 054f3a2b10839..1a7c1542f9d56 100644 --- a/src/libstd/base64.rs +++ b/src/libstd/base64.rs @@ -1,4 +1,4 @@ -// Copyright 2012 The Rust Project Developers. See the COPYRIGHT +// Copyright 2012-2013 The Rust Project Developers. See the COPYRIGHT // file at the top-level directory of this distribution and at // http://rust-lang.org/COPYRIGHT. // From b5c9990c387fff415a7de54f5870e5af92169a5d Mon Sep 17 00:00:00 2001 From: Leah Hanson Date: Sun, 14 Apr 2013 09:24:13 -0400 Subject: [PATCH 6/6] Change to 4-space indents in code examples --- src/libstd/base64.rs | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/src/libstd/base64.rs b/src/libstd/base64.rs index 1a7c1542f9d56..5da7cfa3efed8 100644 --- a/src/libstd/base64.rs +++ b/src/libstd/base64.rs @@ -37,8 +37,8 @@ impl<'self> ToBase64 for &'self [u8] { * use std::base64::ToBase64; * * fn main () { - * let str = [52,32].to_base64(); - * println(fmt!("%s", str)); + * let str = [52,32].to_base64(); + * println(fmt!("%s", str)); * } * ~~~~ */ @@ -102,8 +102,8 @@ impl<'self> ToBase64 for &'self str { * use std::base64::ToBase64; * * fn main () { - * let str = "Hello, World".to_base64(); - * println(fmt!("%s",str)); + * let str = "Hello, World".to_base64(); + * println(fmt!("%s",str)); * } * ~~~~ * @@ -130,10 +130,10 @@ impl FromBase64 for ~[u8] { * use std::base64::FromBase64; * * fn main () { - * let str = [52,32].to_base64(); - * println(fmt!("%s", str)); - * let bytes = str.from_base64(); - * println(fmt!("%?",bytes)); + * let str = [52,32].to_base64(); + * println(fmt!("%s", str)); + * let bytes = str.from_base64(); + * println(fmt!("%?",bytes)); * } * ~~~~ */ @@ -217,12 +217,12 @@ impl FromBase64 for ~str { * use core::str; * * fn main () { - * let hello_str = "Hello, World".to_base64(); - * println(fmt!("%s",hello_str)); - * let bytes = hello_str.from_base64(); - * println(fmt!("%?",bytes)); - * let result_str = str::from_bytes(bytes); - * println(fmt!("%s",result_str)); + * let hello_str = "Hello, World".to_base64(); + * println(fmt!("%s",hello_str)); + * let bytes = hello_str.from_base64(); + * println(fmt!("%?",bytes)); + * let result_str = str::from_bytes(bytes); + * println(fmt!("%s",result_str)); * } * ~~~~ */