lipsum_words: new function for random lorem ipsum text

README.md

@@ -78,6 +78,9 @@ This is a changelog with the most important changes in each release.
 
 ### Unreleased
 
+The new `lipsum_words` function can be used to generate random lorem
+ipsum text that doesn't always start with "Lorem ipsum".
+
 Dependencies were updated and the oldest supported version of Rust is
 now 1.22.
 

src/lib.rs

@@ -395,10 +395,12 @@ thread_local! {
     }
 }
 
-/// Generate `n` words of lorem ipsum text. The output starts with
-/// "Lorem ipsum" and continues with the standard lorem ipsum text
-/// from [`LOREM_IPSUM`]. The text will become random if sufficiently
-/// long output is requested.
+/// Generate `n` words of lorem ipsum text. The output will always
+/// start with "Lorem ipsum".
+///
+/// The text continues with the standard lorem ipsum text from
+/// [`LOREM_IPSUM`] and becomes random if more than 18 words is
+/// requested. See [`lipsum_words`] if fully random text is needed.
 ///
 /// # Examples
 ///
@@ -409,22 +411,47 @@ thread_local! {
 /// ```
 ///
 /// [`LOREM_IPSUM`]: constant.LOREM_IPSUM.html
+/// [`lipsum_words`]: fn.lipsum_words.html
 pub fn lipsum(n: usize) -> String {
     LOREM_IPSUM_CHAIN.with(|cell| {
         let mut chain = cell.borrow_mut();
         chain.generate_from(n, ("Lorem", "ipsum"))
     })
 }
 
+/// Generate `n` words of random lorem ipsum text.
+///
+/// The text starts with a random word from [`LOREM_IPSUM`]. Multiple
+/// sentences may be generated, depending on the punctuation of the
+/// words being random selected.
+///
+/// # Examples
+///
+/// ```
+/// use lipsum::lipsum_words;
+///
+/// println!("{}", lipsum_words(6));
+/// // -> "Propter soliditatem, censet in infinito inani."
+/// ```
+///
+/// [`LOREM_IPSUM`]: constant.LOREM_IPSUM.html
+pub fn lipsum_words(n: usize) -> String {
+    LOREM_IPSUM_CHAIN.with(|cell| {
+        let mut chain = cell.borrow_mut();
+        chain.generate(n)
+    })
+}
+
 /// Minimum number of words to include in a title.
 const TITLE_MIN_WORDS: usize = 3;
 /// Maximum number of words to include in a title.
 const TITLE_MAX_WORDS: usize = 8;
 /// Words shorter than this size are not capitalized.
 const TITLE_SMALL_WORD: usize = 3;
 
-/// Generate a short lorem ipsum string where the words are
-/// capitalized and stripped for punctuation characters.
+/// Generate a short lorem ipsum text with words in title case.
+///
+/// The words are capitalized and stripped for punctuation characters.
 ///
 /// # Examples
 ///
@@ -496,6 +523,14 @@ mod tests {
         assert_eq!(lipsum(2).split_whitespace().count(), 2);
     }
 
+    #[test]
+    fn starts_differently() {
+        // Check that calls to lipsum_words don't always start with
+        // "Lorem ipsum".
+        let idx = "Lorem ipsum".len();
+        assert_ne!(&lipsum_words(5)[..idx], &lipsum_words(5)[..idx]);
+    }
+
     #[test]
     fn generate_title() {
         for word in lipsum_title().split_whitespace() {