GsFindFirst___ - geostan_1 - 2024.01

Finds the first street, segment, or range object that meets the search criteria.

Syntax

GsFunStat GsFindFirstRange(GsId gs, GsRangeHandle *pRange);
GsFunStat GsFindFirstSegment(GsId gs, GsSegmentHandle *pSegment);
GsFunStat GsFindFirstStreet(GsId gs, GsStreetHandle *pStreet, GsEnum option, gs_const_str pLocale,
gs_const_str pName, gs_const_str pNumber);

Arguments

GsIdgs   ID returned by GsInitWithProps() for the current instance of GeoStan. Input.

GsRangeHandle *pRange   Pointer to a segment/range handle. Returns a valid handle if GeoStan finds a range. Input, Output.

GsSegmentHandle *pSegment   Pointer to a street/segment handle. Returns a valid handle If GeoStan finds a segment. Input, Output.

GsStreetHandle *pStreet   Pointer to a street handle. Returns a valid handle if GeoStan finds a street. Output.

GsEnumoption   Determines the type of search performed by GeoStan. The following table lists the type of searches available. Input.

You must specify either GS_ZIP_SEARCH or GS_CITY_SEARCH.

gs_const_strpLocale    Sets the search area. If option is set to GS_ZIP_SEARCH, then pLocale is a valid ZIP Code. If option is set to GS_CITY_SEARCH, then pLocale is a valid city and state. GeoStan performs a city search by searching all finance areas that cover that city. This may result in found objects outside the actual city.Input.

gs_const_strpName   Street name, or partial street name, for which to search. If option is set to GS_SDX_SEARCH, then pName is a pointer to a numeric soundex key. Input.

This limits the search to street names that begin with the name string. If pName is "APPLE," then GeoStan returns only streets beginning with Apple, such as Apple or Appleton. If pName is not specified, GeoStan finds all streets specified by pLocale.

gs_const_strpNumber   House number that must be within a range. If option is set to GS_EXTRA_SEARCH, then pNumber must be blank. Input.

This returns only those ranges that contain that house number. This can be an alpha-numeric house number, such as 12N123W.

Return Values

GS_ERROR    Error occurred. You can retrieve the error using GsErrorGet.

GS_LASTLINE_NOT_FOUND    GeoStan could not find pLocale.

GS_NOT_FOUND    GeoStan did not find a match.

GS_SUCCESS    GeoStan found a match. You can retrieve the data using GsHandleGet().

Prerequisites

GsInitWithProps() and GsClear()

Notes

You must call GsFindFirstStreet() before GsFindFirstSegment() and GsFindFirstSegment() before GsFindFirstRange(). GsFindFirstStreet() also sets the area and criteria for subsequent segment and range searches.

If you are using GsFindFirstStreet() to find a street that has a number as a component of the street name, such as "US HWY 41" or "I-95," enter just the number, as the text is not part of the index for such streets.

GsFindFirst___ and GsFindNext___ functions work together to allow you to access to the entire address directory database.

See Extracting Data from GSD Files for more information on the Find First functions and segment and range searches.

Example

/* This example searches ZIP Code 80301 for streets beginning with "A" and no * specific house number. */
char tempstr[60];
GsStreetHandle hStreet;
GsSegmentHandle hSegment;
GsRangeHandle hRange;
             
/* Use GsFindFirstStreet to get the first street handle that matches the criteria. */
int iStat = GsFindFirstStreet(gs, &hStreet, GS_ZIP_SEARCH, "80301", "A", "");
while(iStat == GS_SUCCESS)
{
/* We have a valid street handle, which we convert to a range handle so that we can use GsHandleGet to 
retrieve information to show the user. Even though we converted to a range handle, it really is still just 
a street handle, so we can only access those elements that are valid at the street level. See "Deprecated 
Functions" for a complete list of valid elements for each handle type.*/
             
hSegment.hStreet = hStreet;
hRange.hSegment = hSegment;
GsHandleGet(gs, GS_PREDIR, &hRange, tempstr,sizeof(tempstr));
printf("Street: %s ", tempstr);
GsHandleGet(gs, GS_NAME, &hRange, tempstr, sizeof(tempstr));
printf("%s ", tempstr);
GsHandleGet( gs, GS_TYPE, &hRange, tempstr, sizeof(tempstr) );
printf("%s ", tempstr);
GsHandleGet(gs, GS_POSTDIR, &hRange, tempstr,sizeof(tempstr));
printf( "%s\n", tempstr);
/* find the first valid segment for the current street*/
iStat = GsFindFirstSegment(gs, &hSegment);
while(iStat == GS_SUCCESS)
{
/* We have a valid segment, convert to a range handle to get information to display.*/
hRange.hSegment = hSegment;
printf(" Segment: " );
GsHandleGet(gs, GS_BLOCK_LEFT, &hRange, tempstr, sizeof(tempstr));
printf("%s ", tempstr);
GsHandleGet(gs, GS_BLOCK_RIGHT, &hRange, tempstr, sizeof(tempstr));
printf("%s ", tempstr);
GsHandleGet(gs, GS_SEGMENT_PARITY, &hRange, tempstr, sizeof(tempstr));
printf("%s ", tempstr);
GsHandleGet(gs, GS_SEGMENT_DIRECTION, &hRange, tempstr, sizeof(tempstr));
printf("%s \n", tempstr);
             
/* Get the first valid range for the current segment. */
iStat = GsFindFirstRange(gs, &hRange);
while(iStat == GS_SUCCESS)
{
GsHandleGet(gs, GS_LORANGE, &hRange, tempstr,sizeof(tempstr));
printf(" Range: %s ", tempstr);
GsHandleGet(gs, GS_HIRANGE, &hRange, tempstr,sizeof(tempstr));
printf("%s ", tempstr);
GsHandleGet(gs, GS_BLOCK_LEFT, &hRange, tempstr, sizeof(tempstr));
printf("%s ", tempstr);
GsHandleGet(gs, GS_PREDIR, &hRange, tempstr,sizeof(tempstr));
printf("%s ", tempstr);
GsHandleGet(gs, GS_NAME, &hRange, tempstr, sizeof(tempstr));
printf("%s ", tempstr);
GsHandleGet(gs, GS_TYPE, &hRange, tempstr, sizeof(tempstr));
printf("%s ", tempstr);
GsHandleGet(gs, GS_POSTDIR, &hRange, tempstr,sizeof(tempstr));
printf("%s ", tempstr);
GsHandleGet(gs, GS_ZIP, &hRange, tempstr, sizeof(tempstr));
printf("%s ", tempstr);
GsHandleGet(gs, GS_LOUNIT, &hRange, tempstr,sizeof(tempstr));
printf("%s ", tempstr);
GsHandleGet(gs, GS_HIUNIT, &hRange, tempstr,sizeof(tempstr));
printf("%s\n", tempstr);
/* Get the next valid range for this segment. */
iStat = GsFindNextRange(gs, &hRange);
}
if (iStat == GS_ERROR) break;
/* get the next valid segment for this street*/
iStat = GsFindNextSegment(gs, &hSegment);
}if (iStat == GS_ERROR) break;
/* Get the next street that meets the initial criteria. */
iStat = GsFindNextStreet(gs, &hStreet);
}