Merge pull request #306 from mexx/singularize-pluralize-obsolete-plur…

…ality

add singularize/pluralize overload without using obsolete plurality enum

readme.md

@@ -368,14 +368,17 @@ There are also a few inflector methods:
 "string".Pluralize() => "strings"
 ```
 
-Normally you would call `Pluralize` on a singular word but if you're unsure about the singularity of the word you can call the method with the optional `plurality` argument:
+Normally you would call `Pluralize` on a singular word but if you're unsure about the singularity of the word you can call the method with the optional `inputIsKnownToBeSingular` argument:
 
 ```C#
-"Men".Pluralize(Plurality.CouldBeEither) => "Men"
-"Man".Pluralize(Plurality.CouldBeEither) => "Men"
-"string".Pluralize(Plurality.CouldBeEither) => "strings"
+"Men".Pluralize(inputIsKnownToBeSingular: false) => "Men"
+"Man".Pluralize(inputIsKnownToBeSingular: false) => "Men"
+"string".Pluralize(inputIsKnownToBeSingular: false) => "strings"
 ```
 
+
+The overload of `Pluralize` with `plurality` argument is obsolete and will be removed in next major release.
+
 ####<a id="singularize">Singularize</a>
 `Singularize` singularizes the provided input while taking irregular and uncountable words into consideration:
 
@@ -384,14 +387,17 @@ Normally you would call `Pluralize` on a singular word but if you're unsure abou
 "strings".Singularize() => "string"
 ```
 
-Normally you would call `Singularize` on a plural word but if you're unsure about the plurality of the word you can call the method with the optional `plurality` argument:
+Normally you would call `Singularize` on a plural word but if you're unsure about the plurality of the word you can call the method with the optional `inputIsKnownToBePlural` argument:
 
 ```C#
-"Men".Singularize(Plurality.CouldBeEither) => "Man"
-"Man".Singularize(Plurality.CouldBeEither) => "Man"
-"strings".Singularize(Plurality.CouldBeEither) => "string"
+"Men".Singularize(inputIsKnownToBePlural: false) => "Man"
+"Man".Singularize(inputIsKnownToBePlural: false) => "Man"
+"strings".Singularize(inputIsKnownToBePlural: false) => "string"
 ```
 
+
+The overload of `Singularize` with `plurality` argument is obsolete and will be removed in next major release.
+
 ####<a id="toquantity">ToQuantity</a>
 Many times you want to call `Singularize` and `Pluralize` to prefix a word with a number; e.g. "2 requests", "3 men". `ToQuantity` prefixes the provided word with the number and accordingly pluralizes or singularizes the word:
 

release_notes.md

@@ -1,4 +1,5 @@
 ###In Development
+  - [#306](https://github.com/MehdiK/Humanizer/pull/306): Added Singularize/Pluralize overload without using obsolete plurality enum
 
 [Commits](https://github.com/MehdiK/Humanizer/compare/v1.27.0...master)
 

src/Humanizer.Tests/ApiApprover/PublicApiApprovalTest.approve_public_api.approved.txt

@@ -182,7 +182,9 @@ public class InflectorExtensions
     public string Hyphenate(string underscoredWord) { }
     public string Pascalize(string input) { }
     public string Pluralize(string word, Humanizer.Plurality plurality) { }
+    public string Pluralize(string word, bool inputIsKnownToBeSingular) { }
     public string Singularize(string word, Humanizer.Plurality plurality) { }
+    public string Singularize(string word, bool inputIsKnownToBePlural) { }
     public string Titleize(string input) { }
     public string Underscore(string input) { }
 }

src/Humanizer.Tests/InflectorTests.cs

@@ -39,19 +39,12 @@ public void Pluralize(string singular, string plural)
             Assert.Equal(plural, singular.Pluralize());
         }
 
-        [Theory]
-        [ClassData(typeof(PluralTestSource))]
-        public void PluralizeAlreadyPluralWord(string singular, string plural)
-        {
-            Assert.Equal(plural, plural.Pluralize(Plurality.Plural));
-        }
-
         [Theory]
         [ClassData(typeof(PluralTestSource))]
         public void PluralizeWordsWithUnknownPlurality(string singular, string plural)
         {
-            Assert.Equal(plural, plural.Pluralize(Plurality.CouldBeEither));
-            Assert.Equal(plural, singular.Pluralize(Plurality.CouldBeEither));
+            Assert.Equal(plural, plural.Pluralize(false));
+            Assert.Equal(plural, singular.Pluralize(false));
         }
 
         [Theory]
@@ -61,19 +54,12 @@ public void Singularize(string singular, string plural)
             Assert.Equal(singular, plural.Singularize());
         }
 
-        [Theory]
-        [ClassData(typeof(PluralTestSource))]
-        public void SingularizeAlreadySingularWord(string singular, string plural)
-        {
-            Assert.Equal(singular, singular.Singularize(Plurality.Singular));
-        }
-
         [Theory]
         [ClassData(typeof(PluralTestSource))]
         public void SingularizeWordsWithUnknownSingularity(string singular, string plural)
         {
-            Assert.Equal(singular, singular.Singularize(Plurality.CouldBeEither));
-            Assert.Equal(singular, plural.Singularize(Plurality.CouldBeEither));
+            Assert.Equal(singular, singular.Singularize(false));
+            Assert.Equal(singular, plural.Singularize(false));
         }
 
         //Uppercases individual words and removes some characters 

src/Humanizer/InflectorExtensions.cs

@@ -21,6 +21,7 @@
 //IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
 //CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
+using System;
 using System.Collections.Generic;
 using System.Text.RegularExpressions;
 
@@ -168,14 +169,23 @@ private static void AddSingular(string rule, string replacement)
         /// <param name="word">Word to be pluralized</param>
         /// <param name="plurality">Normally you call Pluralize on singular words; but if you're unsure call it with Plurality.CouldBeEither</param>
         /// <returns></returns>
-        public static string Pluralize(this string word, Plurality plurality = Plurality.Singular)
+        [Obsolete("Use string.Pluralize(bool) instead. This method will be removed in next major release.")]
+        public static string Pluralize(this string word, Plurality plurality)
         {
-            if (plurality == Plurality.Plural)
-                return word;
+            return plurality == Plurality.Plural ? word : word.Pluralize(inputIsKnownToBeSingular: false);
+        }
 
+        /// <summary>
+        /// Pluralizes the provided input considering irregular words
+        /// </summary>
+        /// <param name="word">Word to be pluralized</param>
+        /// <param name="inputIsKnownToBeSingular">Normally you call Pluralize on singular words; but if you're unsure call it with false</param>
+        /// <returns></returns>
+        public static string Pluralize(this string word, bool inputIsKnownToBeSingular = true)
+        {
             var result = ApplyRules(Plurals, word);
 
-            if (plurality == Plurality.Singular)
+            if (inputIsKnownToBeSingular)
                 return result;
 
             var asSingular = ApplyRules(Singulars, word);
@@ -192,20 +202,30 @@ public static string Pluralize(this string word, Plurality plurality = Plurality
         /// <param name="word">Word to be singularized</param>
         /// <param name="plurality">Normally you call Singularize on plural words; but if you're unsure call it with Plurality.CouldBeEither</param>
         /// <returns></returns>
-        public static string Singularize(this string word, Plurality plurality = Plurality.Plural)
+        [Obsolete("Use string.Singularize(bool) instead. This method will be removed in next major release.")]
+        public static string Singularize(this string word, Plurality plurality)
+        {
+            return plurality == Plurality.Singular ? word : word.Singularize(inputIsKnownToBePlural: false);
+        }
+
+        /// <summary>
+        /// Singularizes the provided input considering irregular words
+        /// </summary>
+        /// <param name="word">Word to be singularized</param>
+        /// <param name="inputIsKnownToBePlural">Normally you call Singularize on plural words; but if you're unsure call it with false</param>
+        /// <returns></returns>
+        public static string Singularize(this string word, bool inputIsKnownToBePlural = true)
         {
-            if (plurality == Plurality.Singular)
-                return word;
 
             var result = ApplyRules(Singulars, word);
 
-            if (plurality == Plurality.Plural)
+            if (inputIsKnownToBePlural)
                 return result;
 
             // the Plurality is unknown so we should check all possibilities
             var asPlural = ApplyRules(Plurals, word);
             var asPluralAsSingular = ApplyRules(Singulars, asPlural);
-            if (asPlural != word && word+"s" != asPlural && asPluralAsSingular == word && result != word)
+            if (asPlural != word && word + "s" != asPlural && asPluralAsSingular == word && result != word)
                 return word;
 
             return result ?? word;

src/Humanizer/ToQuantityExtensions.cs

@@ -70,8 +70,8 @@ public static string ToQuantity(this string input, int quantity, string format,
         private static string ToQuantity(this string input, int quantity, ShowQuantityAs showQuantityAs = ShowQuantityAs.Numeric, string format = null, IFormatProvider formatProvider = null)
         {
             var transformedInput = quantity == 1
-                ? input.Singularize(Plurality.CouldBeEither)
-                : input.Pluralize(Plurality.CouldBeEither);
+                ? input.Singularize(inputIsKnownToBePlural: false)
+                : input.Pluralize(inputIsKnownToBeSingular: false);
 
             if (showQuantityAs == ShowQuantityAs.None)
                 return transformedInput;