[aXSL-commit] SF.net SVN: axsl:[3335] trunk/axsl/axsl-orthography/s rc/main/java/org/axsl/orthography

[<vic...@us...>]

Revision: 3335
          http://sourceforge.net/p/axsl/code/3335
Author:   victormote
Date:     2026-07-23 13:19:47 +0000 (Thu, 23 Jul 2026)
Log Message:
-----------
Add AmbiguousWord interface and method to retrieve it from Dictionary.

Modified Paths:
--------------
    trunk/axsl/axsl-orthography/src/main/java/org/axsl/orthography/Dictionary.java
    trunk/axsl/axsl-orthography/src/main/java/org/axsl/orthography/Orthography.java

Added Paths:
-----------
    trunk/axsl/axsl-orthography/src/main/java/org/axsl/orthography/AmbiguousWord.java

Added: trunk/axsl/axsl-orthography/src/main/java/org/axsl/orthography/AmbiguousWord.java
===================================================================
--- trunk/axsl/axsl-orthography/src/main/java/org/axsl/orthography/AmbiguousWord.java	                        (rev 0)
+++ trunk/axsl/axsl-orthography/src/main/java/org/axsl/orthography/AmbiguousWord.java	2026-07-23 13:19:47 UTC (rev 3335)
@@ -0,0 +1,45 @@
+/*
+ * Copyright 2026 The aXSL Project.
+ *      http://www.axsl.org
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/*
+ * $LastChangedRevision$
+ * $LastChangedDate$
+ * $LastChangedBy$
+ */
+
+package org.axsl.orthography;
+
+/**
+ * Container for words that are spelled the same, but that have different hyphenation, depending on part-of-speech.
+ * Instances are obtained from {@link Dictionary#getAmbiguousWord(CharSequence)}.
+ */
+public interface AmbiguousWord {
+
+    /**
+     * Returns the number of alternatives for this ambiguous word.
+     * @return The number of alternatives for this ambiguous word.
+     */
+    int size();
+
+    /**
+     * Retrieves an alternative from this ambiguous word.
+     * @param index The index into the (conceptual) array of alternatives.
+     * @return The word at {code index}.
+     */
+    Word getAlternative(int index);
+
+}


Property changes on: trunk/axsl/axsl-orthography/src/main/java/org/axsl/orthography/AmbiguousWord.java
___________________________________________________________________
Added: svn:keywords
## -0,0 +1 ##
+Author Date Id Rev
\ No newline at end of property
Modified: trunk/axsl/axsl-orthography/src/main/java/org/axsl/orthography/Dictionary.java
===================================================================
--- trunk/axsl/axsl-orthography/src/main/java/org/axsl/orthography/Dictionary.java	2026-07-22 17:30:36 UTC (rev 3334)
+++ trunk/axsl/axsl-orthography/src/main/java/org/axsl/orthography/Dictionary.java	2026-07-23 13:19:47 UTC (rev 3335)
@@ -40,26 +40,50 @@
     WritingSystem getWritingSystem();
 
     /**
-     * Returns the number of alternative ways a given sequence of characters appears in this dictionary.
-     * @param wordChars The chars whose word is being queried.
-     * @return The number of alternatives for this word in this dictionary.
-     * @see #getWord(CharSequence, int) where this quantity can be used to iterate the alternatives.
+     * Retrieves an unambiguous word from this dictionary.
+     * By "unambiguous" is meant that there is only one correct way to hyphenate the word.
+     * Applications looking up words in a dictionary should generally check both {@link #getWord(CharSequence)} and
+     * {@link #getAmbiguousWord(CharSequence)} before deciding that the word is not available.
+     * @param wordChars The chars whose word should be retrieved.
+     * @return The word matching {@code wordChars} or null if none matches.
+     * @see #getAmbiguousWord(CharSequence)} to obtain a word that has more than one correct way to be hyphenated,
+     * based on usage.
+     * @see Orthography#recognizeWord(CharSequence, int, int, org.axsl.orthography.Word.PartOfSpeech) which can
+     * also consider other dictionaries as well as derivative forms.
      */
-    int qtyAlternatives(CharSequence wordChars);
+    Word getWord(CharSequence wordChars);
 
     /**
-     * Retrieves a word from this dictionary based on an index into its alternatives.
+     * Retrieves an ambiguous word from this dictionary.
      * The same sequence of characters can be represented by different words, usually because of differences in
      * part-of-speech.
+     * Applications looking up words in a dictionary should generally check both {@link #getWord(CharSequence)} and
+     * {@link #getAmbiguousWord(CharSequence)} before deciding that the word is not available.
      * @param wordChars The chars whose word should be retrieved.
-     * @param alternativeIndex The index into the (conceptual) array of alternatives for {@code wordChars}.
-     * If the word is in this dictionary at all, setting this to zero should always return something.
-     * @return The word matching the parameters, or null if none matches.
+     * @return The ambiguous word matching {@code wordChars} or null if none matches.
+     * @see #getWord(CharSequence)} to obtain a word that has only one correct way to be hyphenated.
      * @see Orthography#recognizeWord(CharSequence, int, int, org.axsl.orthography.Word.PartOfSpeech) which can
      * also consider other dictionaries as well as derivative forms.
-     * @see #qtyAlternatives(CharSequence) for the range of alternatives that can be iterated.
+     *
+     * @apiNote <p>Consideration was given to keeping the functionality of this method within what is now
+     * {@link #getWord(CharSequence)} by requiring a parameter in that method to specify the index into the alternatives
+     * for the word, and a method to first report how many alternatives there were.
+     * This forced implementations to either 1) awkwardly try to handle these two methods as a single transaction, or
+     * 2) lookup up the word twice, once to report the number of alternatives, then another to actually return the word.
+     * In the case of an ambiguous word, yet another lookup was required to get the second alternative to the word.</p>
+     *
+     * <p>Consideration was also given to returning a {@link java.util.List} at {@link #getWord(CharSequence)}, but this
+     * places unnecessary memory and processing overhead on unambiguous words.</p>
+     *
+     * <p>Consideration was also given to devising a return type that could return both an unambiguous word and an
+     * ambiguous one. It was decided that this introduced unnecessary complexity.</p>
+     *
+     * <p>Finally, consideration was also given to passing part-of-speech and any other information needed to
+     * {@link #getWord(CharSequence)} to disambiguate the requested word. It was decided that this placed more
+     * responsibility on the {@link Dictionary} than was warranted, requiring an {@link Orthography} to be passed to
+     * that method.<p>
      */
-    Word getWord(CharSequence wordChars, int alternativeIndex);
+    AmbiguousWord getAmbiguousWord(CharSequence wordChars);
 
     /**
      * Indicates whether this dictionary stores information about a specific part-of-speech qualifier.

Modified: trunk/axsl/axsl-orthography/src/main/java/org/axsl/orthography/Orthography.java
===================================================================
--- trunk/axsl/axsl-orthography/src/main/java/org/axsl/orthography/Orthography.java	2026-07-22 17:30:36 UTC (rev 3334)
+++ trunk/axsl/axsl-orthography/src/main/java/org/axsl/orthography/Orthography.java	2026-07-23 13:19:47 UTC (rev 3335)
@@ -51,8 +51,10 @@
      * @param pos The part of speech for the word that should be returned.
      * This can be null, implying that a word with no part of speech or any part of speech can be returned.
      * @return The word matching the parameters, or null if none is found.
-     * @see Dictionary#getWord(CharSequence, int) which retrieves a word directly from a dictionary without
+     * @see Dictionary#getWord(CharSequence) which retrieves an unambiguous word directly from a dictionary without
      * consideration for other dictionaries or finding derivatives.
+     * @see Dictionary#getAmbiguousWord(CharSequence) which retrieves an ambiguous word directly from a dictionary
+     * without consideration for other dictionaries or finding derivatives.
      */
     Word recognizeWord(CharSequence wordChars, int offset, int length, PartOfSpeech pos);
 

This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.