ADC Home > Reference Library > Reference > Internationalization > Localization > Language Analysis Manager Reference >

< Previous PageNext Page > Hide TOC

Deprecated Language Analysis Manager Functions

A function identified as deprecated has been superseded and may become unsupported in the future.

Deprecated in Mac OS X v10.5

LAAddNewWord

Adds a new word to a dictionary. (Deprecated in Mac OS X v10.5.)

OSStatus LAAddNewWord (
   LAEnvironmentRef environ,
   const FSSpec *dictionary,
   const AEDesc *dataList
);

Parameters
environ

A reference to the language analysis environment for the dictionary you want to modify.

dictionary

The file specification for the dictionary you want to modify.

dataList

A pointer to an AEDesc data structure that specifies the word you want to add to the dictionary. See the Apple Event Manager documentation for more information on Apple Event descriptor records.

Return Value

A result code. See “Result Codes.”

Availability
Declared In
LanguageAnalysis.h

LACloseAnalysisContext

Closes the specified language analysis context. (Deprecated in Mac OS X v10.5.)

OSStatus LACloseAnalysisContext (
   LAContextRef context
);

Parameters
context

A reference to the language analysis context you want to close.

Return Value

A result code. See “Result Codes.”

Availability
Declared In
LanguageAnalysis.h

LACloseDictionary

Closes a dictionary in the specified environment. (Deprecated in Mac OS X v10.5.)

OSStatus LACloseDictionary (
   LAEnvironmentRef environ,
   const FSSpec *dictionary
);

Parameters
environ

A reference to the language analysis environment for which you want to close a dictionary.

dictionary

The file specification for the dictionary you want to close.

Return Value

A result code. See “Result Codes.”

Availability
Declared In
LanguageAnalysis.h

LAContinuousMorphemeAnalysis

Performs a continuous morphological analysis of Unicode text. (Deprecated in Mac OS X v10.5.)

OSStatus LAContinuousMorphemeAnalysis (
   LAContextRef context,
   ConstUniCharArrayPtr text,
   UniCharCount textLength,
   Boolean incrementalText,
   LAMorphemePath *leadingPath,
   LAMorphemePath *trailingPath,
   Boolean *modified
);

Parameters
context

A reference to the language analysis context whose text you want to analyze. You can obtain a language analysis context by calling the function LAOpenAnalysisContext.

text

A pointer to the Unicode text string you want to analyze.

textLength

The length of the Unicode text string specified in the text parameter. This value must specify the number of UniChar (double-byte) values in the string.

incrementalText

A Boolean value that indicates the method for passing text. Pass false to specify you want the text to be analyzed as a whole and the analysis started. Pass true if the text is a continuation of the text currently held by the context, and should be added to the context before undergoing analysis.

leadingPath

A pointer to the morpheme path that specifies the results of analyzing the text just previous to the string specified by the text parameter. The Langauage Analysis Manager uses this string to restrict the analyis. For example, if the previous section ends with a noun, the text that follows can begin with a verb. If no valid leading path is available you can pass NULL or a “Leading and Trailing Constants”—kLAFreeEdge or kLADefaultEdge. Pass kLAFreeEdge if it is possible for an optional morpheme to come at the start or the end of analysis. Pass kLADefaultEdge if you want the analysis is carried out so that the start/end of analysis becomes the start of the sentence/end of sentence or the start of the segment/end of segment. Definitions for start of sentence/end of sentence and start of segment/end of segment depend on the engine.

trailingPath

A pointer to the morpheme path that specifies the results of analyzing the text that follows the string specified by the text parameter. When performing a continuous analysis, you must pass the constant kLAIncompleteEdge to indicate that the string is not complete. Note that the function LAGetMorphemes only returns the results it has completed analyzing, not the analysis of the complete source text. If you want to obtain all of the analysis results up to a point, (if a user expressly indicates a conversion with the space bar in a kana-kanji conversion program, and so forth) then you can pass a value other than kLAIncompleteEdge. Then, when you call the function LAGetMorphemes you obtain analysis results for that portion of the string that has been analyzed to that point.

modified

On output, true if the internal state of the context is changed (new analyzed morphemes are generated); otherwise false. When true is returned, you should call the function LAGetMorphemes and update the display. If modified is specified as NULL, values are not returned.

Return Value

A result code. See “Result Codes.”

Discussion

The function LAContinuousMorphemeAnalysis does not return analysis results, but holds them internally. You can obtain the results by calling the functions LAGetMorphemes or LAShiftMorphemes. In contrast to the function LAMorphemeAnalysis you cannot obtain multiple paths for an analysis done using the function LAContinuousMorphemeAnalysis.

You can obtain the same results as calling the function LAResetAnalysis by calling LAContinuousMorphemeAnalysis with the text parameter set to "" and the incrementalText parameter set to false.

Availability
Declared In
LanguageAnalysis.h

LACreateCustomEnvironment

Creates a new environment with the specified name. (Deprecated in Mac OS X v10.5.)

OSStatus LACreateCustomEnvironment (
   LAEnvironmentRef baseEnvironment,
   ConstStr63Param newEnvironmentName,
   Boolean persistent,
   LAEnvironmentRef *newEnvironment
);

Parameters
baseEnvironment

A reference to the language analysis environment that you want to use as the base environment.

newEnvironmentName

The name for the newly-created environment. This name must be unique. If an environment with the same name already exists, the function returns the result code laEnvironmentExistErr.

persistent

A Boolean value that specifies whether the environment should be persistent (true) or not (false). If you pass true, the newly-created environment is saved to disk, and it can be referred to at any time subsequently by using the name. If you pass false, the newly-created environment can only be used during that session. Additionally, environments created with persistent set to false are not returned in the list provided by the function LAGetEnvironmentList, so these environments can be used only as private environments. If you create a private environment, you must call the function LADeleteCustomEnviroment to dispose of it before you terminate your application.

newEnvironemnt

On output, a reference to the newly-created language analysis environment.

Return Value

A result code. See “Result Codes.”

Discussion

If you open or close dictionaries for custom environments, it is possible to create independent environments without interfering with existing environments.

Availability
Declared In
LanguageAnalysis.h

LADeleteCustomEnvironment

Disposes of a reference to a custom language analysis environment. (Deprecated in Mac OS X v10.5.)

OSStatus LADeleteCustomEnvironment (
   LAEnvironmentRef environment
);

Parameters
environment

A reference to the language analysis environment you want to dispose of.

Return Value

A result code. See “Result Codes.”

Availability
Declared In
LanguageAnalysis.h

LAGetEnvironmentList

Obtains a list of the available language analysis environments. (Deprecated in Mac OS X v10.5.)

OSStatus LAGetEnvironmentList (
   UInt32 maxCount,
   UInt32 *actualCount,
   LAEnvironmentRef environmentList[]
);

Parameters
maxCount

The maximum number of environments provided by the system. To determine this value, see the Discussion.

actualCount

On output, the actual number of environments.

environmentList

On output, a list of the available environments. You must allocate a buffer of the appropriate size. If you are uncertain of how much memory to allocate for this array, see the Discussion.

Return Value

A result code. See “Result Codes.”

Discussion

Typically, you use the function LAGetEnvironmentList by calling it twice, as follows:

  1. Pass 0 for the maxCount parameter and NULL for the environmentList parameter.

  2. Allocate enough space for an array of the size specified by actualCount, then call the function LAGetEnvironmentList again. This time, provide a count of the actual number of environments as the maxCount parameter, and a pointer to a buffer of the correct size for the environmentList parameter. On output, the pointer points to an array of the available environments.

Availability
Declared In
LanguageAnalysis.h

LAGetEnvironmentName

Obtains the name of an environment. (Deprecated in Mac OS X v10.5.)

OSStatus LAGetEnvironmentName (
   LAEnvironmentRef environment,
   Str63 environmentName
);

Parameters
environment

A reference to the language analysis environment whose name you want to obtain.

environmentName

On return, the environment name.

Return Value

A result code. See “Result Codes.”

Availability
Declared In
LanguageAnalysis.h

LAGetEnvironmentRef

Obtains the language analysis environment reference associated with an environment name (Deprecated in Mac OS X v10.5.)

OSStatus LAGetEnvironmentRef (
   ConstStr63Param targetEnvironmentName,
   LAEnvironmentRef *environment
);

Parameters
targetEnvironmentName

The environment name whose language analysis environment reference you want to obtain.

environment

On output, a reference to the language analysis environment associated with the environment name.

Return Value

A result code. See “Result Codes.”

Availability
Declared In
LanguageAnalysis.h

LAGetMorphemes

Reads the results of a continuous morpheme analysis. (Deprecated in Mac OS X v10.5.)

OSStatus LAGetMorphemes (
   LAContextRef context,
   LAMorphemePath *result
);

Parameters
context

A reference to the language analysis context whose result you want to obtain. You can obtain a language analysis context by calling the function LAOpenAnalysisContext.

result

On output, points to the morpheme bundle that contains the results of the analysis. You are responsible for disposing of this structure by calling the Apple Event Manager function AEDisposeDesc.

Return Value

A result code. See “Result Codes.”

Availability
Declared In
LanguageAnalysis.h

LALibraryVersion

Returns the version of the Language Analysis Manager installed. (Deprecated in Mac OS X v10.5.)

UInt32 LALibraryVersion (
   void
);

Return Value

Returns the version of Language Analysis manager that is installed.

Discussion

The function LALibraryVersion returns the version of the Language Analysis Manager installed in the same format as 'vers' resource. That is to say, the version number is returned in BCD (Binary-Coded Decimal) format to higher-place words, while release stage information is returned to lower-place words. For example, version 1.1.1 final release library returns 0x01118000.

Availability
Declared In
LanguageAnalysis.h

LAListAvailableDictionaries

Obtains the number of dictionaries available in a specified environment. (Deprecated in Mac OS X v10.5.)

OSStatus LAListAvailableDictionaries (
   LAEnvironmentRef environ,
   ItemCount maxCount,
   ItemCount *actualCount,
   FSSpec dictionaryList[],
   Boolean opened[]
);

Parameters
environ

A reference to the language analysis environment for which you want to obtain a list of available dictionaries.

maxCount

The maximum number of available dictionaries. To determine this value, see the Discussion.

actualCount

On output, the actual number of available dictionaries.

dictionaryList

On output, points to a list of available dictionaries. You must allocate a buffer of the appropriate size. If you are uncertain of how much memory to allocate for this array, see the Discussion.

opened

On output, points to a list of Boolean values that specify whether the available dictionaries are open. This array is parallel to the dictionaryList array. A dictionary file whose associated value is true is open and false if it is not open. You must allocate a buffer of the appropriate size. If you are uncertain of how much memory to allocate for this array, see the Discussion.

Return Value

A result code. See “Result Codes.”

Discussion

Typically, you use the function LAListAvailableDictionaries by calling it twice, as follows:

  1. Pass 0 for the maxCount parameter, NULL for the dictionaryList parameter, and NULL for the opened parameter.

  2. Allocate enough space for arrays of the size specified by actualCount, then call the function LAListAvailableDictionaries again. This time, provide a count of the actual number of dictionaries as the maxCount parameter, and a pointer to buffers of the correct size for the dictionaryList and opened parameters. On output, dictionaryList points to an array of the available dictionaries and opened points to an array that specifies whether each dictionary is opened or closed.

Availability
Declared In
LanguageAnalysis.h

LAMorphemeAnalysis

Performs a morphological analysis of the specified Unicode text. (Deprecated in Mac OS X v10.5.)

OSStatus LAMorphemeAnalysis (
   LAContextRef context,
   ConstUniCharArrayPtr text,
   UniCharCount textLength,
   LAMorphemePath *leadingPath,
   LAMorphemePath *trailingPath,
   ItemCount pathCount,
   LAMorphemeBundle *result
);

Parameters
context

A reference to the language analysis context whose text you want to analyze. You can obtain a language analysis context by calling the function LAOpenAnalysisContext.

text

A pointer to the Unicode text string you want to analyze.

textLength

The length of the Unicode text string specified in the text parameter. This value must specify the number of UniChar (double-byte) values in the string.

leadingPath

A pointer to the morpheme path that specifies the results of analyzing the text just previous to the string specified by the text parameter. The Language Analysis Manager uses this string to restrict the analysis. For example, if the previous section ends with a noun, the text that follows can begin with a verb. If no valid leading path is available you can pass NULL or a “Leading and Trailing Constants”—kLAFreeEdge or kLADefaultEdge. Pass kLAFreeEdge if it is possible for an optional morpheme to come at the start or the end of analysis. Pass kLADefaultEdge if you want the analysis is carried out so that the start/end of analysis becomes the start of the sentence/end of sentence or the start of the segment/end of segment. Definitions for start of sentence/end of sentence and start of segment/end of segment depend on the engine.

trailingPath

A pointer to the morpheme path that specifies the results of analyzing the text that follows the string specified by the text parameter. The Language Analysis Manager uses this string to restrict the analysis. For example, if the following section begins with a verb, the text that precedes it can begin with a noun. If no valid trailing path is available you can pass NULL or a “Leading and Trailing Constants”—kLAFreeEdge or kLADefaultEdge. Pass kLAFreeEdge if it is possible for an optional morpheme to come at the start or the end of analysis. Pass kLADefaultEdge if you want the analysis is carried out so that the start/end of analysis becomes the start of the sentence/end of sentence or the start of the segment/end of segment. Definitions for start of sentence/end of sentence and start of segment/end of segment depend on the engine.

pathCount

On output, specifies the maximum rank of the returned path.

result

On output, points to the morpheme bundle that contains the results of the analysis. You are responsible for disposing of this structure by calling the Apple Event Manager function AEDisposeDesc.

Return Value

A result code. See “Result Codes.”

Discussion

If you have previously called the function LAContinuousMorphemeAnalysis, and you the call the function LAMorphemeAnalysis, the internal state maintained by the function LAContinuousMorphemeAnalysis is disposed of. Then, if you call the functions LAGetMorphemes and LAShiftMorphemes the result code laNoMoreMorphemeErr is returned .

Availability
Declared In
LanguageAnalysis.h

LAOpenAnalysisContext

Creates a language analysis context from a specified language analysis environment. (Deprecated in Mac OS X v10.5.)

OSStatus LAOpenAnalysisContext (
   LAEnvironmentRef environ,
   LAContextRef *context
);

Parameters
environ

A reference to the language analysis environment for which you want to open a context.

context

On output, a language analysis context derived from the specified language analysis environment.

Return Value

A result code. See “Result Codes.”

Availability
Declared In
LanguageAnalysis.h

LAOpenDictionary

Opens a dictionary for the specified environment. (Deprecated in Mac OS X v10.5.)

OSStatus LAOpenDictionary (
   LAEnvironmentRef environ,
   const FSSpec *dictionary
);

Parameters
environ

A reference to the language analysis environment for which you want to open the dictionary.

dictionary

The file specification for the dictionary you want to open.

Return Value

A result code. See “Result Codes.”

Discussion

The environment makes an appropriate assessment of type of dictionary, user dictionary, option dictionary and so forth, before carrying out necessary operations.

Availability
Declared In
LanguageAnalysis.h

LAResetAnalysis

Clears the internal status of the analysis context. (Deprecated in Mac OS X v10.5.)

OSStatus LAResetAnalysis (
   LAContextRef context
);

Parameters
context

A reference to the language analysis context whose analysis you want to reset. You can obtain a language analysis context by calling the function LAOpenAnalysisContext.

Return Value

A result code. See “Result Codes.”

Discussion

Clear the internal status of analysis context. This is accessed before the continuous analysis by the next LAContinuousMorphemeAnalysis. Accessing LAGetMorphemes and LAShiftMorphemes immediately after this call will fail.

The same result will be achieved even if LAContinuousMorphemeAnalysis is accessed as text = "", incrementalText = false

Availability
Declared In
LanguageAnalysis.h

LAShiftMorphemes

Shifts the read out of continuous morpheme analysis. (Deprecated in Mac OS X v10.5.)

OSStatus LAShiftMorphemes (
   LAContextRef context,
   ItemCount morphemeCount,
   LAMorphemePath *path,
   UniCharCount *shiftedLength
);

Parameters
context

A reference to the language analysis context whose read-out you want to shift. You can obtain a language analysis context by calling the function LAOpenAnalysisContext.

morphemeCount

The number of morphemes to be shifted. If you pass kAllMorphemes, all morphemes which are analized are returned.

path

If you pass typeNull a new path is created. If you pass a valid path, the morpheme read out at the end of the path is added. This is handy when this path is to be used as the leading edge the next time LAContinuousMorphemeAnalysis is accessed. In both cases, when you are done using the path, you must dispose of it by calling the Apple Event Manager function AEDispose.

shiftedLength

A pointer to the input character string length (in UniChars) corresponding to the morpheme read out. If you pass NULL, it is not returned.

Return Value

A result code. See “Result Codes.”

Discussion

When you call the function LAShiftMorphemes, the results of the analysis performed by the function LAContinuousMorphemeAnalysis are returned from the start to the number of morpheme readout paths specified in the morphemeCount parameter . Morphemes which have been read out are deleted from analysis context. For example, if "AABBCC" represents the internal status, after you fetch the morpheme "AA" by calling LAShiftMorphemes, the internal status becomes "BBCC".

The results you obtain by calling the funciton LAShiftMorphemes, are impacted by the trailingEdge parameter of the function LAContinuousMorphemeAnalysis. If the value of the trailingEdge parameter is kLAIncompleteEdge, the function LAShiftMorphemes might not return all morphemes and non-converted sections. The analysis engine only returns morphemes with a high degree of certainty. For example, those morphemes which are likely to change if text is added, and laNoMoreMorphemeErr is returned in subsequent accesses. If something other than kLAIncompleteEdge is passed as the trailingEdge parameter, it is possible to fetch morphemes up to the final morpheme. After all morphemes are fetched, the result code laNoMoreMorphemeErr is returned to indicate that nothing remains. This is the same as the status returned after calling the function LAResetAnalysis.

You can carry out a continuous analysis using the functions LAContinuousMorphemeAnalysis and LAShiftMorphemes in two ways. The first method leaves as much text as possible within the analysis engine. That is, continue to provide text to the fucntoin LAContinuousMorphemeAnalysis until you encounter the result code laTextOverflowErr , and call the function LAShiftMorphemes once when the error is returned. The second method leaves as little text as possible within the analysis search engine. That is, continue to provide text to the function LAContinuousMorphemeAnalysis until true is returned to the modified parameter. When true is returned, call the function LAShiftMorphemes with the morphemeCount parameter set to kAllMorphemes.

Availability
Declared In
LanguageAnalysis.h

LATextToMorphemes

Performs a morphological analysis of the specified text. (Deprecated in Mac OS X v10.5.)

OSStatus LATextToMorphemes (
   LAContextRef context,
   TextEncoding preferedEncoding,
   ByteCount textLength,
   ConstLogicalAddress sourceText,
   ByteCount bufferSize,
   OptionBits convertFlags,
   UInt32 structureVersion,
   ByteCount *acceptedLength,
   LAMorphemesArrayPtr resultBuffer
);

Parameters
context

A reference to the language analysis context whose text you want to analyze. You can obtain a language analysis context by calling the function LAOpenAnalysisContext.

preferedEncoding

A value of type TextEncoding that specifies the encoding of text to use for both input and output. The text and length included in the results parameter are adjusted in accordance with the encoding specified here.

textLength

The length, in bytes, of the text you want to analyze.

sourceText

A pointer to the text you want to analyze.

bufferSize

The size of the buffer pointed to by the resultBuffer parameter.

convertFlags

An OptionBits value that specifies how to proceed with the analysis. Currently the only option you can set is kLAEndOfSourceTextMask. If this bit is set, the source text is analyzed to the end, and then results are generated. If this bit is not set, there is a possibility that the end portion of the source text is not yet analyzed when results are available. For example, when a large text file is analyzed it may be preferable to analyze it in chunks, returning results as each chunk is analyzed. You can specify this by passing 0 for the convertFlags parameter, advancing the analysis, and the setting kLAEndOfSourceTextMask when the whole file has been read.

structureVersion

The current version of LAMorphemesArrayPtr. You should pass kLAMorphemesArrayVersion.

acceptedLength

On output, the length of the source text that is accepted by the analysis engine.

resultBuffer

On output, a pointer to an array of LAMorphmesArray structures that contain the results of the morphological analysis.

Return Value

A result code. See “Result Codes.”

Discussion

The function LATextToMorphemes analyzes the text specified in textLength and sourceText, and returns the results to resultBuffer in the form of LAMorphemesArray. While there are no restrictions on the length of text specified, the length in byte units of sourceText received in this call is set to acceptedLength at the point where the output buffer becomes full, or until all text provided has been analyzed. In practice, sections currently being analyzed exist within the analysis context, so be aware that the length returned may not necessarily be the same as the section included in analysis results. This means that if the length of the returned text is shorter than the source text, analysis results are not complete. In this case, fetch the results, increment the sourceText by the acceptedLength, shorten textLength by the acceptedLength, and repeatedly call LATextToMorphemes until all the text is analyzed. The sample code below shows how to analyze text while loading it from a file.

while ( fileErr == noErr )
{
    fileErr = ReadFile (readBufferSize, &actualReadSize, readBuffer);
    if ( fileErr == eofErr )
        analyzeOption = kLAEndOfSourceTextMask;
    else
        analyzeOption = 0;
    analyzeLen = actualReadSize;
    analyzeText = readBuffer;
    result->morphemesCount = 0;
    while (analyzeLen || result->morphemesCount)
    {
        err = LATextToMorphemes (context, kTextEncodingMacJapanese,
                        analyzeLen, analyzeText, resultBufferSize,
                        analyzeOption, kLAMorphemesArrayVersion,
                        &acceptedLen, result);
        if (result->morphemesCount > 0 )
        {
                //
                // Retrieve result here...
                //
        }
        analyzeText += acceptedLen; // Increment source text ptr
        analyzeLen -= acceptedLen; // Decrement source text length
         }
}

If kLAEndOfSourceTextMask is specified and the analysis of all of the source text is done, the context becomes empty. If the analysis is suspended under this or other conditions (including errors), you must call the function LAResetAnalysis to clear the context.

Availability
Declared In
LanguageAnalysis.h

< Previous PageNext Page > Hide TOC

© 2003 Apple Computer, Inc. All Rights Reserved. (Last updated: 2003-04-01)

Did this document help you?
Yes: Tell us what works for you.
It’s good, but: Report typos, inaccuracies, and so forth.
It wasn’t helpful: Tell us what would have helped.